Statistics
==========

.. module:: sympy.statistics

.. note ::

    This module has been deprecated. See the :mod:`stats <sympy.stats>` module.

The ``statistics`` module in SymPy implements standard probability distributions
and related tools. Its contents can be imported with the following statement::

    >>> from sympy import *
    >>> from sympy.statistics import *
    >>> init_printing(use_unicode=False, wrap_line=False, no_global=True)

Normal distributions
--------------------

``Normal(mu, sigma)`` creates a normal distribution with mean value ``mu`` and
standard deviation ``sigma``. The ``Normal`` class defines several
useful methods and properties. Various properties can be accessed directly as
follows:

    >>> N = Normal(0, 1)
    >>> N.mean
    0
    >>> N.median
    0
    >>> N.variance
    1
    >>> N.stddev
    1

You can generate random numbers from the desired distribution with the
``random`` method:

    >>> N = Normal(10, 5)
    >>> N.random() #doctest: +SKIP
    4.914375200829805834246144514
    >>> N.random() #doctest: +SKIP
    11.84331557474637897087177407
    >>> N.random() #doctest: +SKIP
    17.22474580071733640806996846
    >>> N.random() #doctest: +SKIP
    9.864643097429464546621602494

The probability density function (pdf) and cumulative distribution function
(cdf) of a distribution can be computed, either in symbolic form or for
particular values:

    >>> N = Normal(1, 1)
    >>> x = Symbol('x')
    >>> N.pdf(1)
       ___
     \/ 2
    --------
        ____
    2*\/ pi
    >>> N.pdf(3).evalf()
    0.0539909665131880
    >>> N.cdf(x)
       /  ___        \
       |\/ 2 *(x - 1)|
    erf|-------------|
       \      2      /   1
    ------------------ + -
            2            2
    >>> N.cdf(-oo), N.cdf(1), N.cdf(oo)
    (0, 1/2, 1)
    >>> N.cdf(5).evalf()
    0.999968328758167

The method ``probability`` gives the total probability on a given interval (a
convenient alternative syntax for cdf(b)-cdf(a)):

    >>> N = Normal(0, 1)
    >>> N.probability(-oo, 0)
    1/2
    >>> N.probability(-1, 1)
       /  ___\
       |\/ 2 |
    erf|-----|
       \  2  /
    >>> N.probability(-1, 1).evalf()
    0.682689492137086

You can also generate a symmetric confidence interval from a given desired
confidence level (given as a fraction 0-1). For the normal distribution, 68%,
95% and 99.7% confidence levels respectively correspond to approximately 1, 2
and 3 standard deviations:

    >>> N = Normal(0, 1)
    >>> N.confidence(0.68)
    (-0.994457883209753, 0.994457883209753)
    >>> N.confidence(0.95)
    (-1.95996398454005, 1.95996398454005)
    >>> N.confidence(0.997)
    (-2.96773792534178, 2.96773792534178)

Plug the interval back in to see that the value is correct:

    >>> N.probability(*N.confidence(0.95)).evalf()
    0.950000000000000

Other distributions
-------------------

Besides the normal distribution, uniform continuous distributions are also
supported. ``Uniform(a, b)`` represents the distribution with uniform
probability on the interval [a, b] and zero probability everywhere else. The
``Uniform`` class supports the same methods as the ``Normal`` class.

Additional distributions, including support for arbitrary user-defined distributions, are planned for the future.

API Reference
-------------

Sample
^^^^^^

.. autoclass:: sympy.statistics.distributions.Sample
   :members:

Continuous Probability Distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: sympy.statistics.distributions.ContinuousProbability
   :members:

.. autoclass:: sympy.statistics.distributions.Normal
   :members:

.. autoclass:: sympy.statistics.distributions.Uniform
   :members:

.. autoclass:: sympy.statistics.distributions.PDF
   :members:


