# Source code for simplestatistics.statistics.standard_deviation

"""
Implements standard_deviation().
"""

import math
from .variance import variance

[docs]def standard_deviation(data, sample=True):
"""
The standard deviation_ is the square root of variance_ (the sum of squared deviations
from the mean).
The standard deviation is a commonly used measure of the variation and distance of
a set of values in a sample from the mean of the sample.

.. _standard deviation: https://en.wikipedia.org/wiki/Standard_deviation
.. _variance: http://en.wikipedia.org/wiki/Variance

Equation:

.. math::
\\sigma = \\sqrt{\\frac{\\sum (x - \\mu)^2}{N - 1}}

In English:
- Obtain the difference between each value and the mean.
- Square those values.
- Sum the squared values.
- Divide by the number of values - 1 (to correct for the sampling).
- Obtain the square root of the result.

Args:
data: A list of numerical objects.
sample: A boolean value. If True, calculates standard deviation for
sample. If False, calculates standard deviation for population.

Returns:
A float object.

Examples:

>>> standard_deviation([1, 2, 3])
1.0
>>> standard_deviation([1, 2, 3], False)
0.816496580927726
>>> standard_deviation([1, 2, 3, 4])
1.2909944487358056
>>> standard_deviation([-1, 0, 1, 2, 3, 4])
1.8708286933869707
"""
return math.sqrt(variance(data, sample))