bpo-35904: Add statistics.fmean() (GH-11892)

This commit is contained in:
Raymond Hettinger 2019-02-21 15:06:29 -08:00 committed by GitHub
parent f36f89257b
commit 47d9987247
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 104 additions and 3 deletions

View File

@ -404,7 +404,7 @@ with replacement to estimate a confidence interval for the mean of a sample of
size five::
# http://statistics.about.com/od/Applications/a/Example-Of-Bootstrapping.htm
from statistics import mean
from statistics import fmean as mean
from random import choices
data = 1, 2, 4, 4, 10
@ -419,7 +419,7 @@ to determine the statistical significance or `p-value
between the effects of a drug versus a placebo::
# Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson
from statistics import mean
from statistics import fmean as mean
from random import shuffle
drug = [54, 73, 53, 70, 73, 68, 52, 65, 65]

View File

@ -39,6 +39,7 @@ or sample.
======================= =============================================
:func:`mean` Arithmetic mean ("average") of data.
:func:`fmean` Fast, floating point arithmetic mean.
:func:`harmonic_mean` Harmonic mean of data.
:func:`median` Median (middle value) of data.
:func:`median_low` Low median of data.
@ -111,6 +112,23 @@ However, for reading convenience, most of the examples show sorted sequences.
``mean(data)`` is equivalent to calculating the true population mean μ.
.. function:: fmean(data)
Convert *data* to floats and compute the arithmetic mean.
This runs faster than the :func:`mean` function and it always returns a
:class:`float`. The result is highly accurate but not as perfect as
:func:`mean`. If the input dataset is empty, raises a
:exc:`StatisticsError`.
.. doctest::
>>> fmean([3.5, 4.0, 5.25])
4.25
.. versionadded:: 3.8
.. function:: harmonic_mean(data)
Return the harmonic mean of *data*, a sequence or iterator of

View File

@ -254,6 +254,15 @@ Added :attr:`SSLContext.post_handshake_auth` to enable and
post-handshake authentication.
(Contributed by Christian Heimes in :issue:`34670`.)
statistics
----------
Added :func:`statistics.fmean` as a faster, floating point variant of
:func:`statistics.mean()`. (Contributed by Raymond Hettinger and
Steven D'Aprano in :issue:`35904`.)
tokenize
--------

View File

@ -79,7 +79,7 @@ A single exception is defined: StatisticsError is a subclass of ValueError.
__all__ = [ 'StatisticsError',
'pstdev', 'pvariance', 'stdev', 'variance',
'median', 'median_low', 'median_high', 'median_grouped',
'mean', 'mode', 'harmonic_mean',
'mean', 'mode', 'harmonic_mean', 'fmean',
]
import collections
@ -312,6 +312,33 @@ def mean(data):
assert count == n
return _convert(total/n, T)
def fmean(data):
""" Convert data to floats and compute the arithmetic mean.
This runs faster than the mean() function and it always returns a float.
The result is highly accurate but not as perfect as mean().
If the input dataset is empty, it raises a StatisticsError.
>>> fmean([3.5, 4.0, 5.25])
4.25
"""
try:
n = len(data)
except TypeError:
# Handle iterators that do not define __len__().
n = 0
def count(x):
nonlocal n
n += 1
return x
total = math.fsum(map(count, data))
else:
total = math.fsum(data)
try:
return total / n
except ZeroDivisionError:
raise StatisticsError('fmean requires at least one data point') from None
def harmonic_mean(data):
"""Return the harmonic mean of data.

View File

@ -1810,6 +1810,51 @@ class TestMode(NumericTestCase, AverageMixin, UnivariateTypeMixin):
# counts, this should raise.
self.assertRaises(statistics.StatisticsError, self.func, data)
class TestFMean(unittest.TestCase):
def test_basics(self):
fmean = statistics.fmean
D = Decimal
F = Fraction
for data, expected_mean, kind in [
([3.5, 4.0, 5.25], 4.25, 'floats'),
([D('3.5'), D('4.0'), D('5.25')], 4.25, 'decimals'),
([F(7, 2), F(4, 1), F(21, 4)], 4.25, 'fractions'),
([True, False, True, True, False], 0.60, 'booleans'),
([3.5, 4, F(21, 4)], 4.25, 'mixed types'),
((3.5, 4.0, 5.25), 4.25, 'tuple'),
(iter([3.5, 4.0, 5.25]), 4.25, 'iterator'),
]:
actual_mean = fmean(data)
self.assertIs(type(actual_mean), float, kind)
self.assertEqual(actual_mean, expected_mean, kind)
def test_error_cases(self):
fmean = statistics.fmean
StatisticsError = statistics.StatisticsError
with self.assertRaises(StatisticsError):
fmean([]) # empty input
with self.assertRaises(StatisticsError):
fmean(iter([])) # empty iterator
with self.assertRaises(TypeError):
fmean(None) # non-iterable input
with self.assertRaises(TypeError):
fmean([10, None, 20]) # non-numeric input
with self.assertRaises(TypeError):
fmean() # missing data argument
with self.assertRaises(TypeError):
fmean([10, 20, 60], 70) # too many arguments
def test_special_values(self):
# Rules for special values are inherited from math.fsum()
fmean = statistics.fmean
NaN = float('Nan')
Inf = float('Inf')
self.assertTrue(math.isnan(fmean([10, NaN])), 'nan')
self.assertTrue(math.isnan(fmean([NaN, Inf])), 'nan and infinity')
self.assertTrue(math.isinf(fmean([10, Inf])), 'infinity')
with self.assertRaises(ValueError):
fmean([Inf, -Inf])
# === Tests for variances and standard deviations ===

View File

@ -0,0 +1,2 @@
Added statistics.fmean() as a faster, floating point variant of the existing
mean() function.