Skip to main content
`Ctrl`+`K`
scipy.stats.Binomial.

# logcdf

Binomial.logcdf(x, y=None, /, *, method=None)

  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, y array_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 (or, in the discrete case, log-sum the log-PMF)

      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 `NotImplementedError` will be raised.

  Returns:
    out array

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

  See also

  `cdf`
  `logccdf`

  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\). An analogous statement can be made for discrete distributions, but the inequality governing the minimum value is strict.

  For distributions with infinite support, it is common for `cdf` 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

  [1]

  Cumulative distribution function, Wikipedia, https://en.wikipedia.org/wiki/Cumulative_distribution_function

  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