# Statistics
For the following functions, when the input is a _collection_, it can take the
following forms:
- Multiple arguments, e.g. `["Mean", 1, 2, 3]`
- A list of numbers, e.g. `["Mean", ["List", 1, 2, 3]]`
- A matrix, e.g. `["Mean", ["List", ["List", 1, 2], ["List", 3, 4]]]`
- A range, e.g. `["Mean", ["Range", 1, 10]]`
- A linear space: `["Mean", ["Linspace", 1, 5, 10]]`
## Functions
_collection_
Evaluate to the **arithmetic mean** of a collection of numbers.
The arithmetic mean is the average of the list of numbers. The mean is
calculated by dividing the sum of the numbers by the number of numbers in the
list.
The formula for the mean of a list of numbers is $$\bar{x} = \frac{1}{n}
\sum\_{i=1}^n x_i$$, where $$n$$ is the number of numbers in the list, and
$$x_i$$ is the $$i$$-th number in the list.
```json example
["Mean", ["List", 7, 8, 3.1, 12, 77]]
// 21.02
```
_distribution_
When the argument is a [probability distribution](#probability-distributions),
evaluate to the mean of the distribution, as a symbolic expression when the
parameters are symbolic.
```json example
["Mean", ["NormalDistribution", "mu", "sigma"]]
// mu
```
_collection_
Evaluate to the **median** of a _collection_ of numbers.
The median is the value separating the higher half from the lower half of a data
sample. For a list of numbers sorted in ascending order, the median is the
middle value of the list. If the list has an odd number of elements, the median
is the middle element. If the list has an even number of elements, the median is
the average of the two middle elements.
```json example
["Median", ["List", 1, 2, 3, 4, 5]]
// 3
```
_collection_
Evaluate to the **mode** of a _collection_ of numbers.
The mode is the value that appears most often in a list of numbers. A list of
numbers can have more than one mode. If there are two modes, the list is called
**bimodal**. For example $$ \lbrack 2, 5, 5, 3, 2\rbrack$$. If there are three
modes, the list is called **trimodal**. If there are more than three modes, the
list is called **multimodal**.
```json example
["Mode", ["List", 1, 2, 2, 3, 4, 4, 5, 5]]
// 2
```
_collection_
Evaluate to the **variance** of a _collection_ of numbers.
The variance is a measure of the amount of variation or dispersion of a set of
values. A low variance indicates that the values tend to be close to the mean of
the set, while a high variance indicates that the values are spread out over a
wider range.
The formula for the variance of a list of numbers is
$$\frac{1}{n} \sum_{i=1}^n(x_i - \mu)^2$$
where $$\mu$$ is the mean of the list.
_distribution_
When the argument is a [probability distribution](#probability-distributions),
evaluate to the variance of the distribution.
```json example
["Variance", ["PoissonDistribution", "lambda"]]
// lambda
```
_collection_
Evaluate to the **population variance** of a _collection_ of numbers.
The population variance is the variance calculated by dividing the sum of squared
differences from the mean by the number of elements in the population.
The formula for the population variance is
$$\frac{1}{N} \sum_{i=1}^N (x_i - \mu)^2$$
where $$N$$ is the size of the population, and $$\mu$$ is the population mean.
_collection_
Evaluate to the **standard deviation** of a _collection_ of numbers.
The standard deviation is a measure of the amount of variation or dispersion of
a set of values. A low standard deviation indicates that the values tend to be
close to the mean of the set, while a high standard deviation indicates that the
values are spread out over a wider range.
The formula for the standard deviation of a _collection_ of numbers is
$$\sqrt{\frac{1}{n} \sum_{i=1}^n (x_i - \mu)^2}$$
where $$\mu$$ is the mean of the list.
_distribution_
When the argument is a [probability distribution](#probability-distributions),
evaluate to the standard deviation of the distribution.
```json example
["StandardDeviation", ["NormalDistribution", "mu", "sigma"]]
// sigma
```
_collection_
Evaluate to the **population standard deviation** of a _collection_ of numbers.
The population standard deviation is the square root of the population variance.
The formula for the population standard deviation is
$$\sqrt{\frac{1}{N} \sum_{i=1}^N (x_i - \mu)^2}$$
where $$N$$ is the size of the population, and $$\mu$$ is the population mean.
_collection_
Evaluate to the **skewness** of a list of numbers.
The skewness is a measure of the asymmetry of the distribution of a real-valued
random variable about its mean. The skewness value can be positive or negative,
or undefined.
The formula for the skewness of a _collection_ of numbers is: $$\frac{1}{n}
\sum_{i=1}^n \left(\frac{x_i - \mu}{\sigma}\right)^3$$
where $$\mu$$ is the mean of the _collection_, and $$\sigma$$ is the
standard deviation of the _collection_.
_collection_
Evaluate to the **kurtosis** of a _collection_ of numbers.
The kurtosis is a measure of the "tailedness" of the distribution of a
real-valued random variable. The kurtosis value can be positive or negative, or
undefined.
The formula for the kurtosis of a _collection_ of numbers is
$$ \frac{1}{n} \sum_{i=1}^n \left(\frac{x_i - \mu}{\sigma}\right)^4$$
where $$\mu$$ is the mean of the list, and $$\sigma$$ is the standard
deviation of the list.
_xs:collection_, _ys:collection__points:collection_
Evaluate to the **sample covariance** of two data sets: either two
equal-length collections, or a single collection of $$(x, y)$$ pairs.
$$\operatorname{cov}(x, y) = \frac{1}{n-1} \sum_{i=1}^n (x_i - \bar{x})(y_i - \bar{y})$$
Exact data gives an exact result.
```json example
["Covariance", ["List", 1, 2, 3, 4, 5], ["List", 2, 4, 5, 4, 5]]
// 3/2
```
_xs:collection_, _ys:collection__points:collection_
Evaluate to the **population covariance** of two data sets: the covariance
with an $$n$$ denominator instead of $$n - 1$$.
$$\frac{1}{n} \sum_{i=1}^n (x_i - \bar{x})(y_i - \bar{y})$$
_xs:collection_, _ys:collection__points:collection_
Evaluate to the **Pearson correlation coefficient** of two data sets: a value
between $$-1$$ and $$1$$ measuring the strength of their linear relationship.
$$r = \frac{\operatorname{cov}(x, y)}{\sigma_x \sigma_y}$$
Exact data gives an exact result.
```json example
["Correlation", ["List", 1, 2, 3, 4, 5], ["List", 2, 4, 5, 4, 5]]
// sqrt(15) / 5
```
_xs:collection_, _ys:collection__points:collection_..., _variable:symbol_
Evaluate to the **least-squares linear fit** of the data, as the tuple
$$(b_0, b_1)$$ of the intercept and slope of the fitted line
$$y = b_0 + b_1 x$$.
Exact data yields exact coefficients.
```json example
["LinearRegression", ["List", 1, 2, 3, 4, 5], ["List", 2, 4, 5, 4, 5]]
// (11/5, 3/5)
```
With a trailing _variable_ argument, evaluate to the fitted **expression** in
that variable instead, ready to plot alongside the data.
```json example
["LinearRegression", ["List", 1, 2, 3, 4, 5], ["List", 2, 4, 5, 4, 5], "x"]
// 3/5 x + 11/5
```
_xs:collection_, _ys:collection_, _degree:number__points:collection_, _degree:number_..., _variable:symbol_
Evaluate to the **least-squares polynomial fit** of the data at the given
degree, as the list of coefficients, constant term first.
Exact data yields exact coefficients: points lying exactly on a polynomial
recover it exactly.
```json example
["PolynomialFit",
["List", ["List", 0, 1], ["List", 1, 2], ["List", 2, 5], ["List", 3, 10]],
2]
// [1, 0, 1] (the polynomial 1 + x²)
```
With a trailing _variable_ argument, evaluate to the fitted expression in
that variable instead.
The degree must satisfy $$\deg \le \min(n - 1, 12)$$ where $$n$$ is the
number of data points.
_collection_
Evaluate to the **quartiles** of a _collection_ of numbers.
The quartiles are the three points that divide a _collection_ of numbers into
four equal groups, each group comprising a quarter of the _collection_.
```json example
["Quartiles", ["List", 1, 2, 3, 4, 5, 6, 7, 8]]
// [2.5, 4.5, 6.5]
```
_collection_
Evaluate to the **interquartile range** (IQR) of a _collection_ of numbers.
The interquartile range is the difference between the third quartile and the
first quartile.
_collection_, _bins:number_
Evaluate to the **histogram** of a _collection_ of numbers.
The histogram groups the data into a specified number of bins and counts the
number of elements in each bin. The _bins_ argument is an integer bin count or
a list of explicit bin edges; a non-integer bin count is left unevaluated (a
Desmos-style bin *width* should be translated to explicit bin edges).
The LaTeX `\operatorname{histogram}` parses to `Histogram` (likewise
`\operatorname{pdf}` and `\operatorname{cdf}` parse to `PDF` and `CDF`).
```json example
["Histogram", ["List", 1, 2, 2, 3, 4, 5, 5, 5], 3]
// [[1, 3], [2.3333…, 1], [3.6667…, 4]] (bin start, count)
```
_collection_, _bins:number_
Evaluate to the **bin counts** of a _collection_ of numbers.
Bin counts are the counts of the number of elements in each bin for a given
number of bins.
```json example
["BinCounts", ["List", 1, 2, 2, 3, 4, 5, 5, 5], 3]
// [3, 1, 4]
```
_collection_, _windowSize:number_
Evaluate to the **sliding windows** of a _collection_ of numbers.
A sliding window is a moving subset of the data of a specified window size.
```json example
["SlidingWindow", ["List", 1, 2, 3, 4, 5], 3]
// [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
```
_xs_: indexed_collection, _k_: number
Evaluate to a **random sample** of `k` elements drawn from the indexed
collection _xs_, **without replacement**.
"Without replacement" is over **positions**, not values: each position of _xs_
is drawn at most once, but a multiset still yields repeated values.
`["RandomSample", ["List", 1, 1, 2], 2]` returns `[1, 1]` in about a quarter of
trials — it does not return distinct *values*.
```json example
["RandomSample", ["List", 5, 2, 10, 18], 2]
// ➔ ["List", 10, 5] (for example)
["WithRandomSeed", 42, ["RandomSample", ["Range", 1, 100], 3]]
// ➔ the same three elements on every evaluation
```
`k` may not exceed the number of elements of _xs_ (an `out-of-range` error);
`k` equal to that number returns a permutation. `k` is rounded on evaluation, so
a computed count needs no rounding by the caller.
_xs_ must be an **indexed** collection: an `Interval` or a `Set` is an invalid
domain. Use [`RandomChoice`](/compute-engine/reference/arithmetic/#randomchoice)
for drawing **with** replacement, or from a non-indexed domain.
The collection is never materialized — a sparse Fisher-Yates over the index
space draws exactly `k` elements, so `["RandomSample", ["Range", 1, 1000000], 3]`
is cheap.
`Sample` was renamed to `RandomSample` and no longer takes a seed argument; the
old name throws an `operator-removed` error for one release.
_collection_
Evaluate to the **rank** of each element in a _collection_ of numbers.
The rank is the position of each element in the sorted order of the collection.
_collection_
Evaluate to the **indices that would sort** a _collection_ of numbers.
This returns a list of indices that sorts the collection.
## Probability Distributions
A **probability distribution** is a first-class value constructed with one of
the distribution functions below. It can be assigned to a symbol, passed as an
argument, and queried with `PDF`, `CDF`, `Quantile`, `Mean`, `Variance` and
`StandardDeviation`.
These operators evaluate to **exact closed forms**: the result is an ordinary
expression that can be simplified, differentiated, compiled or plotted, and
numeric approximation (`.N()`) works at machine or arbitrary precision.
```json example
["CDF", ["NormalDistribution", 0, 1], "x"]
// 1/2 + Erf(x / sqrt(2)) / 2
```
_mean_, _standardDeviation_
A **normal (Gaussian) distribution** with the given mean $$\mu$$ and standard
deviation $$\sigma > 0$$.
Note that the second parameter is the standard deviation, not the variance,
following the convention of most computer algebra and statistics systems.
_n_, _p_
A **binomial distribution**: the number of successes in $$n \ge 0$$ independent
trials, each succeeding with probability $$0 \le p \le 1$$.
_lambda_
A **Poisson distribution**: the number of events occurring in a fixed interval
when events occur independently at a mean rate of $$\lambda > 0$$.
_a_, _b_
A **continuous uniform distribution** on the interval $$[a, b]$$, with
$$a < b$$.
_lambda_
An **exponential distribution**: the waiting time between events occurring at
a mean rate of $$\lambda > 0$$ (the _rate_ parameterization; the mean is
$$1/\lambda$$).
_distribution_, _x_
Evaluate to the **probability density function** of _distribution_ at _x_.
For a discrete distribution, this is the **probability mass function**, and it
is `0` at numeric non-integer points.
The result is a closed-form expression: with a symbolic _x_ it is the density
formula itself, ready to plot or integrate.
```json example
["PDF", ["BinomialDistribution", 4, ["Rational", 1, 2]], 2]
// 3/8
```
_distribution_, _x_
Evaluate to the **cumulative distribution function** of _distribution_ at _x_:
the probability that a random value is less than or equal to _x_.
The result is exact: a normal CDF is expressed with `Erf`, and discrete CDFs
with `GammaRegularized`/`BetaRegularized`. Use `N()` for a numeric value.
```json example
["N", ["CDF", ["NormalDistribution", 0, 1], 1]]
// 0.8413447460685429
```
_distribution_, _p:number_
Evaluate to the **quantile** (inverse CDF) of _distribution_: the smallest
value $$x$$ such that $$\operatorname{CDF}(x) \ge p$$, for $$0 \le p \le 1$$.
`Quantile(dist, 0.5)` is the median of the distribution.
_collection_, _p:number_
When the first argument is a collection of numbers, evaluate to the
**empirical quantile** of the data, interpolating the sorted values. It is
consistent with `Quartiles` and `Median`: `Quantile(xs, 1/4)`,
`Quantile(xs, 1/2)` and `Quantile(xs, 3/4)` equal the three quartiles, and
$$p = 0$$ and $$p = 1$$ give the minimum and maximum.
```json example
["Quantile", ["PoissonDistribution", 9], 0.95]
// 14
```
For continuous distributions the result is a closed form
(`Quantile(NormalDistribution(mu, sigma), p)` is
$$\mu + \sigma\sqrt2\operatorname{erf}^{-1}(2p-1)$$); for discrete
distributions it is computed by exact search when `p` is numeric.
See also Special Functions for
the Error Functions and the regularized incomplete
gamma and beta functions