Module « scipy.special »

Fonction ncfdtr - module scipy.special

Signature de la fonction ncfdtr

Description

ncfdtr.__doc__

ncfdtr(x1, x2, x3, x4, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])

ncfdtr(dfn, dfd, nc, f)

Cumulative distribution function of the non-central F distribution.

The non-central F describes the distribution of,

.. math::
    Z = \frac{X/d_n}{Y/d_d}

where :math:`X` and :math:`Y` are independently distributed, with
:math:`X` distributed non-central :math:`\chi^2` with noncentrality
parameter `nc` and :math:`d_n` degrees of freedom, and :math:`Y`
distributed :math:`\chi^2` with :math:`d_d` degrees of freedom.

Parameters
----------
dfn : array_like
    Degrees of freedom of the numerator sum of squares.  Range (0, inf).
dfd : array_like
    Degrees of freedom of the denominator sum of squares.  Range (0, inf).
nc : array_like
    Noncentrality parameter.  Should be in range (0, 1e4).
f : array_like
    Quantiles, i.e. the upper limit of integration.

Returns
-------
cdf : float or ndarray
    The calculated CDF.  If all inputs are scalar, the return will be a
    float.  Otherwise it will be an array.

See Also
--------
ncfdtri : Quantile function; inverse of `ncfdtr` with respect to `f`.
ncfdtridfd : Inverse of `ncfdtr` with respect to `dfd`.
ncfdtridfn : Inverse of `ncfdtr` with respect to `dfn`.
ncfdtrinc : Inverse of `ncfdtr` with respect to `nc`.

Notes
-----
Wrapper for the CDFLIB [1]_ Fortran routine `cdffnc`.

The cumulative distribution function is computed using Formula 26.6.20 of
[2]_:

.. math::
    F(d_n, d_d, n_c, f) = \sum_{j=0}^\infty e^{-n_c/2} \frac{(n_c/2)^j}{j!} I_{x}(\frac{d_n}{2} + j, \frac{d_d}{2}),

where :math:`I` is the regularized incomplete beta function, and
:math:`x = f d_n/(f d_n + d_d)`.

The computation time required for this routine is proportional to the
noncentrality parameter `nc`.  Very large values of this parameter can
consume immense computer resources.  This is why the search range is
bounded by 10,000.

References
----------
.. [1] Barry Brown, James Lovato, and Kathy Russell,
       CDFLIB: Library of Fortran Routines for Cumulative Distribution
       Functions, Inverses, and Other Parameters.
.. [2] Milton Abramowitz and Irene A. Stegun, eds.
       Handbook of Mathematical Functions with Formulas,
       Graphs, and Mathematical Tables. New York: Dover, 1972.

Examples
--------
>>> from scipy import special
>>> from scipy import stats
>>> import matplotlib.pyplot as plt

Plot the CDF of the non-central F distribution, for nc=0.  Compare with the
F-distribution from scipy.stats:

>>> x = np.linspace(-1, 8, num=500)
>>> dfn = 3
>>> dfd = 2
>>> ncf_stats = stats.f.cdf(x, dfn, dfd)
>>> ncf_special = special.ncfdtr(dfn, dfd, 0, x)

>>> fig = plt.figure()
>>> ax = fig.add_subplot(111)
>>> ax.plot(x, ncf_stats, 'b-', lw=3)
>>> ax.plot(x, ncf_special, 'r-')
>>> plt.show()