diff options
Diffstat (limited to 'Doc/library/statistics.rst')
| -rw-r--r-- | Doc/library/statistics.rst | 43 |
1 files changed, 38 insertions, 5 deletions
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst index 7685621385..2aa778c4d0 100644 --- a/Doc/library/statistics.rst +++ b/Doc/library/statistics.rst @@ -39,6 +39,7 @@ or sample. ======================= ============================================= :func:`mean` Arithmetic mean ("average") of data. +:func:`harmonic_mean` Harmonic mean of data. :func:`median` Median (middle value) of data. :func:`median_low` Low median of data. :func:`median_high` High median of data. @@ -68,8 +69,7 @@ However, for reading convenience, most of the examples show sorted sequences. .. 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* which can be a sequence or iterator. 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 @@ -111,10 +111,43 @@ However, for reading convenience, most of the examples show sorted sequences. ``mean(data)`` is equivalent to calculating the true population mean μ. +.. function:: harmonic_mean(data) + + Return the harmonic mean of *data*, a sequence or iterator of + real-valued numbers. + + The harmonic mean, sometimes called the subcontrary mean, is the + reciprocal of the arithmetic :func:`mean` of the reciprocals of the + data. For example, the harmonic mean of three values *a*, *b* and *c* + will be equivalent to ``3/(1/a + 1/b + 1/c)``. + + The harmonic mean is a type of average, a measure of the central + location of the data. It is often appropriate when averaging quantities + which are rates or ratios, for example speeds. For example: + + Suppose an investor purchases an equal value of shares in each of + three companies, with P/E (price/earning) ratios of 2.5, 3 and 10. + What is the average P/E ratio for the investor's portfolio? + + .. doctest:: + + >>> harmonic_mean([2.5, 3, 10]) # For an equal investment portfolio. + 3.6 + + Using the arithmetic mean would give an average of about 5.167, which + is too high. + + :exc:`StatisticsError` is raised if *data* is empty, or any element + is less than zero. + + .. versionadded:: 3.6 + + .. function:: median(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. + *data* can be a sequence or iterator. 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 @@ -142,7 +175,7 @@ However, for reading convenience, most of the examples show sorted sequences. .. function:: median_low(data) Return the low median of numeric data. If *data* is empty, - :exc:`StatisticsError` is raised. + :exc:`StatisticsError` is raised. *data* can be a sequence or iterator. 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 @@ -162,7 +195,7 @@ However, for reading convenience, most of the examples show sorted sequences. .. function:: median_high(data) Return the high median of data. If *data* is empty, :exc:`StatisticsError` - is raised. + is raised. *data* can be a sequence or iterator. 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 @@ -183,7 +216,7 @@ However, for reading convenience, most of the examples show sorted sequences. Return the median of grouped continuous data, calculated as the 50th percentile, using interpolation. If *data* is empty, :exc:`StatisticsError` - is raised. + is raised. *data* can be a sequence or iterator. .. doctest:: |