cpython-lru_cache-weakref: Lib/statistics.py annotate

annotate Lib/statistics.py @ 87690:66c1c9f32567 default tip

Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859

author	Radomir Dopieralski <devel@sheep.art.pl>
date	Tue, 03 Dec 2013 16:02:48 +0100
parents	16357a6786cb
children

rev	line source
86489 685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	1 ## Module statistics.py
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	2 ##
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	3 ## Copyright (c) 2013 Steven D'Aprano <steve+python@pearwood.info>.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	4 ##
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	5 ## Licensed under the Apache License, Version 2.0 (the "License");
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	6 ## you may not use this file except in compliance with the License.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	7 ## You may obtain a copy of the License at
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	8 ##
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	9 ## http://www.apache.org/licenses/LICENSE-2.0
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	10 ##
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	11 ## Unless required by applicable law or agreed to in writing, software
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	12 ## distributed under the License is distributed on an "AS IS" BASIS,
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	13 ## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	14 ## See the License for the specific language governing permissions and
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	15 ## limitations under the License.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	16
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	17
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	18 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	19 Basic statistics module.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	20
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	21 This module provides functions for calculating statistics of data, including
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	22 averages, variance, and standard deviation.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	23
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	24 Calculating averages
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	25 --------------------
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	26
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	27 ================== =============================================
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	28 Function Description
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	29 ================== =============================================
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	30 mean Arithmetic mean (average) of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	31 median Median (middle value) of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	32 median_low Low median of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	33 median_high High median of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	34 median_grouped Median, or 50th percentile, of grouped data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	35 mode Mode (most common value) of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	36 ================== =============================================
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	37
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	38 Calculate the arithmetic mean ("the average") of data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	39
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	40 >>> mean([-1.0, 2.5, 3.25, 5.75])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	41 2.625
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	42
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	43
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	44 Calculate the standard median of discrete data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	45
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	46 >>> median([2, 3, 4, 5])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	47 3.5
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	48
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	49
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	50 Calculate the median, or 50th percentile, of data grouped into class intervals
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	51 centred on the data values provided. E.g. if your data points are rounded to
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	52 the nearest whole number:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	53
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	54 >>> median_grouped([2, 2, 3, 3, 3, 4]) #doctest: +ELLIPSIS
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	55 2.8333333333...
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	56
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	57 This should be interpreted in this way: you have two data points in the class
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	58 interval 1.5-2.5, three data points in the class interval 2.5-3.5, and one in
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	59 the class interval 3.5-4.5. The median of these data points is 2.8333...
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	60
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	61
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	62 Calculating variability or spread
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	63 ---------------------------------
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	64
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	65 ================== =============================================
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	66 Function Description
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	67 ================== =============================================
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	68 pvariance Population variance of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	69 variance Sample variance of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	70 pstdev Population standard deviation of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	71 stdev Sample standard deviation of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	72 ================== =============================================
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	73
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	74 Calculate the standard deviation of sample data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	75
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	76 >>> stdev([2.5, 3.25, 5.5, 11.25, 11.75]) #doctest: +ELLIPSIS
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	77 4.38961843444...
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	78
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	79 If you have previously calculated the mean, you can pass it as the optional
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	80 second argument to the four "spread" functions to avoid recalculating it:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	81
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	82 >>> data = [1, 2, 2, 4, 4, 4, 5, 6]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	83 >>> mu = mean(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	84 >>> pvariance(data, mu)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	85 2.5
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	86
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	87
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	88 Exceptions
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	89 ----------
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	90
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	91 A single exception is defined: StatisticsError is a subclass of ValueError.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	92
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	93 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	94
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	95 __all__ = [ 'StatisticsError',
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	96 'pstdev', 'pvariance', 'stdev', 'variance',
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	97 'median', 'median_low', 'median_high', 'median_grouped',
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	98 'mean', 'mode',
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	99 ]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	100
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	101
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	102 import collections
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	103 import math
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	104
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	105 from fractions import Fraction
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	106 from decimal import Decimal
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	107
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	108
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	109 # === Exceptions ===
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	110
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	111 class StatisticsError(ValueError):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	112 pass
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	113
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	114
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	115 # === Private utilities ===
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	116
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	117 def _sum(data, start=0):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	118 """_sum(data [, start]) -> value
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	119
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	120 Return a high-precision sum of the given numeric data. If optional
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	121 argument ``start`` is given, it is added to the total. If ``data`` is
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	122 empty, ``start`` (defaulting to 0) is returned.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	123
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	124
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	125 Examples
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	126 --------
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	127
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	128 >>> _sum([3, 2.25, 4.5, -0.5, 1.0], 0.75)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	129 11.0
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	130
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	131 Some sources of round-off error will be avoided:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	132
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	133 >>> _sum([1e50, 1, -1e50] * 1000) # Built-in sum returns zero.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	134 1000.0
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	135
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	136 Fractions and Decimals are also supported:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	137
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	138 >>> from fractions import Fraction as F
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	139 >>> _sum([F(2, 3), F(7, 5), F(1, 4), F(5, 6)])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	140 Fraction(63, 20)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	141
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	142 >>> from decimal import Decimal as D
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	143 >>> data = [D("0.1375"), D("0.2108"), D("0.3061"), D("0.0419")]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	144 >>> _sum(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	145 Decimal('0.6963')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	146
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	147 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	148 n, d = _exact_ratio(start)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	149 T = type(start)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	150 partials = {d: n} # map {denominator: sum of numerators}
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	151 # Micro-optimizations.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	152 coerce_types = _coerce_types
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	153 exact_ratio = _exact_ratio
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	154 partials_get = partials.get
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	155 # Add numerators for each denominator, and track the "current" type.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	156 for x in data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	157 T = _coerce_types(T, type(x))
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	158 n, d = exact_ratio(x)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	159 partials[d] = partials_get(d, 0) + n
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	160 if None in partials:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	161 assert issubclass(T, (float, Decimal))
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	162 assert not math.isfinite(partials[None])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	163 return T(partials[None])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	164 total = Fraction()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	165 for d, n in sorted(partials.items()):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	166 total += Fraction(n, d)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	167 if issubclass(T, int):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	168 assert total.denominator == 1
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	169 return T(total.numerator)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	170 if issubclass(T, Decimal):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	171 return T(total.numerator)/total.denominator
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	172 return T(total)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	173
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	174
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	175 def _exact_ratio(x):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	176 """Convert Real number x exactly to (numerator, denominator) pair.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	177
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	178 >>> _exact_ratio(0.25)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	179 (1, 4)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	180
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	181 x is expected to be an int, Fraction, Decimal or float.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	182 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	183 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	184 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	185 # int, Fraction
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	186 return (x.numerator, x.denominator)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	187 except AttributeError:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	188 # float
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	189 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	190 return x.as_integer_ratio()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	191 except AttributeError:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	192 # Decimal
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	193 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	194 return _decimal_to_ratio(x)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	195 except AttributeError:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	196 msg = "can't convert type '{}' to numerator/denominator"
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	197 raise TypeError(msg.format(type(x).__name__)) from None
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	198 except (OverflowError, ValueError):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	199 # INF or NAN
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	200 if __debug__:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	201 # Decimal signalling NANs cannot be converted to float :-(
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	202 if isinstance(x, Decimal):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	203 assert not x.is_finite()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	204 else:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	205 assert not math.isfinite(x)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	206 return (x, None)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	207
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	208
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	209 # FIXME This is faster than Fraction.from_decimal, but still too slow.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	210 def _decimal_to_ratio(d):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	211 """Convert Decimal d to exact integer ratio (numerator, denominator).
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	212
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	213 >>> from decimal import Decimal
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	214 >>> _decimal_to_ratio(Decimal("2.6"))
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	215 (26, 10)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	216
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	217 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	218 sign, digits, exp = d.as_tuple()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	219 if exp in ('F', 'n', 'N'): # INF, NAN, sNAN
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	220 assert not d.is_finite()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	221 raise ValueError
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	222 num = 0
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	223 for digit in digits:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	224 num = num*10 + digit
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	225 if sign:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	226 num = -num
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	227 den = 10**-exp
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	228 return (num, den)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	229
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	230
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	231 def _coerce_types(T1, T2):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	232 """Coerce types T1 and T2 to a common type.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	233
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	234 >>> _coerce_types(int, float)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	235 <class 'float'>
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	236
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	237 Coercion is performed according to this table, where "N/A" means
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	238 that a TypeError exception is raised.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	239
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	240 +----------+-----------+-----------+-----------+----------+
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	241 \| \| int \| Fraction \| Decimal \| float \|
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	242 +----------+-----------+-----------+-----------+----------+
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	243 \| int \| int \| Fraction \| Decimal \| float \|
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	244 \| Fraction \| Fraction \| Fraction \| N/A \| float \|
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	245 \| Decimal \| Decimal \| N/A \| Decimal \| float \|
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	246 \| float \| float \| float \| float \| float \|
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	247 +----------+-----------+-----------+-----------+----------+
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	248
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	249 Subclasses trump their parent class; two subclasses of the same
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	250 base class will be coerced to the second of the two.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	251
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	252 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	253 # Get the common/fast cases out of the way first.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	254 if T1 is T2: return T1
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	255 if T1 is int: return T2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	256 if T2 is int: return T1
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	257 # Subclasses trump their parent class.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	258 if issubclass(T2, T1): return T2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	259 if issubclass(T1, T2): return T1
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	260 # Floats trump everything else.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	261 if issubclass(T2, float): return T2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	262 if issubclass(T1, float): return T1
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	263 # Subclasses of the same base class give priority to the second.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	264 if T1.__base__ is T2.__base__: return T2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	265 # Otherwise, just give up.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	266 raise TypeError('cannot coerce types %r and %r' % (T1, T2))
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	267
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	268
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	269 def _counts(data):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	270 # Generate a table of sorted (value, frequency) pairs.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	271 if data is None:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	272 raise TypeError('None is not iterable')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	273 table = collections.Counter(data).most_common()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	274 if not table:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	275 return table
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	276 # Extract the values with the highest frequency.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	277 maxfreq = table[0][1]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	278 for i in range(1, len(table)):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	279 if table[i][1] != maxfreq:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	280 table = table[:i]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	281 break
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	282 return table
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	283
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	284
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	285 # === Measures of central tendency (averages) ===
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	286
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	287 def mean(data):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	288 """Return the sample arithmetic mean of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	289
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	290 >>> mean([1, 2, 3, 4, 4])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	291 2.8
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	292
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	293 >>> from fractions import Fraction as F
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	294 >>> mean([F(3, 7), F(1, 21), F(5, 3), F(1, 3)])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	295 Fraction(13, 21)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	296
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	297 >>> from decimal import Decimal as D
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	298 >>> mean([D("0.5"), D("0.75"), D("0.625"), D("0.375")])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	299 Decimal('0.5625')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	300
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	301 If ``data`` is empty, StatisticsError will be raised.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	302 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	303 if iter(data) is data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	304 data = list(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	305 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	306 if n < 1:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	307 raise StatisticsError('mean requires at least one data point')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	308 return _sum(data)/n
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	309
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	310
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	311 # FIXME: investigate ways to calculate medians without sorting? Quickselect?
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	312 def median(data):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	313 """Return the median (middle value) of numeric data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	314
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	315 When the number of data points is odd, return the middle data point.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	316 When the number of data points is even, the median is interpolated by
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	317 taking the average of the two middle values:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	318
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	319 >>> median([1, 3, 5])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	320 3
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	321 >>> median([1, 3, 5, 7])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	322 4.0
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	323
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	324 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	325 data = sorted(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	326 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	327 if n == 0:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	328 raise StatisticsError("no median for empty data")
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	329 if n%2 == 1:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	330 return data[n//2]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	331 else:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	332 i = n//2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	333 return (data[i - 1] + data[i])/2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	334
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	335
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	336 def median_low(data):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	337 """Return the low median of numeric data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	338
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	339 When the number of data points is odd, the middle value is returned.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	340 When it is even, the smaller of the two middle values is returned.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	341
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	342 >>> median_low([1, 3, 5])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	343 3
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	344 >>> median_low([1, 3, 5, 7])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	345 3
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	346
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	347 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	348 data = sorted(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	349 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	350 if n == 0:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	351 raise StatisticsError("no median for empty data")
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	352 if n%2 == 1:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	353 return data[n//2]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	354 else:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	355 return data[n//2 - 1]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	356
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	357
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	358 def median_high(data):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	359 """Return the high median of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	360
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	361 When the number of data points is odd, the middle value is returned.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	362 When it is even, the larger of the two middle values is returned.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	363
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	364 >>> median_high([1, 3, 5])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	365 3
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	366 >>> median_high([1, 3, 5, 7])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	367 5
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	368
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	369 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	370 data = sorted(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	371 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	372 if n == 0:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	373 raise StatisticsError("no median for empty data")
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	374 return data[n//2]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	375
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	376
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	377 def median_grouped(data, interval=1):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	378 """"Return the 50th percentile (median) of grouped continuous data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	379
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	380 >>> median_grouped([1, 2, 2, 3, 4, 4, 4, 4, 4, 5])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	381 3.7
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	382 >>> median_grouped([52, 52, 53, 54])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	383 52.5
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	384
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	385 This calculates the median as the 50th percentile, and should be
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	386 used when your data is continuous and grouped. In the above example,
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	387 the values 1, 2, 3, etc. actually represent the midpoint of classes
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	388 0.5-1.5, 1.5-2.5, 2.5-3.5, etc. The middle value falls somewhere in
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	389 class 3.5-4.5, and interpolation is used to estimate it.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	390
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	391 Optional argument ``interval`` represents the class interval, and
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	392 defaults to 1. Changing the class interval naturally will change the
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	393 interpolated 50th percentile value:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	394
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	395 >>> median_grouped([1, 3, 3, 5, 7], interval=1)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	396 3.25
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	397 >>> median_grouped([1, 3, 3, 5, 7], interval=2)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	398 3.5
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	399
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	400 This function does not check whether the data points are at least
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	401 ``interval`` apart.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	402 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	403 data = sorted(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	404 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	405 if n == 0:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	406 raise StatisticsError("no median for empty data")
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	407 elif n == 1:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	408 return data[0]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	409 # Find the value at the midpoint. Remember this corresponds to the
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	410 # centre of the class interval.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	411 x = data[n//2]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	412 for obj in (x, interval):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	413 if isinstance(obj, (str, bytes)):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	414 raise TypeError('expected number but got %r' % obj)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	415 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	416 L = x - interval/2 # The lower limit of the median interval.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	417 except TypeError:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	418 # Mixed type. For now we just coerce to float.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	419 L = float(x) - float(interval)/2
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	420 cf = data.index(x) # Number of values below the median interval.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	421 # FIXME The following line could be more efficient for big lists.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	422 f = data.count(x) # Number of data points in the median interval.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	423 return L + interval*(n/2 - cf)/f
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	424
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	425
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	426 def mode(data):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	427 """Return the most common data point from discrete or nominal data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	428
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	429 ``mode`` assumes discrete data, and returns a single value. This is the
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	430 standard treatment of the mode as commonly taught in schools:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	431
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	432 >>> mode([1, 1, 2, 3, 3, 3, 3, 4])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	433 3
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	434
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	435 This also works with nominal (non-numeric) data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	436
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	437 >>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	438 'red'
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	439
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	440 If there is not exactly one most common value, ``mode`` will raise
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	441 StatisticsError.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	442 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	443 # Generate a table of sorted (value, frequency) pairs.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	444 table = _counts(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	445 if len(table) == 1:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	446 return table[0][0]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	447 elif table:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	448 raise StatisticsError(
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	449 'no unique mode; found %d equally common values' % len(table)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	450 )
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	451 else:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	452 raise StatisticsError('no mode for empty data')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	453
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	454
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	455 # === Measures of spread ===
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	456
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	457 # See http://mathworld.wolfram.com/Variance.html
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	458 # http://mathworld.wolfram.com/SampleVariance.html
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	459 # http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	460 #
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	461 # Under no circumstances use the so-called "computational formula for
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	462 # variance", as that is only suitable for hand calculations with a small
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	463 # amount of low-precision data. It has terrible numeric properties.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	464 #
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	465 # See a comparison of three computational methods here:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	466 # http://www.johndcook.com/blog/2008/09/26/comparing-three-methods-of-computing-standard-deviation/
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	467
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	468 def _ss(data, c=None):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	469 """Return sum of square deviations of sequence data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	470
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	471 If ``c`` is None, the mean is calculated in one pass, and the deviations
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	472 from the mean are calculated in a second pass. Otherwise, deviations are
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	473 calculated from ``c`` as given. Use the second case with care, as it can
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	474 lead to garbage results.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	475 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	476 if c is None:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	477 c = mean(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	478 ss = _sum((x-c)**2 for x in data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	479 # The following sum should mathematically equal zero, but due to rounding
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	480 # error may not.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	481 ss -= _sum((x-c) for x in data)**2/len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	482 assert not ss < 0, 'negative sum of square deviations: %f' % ss
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	483 return ss
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	484
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	485
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	486 def variance(data, xbar=None):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	487 """Return the sample variance of data.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	488
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	489 data should be an iterable of Real-valued numbers, with at least two
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	490 values. The optional argument xbar, if given, should be the mean of
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	491 the data. If it is missing or None, the mean is automatically calculated.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	492
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	493 Use this function when your data is a sample from a population. To
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	494 calculate the variance from the entire population, see ``pvariance``.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	495
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	496 Examples:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	497
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	498 >>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	499 >>> variance(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	500 1.3720238095238095
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	501
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	502 If you have already calculated the mean of your data, you can pass it as
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	503 the optional second argument ``xbar`` to avoid recalculating it:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	504
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	505 >>> m = mean(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	506 >>> variance(data, m)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	507 1.3720238095238095
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	508
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	509 This function does not check that ``xbar`` is actually the mean of
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	510 ``data``. Giving arbitrary values for ``xbar`` may lead to invalid or
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	511 impossible results.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	512
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	513 Decimals and Fractions are supported:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	514
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	515 >>> from decimal import Decimal as D
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	516 >>> variance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	517 Decimal('31.01875')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	518
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	519 >>> from fractions import Fraction as F
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	520 >>> variance([F(1, 6), F(1, 2), F(5, 3)])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	521 Fraction(67, 108)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	522
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	523 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	524 if iter(data) is data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	525 data = list(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	526 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	527 if n < 2:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	528 raise StatisticsError('variance requires at least two data points')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	529 ss = _ss(data, xbar)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	530 return ss/(n-1)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	531
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	532
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	533 def pvariance(data, mu=None):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	534 """Return the population variance of ``data``.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	535
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	536 data should be an iterable of Real-valued numbers, with at least one
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	537 value. The optional argument mu, if given, should be the mean of
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	538 the data. If it is missing or None, the mean is automatically calculated.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	539
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	540 Use this function to calculate the variance from the entire population.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	541 To estimate the variance from a sample, the ``variance`` function is
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	542 usually a better choice.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	543
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	544 Examples:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	545
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	546 >>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	547 >>> pvariance(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	548 1.25
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	549
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	550 If you have already calculated the mean of the data, you can pass it as
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	551 the optional second argument to avoid recalculating it:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	552
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	553 >>> mu = mean(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	554 >>> pvariance(data, mu)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	555 1.25
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	556
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	557 This function does not check that ``mu`` is actually the mean of ``data``.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	558 Giving arbitrary values for ``mu`` may lead to invalid or impossible
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	559 results.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	560
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	561 Decimals and Fractions are supported:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	562
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	563 >>> from decimal import Decimal as D
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	564 >>> pvariance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	565 Decimal('24.815')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	566
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	567 >>> from fractions import Fraction as F
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	568 >>> pvariance([F(1, 4), F(5, 4), F(1, 2)])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	569 Fraction(13, 72)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	570
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	571 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	572 if iter(data) is data:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	573 data = list(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	574 n = len(data)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	575 if n < 1:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	576 raise StatisticsError('pvariance requires at least one data point')
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	577 ss = _ss(data, mu)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	578 return ss/n
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	579
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	580
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	581 def stdev(data, xbar=None):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	582 """Return the square root of the sample variance.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	583
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	584 See ``variance`` for arguments and other details.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	585
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	586 >>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	587 1.0810874155219827
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	588
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	589 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	590 var = variance(data, xbar)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	591 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	592 return var.sqrt()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	593 except AttributeError:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	594 return math.sqrt(var)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	595
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	596
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	597 def pstdev(data, mu=None):
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	598 """Return the square root of the population variance.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	599
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	600 See ``pvariance`` for arguments and other details.
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	601
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	602 >>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	603 0.986893273527251
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	604
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	605 """
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	606 var = pvariance(data, mu)
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	607 try:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	608 return var.sqrt()
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	609 except AttributeError:
685e044bed5e Issue #18606: Add the new "statistics" module (PEP 450). Contributed Larry Hastings <larry@hastings.org> parents: diff changeset	610 return math.sqrt(var)

Mercurial > cpython-lru_cache-weakref

annotate Lib/statistics.py @ 87690:66c1c9f32567 default tip