diff options
| author | Raymond Hettinger <rhettinger@users.noreply.github.com> | 2020-12-24 03:52:09 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2020-12-24 03:52:09 (GMT) |
| commit | cc3467a57b61b0e7ef254b36790a1c44b13f2228 (patch) | |
| tree | fc06989e28174a8421e4c191186ccf9b8ee9fba0 /Doc/library/statistics.rst | |
| parent | 6dd3da3cf4a0d6cb62d9c2a155434c127183454d (diff) | |
| download | cpython-cc3467a57b61b0e7ef254b36790a1c44b13f2228.zip cpython-cc3467a57b61b0e7ef254b36790a1c44b13f2228.tar.gz cpython-cc3467a57b61b0e7ef254b36790a1c44b13f2228.tar.bz2 | |
bpo-38308: Add optional weighting to statistics.harmonic_mean() (GH-23914)
Diffstat (limited to 'Doc/library/statistics.rst')
| -rw-r--r-- | Doc/library/statistics.rst | 21 |
1 files changed, 12 insertions, 9 deletions
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst index 38a499a..6467704 100644 --- a/Doc/library/statistics.rst +++ b/Doc/library/statistics.rst @@ -156,10 +156,11 @@ However, for reading convenience, most of the examples show sorted sequences. .. versionadded:: 3.8 -.. function:: harmonic_mean(data) +.. function:: harmonic_mean(data, weights=None) Return the harmonic mean of *data*, a sequence or iterable of - real-valued numbers. + real-valued numbers. If *weights* is omitted or *None*, then + equal weighting is assumed. The harmonic mean, sometimes called the subcontrary mean, is the reciprocal of the arithmetic :func:`mean` of the reciprocals of the @@ -179,17 +180,17 @@ However, for reading convenience, most of the examples show sorted sequences. >>> harmonic_mean([40, 60]) 48.0 - 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? + Suppose a car travels 40 km/hr for 5 km, and when traffic clears, + speeds-up to 60 km/hr for the remaining 30 km of the journey. What + is the average speed? .. doctest:: - >>> harmonic_mean([2.5, 3, 10]) # For an equal investment portfolio. - 3.6 + >>> harmonic_mean([40, 60], weights=[5, 30]) + 56.0 - :exc:`StatisticsError` is raised if *data* is empty, or any element - is less than zero. + :exc:`StatisticsError` is raised if *data* is empty, any element + is less than zero, or if the weighted sum isn't positive. The current algorithm has an early-out when it encounters a zero in the input. This means that the subsequent inputs are not tested @@ -197,6 +198,8 @@ However, for reading convenience, most of the examples show sorted sequences. .. versionadded:: 3.6 + .. versionchanged:: 3.8 + Added support for *weights*. .. function:: median(data) |