Some basic stat functions

stat_functions.py

#!/usr/bin/python

"""
Some stats functions::

    >>> mean([1, 2, 6])
    3.0
    >>> variance([1, 2, 6], bias=True)
    4.666666...

"""

from math import sqrt


def mean(iterable):
    """Mean computation.

    :param iterable: the list containing the numbers
    :raises:         ValueError, if empty iterable
    :returns:        returns the mean of the iterable

    >>> mean([1, 2, 6])
    3.0
    >>> mean([1, 2])
    1.5
    >>> mean([1])
    1.0
    >>> mean([])
    Traceback (most recent call last):
    ValueError: Empty iterable.
    """
    if not iterable:
        raise ValueError("Empty iterable.")

    return float(sum(iterable)) / len(iterable)


def median(alist):
    """Median computation.

    >>> median([1, 2, 5])
    2
    >>> median([1, 2])
    1.5
    >>> median([1])
    1
    """
    srtd = sorted(alist)  # returns a sorted copy
    mid = len(alist) / 2  # remember that integer division truncates

    if len(alist) % 2 == 0:  # take the avg of middle two
        return (srtd[mid - 1] + srtd[mid]) / 2.0
    else:
        return srtd[mid]


def variance(iterable, bias=False):
    """
    Implementation of the *variance*.

    :param iterable:  the list containing the numbers
    :param bias:    biased formula or not, boolean
    :raises:        ValueError, if empty iterable
    :returns:       returns the variance of the iterable

    >>> variance([1, 2, 6])
    7.0
    >>> variance([1, 2, 6], bias=True)
    4.666666...
    >>> variance([1])
    0.0
    >>> variance([1], bias=True)
    0.0
    >>> variance([])
    Traceback (most recent call last):
    ValueError: Empty iterable.
    """
    if not iterable:
        raise ValueError("Empty iterable.")

    n = len(iterable)
    m = mean(iterable)

    if n == 1:
        # If only one element in the iterable,
        # the variance is obviously 0
        return 0.0

    if bias:
        return mean([(x - m) ** 2 for x in iterable])

    return mean([(x - m) ** 2 for x in iterable]) * n / (n-1)


def sd(iterable, bias=False) :
    """
    Implementation of the *standard deviation*.

    :param iterable:  the list containing the numbers
    :param bias:    biased formula or not, boolean
    :raises:        ValueError, if empty iterable
    :returns:       returns the standard deviation of the iterable

    >>> sd([1, 2, 6])
    2.645751...
    >>> sd([1, 2, 6], bias=True)
    2.160246...
    >>> sd([1])
    0.0
    >>> sd([1], bias=True)
    0.0
    >>> sd([])
    Traceback (most recent call last):
    ValueError: Empty iterable.
    """

    if not iterable:
        raise ValueError("Empty iterable.")

    return sqrt(variance(iterable, bias=bias))
    

def _test():
    """
    When called directly, launching doctests.
    """
    import doctest

    opt =  (doctest.ELLIPSIS |
            doctest.NORMALIZE_WHITESPACE |
            doctest.REPORT_ONLY_FIRST_FAILURE )
            #doctest.IGNORE_EXCEPTION_DETAIL)

    doctest.testmod(optionflags=opt, verbose=False)


if __name__ == '__main__':
    _test()