Reformat statistics.rst and remove unnecessary headings for each function.

Doc/library/statistics.rst

@@ -35,21 +35,34 @@ or sample.
 :func:`mode`             Mode (most common value) of discrete data.
 =======================  =============================================
 
-:func:`mean`
-~~~~~~~~~~~~
+Measures of spread
+------------------
+
+These functions calculate a measure of how much the population or sample
+tends to deviate from the typical or average values.
+
+=======================  =============================================
+:func:`pstdev`           Population standard deviation of data.
+:func:`pvariance`        Population variance of data.
+:func:`stdev`            Sample standard deviation of data.
+:func:`variance`         Sample variance of data.
+=======================  =============================================
 
-The :func:`mean` function calculates the arithmetic mean, commonly known
-as the average, of its iterable argument:
+
+Function details
+----------------
 
 .. function:: mean(data)
 
-   Return the sample arithmetic mean of *data*, a sequence or iterator
-   of real-valued numbers.
+   Return the sample arithmetic mean of *data*, a sequence or iterator of
+   real-valued numbers.
+
+   The arithmetic mean is the sum of the data divided by the number of data
+   points.  It is commonly called "the average", although it is only one of many
+   different mathematical averages.  It is a measure of the central location of
+   the data.
 
-   The arithmetic mean is the sum of the data divided by the number of
-   data points. It is commonly called "the average", although it is only
-   one of many different mathematical averages. It is a measure of the
-   central location of the data.
+   If *data* is empty, :exc:`StatisticsError` will be raised.
 
    Some examples of use:
 
@@ -70,75 +83,56 @@ as the average, of its iterable argument:
 
    .. note::
 
-      The mean is strongly effected by outliers and is not a robust
-      estimator for central location: the mean is not necessarily a
-      typical example of the data points. For more robust, although less
-      efficient, measures of central location, see :func:`median` and
-      :func:`mode`. (In this case, "efficient" refers to statistical
-      efficiency rather than computational efficiency.)
-
-      The sample mean gives an unbiased estimate of the true population
-      mean, which means that, taken on average over all the possible
-      samples, ``mean(sample)`` converges on the true mean of the entire
-      population. If *data* represents the entire population rather than
-      a sample, then ``mean(data)`` is equivalent to calculating the true
-      population mean μ.
+      The mean is strongly effected by outliers and is not a robust estimator
+      for central location: the mean is not necessarily a typical example of the
+      data points.  For more robust, although less efficient, measures of
+      central location, see :func:`median` and :func:`mode`.  (In this case,
+      "efficient" refers to statistical efficiency rather than computational
+      efficiency.)
 
-   If ``data`` is empty, :exc:`StatisticsError` will be raised.
+      The sample mean gives an unbiased estimate of the true population mean,
+      which means that, taken on average over all the possible samples,
+      ``mean(sample)`` converges on the true mean of the entire population.  If
+      *data* represents the entire population rather than a sample, then
+      ``mean(data)`` is equivalent to calculating the true population mean μ.
 
-:func:`median`
-~~~~~~~~~~~~~~
-
-The :func:`median` function calculates the median, or middle, data point,
-using the common "mean of middle two" method.
-
-   .. seealso::
-
-      :func:`median_low`
-
-      :func:`median_high`
-
-      :func:`median_grouped`
 
 .. function:: median(data)
 
-   Return the median (middle value) of numeric data.
+   Return the median (middle value) of numeric data, using the common "mean of
+   middle two" method.  If *data* is empty, :exc:`StatisticsError` is raised.
 
-   The median is a robust measure of central location, and is less affected
-   by the presence of outliers in your data. When the number of data points
-   is odd, the middle data point is returned:
+   The median is a robust measure of central location, and is less affected by
+   the presence of outliers in your data.  When the number of data points is
+   odd, the middle data point is returned:
 
    .. doctest::
 
       >>> median([1, 3, 5])
       3
 
-   When the number of data points is even, the median is interpolated by
-   taking the average of the two middle values:
+   When the number of data points is even, the median is interpolated by taking
+   the average of the two middle values:
 
    .. doctest::
 
       >>> median([1, 3, 5, 7])
       4.0
 
-   This is suited for when your data is discrete, and you don't mind that
-   the median may not be an actual data point.
+   This is suited for when your data is discrete, and you don't mind that the
+   median may not be an actual data point.
 
-   If data is empty, :exc:`StatisticsError` is raised.
+   .. seealso:: :func:`median_low`, :func:`median_high`, :func:`median_grouped`
 
-:func:`median_low`
-~~~~~~~~~~~~~~~~~~
-
-The :func:`median_low` function calculates the low median without
-interpolation.
 
 .. function:: median_low(data)
 
-   Return the low median of numeric data.
+   Return the low median of numeric data.  If *data* is empty,
+   :exc:`StatisticsError` is raised.
 
-   The low median is always a member of the data set. When the number
-   of data points is odd, the middle value is returned. When it is
-   even, the smaller of the two middle values is returned.
+   The low median is always a member of the data set.  When the number of data
+   points is odd, the middle value is returned.  When it is even, the smaller of
+   the two middle values is returned.
 
    .. doctest::
 
@@ -147,24 +141,18 @@ interpolation.
       >>> median_low([1, 3, 5, 7])
       3
 
-   Use the low median when your data are discrete and you prefer the median
-   to be an actual data point rather than interpolated.
+   Use the low median when your data are discrete and you prefer the median to
+   be an actual data point rather than interpolated.
 
-   If data is empty, :exc:`StatisticsError` is raised.
-
-:func:`median_high`
-~~~~~~~~~~~~~~~~~~~
-
-The :func:`median_high` function calculates the high median without
-interpolation.
 
 .. function:: median_high(data)
 
-   Return the high median of data.
+   Return the high median of data.  If *data* is empty, :exc:`StatisticsError`
+   is raised.
 
-   The high median is always a member of the data set. When the number of
-   data points is odd, the middle value is returned. When it is even, the
-   larger of the two middle values is returned.
+   The high median is always a member of the data set.  When the number of data
+   points is odd, the middle value is returned.  When it is even, the larger of
+   the two middle values is returned.
 
    .. doctest::
 
@@ -173,41 +161,34 @@ interpolation.
       >>> median_high([1, 3, 5, 7])
       5
 
-   Use the high median when your data are discrete and you prefer the median
-   to be an actual data point rather than interpolated.
-
-   If data is empty, :exc:`StatisticsError` is raised.
-
-:func:`median_grouped`
-~~~~~~~~~~~~~~~~~~~~~~
+   Use the high median when your data are discrete and you prefer the median to
+   be an actual data point rather than interpolated.
 
-The :func:`median_grouped` function calculates the median of grouped data
-as the 50th percentile, using interpolation.
 
-.. function:: median_grouped(data [, interval])
+.. function:: median_grouped(data, interval=1)
 
-   Return the median of grouped continuous data, calculated as the
-   50th percentile.
+   Return the median of grouped continuous data, calculated as the 50th
+   percentile, using interpolation.  If *data* is empty, :exc:`StatisticsError`
+   is raised.
 
    .. doctest::
 
       >>> median_grouped([52, 52, 53, 54])
       52.5
 
-   In the following example, the data are rounded, so that each value
-   represents the midpoint of data classes, e.g. 1 is the midpoint of the
-   class 0.5-1.5, 2 is the midpoint of 1.5-2.5, 3 is the midpoint of
-   2.5-3.5, etc. With the data given, the middle value falls somewhere in
-   the class 3.5-4.5, and interpolation is used to estimate it:
+   In the following example, the data are rounded, so that each value represents
+   the midpoint of data classes, e.g. 1 is the midpoint of the class 0.5-1.5, 2
+   is the midpoint of 1.5-2.5, 3 is the midpoint of 2.5-3.5, etc.  With the data
+   given, the middle value falls somewhere in the class 3.5-4.5, and
+   interpolation is used to estimate it:
 
    .. doctest::
 
       >>> median_grouped([1, 2, 2, 3, 4, 4, 4, 4, 4, 5])
       3.7
 
-   Optional argument ``interval`` represents the class interval, and
-   defaults to 1. Changing the class interval naturally will change the
-   interpolation:
+   Optional argument *interval* represents the class interval, and defaults
+   to 1.  Changing the class interval naturally will change the interpolation:
 
    .. doctest::
 
@@ -217,36 +198,34 @@ as the 50th percentile, using interpolation.
       3.5
 
    This function does not check whether the data points are at least
-   ``interval`` apart.
+   *interval* apart.
 
    .. impl-detail::
 
-      Under some circumstances, :func:`median_grouped` may coerce data
-      points to floats. This behaviour is likely to change in the future.
+      Under some circumstances, :func:`median_grouped` may coerce data points to
+      floats.  This behaviour is likely to change in the future.
 
    .. seealso::
 
-      * "Statistics for the Behavioral Sciences", Frederick J Gravetter
-         and Larry B Wallnau (8th Edition).
+      * "Statistics for the Behavioral Sciences", Frederick J Gravetter and
+        Larry B Wallnau (8th Edition).
 
       * Calculating the `median <http://www.ualberta.ca/~opscan/median.html>`_.
 
-      * The `SSMEDIAN <https://projects.gnome.org/gnumeric/doc/gnumeric-function-SSMEDIAN.shtml>`_
-         function in the Gnome Gnumeric spreadsheet, including
-         `this discussion <https://mail.gnome.org/archives/gnumeric-list/2011-April/msg00018.html>`_.
+      * The `SSMEDIAN
+        <https://projects.gnome.org/gnumeric/doc/gnumeric-function-SSMEDIAN.shtml>`_
+        function in the Gnome Gnumeric spreadsheet, including `this discussion
+        <https://mail.gnome.org/archives/gnumeric-list/2011-April/msg00018.html>`_.
 
-   If data is empty, :exc:`StatisticsError` is raised.
-
-:func:`mode`
-~~~~~~~~~~~~
-
-The :func:`mode` function calculates the mode, or most common element, of
-discrete or nominal data. The mode (when it exists) is the most typical
-value, and is a robust measure of central location.
 
 .. function:: mode(data)
 
-   Return the most common data point from discrete or nominal data.
+   Return the most common data point from discrete or nominal *data*.  The mode
+   (when it exists) is the most typical value, and is a robust measure of
+   central location.
+
+   If *data* is empty, or if there is not exactly one most common value,
+   :exc:`StatisticsError` is raised.
 
    ``mode`` assumes discrete data, and returns a single value. This is the
    standard treatment of the mode as commonly taught in schools:
@@ -264,60 +243,35 @@ value, and is a robust measure of central location.
       >>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
       'red'
 
-   If data is empty, or if there is not exactly one most common value,
-   :exc:`StatisticsError` is raised.
-
-Measures of spread
-------------------
-
-These functions calculate a measure of how much the population or sample
-tends to deviate from the typical or average values.
-
-=======================  =============================================
-:func:`pstdev`           Population standard deviation of data.
-:func:`pvariance`        Population variance of data.
-:func:`stdev`            Sample standard deviation of data.
-:func:`variance`         Sample variance of data.
-=======================  =============================================
-
-:func:`pstdev`
-~~~~~~~~~~~~~~
 
-The :func:`pstdev` function calculates the standard deviation of a
-population. The standard deviation is equivalent to the square root of
-the variance.
+.. function:: pstdev(data, mu=None)
 
-.. function:: pstdev(data [, mu])
-
-   Return the square root of the population variance. See :func:`pvariance`
-   for arguments and other details.
+   Return the population standard deviation (the square root of the population
+   variance).  See :func:`pvariance` for arguments and other details.
 
    .. doctest::
 
       >>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
       0.986893273527251
 
-:func:`pvariance`
-~~~~~~~~~~~~~~~~~
-
-The :func:`pvariance` function calculates the variance of a population.
-Variance, or second moment about the mean, is a measure of the variability
-(spread or dispersion) of data. A large variance indicates that the data is
-spread out; a small variance indicates it is clustered closely around the
-mean.
 
-.. function:: pvariance(data [, mu])
+.. function:: pvariance(data, mu=None)
 
-   Return the population variance of *data*, a non-empty iterable of
-   real-valued numbers.
+   Return the population variance of *data*, a non-empty iterable of real-valued
+   numbers.  Variance, or second moment about the mean, is a measure of the
+   variability (spread or dispersion) of data.  A large variance indicates that
+   the data is spread out; a small variance indicates it is clustered closely
+   around the mean.
 
-   If the optional second argument *mu* is given, it should be the mean
-   of *data*. If it is missing or None (the default), the mean is
+   If the optional second argument *mu* is given, it should be the mean of
+   *data*.  If it is missing or ``None`` (the default), the mean is
    automatically calculated.
 
-   Use this function to calculate the variance from the entire population.
-   To estimate the variance from a sample, the :func:`variance` function is
-   usually a better choice.
+   Use this function to calculate the variance from the entire population.  To
+   estimate the variance from a sample, the :func:`variance` function is usually
+   a better choice.
+
+   Raises :exc:`StatisticsError` if *data* is empty.
 
    Examples:
 
@@ -327,8 +281,8 @@ mean.
       >>> pvariance(data)
       1.25
 
-   If you have already calculated the mean of your data, you can pass
-   it as the optional second argument *mu* to avoid recalculation:
+   If you have already calculated the mean of your data, you can pass it as the
+   optional second argument *mu* to avoid recalculation:
 
    .. doctest::
 
@@ -336,9 +290,9 @@ mean.
       >>> pvariance(data, mu)
       1.25
 
-   This function does not attempt to verify that you have passed the actual
-   mean as *mu*. Using arbitrary values for *mu* may lead to invalid or
-   impossible results.
+   This function does not attempt to verify that you have passed the actual mean
+   as *mu*.  Using arbitrary values for *mu* may lead to invalid or impossible
+   results.
 
    Decimals and Fractions are supported:
 
@@ -354,53 +308,44 @@ mean.
 
    .. note::
 
-      When called with the entire population, this gives the population
-      variance σ². When called on a sample instead, this is the biased
-      sample variance s², also known as variance with N degrees of freedom.
+      When called with the entire population, this gives the population variance
+      σ².  When called on a sample instead, this is the biased sample variance
+      s², also known as variance with N degrees of freedom.
 
-      If you somehow know the true population mean μ, you may use this
-      function to calculate the variance of a sample, giving the known
-      population mean as the second argument. Provided the data points are
-      representative (e.g. independent and identically distributed), the
-      result will be an unbiased estimate of the population variance.
-
-   Raises :exc:`StatisticsError` if *data* is empty.
+      If you somehow know the true population mean μ, you may use this function
+      to calculate the variance of a sample, giving the known population mean as
+      the second argument.  Provided the data points are representative
+      (e.g. independent and identically distributed), the result will be an
+      unbiased estimate of the population variance.
 
-:func:`stdev`
-~~~~~~~~~~~~~~
 
-The :func:`stdev` function calculates the standard deviation of a sample.
-The standard deviation is equivalent to the square root of the variance.
+.. function:: stdev(data, xbar=None)
 
-.. function:: stdev(data [, xbar])
-
-   Return the square root of the sample variance. See :func:`variance` for
-   arguments and other details.
+   Return the sample standard deviation (the square root of the sample
+   variance).  See :func:`variance` for arguments and other details.
 
    .. doctest::
 
       >>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
       1.0810874155219827
 
-:func:`variance`
-~~~~~~~~~~~~~~~~~
-
-The :func:`variance` function calculates the variance of a sample. Variance,
-or second moment about the mean, is a measure of the variability (spread or
-dispersion) of data. A large variance indicates that the data is spread out;
-a small variance indicates it is clustered closely around the mean.
 
-.. function:: variance(data [, xbar])
+.. function:: variance(data, xbar=None)
 
-   Return the sample variance of *data*, an iterable of at least two
-   real-valued numbers.
+   Return the sample variance of *data*, an iterable of at least two real-valued
+   numbers.  Variance, or second moment about the mean, is a measure of the
+   variability (spread or dispersion) of data.  A large variance indicates that
+   the data is spread out; a small variance indicates it is clustered closely
+   around the mean.
 
-   If the optional second argument *xbar* is given, it should be the mean
-   of *data*. If it is missing or None (the default), the mean is
+   If the optional second argument *xbar* is given, it should be the mean of
+   *data*.  If it is missing or ``None`` (the default), the mean is
    automatically calculated.
 
-   Use this function when your data is a sample from a population. To
-   calculate the variance from the entire population, see :func:`pvariance`.
+   Use this function when your data is a sample from a population. To calculate
+   the variance from the entire population, see :func:`pvariance`.
+
+   Raises :exc:`StatisticsError` if *data* has fewer than two values.
 
    Examples:
 
@@ -410,8 +355,8 @@ a small variance indicates it is clustered closely around the mean.
       >>> variance(data)
       1.3720238095238095
 
-   If you have already calculated the mean of your data, you can pass
-   it as the optional second argument *xbar* to avoid recalculation:
+   If you have already calculated the mean of your data, you can pass it as the
+   optional second argument *xbar* to avoid recalculation:
 
    .. doctest::
 
@@ -419,8 +364,8 @@ a small variance indicates it is clustered closely around the mean.
       >>> variance(data, m)
       1.3720238095238095
 
-   This function does not attempt to verify that you have passed the actual
-   mean as *xbar*. Using arbitrary values for *xbar* can lead to invalid or
+   This function does not attempt to verify that you have passed the actual mean
+   as *xbar*.  Using arbitrary values for *xbar* can lead to invalid or
    impossible results.
 
    Decimal and Fraction values are supported:
@@ -437,17 +382,14 @@ a small variance indicates it is clustered closely around the mean.
 
    .. note::
 
-      This is the sample variance s² with Bessel's correction, also known
-      as variance with N-1 degrees of freedom. Provided that the data
-      points are representative (e.g. independent and identically
-      distributed), the result should be an unbiased estimate of the true
-      population variance.
-
-      If you somehow know the actual population mean μ you should pass it
-      to the :func:`pvariance` function as the *mu* parameter to get
-      the variance of a sample.
+      This is the sample variance s² with Bessel's correction, also known as
+      variance with N-1 degrees of freedom.  Provided that the data points are
+      representative (e.g. independent and identically distributed), the result
+      should be an unbiased estimate of the true population variance.
 
-   Raises :exc:`StatisticsError` if *data* has fewer than two values.
+      If you somehow know the actual population mean μ you should pass it to the
+      :func:`pvariance` function as the *mu* parameter to get the variance of a
+      sample.
 
 Exceptions
 ----------