Statistics
==========

.. module:: sympy.statistics

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 *
    >>> import sys
    >>> sys.displayhook = pprint

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.0539909665131881
    >>> N.cdf(x)
             /  ___        \
             |\/ 2 *(1 - x)|
          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.