Descriptive Statistics

# covariance function

      signature
      
covariance(xs: number[], ys: number[]): number

Returns the sample covariance between two equal-length arrays xs and ys (divided by n − 1).

Covariance measures the joint variability of two variables — a positive value means they tend to increase together; a negative value means one tends to decrease as the other increases.

Returns NaN when:

Either array is empty.
The arrays have different lengths.
There is fewer than 2 paired observations.

Parameters

Name	Type	Description
xs	number[]	Array of independent-variable values.
ys	number[]	Array of dependent-variable values (same length as `xs`).

Returns

number

Sample covariance, or NaN for degenerate inputs.

insight covariance is the numerator of the Pearson correlation coefficient and also appears directly in the OLS slope formula (slope = cov(x, y) / var(x)), making it a foundational primitive for @statili/stats regression methods.

Example

covariance([1, 2, 3], [4, 5, 6])   //  1 (perfect positive covariance)
covariance([1, 2, 3], [6, 5, 4])   // -1 (perfect negative covariance)
covariance([1, 2, 3], [3, 3, 3])   //  0 (no covariance)

# mad function

packages/math/src/descriptive.ts:266

      signature
      
mad(numbers: number[]): number

Returns the Median Absolute Deviation (MAD) — the median of absolute deviations from the dataset’s median.

MAD is a robust measure of spread that is far less sensitive to outliers than standardDeviation. A scaled MAD (1.4826 × MAD) approximates the standard deviation for normally-distributed data.

Returns NaN for an empty array.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.

Returns

number

The MAD value, or NaN if the array is empty.

insight use MAD instead of standard deviation when your dataset contains suspected outliers. In a chart context, data points beyond median ± 3 × 1.4826 × MAD can be flagged as anomalies in a distribution-agnostic way.

Example

mad([1, 1, 2, 2, 4, 6, 9])  // 1
mad([])                     // NaN

# max function

packages/math/src/descriptive.ts:165

      signature
      
max(numbers: number[]): number

Returns the maximum value in numbers.

Returns NaN for an empty array.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.

Returns

number

The largest element, or NaN if the array is empty.

Example

max([3, 1, 4, 1, 5, 9])  // 9
max([])                  // NaN

# mean function

packages/math/src/descriptive.ts:36

      signature
      
mean(numbers: number[]): number

Returns the arithmetic mean (average) of numbers.

Returns NaN for an empty array — there is no meaningful average of zero values. Downstream consumers should guard with isNaN(result).

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.

Returns

number

The mean, or NaN if the array is empty.

insight the mean is the foundation for variance, standard deviation, z-scores, and OLS regression. A large gap between mean and median signals skew in the distribution.

Example

mean([2, 4, 6])  // 4
mean([])         // NaN

# median function

packages/math/src/descriptive.ts:64

      signature
      
median(numbers: number[]): number

Returns the median (middle value) of numbers.

For an odd count the median is the exact middle element of the sorted array.
For an even count it is the mean of the two middle elements.

Returns NaN for an empty array.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers (need not be pre-sorted).

Returns

number

The median value, or NaN if the array is empty.

insight the median is robust to outliers and preferred over the mean for skewed distributions (e.g. salaries, house prices). Use alongside mean to detect skew: mean > median → right-skewed; mean < median → left-skewed.

Example

median([3, 1, 4, 1, 5])   // 3
median([1, 2, 3, 4])      // 2.5
median([])                // NaN

# min function

packages/math/src/descriptive.ts:148

      signature
      
min(numbers: number[]): number

Returns the minimum value in numbers.

Returns NaN for an empty array.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.

Returns

number

The smallest element, or NaN if the array is empty.

Example

min([3, 1, 4, 1, 5, 9])  // 1
min([])                  // NaN

# pearsonCorrelation function

packages/math/src/descriptive.ts:338

      signature
      
pearsonCorrelation(xs: number[], ys: number[]): number

Returns the Pearson product-moment correlation coefficient between xs and ys, always in the range [−1, 1].

r ≈ 1 → strong positive linear relationship
r ≈ −1 → strong negative linear relationship
r ≈ 0 → no linear relationship

Returns NaN when:

Either array is empty or their lengths differ.
Either array has zero variance (all values identical), making the correlation mathematically undefined.

Parameters

Name	Type	Description
xs	number[]	First variable (same length as `ys`).
ys	number[]	Second variable (same length as `xs`).

Returns

number

Pearson r in [−1, 1], or NaN for degenerate inputs.

insight

Pearson r is the square-root of R² for simple linear regression and directly quantifies linear association strength. Use it to:

Pre-screen variables before running regression.
Classify relationship strength (|r| ≥ 0.7 strong, 0.4–0.7 moderate, < 0.4 weak) for @statili/forge insight generation.
Surface pairwise correlations in heatmap / scatterplot matrix views.

Example

pearsonCorrelation([1, 2, 3], [4, 5, 6])   //  1
pearsonCorrelation([1, 2, 3], [6, 5, 4])   // -1
pearsonCorrelation([1, 2, 3], [3, 3, 3])   // NaN  (zero variance in ys)

# quantile function

packages/math/src/descriptive.ts:230

      signature
      
quantile(p: number, numbers: number[]): number

Returns the value at quantile p using linear interpolation between adjacent ranks (equivalent to R’s Type 7 / NumPy’s default method).

The array does not need to be pre-sorted.

Partial-application pattern — p (the quantile level) is the infrequently-changing argument; numbers (the data) is last:

const median    = quantile(0.5);
const p25       = quantile(0.25);
const p75       = quantile(0.75);
const iqr       = (data: number[]) => p75(data) - p25(data);

Parameters

Name	Type	Description
p	number	Quantile level in `[0, 1]`. `0.5` = median, `0.25` = Q1, `0.75` = Q3. Throws a `RangeError` if outside `[0, 1]`.
numbers	number[]	Array of finite numbers.

Returns

number

The interpolated quantile value, or NaN if the array is empty.

insight

quantiles divide data into equal-probability regions. Common uses:

Interquartile range (IQR) = Q3 − Q1 (robust spread, used in box-plots and outlier detection).
Percentile ranks communicate where a value sits in a distribution.
Tail analysis — extreme quantiles (p = 0.01, p = 0.99) surface outlier thresholds for anomaly-detection annotations in charts.

Example

quantile(0.5, [1, 2, 3, 4, 5])   // 3     (median)
quantile(0.25, [1, 2, 3, 4])     // 1.75  (Q1)
quantile(0.75, [1, 2, 3, 4])     // 3.25  (Q3)
quantile(0, [5, 3, 1])           // 1     (min)
quantile(1, [5, 3, 1])           // 5     (max)

# range function

packages/math/src/descriptive.ts:189

      signature
      
range(numbers: number[]): number

Returns the range — the difference between the maximum and minimum values.

Returns NaN for an empty array.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.

Returns

number

max(numbers) − min(numbers), or NaN if the array is empty.

insight the range gives a quick sense of data spread but is highly sensitive to outliers. Prefer standardDeviation or iqr (interquartile range via quantile) for robust spread estimates.

Example

range([3, 1, 4, 1, 5, 9])  // 8   (9 − 1)
range([7])                  // 0
range([])                   // NaN

# standardDeviation function

packages/math/src/descriptive.ts:132

      signature
      
standardDeviation(numbers: number[], ddof?: 0 | 1): number

Returns the sample standard deviation of numbers (Bessel’s correction, divided by n − 1).

Use ddof: 0 for the population standard deviation.

Returns NaN for an empty array or a single-element array when ddof = 1.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.
ddofoptional	0 \| 1	Delta degrees of freedom: `1` (default) = sample std dev, `0` = population std dev.

Returns

number

The standard deviation, or NaN for degenerate inputs.

insight std dev is the most common measure of data spread, expressed in the same units as the data (unlike variance). It is used to compute z-scores, confidence intervals, and to detect outliers (points beyond ±2–3 std devs). Compared to mad, std dev is sensitive to outliers.

Example

standardDeviation([2, 4, 4, 4, 5, 5, 7, 9])     // ≈ 2.138 (sample)
standardDeviation([2, 4, 4, 4, 5, 5, 7, 9], 0)  // 2       (population)

# sum function

packages/math/src/descriptive.ts:14

      signature
      
sum(numbers: number[]): number

Returns the sum of all values in numbers.

Returns 0 for an empty array (the additive identity), consistent with standard mathematical convention and most statistics libraries.

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.

Returns

number

The sum, or 0 if the array is empty.

Example

sum([1, 2, 3, 4])  // 10
sum([])            // 0

# variance function

packages/math/src/descriptive.ts:100

      signature
      
variance(numbers: number[], ddof?: 0 | 1): number

Returns the sample variance of numbers (Bessel’s correction, divided by n − 1).

Use ddof: 0 to obtain the population variance (divided by n), which is appropriate when numbers represents an entire population rather than a sample.

Returns NaN when:

The array is empty.
ddof = 1 and the array has fewer than 2 elements (variance is undefined for a single-element sample).

Parameters

Name	Type	Description
numbers	number[]	Array of finite numbers.
ddofoptional	0 \| 1	Delta degrees of freedom: `1` (default) = sample variance, `0` = population variance.

Returns

number

The variance, or NaN for degenerate inputs.

insight variance quantifies the spread of data around the mean. High variance signals noisy or widely-distributed data; low variance signals tightly clustered data. It is the square of standardDeviation.

Example

variance([2, 4, 4, 4, 5, 5, 7, 9])        // 4.571... (sample)
variance([2, 4, 4, 4, 5, 5, 7, 9], 0)     // 4        (population)
variance([42])                             // NaN      (single-element sample)