Skip to content
Tutorials Center
My learning

Topics

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.

Python
import statistics

print(statistics.mean([1, 2, 3, 4]))

Try it

Python Averages and spread

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.

Python Relationships, normal distribution and errors

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/variance when your data is a sample of something larger (most real data) and pstdev/pvariance when 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). Use multimode() to see them all.
  • Non-numeric data. mode and multimode work 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 as Fraction and Decimal, but it is slower than fmean(), 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.