[Python-checkins] cpython: Reformat statistics.rst and remove unnecessary headings for each function.
georg.brandl
python-checkins at python.org
Mon Oct 21 08:56:35 CEST 2013
http://hg.python.org/cpython/rev/195dc7f303fe
changeset: 86541:195dc7f303fe
user: Georg Brandl <georg at python.org>
date: Mon Oct 21 08:57:26 2013 +0200
summary:
Reformat statistics.rst and remove unnecessary headings for each function.
files:
Doc/library/statistics.rst | 336 ++++++++++--------------
1 files changed, 139 insertions(+), 197 deletions(-)
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -35,21 +35,34 @@
:func:`mode` Mode (most common value) of discrete data.
======================= =============================================
-:func:`mean`
-~~~~~~~~~~~~
+Measures of spread
+------------------
-The :func:`mean` function calculates the arithmetic mean, commonly known
-as the average, of its iterable argument:
+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.
+======================= =============================================
+
+
+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 @@
.. 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 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 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 μ.
- If ``data`` is empty, :exc:`StatisticsError` will be raised.
-
-: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 @@
>>> 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 @@
>>> 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.
+ 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`
-~~~~~~~~~~~~~~~~~~~~~~
+.. function:: median_grouped(data, interval=1)
-The :func:`median_grouped` function calculates the median of grouped data
-as the 50th percentile, using interpolation.
-
-.. function:: median_grouped(data [, interval])
-
- 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 @@
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 @@
>>> 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
-------------------
+.. function:: pstdev(data, mu=None)
-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])
-
- 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=None)
-.. function:: pvariance(data [, mu])
+ 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.
- Return the population variance of *data*, a non-empty iterable of
- real-valued numbers.
-
- 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 @@
>>> 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 @@
>>> 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 @@
.. 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.
+ 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.
-:func:`stdev`
-~~~~~~~~~~~~~~
+.. function:: stdev(data, xbar=None)
-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])
-
- 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=None)
-.. function:: variance(data [, xbar])
+ 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.
- Return the sample variance of *data*, an iterable of at least two
- real-valued numbers.
-
- 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 @@
>>> 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 @@
>>> 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 @@
.. 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.
+ 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.
-
- 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
----------
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list