scipy.special.xlog1py#

scipy.special.xlog1py(x, y, out=None) = <ufunc 'xlog1py'>#

Compute x*log1p(y) so that the result is 0 if x = 0.

Parameters:
xarray_like

Multiplier

yarray_like

Argument

outndarray, optional

Optional output array for the function results

Returns:
zscalar or ndarray

Computed x*log1p(y)

Notes

Added in version 0.13.0.

Array API Standard Support

xlog1py has support for Python Array API Standard compatible backends in addition to NumPy. The following combinations of backend and device (or other capability) are supported.

Library

CPU

GPU

NumPy

✅

n/a

CuPy

n/a

✅

PyTorch

✅

✅

JAX

✅

✅

Dask

✅

n/a

For the NumPy backend, this function supports all NumPy ufunc keyword arguments. Other backends may support out, but none of the other ufunc kwargs. out is typically supported for CuPy and PyTorch, but not currently in cases where SciPy relies on a generic Array API implementation or, for PyTorch on CPU, falls back to the NumPy backend. out is never supported for JAX because JAX arrays are immutable.

See Support for the array API standard for more information.

Examples

This example shows how the function can be used to calculate the log of the probability mass function for a geometric discrete random variable. The probability mass function of the geometric distribution is defined as follows:

\[f(k) = (1-p)^{k-1} p\]

where \(p\) is the probability of a single success and \(1-p\) is the probability of a single failure and \(k\) is the number of trials to get the first success.

>>> import numpy as np
>>> from scipy.special import xlog1py
>>> p = 0.5
>>> k = 100
>>> _pmf = np.power(1 - p, k - 1) * p
>>> _pmf
7.888609052210118e-31

If we take k as a relatively large number the value of the probability mass function can become very low. In such cases taking the log of the pmf would be more suitable as the log function can change the values to a scale that is more appropriate to work with.

>>> _log_pmf = xlog1py(k - 1, -p) + np.log(p)
>>> _log_pmf
-69.31471805599453

We can confirm that we get a value close to the original pmf value by taking the exponential of the log pmf.

>>> _orig_pmf = np.exp(_log_pmf)
>>> np.isclose(_pmf, _orig_pmf)
True
On this page