Boxplot aggregation #

A multi-value metrics aggregation producing the five-number summary of a distribution: minimum, lower quartile (q1), median (q2), upper quartile (q3) and maximum, plus whiskers.

How it works #

The engine collects and sorts the values of the field, then:

• min / max are the observed extremes (after missing substitution).
• q1, q2, q3 are the 25th, 50th and 75th percentiles, computed with the same TDigest arithmetic percentiles uses — weight-1 centroids at (i + 0.5) / n with linear interpolation between the two bracketing values. A quartile can therefore land between observed values (q2 of the sale prices is 22.5, between 15 and 30).
• The whiskers extend from the quartiles by 1.5 × IQR, where IQR = q3 − q1, and are clamped to the data: lower = max(q1 − 1.5·IQR, min), upper = min(q3 + 1.5·IQR, max). Values beyond the unclamped whisker positions are the conventional boxplot outliers.

Clamping means on a compact distribution the whiskers simply touch the extremes — over the teaching sales prices the whiskers land exactly on min and max. If no document has a value for the field, all seven numbers are 0.

Example #

For the four-price dataset: min 15, q1 15, q2 22.5, q3 37.5, max 60, with lower/upper whiskers at the data extremes.

POST /sales/_search
{
  "aggs": {
    "price_box": {
      "boxplot": {
        "field": "price"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "price_box": {
      "min": 15.0,
      "max": 60.0,
      "q1": 15.0,
      "q2": 22.5,
      "q3": 37.5,
      "lower": 15.0,
      "upper": 60.0
    }
  }
}

Use cases #

• Comparing groups at a glance. Nest boxplot under terms and every bucket draws as one box: quartile overlap (or the lack of it) between product types, hosts or customers is visible without plotting raw points.
• Skew and tail diagnostics. The box is asymmetric when q2 − q1 and q3 − q2 differ, and whiskers pinned to the extremes (as with the teaching prices) say “no room for outliers” while long whiskers point at exactly the region where outliers begin.
• Outlier screening. Anything outside [lower, upper] is a Tukey-style outlier candidate — the whisker positions come precomputed, so a filter or alert only needs two comparisons.
• Dashboard thumbnails. One aggregation returns everything a box-and- whisker renderer needs; plot per-bucket boxes over a date_histogram for a rolling shape view.

Parameters for boxplot #

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

Related #

• percentiles — the quartiles are percentiles at 25, 50, 75; request an arbitrary ladder there.
• percentile_ranks — the inverse: which rank a specific value holds.
• median_absolute_deviation — a robust spread summary to pair with the IQR.
• extended_stats — the parametric summary (mean, variance, deviation bounds) for the same fields.