From eb2aeecc2f1fce4baea4e633768181d831bb1b33 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 21 Oct 2013 08:57:26 +0200 Subject: [PATCH] Reformat statistics.rst and remove unnecessary headings for each function. --- Doc/library/statistics.rst | 336 +++++++++++++++---------------------- 1 file changed, 139 insertions(+), 197 deletions(-) diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst index 463bcf41c6a..bd40b74c530 100644 --- a/Doc/library/statistics.rst +++ b/Doc/library/statistics.rst @@ -35,21 +35,34 @@ or sample. :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 @@ 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 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 @@ 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. + 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 @@ 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 `_. - * The `SSMEDIAN `_ - function in the Gnome Gnumeric spreadsheet, including - `this discussion `_. + * The `SSMEDIAN + `_ + function in the Gnome Gnumeric spreadsheet, including `this discussion + `_. - 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 ------------------- +.. 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 @@ 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. + 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 @@ 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. + 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 ----------