Python Reference ยท Standard Library: Math, Data and Text
The statistics module
Reference for Python's statistics module: mean, median, mode, variance, standard deviation, quantiles, correlation and linear regression for plain data.
The statistics module computes descriptive statistics for lists of numbers: averages, spread, quantiles, correlation and a simple linear regression. It works on any iterable of ints, floats, Fraction or Decimal values and needs no third-party packages.
It is meant for ordinary data sets, not huge numeric arrays. When you work with millions of values or need a full statistics toolbox, use NumPy, pandas or SciPy. For small to medium data, the clear function names (mean, median, stdev) make code easy to read.
import statistics print(statistics.mean([1, 2, 3, 4]))
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Frequently used names
| Name | Description |
|---|---|
mean(data) |
Arithmetic mean. Exact for ints and fractions. Whole results from ints come back as int (mean([1, 2, 3]) is 2), others as float. |
fmean(data, weights=None) |
Faster float mean, always returns a float; optional weights (3.11+). |
geometric_mean(data), harmonic_mean(data, weights=None) |
Other kinds of averages (positive values). |
median(data), median_low(data), median_high(data), median_grouped(data) |
Middle value. For an even count median averages the two middle values; the low/high versions return one of them. |
mode(data), multimode(data) |
Most common value; list of all most-common values (empty list for empty data). |
pstdev(data), pvariance(data) |
Standard deviation and variance of a population. |
stdev(data), variance(data) |
Standard deviation and variance of a sample (divides by n - 1). Need at least two values. |
quantiles(data, n=4, method="exclusive") |
n - 1 cut points dividing the data into n groups. |
correlation(x, y), covariance(x, y) |
Pearson correlation (and Spearman with method="ranked" in 3.12+) and covariance. |
linear_regression(x, y) |
Returns a named tuple with slope and intercept (3.10+). |
NormalDist(mu, sigma) |
Normal distribution with cdf, pdf, inv_cdf, samples and arithmetic. |
StatisticsError |
Subclass of ValueError raised for empty or invalid data. |
Usage notes
- Sample or population? Use
stdev/variancewhen your data is a sample of something larger (most real data) andpstdev/pvariancewhen it contains every member of the group. The two give different answers, and mixing them up is the most frequent mistake. - Empty data raises
StatisticsError, and sample statistics need at least two points.multimode()is the exception: it returns[]. mode()returns the first of several equally common values (since 3.8). Usemultimode()to see them all.- Non-numeric data.
modeandmultimodework on any hashable values, for example strings. The others need numbers. - Sorting is not required; each function sorts internally when it needs to.
- Accuracy.
mean()is careful about rounding and preserves exact types such asFractionandDecimal, but it is slower thanfmean(), which is usually the right choice for plain floats. - NaN and infinity are not handled; the result with NaN values is undefined. Clean your data first.
- Quantile methods. The default
"exclusive"method suits samples;method="inclusive"treats the data as the whole population and matches what many spreadsheets call QUARTILE.INC. Different tools disagree on quantile definitions, so check which one you need. - Large data sets. The functions build lists internally; for data that does not fit in memory use a streaming approach or NumPy.