Percentiles, Quantiles, and Quartiles

Install and import#

npm install fintech-algorithms

import { percentilesQuantilesAndQuartiles } from "fintech-algorithms/foundations/location-ranking-and-exploratory-summaries/percentiles-quantiles-and-quartiles";

Signature#

percentilesQuantilesAndQuartiles(input)

Returns the three quartiles of a numeric series and the interquartile range between the first and third, using linear interpolation between neighbouring order statistics.

Parameters#

Returns#

{ quantiles: { '0.25': number; '0.5': number; '0.75': number }; iqr: number }

quantiles is keyed by the three cut points as strings, and iqr is the 0.75 quantile minus the 0.25 quantile.

Errors#

• When input is null, an array, or not an object — throws TypeError
• When values is missing, is not an array, or is empty — throws RangeError
• When any entry of values does not coerce to a finite number — throws RangeError

Complexity: time O(n log n), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

{
  "values": [1, 2, 2, 4, 9],
  "weights": [1, 1, 2, 1, 1],
  "trimProportion": 0.2,
  "bins": 4
}

Call#

percentilesQuantilesAndQuartiles(input)

Returns#

object with 2 fields: quantiles, iqr

{
  "quantiles": {
    "0.25": 2,
    "0.5": 2,
    "0.75": 4
  },
  "iqr": 2
}

Diagrams#

Calculation flow#

flowchart LR
    A["Finite observations"] --> B["Name units and scope"]
    B --> C["Freeze: Type 7: h = 1 + (n−1)q; linearly interpolate between ordered positions around h"]
    C --> D["Calculate full precision"]
    D --> E{"Boundary satisfied?"}
    E -->|Yes| F["Report Q1 2 · median 2 · Q3 4 · IQR 2 (type 7)"]
    E -->|No| G["Abstain and repair contract"]
    F --> H["Pair with distribution context"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Percentile Definitions
• percentile
• Sample Quantiles in Statistical Packages
• Historical-example decision

The rest of the Location, Ranking, and Exploratory Summaries family#

• Count, Sum, Minimum, Maximum, and RangeReduces one numeric series to the five headline aggregates: how many observations there are, their total, the smallest and larg…
• Arithmetic MeanDivides the sum of a numeric series by the number of observations and reports both the mean and the count it was divided by.
• Weighted MeanComputes a weighted average of values using the parallel weights series, dividing the sum of value-times-weight products by…
• Median and ModeReports the middle of a numeric series and its most frequent values, tallying exact equality so a tie produces several modes ra…
• Trimmed and Winsorized MeansCuts the same number of observations off each tail of the sorted series and averages what is left, then averages again with tho…
• Ranks, Ties, and Percentile RankAssigns each observation its position in the sorted series, giving tied observations the average of the positions they span, an…
• Frequency Tables and Relative FrequencyCounts how often each distinct value occurs in a numeric series and expresses those counts as shares of the total.
• Histograms and Empirical Distribution FunctionsSplits the observed span into equal-width bins and counts the observations in each, alongside the empirical distribution functi…
• Five-Number Summary and Box PlotProduces the minimum, three quartiles, and maximum of a numeric series, the Tukey 1.5-IQR fences drawn from them, and the obser…