Tool
Z-Score / Stretch
calc.zscore
Inputs
The number line being measured for stretch (usually the close).
The reference centre the price is compared against (e.g. a moving average).
The unit the gap is divided by — a standard-deviation line for sigma units, or an ATR line for volatility units.
Outputs
A bundle whose key value is the z-score centred on 0: positive means price is above the mean, negative means below, and the magnitude is the stretch in the chosen units.
Z-Score measures how far price has stretched from a mean, expressed in standard units so it works across symbols and timeframes. A reading of +2 means price is two units above the mean; −2 means two units below. It is the core gauge for mean-reversion setups.
How it works
The node takes the gap between input `price` and input `mean`, then divides by input `scale` — the units of that scale are chosen by `units` (statistical sigma or ATR). `clamp_extreme` caps the result so a rare spike can’t blow the score out to an unusable extreme.
Modes
Divides the gap by the statistical standard deviation, so the score is a classic z-score in σ units.
When to use: Pick sigma for textbook statistical extremes when the mean comes from a moving average and scale from its rolling standard deviation.
Divides the gap by ATR, so the score is measured in average-true-range units instead of standard deviations.
When to use: Pick ATR when you size and reason in volatility units — the stretch then reads in the same terms as your ATR-based stops.
Configuration
Which unit the stretch is measured in: ‘sigma’ divides by the statistical standard deviation (a classic z-score), ‘atr’ divides by average true range (a volatility-based stretch).
Caps the score at plus or minus this value so a one-off spike cannot push it to an extreme that swamps your thresholds. Set 0 (or leave off) to disable clamping; 4 is a sensible cap.
Connects to
Examples
- Mean reversion: in sigma units, fade longs when the z-score drops below −2 (price stretched well below its mean) and exit as it returns toward 0.
- Volatility-aware filter: in ATR units, only act on a stretch beyond ±2 so the threshold adapts as market volatility expands and contracts.
Common mistakes
- Feeding a flat or near-zero scale line — dividing by a tiny standard deviation or ATR makes the score explode; clamp_extreme guards against this.
- Mixing units between the strategy and the threshold — a ±2 gate means very different things in sigma versus ATR units, so set both to match.