ReturnDistribution
How far price moved over the last N bars, and how unusual that move is against recent moves of the same length.
Measures the change in close over the last return_bars bars as a fraction, then ranks that change against the last max_history changes of the same length. It outputs three numbers: the raw change, its percentile rank among those changes (0 to 1, signed, so high means an unusually large rise), and its z-score, the number of standard deviations it sits from their average. The percentile and z-score stay blank until min_samples changes are stored.
How to read it
- All three outputs sit in their own panes below the candles, not on the price line, and none is an on/off signal.
- Lookback return is a fraction, so 0.001 is a 0.1% move. In the sample 90% of values sit within about ±0.09%, and the median is exactly zero, so it reads flat for long stretches.
- Percentile runs 0 to 1 and is signed: near 0.95 means the move is larger upward than 95% of recent moves of that length, near 0.05 larger downward. It describes the past move, not what comes next.
- Z-score is the same move in standard deviations from the recent average. Beyond ±2 is unusual; in the sample 90% of values sit between about -1.4 and +1.5.
What it outputs
- Lookback return
- The change in close over the last return_bars bars, as a fraction (0.001 is 0.1%).
- Percentile
- Where this move ranks among recent moves of the same length: near 0 is the largest fall, near 1 the largest rise.
- Z-score
- How many standard deviations this move sits from the average of recent moves of the same length.
Settings
- return_bars
- Bars the move is measured over; 10 means the last 10 minutes on one-minute bars. Raising it looks at slower, larger moves and delays the first value by that many bars. Lowering it reacts to short wiggles and shows more noise.
- min_samples
- Stored moves needed before the percentile and z-score appear. Raising it leaves those two outputs blank for longer at the start of the chart. Lowering it shows them sooner, ranked against a thin history that swings. The lookback return is unaffected.
- max_history
- Most recent moves kept as the reference set, 2000 by default. Raising it ranks against a longer, steadier history that adapts slowly. Lowering it ranks against only the latest bars, so the percentile and z-score adapt fast but react to noise.
Pitfalls
- Flat moves rank high: the median move in the sample is exactly zero, and a percentile counts every tied value at or below it, so a flat move ranks at or above the middle.
- The current move is already in the history it is ranked against, so it nudges the percentile and z-score toward the middle. The effect is largest when max_history or min_samples is small.
- One spike inflates the spread for as long as it stays in the window: sample z-scores reach about +9 and -10.7, so after a large move the z-score of ordinary moves shrinks for up to max_history bars.