Why Diagnostics Ships Two Normalisers (and Why You Should Never Compare Across Them)

Inside each Diagnostics factor group, raw metrics get mapped to 0–100 by a normaliser. The module ships two: MinMax (used by /score) and Percentile (used by /rank). They produce different numbers on the same input data, and the most common misread of Diagnostics output we've seen is comparing a MinMax 70 to a Percentile 70 as if they meant the same thing.

MinMax is parameter-driven. For each metric (annualised volatility, 30-day average daily volume, Gini concentration, etc.) the engine carries a calibrated [lower, upper] pair: vol of 0.3 → 100 (healthy), vol of 2.0 → 0 (fragile), linear in between, clamped at the ends. The bounds are fixed across runs and across assets — a Bitcoin-vol of 0.6 always lands at the same MinMax score regardless of what other coins have done that week. This is the right normalisation when you're asking 'is this asset structurally healthy on its own terms,' which is the single-coin /score question.

Percentile is universe-relative. The engine takes the universe under analysis (the basket of coin ids passed to /rank), ranks each asset's metric value within that universe, and maps the rank to 0–100. A 90th-percentile entry lands at 90; a 10th-percentile entry at 10. This is the right normalisation when you're asking 'how does this asset compare to its peers right now,' which is the universe /rank question.

The two methods are not interchangeable, and the module reports the active one as the normalization_method field on every response so callers can document which axis their score lives on. Three concrete failure modes when the difference is ignored: (1) ranking a 50-coin universe where every asset has historically high volatility — every asset will get a Percentile-volatility score around 50 even though they're all in MinMax fragile territory; the rank-based number flatters them. (2) Diagnosing a single coin with /score, then sliding it into a /rank result and treating the percentile and the MinMax score as comparable — they aren't. (3) Trying to track an asset's score over time using /rank — the universe shifts, so a stable percentile may correspond to a deteriorating MinMax score.

When to reach for which: /score for 'is this asset healthy in absolute terms,' /rank for 'rank these peers against each other.' Mixing them is the most common misread. The methodology page at /methodology calls this out alongside the calibration policy: MinMax bounds are versioned with the engine and don't change between runs, so historical /score outputs remain comparable to today's. Percentile scores compare only within the universe they were run against.