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

# logccdf

Normal.logccdf(x, y=None, /, *, method=None)

  Log of the complementary cumulative distribution function

  The complementary cumulative distribution function (“CCDF”), denoted \(G(x)\) is the complement of the cumulative distribution function \(F(x)\); i.e., probability the random variable \(X\) will assume a value greater than \(x\):

  \[ \begin{align}\begin{aligned} G(x) = 1 - F(x) = P(X > x)\\A two-argument variant of this function is:\end{aligned}\end{align} \]
  \[G(x, y) = 1 - F(x, y) = P(X < x \quad \text{or} \quad X > y)\]

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

  `logccdf` accepts x for \(x\) and y for \(y\).

  Parameters:
    x, y array_like

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

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

      The strategy used to evaluate the log-CCDF. 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 CCDF itself

      - `'logexp'`: evaluate the CCDF and take the logarithm

      - `'complement'`: evaluate the log-CDF and take the logarithmic complement (see Notes)

      - `'quadrature'`: numerically log-integrate the log-PDF (or, in the discrete case, log-sum the log-PMF)

      The two-argument form chooses between:

      - `'formula'`: use a formula for the log CCDF itself

      - `'addition'`: compute the log-CDF at x and the log-CCDF at y, then take the logarithmic sum (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-CCDF evaluated at the provided argument(s).

  See also

  `ccdf`
  `logcdf`

  Notes

  Suppose a continuous probability distribution has support \([l, r]\). The log-CCDF returns its minimum value of \(\log(0)=-\infty\) for \(x ≥ r\) and its maximum value of \(\log(1) = 0\) for \(x ≤ l\). An analogous statement can be made for discrete distributions, but the inequality governing the maximum value is strict.

  For distributions with infinite support, it is common for `ccdf` to return a value of `0` when the argument is theoretically within the support; this can occur because the true value of the CCDF is too small to be represented by the chosen dtype. The log of the CCDF, however, will often be finite (not `-inf`) over a much larger domain. Similarly, `logccdf` may provided a strictly negative result with arguments for which `ccdf` 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 sum” of \(w\) and \(z\) is used here to mean the \(\log(\exp(w)+\exp(z))\), AKA \(\text{LogSumExp}(w, z)\).

  References

  [1]

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

  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-CCDF at the desired argument:

      >>> X.logccdf(0.25)
      -1.3862943611198906
      >>> np.allclose(X.logccdf(0.), np.log(X.ccdf(0.)))
      True