Tag: add percentile()/quantile() — toolbox-free order-statistics primitive (P50/P95/P99 & IQR, order-stat sibling to getStats #223)

[HanSur94]

Problem / motivation

The Tag analysis family has grown a rich set of reduction primitives, but its
statistics surface only covers moment statistics. #223 (getStats) was scoped
explicitly to N / Min / Max / Mean / Rms / Std — the summing/squaring family — and
deliberately left out order statistics (median, percentiles, IQR). Meanwhile #251
(HistogramWidget: overlay distribution percentiles) shows the domain actively wants
percentiles, but it renders them as a widget display overlay — there is no way to get
percentile values from a Tag programmatically.

Verified gap:

• grep -rniE "percentile|quantile|prctile" libs/SensorThreshold/ → nothing.
• No open/closed issue proposes a Tag percentile/quantile method (only HistogramWidget: overlay distribution percentiles (ShowPercentiles / Percentiles) #251, a widget overlay).

Order statistics answer questions moment statistics cannot:

• P95 / P99 — "what level is exceeded only 5 % / 1 % of the time?" (duty-cycle / peak-load exceedance).
• Median — robust central tendency for skewed or outlier-prone channels, where mean (Tag: add a public getStats() statistics primitive (N/Min/Max/Mean/Rms/Std over a series or time range) #223) misleads.
• IQR (P75 − P25) — robust spread, insensitive to outliers.

These are canonical sensor-analysis / loads / duty-cycle descriptors. Today an engineer must
drop to getXY and hand-roll a sort every time.

Proposed feature

A base-Tag convenience method returning percentile values of the resolved series,
toolbox-free, inherited by every subclass:

p95 = tag.percentile(95);              % scalar level  -> scalar value
pv  = tag.percentile([5 50 95]);       % vector levels -> vector of values
pv  = tag.percentile([5 95], t0, t1);  % over a time window (mirrors getStats #223 range args)
m   = tag.median();                     % optional convenience == percentile(50)
r   = tag.iqr();                        % optional convenience == percentile(75) - percentile(25)

Rough sketch

Single method on libs/SensorThreshold/Tag.m (base class — same placement as getStats
#223 and the rest of the family), built on the existing accessors getXY (Tag.m:120) /
getXYRange(obj, tStart, tEnd) (Tag.m:125, which already returns the full series for
empty bounds):

1. [~, Y] = obj.getXYRange(tStart, tEnd) (or getXY when no range) — reuse the same
   range plumbing Tag: add a public getStats() statistics primitive (N/Min/Max/Mean/Rms/Std over a series or time range) #223 uses.
2. Drop NaNs; guard the empty series; validate levels are in [0, 100].
3. Ys = sort(Y(:)); then the standard linear-interpolation percentile:
   i = p/100 * (n-1) + 1, interpolate between Ys(floor(i)) and Ys(ceil(i)).
4. Return values matching the shape of the requested levels.

Pure-function, read-only: no new property, no toStruct/fromStruct change, no
Tag/DashboardWidget contract touched. Output is a plain numeric array — same downstream shape
as the rest of the family.

Value

Medium-High. Completes the Tag statistics surface with the robust / order-statistic
dimension that #223 deliberately left out and that #251 shows is wanted; unlocks
exceedance-level, median, and IQR workflows the library currently forces users to leave for.

Constraints check

• Toolbox-free: ⚠️ important — prctile and quantile are Statistics Toolbox
  functions and must not be used. The sort + linear-interpolation implementation is base
  MATLAB and Octave, keeping the method toolbox-free.
• Backward-compatible: a brand-new method cannot break existing scripts or serialized
  dashboards; no serialization or contract change.
• Pure MATLAB/Octave: yes (sort + arithmetic only).
• Works through the existing Tag contract: yes — reuses getXY / getXYRange.

Effort estimate

S — one method (+ optional median / iqr one-liners) in a single file, plus a focused
test (known vector → known percentiles at endpoints and interior; scalar-vs-vector level
input; NaN handling; empty-series guard; time-range path).

Dedup / relationship note (honest triage flag)

• Tag: add a public getStats() statistics primitive (N/Min/Max/Mean/Rms/Std over a series or time range) #223 (getStats) is the moment family and explicitly excludes percentiles — this
  is the order-statistics sibling.
• HistogramWidget: overlay distribution percentiles (ShowPercentiles / Percentiles) #251 is a HistogramWidget display overlay, not a Tag primitive.
• A reviewer may reasonably prefer to fold this into Tag: add a public getStats() statistics primitive (N/Min/Max/Mean/Rms/Std over a series or time range) #223 (extend getStats to emit
  percentiles) rather than add a separate method — both are toolbox-free and additive. This
  is a product decision.

---

AI-proposed via /feature-scout — needs a human product decision before implementation.