***********************************************************
:mod:`stats` --- Collection of simple statistical functions
***********************************************************

.. module:: stats
   :synopsis: Collection of simple statistical functions

This module contains some useful functions for doing simple statistics with
your data, like calculating means, medians, quantiles and confidence intervals.

Functions
=========

.. function:: mean(data)

   Returns the mean of ``data``, which has to be a list or a tuple.

.. function:: variance(data)

   Calculates the variance of ``data``. Take its square root if you need the
   standard deviation.

.. function:: mean_var(data)

   Returns both the mean and the variance. It's slightly faster than
   calculating them separately and is preferable if you need them both::

      mean, var = mean_var(data)

.. function:: mean_stderr(data)

   This functions returns the mean and the standard error of the sample.

.. function:: mean_ci(data, alpha)

   Returns the mean of the sample ``data`` and half its confidence interval
   width, meaning if the resulting values are ``mean`` and ``ci``, then the
   confidence interval is actually [``mean`` - ``ci``, ``mean`` + ``ci``],

.. function:: median(data)

   Returns the median of the sample.

.. function:: quantile(data, q)

   Returns one or more quantiles of ``data``. If ``q`` is a single number, the
   result will also be just the value of the requested quantile. ``q`` can also
   be a list or a tuple with several quantiles; in this case the return value
   is a list with corresponding values from ``data``. If you need more than one
   quantile for a sample, choose the list way over calculating them repeatedly,
   as this will be faster for large samples.

.. function:: stdnorm_invcdf(p)

   This function calculates the inverse cumulative density function of the
   standard normal distribution. Useful when you need to know the factor to
   multiply the standard deviation with to get a certain confidence interval.
   For example, for a two-sided mean confidence interval of 95%, the factor
   is::

      f = stdnorm_invcdf(0.975) # about 1.96