Median absolute deviation aggregation #

A single-value metrics aggregation that computes the median absolute deviation — the median of the distances from each value to the median of all values. A robust measure of spread: unlike standard deviation it is not skewed by a few extreme values.

How it works #

The aggregation runs in three steps over the collected values of the field:

1. Compute the median with the same TDigest arithmetic percentiles uses — weight-1 centroids at (i + 0.5) / n, linear interpolation between the two bracketing values.
2. Take each value’s absolute distance to that median, |v − median|.
3. Return the median of those distances, using the same arithmetic again.

Because both medians interpolate, the result can land between observed values (over the 120 teaching sale prices: median 22.5, MAD 7.5 — neither is a price anyone paid). The value is expressed in the same units as the field, so a MAD of 7.5 on prices means “a typical sale is $7.50 away from the median price”.

The robustness comes from the outer median: up to half the values can be arbitrarily wrong (or arbitrarily large) before the MAD moves at all, whereas a single huge value already inflates a standard deviation. If no document has a value for the field, value is null.

Example #

Sales prices take only four values (15, 30, 45, 60), so half the documents sit at 15 and the deviation of a typical document is small:

The median price is 22.5; the median distance from that median is 7.5.

Use cases #

• Outlier-resistant spread for skewed data. Latency, income and price distributions have long tails; quote the MAD when a single spike must not change the “typical variation” story.
• Robust z-scores. 0.6745 × (x − median) / MAD is the classic robust analogue of “how many standard deviations from the mean” — flag points beyond ±3 as anomalies. With the sales numbers: a 60 sticker price sits at 0.6745 × 37.5 / 7.5 ≈ 3.4 robust sigmas.
• Comparing variability across groups. Nest MAD under terms to compare how consistent each product type’s prices are, without one expensive outlier dominating a group.
• Data-quality gates. A MAD of 0 means at least half the values sit exactly on the median — a cheap “is this field effectively constant?” check before deduplicating or indexing it.

Parameters for median_absolute_deviation #

• field
  (Required, string) Numeric field you wish to aggregate.
• missing
  (Optional, number) Value substituted for documents without the field.

Related #

• percentiles — supplies the median (the 50th percentile) the deviations are measured against.
• boxplot — the interquartile range (q3 − q1) is the other common robust spread measure; compare the two on the same data.
• extended_stats — standard deviation and variance, the non-robust counterparts, useful when the contrast itself is the signal (a std-deviation far above MAD means heavy tails).