bpo-38308: Add optional weighting to statistics.harmonic_mean() (GH-23914)
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 @@
.. 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 @@
>>> 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 @@
.. versionadded:: 3.6
+ .. versionchanged:: 3.8
+ Added support for *weights*.
.. function:: median(data)