Averages and measures of central location¶

These functions calculate an average or typical value from a populationor sample.

Measures of spread¶

These functions calculate a measure of how much the population or sampletends to deviate from the typical or average values.

Function details¶

Note: The functions do not require the data given to them to be sorted.However, for reading convenience, most of the examples show sorted sequences.

statistics.mean(data)¶

Return the sample arithmetic mean ofdata which can be a sequence or iterable.

The arithmetic mean is the sum of the data divided by the number of datapoints. It is commonly called “the average”, although it is only one of manydifferent mathematical averages. It is a measure of the central location ofthe data.

Ifdata is empty,StatisticsError will be raised.

Some examples of use:

>>>mean([1,2,3,4,4])2.8>>>mean([-1.0,2.5,3.25,5.75])2.625>>>fromfractionsimportFractionasF>>>mean([F(3,7),F(1,21),F(5,3),F(1,3)])Fraction(13, 21)>>>fromdecimalimportDecimalasD>>>mean([D("0.5"),D("0.75"),D("0.625"),D("0.375")])Decimal('0.5625')

Note

The mean is strongly affected by outliers and is not a robust estimatorfor central location: the mean is not necessarily a typical example ofthe data points. For more robust measures of central location, seemedian() andmode().

The sample mean gives an unbiased estimate of the true population mean,so that when taken on average over all the possible samples,mean(sample) converges on the true mean of the entire population. Ifdata represents the entire population rather than a sample, thenmean(data) is equivalent to calculating the true population mean μ.

statistics.fmean(data)¶

Convertdata to floats and compute the arithmetic mean.

This runs faster than themean() function and it always returns afloat. Thedata may be a sequence or iterable. If the inputdataset is empty, raises aStatisticsError.

>>>fmean([3.5,4.0,5.25])4.25

New in version 3.8.

statistics.geometric_mean(data)¶

Convertdata to floats and compute the geometric mean.

The geometric mean indicates the central tendency or typical value of thedata using the product of the values (as opposed to the arithmetic meanwhich uses their sum).

Raises aStatisticsError if the input dataset is empty,if it contains a zero, or if it contains a negative value.Thedata may be a sequence or iterable.

No special efforts are made to achieve exact results.(However, this may change in the future.)

>>>round(geometric_mean([54,24,36]),1)36.0

New in version 3.8.

statistics.harmonic_mean(data)¶

Return the harmonic mean ofdata, a sequence or iterable ofreal-valued numbers.

The harmonic mean, sometimes called the subcontrary mean, is thereciprocal of the arithmeticmean() of the reciprocals of thedata. For example, the harmonic mean of three valuesa,b andcwill be equivalent to3/(1/a+1/b+1/c). If one of the valuesis zero, the result will be zero.

The harmonic mean is a type of average, a measure of the centrallocation of the data. It is often appropriate when averagingrates or ratios, for example speeds.

Suppose a car travels 10 km at 40 km/hr, then another 10 km at 60 km/hr.What is the average speed?

>>>harmonic_mean([40,60])48.0

Suppose an investor purchases an equal value of shares in each ofthree companies, with P/E (price/earning) ratios of 2.5, 3 and 10.What is the average P/E ratio for the investor’s portfolio?

>>>harmonic_mean([2.5,3,10])# For an equal investment portfolio.3.6

StatisticsError is raised ifdata is empty, or any elementis less than zero.

The current algorithm has an early-out when it encounters a zeroin the input. This means that the subsequent inputs are not testedfor validity. (This behavior may change in the future.)

New in version 3.6.

statistics.median(data)¶

Return the median (middle value) of numeric data, using the common “mean ofmiddle two” method. Ifdata is empty,StatisticsError is raised.data can be a sequence or iterable.

The median is a robust measure of central location and is less affected bythe presence of outliers. When the number of data points is odd, themiddle data point is returned:

>>>median([1,3,5])3

When the number of data points is even, the median is interpolated by takingthe average of the two middle values:

>>>median([1,3,5,7])4.0

This is suited for when your data is discrete, and you don’t mind that themedian may not be an actual data point.

If the data is ordinal (supports order operations) but not numeric (doesn’tsupport addition), consider usingmedian_low() ormedian_high()instead.

statistics.median_low(data)¶

Return the low median of numeric data. Ifdata is empty,StatisticsError is raised.data can be a sequence or iterable.

The low median is always a member of the data set. When the number of datapoints is odd, the middle value is returned. When it is even, the smaller ofthe two middle values is returned.

>>>median_low([1,3,5])3>>>median_low([1,3,5,7])3

Use the low median when your data are discrete and you prefer the median tobe an actual data point rather than interpolated.

statistics.median_high(data)¶

Return the high median of data. Ifdata is empty,StatisticsErroris raised.data can be a sequence or iterable.

The high median is always a member of the data set. When the number of datapoints is odd, the middle value is returned. When it is even, the larger ofthe two middle values is returned.

>>>median_high([1,3,5])3>>>median_high([1,3,5,7])5

Use the high median when your data are discrete and you prefer the median tobe an actual data point rather than interpolated.

statistics.median_grouped(data,interval=1)¶

Return the median of grouped continuous data, calculated as the 50thpercentile, using interpolation. Ifdata is empty,StatisticsErroris raised.data can be a sequence or iterable.

>>>median_grouped([52,52,53,54])52.5

In the following example, the data are rounded, so that each value representsthe midpoint of data classes, e.g. 1 is the midpoint of the class 0.5–1.5, 2is the midpoint of 1.5–2.5, 3 is the midpoint of 2.5–3.5, etc. With the datagiven, the middle value falls somewhere in the class 3.5–4.5, andinterpolation is used to estimate it:

>>>median_grouped([1,2,2,3,4,4,4,4,4,5])3.7

Optional argumentinterval represents the class interval, and defaultsto 1. Changing the class interval naturally will change the interpolation:

>>>median_grouped([1,3,3,5,7],interval=1)3.25>>>median_grouped([1,3,3,5,7],interval=2)3.5

This function does not check whether the data points are at leastinterval apart.

CPython implementation detail: Under some circumstances,median_grouped() may coerce data points tofloats. This behaviour is likely to change in the future.

See also

• “Statistics for the Behavioral Sciences”, Frederick J Gravetter andLarry B Wallnau (8th Edition).

• TheSSMEDIANfunction in the Gnome Gnumeric spreadsheet, includingthis discussion.

statistics.mode(data)¶

Return the single most common data point from discrete or nominaldata.The mode (when it exists) is the most typical value and serves as ameasure of central location.

If there are multiple modes with the same frequency, returns the first oneencountered in thedata. If the smallest or largest of those isdesired instead, usemin(multimode(data)) ormax(multimode(data)).If the inputdata is empty,StatisticsError is raised.

mode assumes discrete data and returns a single value. This is thestandard treatment of the mode as commonly taught in schools:

>>>mode([1,1,2,3,3,3,3,4])3

The mode is unique in that it is the only statistic in this package thatalso applies to nominal (non-numeric) data:

>>>mode(["red","blue","blue","red","green","red","red"])'red'

Changed in version 3.8:Now handles multimodal datasets by returning the first mode encountered.Formerly, it raisedStatisticsError when more than one mode wasfound.

statistics.multimode(data)¶

Return a list of the most frequently occurring values in the order theywere first encountered in thedata. Will return more than one result ifthere are multiple modes or an empty list if thedata is empty:

>>>multimode('aabbbbccddddeeffffgg')['b', 'd', 'f']>>>multimode('')[]

New in version 3.8.

statistics.pstdev(data,mu=None)¶

Return the population standard deviation (the square root of the populationvariance). Seepvariance() for arguments and other details.

>>>pstdev([1.5,2.5,2.5,2.75,3.25,4.75])0.986893273527251

statistics.pvariance(data,mu=None)¶

Return the population variance ofdata, a non-empty sequence or iterableof real-valued numbers. Variance, or second moment about the mean, is ameasure of the variability (spread or dispersion) of data. A largevariance indicates that the data is spread out; a small variance indicatesit is clustered closely around the mean.

If the optional second argumentmu is given, it is typically the mean ofthedata. It can also be used to compute the second moment around apoint that is not the mean. If it is missing orNone (the default),the arithmetic mean is automatically calculated.

Use this function to calculate the variance from the entire population. Toestimate the variance from a sample, thevariance() function is usuallya better choice.

RaisesStatisticsError ifdata is empty.

Examples:

>>>data=[0.0,0.25,0.25,1.25,1.5,1.75,2.75,3.25]>>>pvariance(data)1.25

If you have already calculated the mean of your data, you can pass it as theoptional second argumentmu to avoid recalculation:

>>>mu=mean(data)>>>pvariance(data,mu)1.25

Decimals and Fractions are supported:

>>>fromdecimalimportDecimalasD>>>pvariance([D("27.5"),D("30.25"),D("30.25"),D("34.5"),D("41.75")])Decimal('24.815')>>>fromfractionsimportFractionasF>>>pvariance([F(1,4),F(5,4),F(1,2)])Fraction(13, 72)

Note

When called with the entire population, this gives the population varianceσ². When called on a sample instead, this is the biased sample variances², also known as variance with N degrees of freedom.

If you somehow know the true population mean μ, you may use thisfunction to calculate the variance of a sample, giving the knownpopulation mean as the second argument. Provided the data points are arandom sample of the population, the result will be an unbiased estimateof the population variance.

statistics.stdev(data,xbar=None)¶

Return the sample standard deviation (the square root of the samplevariance). Seevariance() for arguments and other details.

>>>stdev([1.5,2.5,2.5,2.75,3.25,4.75])1.0810874155219827

statistics.variance(data,xbar=None)¶

Return the sample variance ofdata, an iterable of at least two real-valuednumbers. Variance, or second moment about the mean, is a measure of thevariability (spread or dispersion) of data. A large variance indicates thatthe data is spread out; a small variance indicates it is clustered closelyaround the mean.

If the optional second argumentxbar is given, it should be the mean ofdata. If it is missing orNone (the default), the mean isautomatically calculated.

Use this function when your data is a sample from a population. To calculatethe variance from the entire population, seepvariance().

RaisesStatisticsError ifdata has fewer than two values.

Examples:

>>>data=[2.75,1.75,1.25,0.25,0.5,1.25,3.5]>>>variance(data)1.3720238095238095

If you have already calculated the mean of your data, you can pass it as theoptional second argumentxbar to avoid recalculation:

>>>m=mean(data)>>>variance(data,m)1.3720238095238095

This function does not attempt to verify that you have passed the actual meanasxbar. Using arbitrary values forxbar can lead to invalid orimpossible results.

Decimal and Fraction values are supported:

>>>fromdecimalimportDecimalasD>>>variance([D("27.5"),D("30.25"),D("30.25"),D("34.5"),D("41.75")])Decimal('31.01875')>>>fromfractionsimportFractionasF>>>variance([F(1,6),F(1,2),F(5,3)])Fraction(67, 108)

Note

This is the sample variance s² with Bessel’s correction, also known asvariance with N-1 degrees of freedom. Provided that the data points arerepresentative (e.g. independent and identically distributed), the resultshould be an unbiased estimate of the true population variance.

If you somehow know the actual population mean μ you should pass it to thepvariance() function as themu parameter to get the variance of asample.

statistics.quantiles(data,*,n=4,method='exclusive')¶

Dividedata inton continuous intervals with equal probability.Returns a list ofn-1 cut points separating the intervals.

Setn to 4 for quartiles (the default). Setn to 10 for deciles. Setn to 100 for percentiles which gives the 99 cuts points that separatedata into 100 equal sized groups. RaisesStatisticsError ifnis not least 1.

Thedata can be any iterable containing sample data. For meaningfulresults, the number of data points indata should be larger thann.RaisesStatisticsError if there are not at least two data points.

The cut points are linearly interpolated from thetwo nearest data points. For example, if a cut point falls one-thirdof the distance between two sample values,100 and112, thecut-point will evaluate to104.

Themethod for computing quantiles can be varied depending onwhether thedata includes or excludes the lowest andhighest possible values from the population.

The defaultmethod is “exclusive” and is used for data sampled froma population that can have more extreme values than found in thesamples. The portion of the population falling below thei-th ofm sorted data points is computed asi/(m+1). Given ninesample values, the method sorts them and assigns the followingpercentiles: 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%.

Setting themethod to “inclusive” is used for describing populationdata or for samples that are known to include the most extreme valuesfrom the population. The minimum value indata is treated as the 0thpercentile and the maximum value is treated as the 100th percentile.The portion of the population falling below thei-th ofm sorteddata points is computed as(i-1)/(m-1). Given 11 samplevalues, the method sorts them and assigns the following percentiles:0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%.

# Decile cut points for empirically sampled data>>>data=[105,129,87,86,111,111,89,81,108,92,110,...100,75,105,103,109,76,119,99,91,103,129,...106,101,84,111,74,87,86,103,103,106,86,...111,75,87,102,121,111,88,89,101,106,95,...103,107,101,81,109,104]>>>[round(q,1)forqinquantiles(data,n=10)][81.0, 86.2, 89.0, 99.4, 102.5, 103.6, 106.0, 109.8, 111.0]

New in version 3.8.

Exceptions¶

A single exception is defined:

exceptionstatistics.StatisticsError¶

Subclass ofValueError for statistics-related exceptions.

NormalDist objects¶

NormalDist is a tool for creating and manipulating normaldistributions of arandom variable. It is aclass that treats the mean and standard deviation of datameasurements as a single entity.

Normal distributions arise from theCentral Limit Theorem and have a wide rangeof applications in statistics.

classstatistics.NormalDist(mu=0.0,sigma=1.0)¶

Returns a newNormalDist object wheremu represents thearithmeticmean andsigmarepresents thestandard deviation.

Ifsigma is negative, raisesStatisticsError.

mean¶

A read-only property for thearithmetic mean of a normaldistribution.

median¶

A read-only property for themedian of a normaldistribution.

mode¶

A read-only property for themode of a normaldistribution.

stdev¶

A read-only property for thestandard deviation of a normaldistribution.

variance¶

A read-only property for thevariance of a normaldistribution. Equal to the square of the standard deviation.

classmethodfrom_samples(data)¶

Makes a normal distribution instance withmu andsigma parametersestimated from thedata usingfmean() andstdev().

Thedata can be anyiterable and should consist of valuesthat can be converted to typefloat. Ifdata does notcontain at least two elements, raisesStatisticsError because ittakes at least one point to estimate a central value and at least twopoints to estimate dispersion.

samples(n,*,seed=None)¶

Generatesn random samples for a given mean and standard deviation.Returns alist offloat values.

Ifseed is given, creates a new instance of the underlying randomnumber generator. This is useful for creating reproducible results,even in a multi-threading context.

pdf(x)¶

Using aprobability density function (pdf), computethe relative likelihood that a random variableX will be near thegiven valuex. Mathematically, it is the limit of the ratioP(x<=X<x+dx)/dx asdx approaches zero.

The relative likelihood is computed as the probability of a sampleoccurring in a narrow range divided by the width of the range (hencethe word “density”). Since the likelihood is relative to other points,its value can be greater than1.0.

cdf(x)¶

Using acumulative distribution function (cdf),compute the probability that a random variableX will be less than orequal tox. Mathematically, it is writtenP(X<=x).

inv_cdf(p)¶

Compute the inverse cumulative distribution function, also known as thequantile functionor thepercent-pointfunction. Mathematically, it is writtenx:P(X<=x)=p.

Finds the valuex of the random variableX such that theprobability of the variable being less than or equal to that valueequals the given probabilityp.

overlap(other)¶

Measures the agreement between two normal probability distributions.Returns a value between 0.0 and 1.0 givingthe overlapping area forthe two probability density functions.

quantiles(n=4)¶

Divide the normal distribution inton continuous intervals withequal probability. Returns a list of (n - 1) cut points separatingthe intervals.

Setn to 4 for quartiles (the default). Setn to 10 for deciles.Setn to 100 for percentiles which gives the 99 cuts points thatseparate the normal distribution into 100 equal sized groups.

Instances ofNormalDist support addition, subtraction,multiplication and division by a constant. These operationsare used for translation and scaling. For example:

>>>temperature_february=NormalDist(5,2.5)# Celsius>>>temperature_february*(9/5)+32# FahrenheitNormalDist(mu=41.0, sigma=4.5)

Dividing a constant by an instance ofNormalDist is not supportedbecause the result wouldn’t be normally distributed.

Since normal distributions arise from additive effects of independentvariables, it is possible toadd and subtract two independent normallydistributed random variablesrepresented as instances ofNormalDist. For example:

>>>birth_weights=NormalDist.from_samples([2.5,3.1,2.1,2.4,2.7,3.5])>>>drug_effects=NormalDist(0.4,0.15)>>>combined=birth_weights+drug_effects>>>round(combined.mean,1)3.1>>>round(combined.stdev,1)0.5

New in version 3.8.

>>>sat=NormalDist(1060,195)>>>fraction=sat.cdf(1200+0.5)-sat.cdf(1100-0.5)>>>round(fraction*100.0,1)18.4

>>>list(map(round,sat.quantiles()))[928, 1060, 1192]>>>list(map(round,sat.quantiles(n=10)))[810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]

>>>defmodel(x,y,z):...return(3*x+7*x*y-5*y)/(11*z)...>>>n=100_000>>>X=NormalDist(10,2.5).samples(n,seed=3652260728)>>>Y=NormalDist(15,1.75).samples(n,seed=4582495471)>>>Z=NormalDist(50,1.25).samples(n,seed=6582483453)>>>quantiles(map(model,X,Y,Z))[1.4591308524824727, 1.8035946855390597, 2.175091447274739]

>>>n=750# Sample size>>>p=0.65# Preference for Python>>>q=1.0-p# Preference for Ruby>>>k=500# Room capacity>>># Approximation using the cumulative normal distribution>>>frommathimportsqrt>>>round(NormalDist(mu=n*p,sigma=sqrt(n*p*q)).cdf(k+0.5),4)0.8402>>># Solution using the cumulative binomial distribution>>>frommathimportcomb,fsum>>>round(fsum(comb(n,r)*p**r*q**(n-r)forrinrange(k+1)),4)0.8402>>># Approximation using a simulation>>>fromrandomimportseed,choices>>>seed(8675309)>>>deftrial():...returnchoices(('Python','Ruby'),(p,q),k=n).count('Python')>>>mean(trial()<=kforiinrange(10_000))0.8398

>>>height_male=NormalDist.from_samples([6,5.92,5.58,5.92])>>>height_female=NormalDist.from_samples([5,5.5,5.42,5.75])>>>weight_male=NormalDist.from_samples([180,190,170,165])>>>weight_female=NormalDist.from_samples([100,150,130,150])>>>foot_size_male=NormalDist.from_samples([12,11,12,10])>>>foot_size_female=NormalDist.from_samples([6,8,7,9])

>>>ht=6.0# height>>>wt=130# weight>>>fs=8# foot size

>>>prior_male=0.5>>>prior_female=0.5>>>posterior_male=(prior_male*height_male.pdf(ht)*...weight_male.pdf(wt)*foot_size_male.pdf(fs))>>>posterior_female=(prior_female*height_female.pdf(ht)*...weight_female.pdf(wt)*foot_size_female.pdf(fs))

>>>'male'ifposterior_male>posterior_femaleelse'female''female'