logcdf — SciPy v1.15.3 Manual (original) (raw)

scipy.stats.Normal.

Normal.logcdf(x, y=None, /, *, method=None)[source]#

Log of the cumulative distribution function

The cumulative distribution function (“CDF”), denoted \(F(x)\), is the probability the random variable \(X\) will assume a value less than or equal to \(x\):

\[F(x) = P(X ≤ x)\]

A two-argument variant of this function is also defined as the probability the random variable \(X\) will assume a value between\(x\) and \(y\).

\[F(x, y) = P(x ≤ X ≤ y)\]

logcdf computes the logarithm of the cumulative distribution function (“log-CDF”), \(\log(F(x))\)/\(\log(F(x, y))\), but it may be numerically favorable compared to the naive implementation (computing the CDF and taking the logarithm).

logcdf accepts x for \(x\) and y for \(y\).

Parameters:

x, yarray_like

The arguments of the log-CDF. x is required; y is optional.

method{None, ‘formula’, ‘logexp’, ‘complement’, ‘quadrature’, ‘subtraction’}

The strategy used to evaluate the log-CDF. By default (None), the one-argument form of the function chooses between the following options, listed in order of precedence.

• 'formula': use a formula for the log-CDF itself
• 'logexp': evaluate the CDF and take the logarithm
• 'complement': evaluate the log-CCDF and take the logarithmic complement (see Notes)
• 'quadrature': numerically log-integrate the log-PDF

In place of 'complement', the two-argument form accepts:

• 'subtraction': compute the log-CDF at each argument and take the logarithmic difference (see Notes)

Not all method options are available for all distributions. If the selected method is not available, a NotImplementedErrorwill be raised.

Returns:

outarray

The log-CDF evaluated at the provided argument(s).

Notes

Suppose a continuous probability distribution has support \([l, r]\). The log-CDF evaluates to its minimum value of \(\log(0) = -\infty\)for \(x ≤ l\) and its maximum value of \(\log(1) = 0\) for\(x ≥ r\).

For distributions with infinite support, it is common forcdf to return a value of 0 when the argument is theoretically within the support; this can occur because the true value of the CDF is too small to be represented by the chosen dtype. logcdf, however, will often return a finite (not -inf) result over a much larger domain. Similarly, logcdf may provided a strictly negative result with arguments for which cdf would return 1.0. Consequently, it may be preferred to work with the logarithms of probabilities to avoid underflow and related limitations of floating point numbers.

The “logarithmic complement” of a number \(z\) is mathematically equivalent to \(\log(1-\exp(z))\), but it is computed to avoid loss of precision when \(\exp(z)\) is nearly \(0\) or \(1\). Similarly, the term “logarithmic difference” of \(w\) and \(z\)is used here to mean \(\log(\exp(w)-\exp(z))\).

If y < x, the CDF is negative, and therefore the log-CCDF is complex with imaginary part \(\pi\). For consistency, the result of this function always has complex dtype when y is provided, regardless of the value of the imaginary part.

References

Examples

Instantiate a distribution with the desired parameters:

import numpy as np from scipy import stats X = stats.Uniform(a=-0.5, b=0.5)

Evaluate the log-CDF at the desired argument:

X.logcdf(0.25) -0.287682072451781 np.allclose(X.logcdf(0.), np.log(X.cdf(0.))) True