The seven components
of match similarity scoring.

Why one number isn't enough

A historical match is reported with a single similarity_score — but that number is a composite. Two setups can land at the same overall score for structurally different reasons: one because the price shapes track closely but volatility regimes differ, another because volatility and trend align but the actual price path looks different. Collapsing the comparison into one figure without explaining what feeds it would hide exactly the information a quant or a model reasoning over the data needs to judge whether a match is actually relevant to the question being asked.

This is why the engine computes seven independent distance components for every comparison, then combines them into the final score:

Each component answers a narrower, more specific question about how alike two price windows are. Together they cover the dimensions that matter for deciding whether a historical setup is genuinely comparable to a current one, or only superficially similar — and they're all exposed individually in matches[].score_components:

Shape distance

Shape distance measures how closely the normalized price path of the historical window tracks the current benchmark window — the actual geometry of the move, independent of scale. Two symbols at very different price levels can still have a near-identical shape distance if the relative path (the sequence of ups, downs, and inflection points) tracks closely once normalized.

This is the component closest to what a trader visually checks when eyeballing a chart for "does this look like what's happening now" — except computed precisely across the full window rather than judged by eye.

Volatility distance

Volatility distance compares how much the price moved around within each window, independent of direction. A historical setup can have a similar shape but a much calmer or much more turbulent volatility profile — and that difference matters, because the same price pattern playing out in a low-volatility regime carries different risk and reliability than the identical pattern playing out during a volatility spike.

This component exists specifically so a match isn't scored as strong purely on shape if the volatility context was meaningfully different.

Trend distance

Trend distance measures the directional bias of the window — whether the broader move over the period was upward, downward, or flat — independent of the smaller fluctuations shape distance captures. A setup can have a similar short-term shape while sitting inside a very different underlying trend, and trend distance is what separates those cases.

This matters because the same short-term pattern can resolve differently depending on whether it's occurring within an uptrend or a downtrend — the broader trend context changes what the pattern means.

Range position distance

Range position distance compares where price sits relative to its recent trading range — near a high, near a low, or in the middle — at the point the window is being evaluated. Two setups can have similar shape and volatility but sit in very different positions within their respective ranges, which changes the structural interpretation of the setup considerably.

This is a dimension that's easy to overlook when comparing price action visually but is straightforward to quantify and compare directly.

Volume distance

Volume distance compares the trading volume profile across the window — not just average volume, but how volume behaved relative to price movement. A price pattern accompanied by rising volume reads differently than the same pattern on declining volume, and volume distance is what allows the engine to distinguish between those cases rather than treating volume as irrelevant background data.

Risk distance

Risk distance compares the drawdown and adverse-movement characteristics within each window — essentially, how much risk was embedded in the path itself before any forward outcome is considered. This is distinct from volatility distance: a window can have moderate volatility but still carry a meaningfully different risk profile depending on the shape of its drawdowns.

This component exists because two windows can look statistically similar in aggregate while having very different downside characteristics along the way.

Price correlation distance

Price correlation distance measures the direct statistical correlation between the historical price series and the current benchmark series. Where shape distance captures the geometric similarity of the normalized paths, price correlation distance captures a more direct statistical relationship between the two price series themselves.

The two components are related but not redundant — a match can score well on one without scoring identically on the other, and combining both gives a more complete picture than either alone.

Why all seven, not a subset

Each component answers a different question — and a match can score well on some of these and poorly on others, which is precisely the information that distinguishes a genuinely comparable historical setup from one that only resembles the current one on the surface.

Reducing this to a single dimension — say, shape alone, or price correlation alone — would produce matches that look superficially similar while differing in ways that matter for interpreting what happened next.

What this means for interpreting a match

When reviewing a historical match, the individual distance components are more informative than the aggregate similarity score alone. A match with a strong similarity score driven mostly by shape and price correlation, but a weak volume distance, is telling a different story than a match where all seven components are uniformly strong. Both might report similar overall scores. They are not equally trustworthy evidence for the same question.