gavindiaz/wickra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

F13c: restructure the indicator catalogue into eight families

Browse Source 
The original taxonomy was four classical families plus a statistics group,
with the F1-F12 expansion slotted in as sub-categories. This regroups the
whole 71-indicator catalogue into eight top-level families, each with at
least five members:

  Moving Averages (12), Momentum Oscillators (13), Trend & Directional (9),
  Price Oscillators (5), Volatility & Bands (12), Trailing Stops (5),
  Volume (9), Price Statistics (7).

- Wiki: docs/wiki/indicators/ reorganised into eight family folders; all 71
  indicator pages moved with `git mv`. Every internal cross-link is
  normalised to `../<family>/Indicator-X.md`, each page's `Family` field is
  set to its new family, and two pre-existing `../Indicator-Chaining.md`
  links (should have been `../../`) are corrected. A link check confirms
  every relative wiki link resolves.
- Indicators-Overview.md fully rewritten around the eight families;
  Home.md indicator reference and the README family table follow suit.
- Warmup-Periods.md gains the eight F13 indicators; CHANGELOG records the
  46-indicator expansion (25 -> 71) and the eight-family taxonomy.
- Tests: Node indicators.test.js and Python test_new_indicators.py cover
  all eight new indicators (Node 91/91, Python 117/117 green).

cargo fmt + clippy (core/wickra/data/wasm/node) clean; 508 core tests,
25 data tests and 74 doctests green.
This commit is contained in:
kingchenc
2026-05-22 21:21:56 +02:00
parent 6643f7a81d
commit d2f99efd78
78 changed files with 612 additions and 616 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/wiki/indicators/price-statistics/Indicator-LinRegAngle.md
+143
View File
@@ -0,0 +1,143 @@
# LinRegAngle
> Linear Regression Angle — the slope of the rolling least-squares fit,
> expressed as an angle in degrees.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `f64` (price) |
| Output type | `f64` |
| Output range | `(−90°, +90°)` |
| Default parameters | `period = 14` (Python) |
| Warmup period | `period` |
| Interpretation | Steepness of the trend; sign is direction, magnitude is pitch. |
## Formula
```
LinRegAngle = atan(LinRegSlope) · 180 / π
```
The angle carries exactly the same information as
[`LinRegSlope`](../price-statistics/Indicator-LinRegSlope.md) — positive while price trends up,
negative while it trends down — but maps the unbounded slope through `atan`
onto `(−90°, +90°)`. That bounded, price-unit-free scale makes "how steep is
the trend" comparable at a glance and across instruments. This is TA-Lib's
`LINEARREG_ANGLE`.
## Parameters
`period` — the regression window. Must be at least `2` (a line needs two
points). The Python binding defaults it to `14`; the Rust and Node
constructors require it explicitly.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/linreg_angle.rs`:
```rust
impl Indicator for LinRegAngle {
type Input = f64;
type Output = f64;
// update(&mut self, input: f64) -> Option<f64>
}
```
`LinRegAngle` is a **scalar** indicator: it consumes one `f64` price per step.
Because `Input = f64` it can sit inside a [`Chain`](../../Indicator-Chaining.md).
## Warmup
`LinRegAngle::new(14).warmup_period() == 14`. The first value lands once the
window holds a full `period` prices.
## Edge cases
- **`period < 2`.** Rejected at construction — a regression line is undefined
for fewer than two points.
- **Unit slope.** A series rising by exactly `1` per step has slope `1`, and
`atan(1) = 45°`.
- **Flat series.** A constant input has slope `0` and therefore angle `0`.
- **Reset.** `angle.reset()` clears the rolling regression window.
## Examples
### Rust
```rust
use wickra::{BatchExt, Indicator, LinRegAngle};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut angle = LinRegAngle::new(5)?;
// Closes rising by 1 per step -> slope 1 -> atan(1) = 45 degrees.
let out = angle.batch(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
println!("{:?}", out);
Ok(())
}
```
Output:
```
[None, None, None, None, Some(45.0), Some(45.0)]
```
### Python
```python
import numpy as np
import wickra as ta
angle = ta.LinRegAngle(5)
print(angle.batch(np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])))
```
Output:
```
[ nan nan nan nan 45. 45.]
```
### Node
```javascript
const ta = require('wickra');
const angle = new ta.LinRegAngle(5);
console.log(angle.batch([1, 2, 3, 4, 5, 6]));
```
Output:
```
[ NaN, NaN, NaN, NaN, 45, 45 ]
```
## Interpretation
The angle is read like a slope: sign gives trend direction, magnitude gives
how steeply price is pitched. Because it is bounded to `±90°` it is convenient
for thresholds — e.g. "only trade with the trend while the angle exceeds
`30°`" — and for comparing trend pitch across instruments with different price
scales, which the raw [`LinRegSlope`](../price-statistics/Indicator-LinRegSlope.md) cannot do.
## Common pitfalls
- **Reading degrees as a price quantity.** The angle depends on the chart's
implicit scaling; treat it as a relative steepness gauge, not an absolute.
- **Tiny periods.** `period = 2` reduces the fit to the last difference.
## References
The angle of an ordinary least-squares fit to a rolling price window; matches
TA-Lib's `LINEARREG_ANGLE`.
## See also
- [Indicator-LinRegSlope.md](../price-statistics/Indicator-LinRegSlope.md) — the same fit's slope,
in raw price-per-bar units.
- [Indicator-LinearRegression.md](../price-statistics/Indicator-LinearRegression.md) — the
endpoint of the same rolling fit.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
docs/wiki/indicators/price-statistics/Indicator-LinRegSlope.md
+149
View File
@@ -0,0 +1,149 @@
# LinRegSlope
> Linear Regression Slope — the slope of a rolling ordinary-least-squares
> fit over the last `period` prices.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `f64` (price) |
| Output type | `f64` |
| Output range | unbounded around zero (price units per bar) |
| Default parameters | `period = 14` (Python) |
| Warmup period | `period` |
| Interpretation | How steeply price trends; positive up, negative down, zero flat. |
## Formula
Over the last `period` inputs, indexed `x = 0, 1, …, period − 1`:
```
b = (n·Σxy − Σx·Σy) / (n·Σxx − (Σx)²)
```
`LinRegSlope` fits a straight line to the window by ordinary least squares —
the same fit as [`LinearRegression`](../price-statistics/Indicator-LinearRegression.md) — but
reports the *slope* `b` instead of the endpoint. The slope is in price units
per bar: positive while price trends up, negative while it trends down, near
zero when it is ranging. This is TA-Lib's `LINEARREG_SLOPE`.
## Parameters
`period` — the regression window. Must be at least `2` (a line needs two
points). The Python binding defaults it to `14`; the Rust and Node
constructors require it explicitly.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/linreg_slope.rs`:
```rust
impl Indicator for LinRegSlope {
type Input = f64;
type Output = f64;
// update(&mut self, input: f64) -> Option<f64>
}
```
`LinRegSlope` is a **scalar** indicator: it consumes one `f64` price per step.
Because `Input = f64` it can sit inside a [`Chain`](../../Indicator-Chaining.md).
## Warmup
`LinRegSlope::new(14).warmup_period() == 14`. The first value lands once the
window holds a full `period` prices — on input index `period − 1`.
## Edge cases
- **`period < 2`.** Rejected at construction — a regression line is undefined
for fewer than two points.
- **Perfect line.** Fed a series rising by a fixed step, the slope is exactly
that step (`perfect_line_returns_its_step` pins this).
- **Constant series.** A flat input returns a slope of `0`.
- **Falling series.** A descending input returns a negative slope.
- **Reset.** `ls.reset()` clears the rolling window.
## Examples
### Rust
```rust
use wickra::{BatchExt, Indicator, LinRegSlope};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut ls = LinRegSlope::new(3)?;
// Fit over [1, 2, 9]: the least-squares line is y = 4x, slope 4.
let out = ls.batch(&[1.0, 2.0, 9.0]);
println!("{:?}", out);
Ok(())
}
```
Output:
```
[None, None, Some(4.0)]
```
This matches the `reference_values` test in
`crates/wickra-core/src/indicators/linreg_slope.rs`.
### Python
```python
import numpy as np
import wickra as ta
ls = ta.LinRegSlope(3)
print(ls.batch(np.array([1.0, 2.0, 9.0])))
```
Output:
```
[nan nan 4.]
```
### Node
```javascript
const ta = require('wickra');
const ls = new ta.LinRegSlope(3);
console.log(ls.batch([1, 2, 9]));
```
Output:
```
[ NaN, NaN, 4 ]
```
## Interpretation
`LinRegSlope` is a momentum gauge: its sign is the trend direction and its
magnitude is the trend's steepness in price-per-bar. A slope crossing zero
marks a trend change; a slope that flattens while price still rises warns the
trend is losing pace. Unlike a difference-based oscillator it uses every bar
in the window, so it is less jumpy.
## Common pitfalls
- **Comparing slopes across instruments.** The slope is in the instrument's
own price units per bar — normalise (e.g. divide by price) to compare.
- **Tiny periods.** `period = 2` reduces the slope to the last simple
difference; use a meaningful window.
## References
The slope of an ordinary least-squares fit to a rolling price window; matches
TA-Lib's `LINEARREG_SLOPE`.
## See also
- [Indicator-LinearRegression.md](../price-statistics/Indicator-LinearRegression.md) — the
endpoint of the same rolling fit.
- [Indicator-Mom.md](../momentum-oscillators/Indicator-Mom.md) — raw price-difference
momentum, the unsmoothed cousin.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
docs/wiki/indicators/price-statistics/Indicator-LinearRegression.md
+151
View File
@@ -0,0 +1,151 @@
# LinearRegression
> Linear Regression — the endpoint of a rolling ordinary-least-squares fit
> over the last `period` prices.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `f64` (price) |
| Output type | `f64` |
| Output range | unbounded (price scale) |
| Default parameters | `period = 14` (Python) |
| Warmup period | `period` |
| Interpretation | A low-lag smoothed price — the trend line extrapolated to now. |
## Formula
Over the last `period` inputs, indexed `x = 0, 1, …, period − 1`:
```
b (slope) = (n·Σxy − Σx·Σy) / (n·Σxx − (Σx)²)
a (intercept) = (Σy − b·Σx) / n
LinearReg = a + b·(period − 1)
```
The indicator fits a straight line to the window by ordinary least squares,
then reports that line's value at the most recent bar. Because it
extrapolates the *local trend* forward rather than averaging it away, it lags
a same-period [`Sma`](../moving-averages/Indicator-Sma.md) noticeably less. This is
TA-Lib's `LINEARREG`.
## Parameters
`period` — the regression window. Must be at least `2` (a line needs two
points). The Python binding defaults it to `14`; the Rust and Node
constructors require it explicitly.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/linreg.rs`:
```rust
impl Indicator for LinearRegression {
type Input = f64;
type Output = f64;
// update(&mut self, input: f64) -> Option<f64>
}
```
`LinearRegression` is a **scalar** indicator: it consumes one `f64` price per
step. Because `Input = f64` it can sit inside a [`Chain`](../../Indicator-Chaining.md).
## Warmup
`LinearRegression::new(14).warmup_period() == 14`. The first value lands once
the window holds a full `period` prices — on input index `period − 1`.
## Edge cases
- **`period < 2`.** Rejected at construction — a regression line is undefined
for fewer than two points.
- **Perfect line.** Fed a perfectly linear series, the fit *is* that line, so
the endpoint equals the current value (`perfect_line_returns_current_value`
pins this).
- **Constant series.** A flat input returns that constant.
- **Reset.** `lr.reset()` clears the rolling window.
## Examples
### Rust
```rust
use wickra::{BatchExt, Indicator, LinearRegression};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut lr = LinearRegression::new(3)?;
// Fit over [1, 2, 9]: the least-squares line is y = 4x, endpoint 4·2 = 8.
let out = lr.batch(&[1.0, 2.0, 9.0]);
println!("{:?}", out);
Ok(())
}
```
Output:
```
[None, None, Some(8.0)]
```
This matches the `reference_values` test in
`crates/wickra-core/src/indicators/linreg.rs`.
### Python
```python
import numpy as np
import wickra as ta
lr = ta.LinearRegression(3)
print(lr.batch(np.array([1.0, 2.0, 9.0])))
```
Output:
```
[nan nan 8.]
```
### Node
```javascript
const ta = require('wickra');
const lr = new ta.LinearRegression(3);
console.log(lr.batch([1, 2, 9]));
```
Output:
```
[ NaN, NaN, 8 ]
```
## Interpretation
Read `LinearRegression` as a low-lag moving average: it tracks price more
closely than an SMA of the same period because it projects the window's trend
to the current bar instead of centring on the window. A shorter `period`
hugs price; a longer one is a smoother trend line. Pair it with
[`LinRegSlope`](../price-statistics/Indicator-LinRegSlope.md) to read the same fit's steepness.
## Common pitfalls
- **Confusing it with an SMA.** It is a *projected* fit, not a centred
average, so it leads an SMA of the same period.
- **Tiny periods.** `period = 2` is allowed but the "fit" just passes through
the last two points; use a meaningful window.
## References
Ordinary least-squares linear regression applied to a rolling price window;
the endpoint formulation matches TA-Lib's `LINEARREG`.
## See also
- [Indicator-LinRegSlope.md](../price-statistics/Indicator-LinRegSlope.md) — the slope of the same
rolling fit.
- [Indicator-Sma.md](../moving-averages/Indicator-Sma.md) — the centred average it is
often compared against.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
docs/wiki/indicators/price-statistics/Indicator-MedianPrice.md
+135
View File
@@ -0,0 +1,135 @@
# MedianPrice
> Median Price — the bar's `(high + low) / 2`, the midpoint of its range.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `Candle` (uses `high`, `low`) |
| Output type | `f64` |
| Output range | unbounded (price scale) |
| Default parameters | none (no parameters) |
| Warmup period | `1` |
| Interpretation | The midpoint of the bar's range, ignoring open and close. |
## Formula
```
MedianPrice = (high + low) / 2
```
The median price is the centre of the bar's range — it discards where the bar
opened and closed entirely. It is the price series Bill Williams'
[`AwesomeOscillator`](../momentum-oscillators/Indicator-AwesomeOscillator.md) is built on,
and a useful close substitute when the close is noisy relative to the range.
## Parameters
`MedianPrice` takes **no parameters** — `MedianPrice::new()` in Rust,
`wickra.MedianPrice()` in Python, `new ta.MedianPrice()` in Node.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/median_price.rs`:
```rust
impl Indicator for MedianPrice {
type Input = Candle;
type Output = f64;
// update(&mut self, input: Candle) -> Option<f64>
}
```
`MedianPrice` is a **candle-input** indicator that reads `high` and `low`. In
Python the streaming `update` accepts a 6-tuple or a dict; the batch helper
takes `high`, `low` numpy arrays. Node and WASM expose `update(high, low)` and
the matching `batch`.
## Warmup
`MedianPrice::new().warmup_period() == 1`. It is a stateless per-bar transform
— it emits a value from the very first candle.
## Edge cases
- **No warmup.** Every candle produces a value immediately.
- **Reset.** `mp.reset()` only clears the `is_ready` flag; there is no
rolling state to discard.
## Examples
### Rust
```rust
use wickra::{Candle, Indicator, MedianPrice};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut mp = MedianPrice::new();
let v = mp.update(Candle::new(10.0, 12.0, 8.0, 11.0, 1.0, 0)?);
println!("{:?}", v);
Ok(())
}
```
Output:
```
Some(10.0)
```
`(12 + 8) / 2 = 10`. This matches the `reference_value` test in
`crates/wickra-core/src/indicators/median_price.rs`.
### Python
```python
import numpy as np
import wickra as ta
mp = ta.MedianPrice()
print(mp.batch(np.array([12.0]), np.array([8.0])))
```
Output:
```
[10.]
```
### Node
```javascript
const ta = require('wickra');
const mp = new ta.MedianPrice();
console.log(mp.batch([12], [8]));
```
Output:
```
[ 10 ]
```
## Interpretation
The median price is the most range-centric of the three transforms — it is
blind to the close. Use it when the question is "where did this bar trade?"
rather than "where did it settle?", or as the input to a Bill Williams setup.
## Common pitfalls
- **Expecting the close to matter.** It does not — by definition the median
price ignores both the open and the close.
## References
The Median Price; the `(H + L) / 2` definition is standard (TA-Lib's
`MEDPRICE`).
## See also
- [Indicator-TypicalPrice.md](../price-statistics/Indicator-TypicalPrice.md) — `(H + L + C) / 3`.
- [Indicator-WeightedClose.md](../price-statistics/Indicator-WeightedClose.md) — `(H + L + 2C) / 4`.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
docs/wiki/indicators/price-statistics/Indicator-TypicalPrice.md
+136
View File
@@ -0,0 +1,136 @@
# TypicalPrice
> Typical Price — the bar's `(high + low + close) / 3`, a single
> representative price per candle.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `Candle` (uses `high`, `low`, `close`) |
| Output type | `f64` |
| Output range | unbounded (price scale) |
| Default parameters | none (no parameters) |
| Warmup period | `1` |
| Interpretation | A representative per-bar price; a smoother stand-in for the close. |
## Formula
```
TypicalPrice = (high + low + close) / 3
```
The typical price collapses a full OHLC bar to one number, giving the close
no more weight than the two extremes. It is the price series that
[`Cci`](../momentum-oscillators/Indicator-Cci.md) and [`Mfi`](../momentum-oscillators/Indicator-Mfi.md)
are defined on, and a common input to feed any close-driven indicator when you
want the bar's range reflected in the value.
## Parameters
`TypicalPrice` takes **no parameters** — `TypicalPrice::new()` in Rust,
`wickra.TypicalPrice()` in Python, `new ta.TypicalPrice()` in Node.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/typical_price.rs`:
```rust
impl Indicator for TypicalPrice {
type Input = Candle;
type Output = f64;
// update(&mut self, input: Candle) -> Option<f64>
}
```
`TypicalPrice` is a **candle-input** indicator that reads `high`, `low` and
`close`. In Python the streaming `update` accepts a 6-tuple or a dict; the
batch helper takes `high`, `low`, `close` numpy arrays. Node and WASM expose
`update(high, low, close)` and the matching `batch`.
## Warmup
`TypicalPrice::new().warmup_period() == 1`. It is a stateless per-bar
transform — it emits a value from the very first candle.
## Edge cases
- **No warmup.** Every candle produces a value immediately.
- **Reset.** `tp.reset()` only clears the `is_ready` flag; there is no
rolling state to discard.
## Examples
### Rust
```rust
use wickra::{Candle, Indicator, TypicalPrice};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut tp = TypicalPrice::new();
let v = tp.update(Candle::new(9.0, 12.0, 6.0, 9.0, 1.0, 0)?);
println!("{:?}", v);
Ok(())
}
```
Output:
```
Some(9.0)
```
`(12 + 6 + 9) / 3 = 9`. This matches the `reference_value` test in
`crates/wickra-core/src/indicators/typical_price.rs`.
### Python
```python
import numpy as np
import wickra as ta
tp = ta.TypicalPrice()
print(tp.batch(np.array([12.0]), np.array([6.0]), np.array([9.0])))
```
Output:
```
[9.]
```
### Node
```javascript
const ta = require('wickra');
const tp = new ta.TypicalPrice();
console.log(tp.batch([12], [6], [9]));
```
Output:
```
[ 9 ]
```
## Interpretation
Use it wherever you would use the close but want the bar's range to count —
feeding a moving average, an oscillator, or a band. It is marginally smoother
than the raw close because a wild close is pulled back toward the bar's mid.
## Common pitfalls
- **Feeding it scalar prices.** It needs the full `high`/`low`/`close` bar.
## References
The Typical Price (also "pivot price"); the `(H + L + C) / 3` definition is
standard (StockCharts, TA-Lib's `TYPPRICE`).
## See also
- [Indicator-MedianPrice.md](../price-statistics/Indicator-MedianPrice.md) — `(H + L) / 2`.
- [Indicator-WeightedClose.md](../price-statistics/Indicator-WeightedClose.md) — `(H + L + 2C) / 4`.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
docs/wiki/indicators/price-statistics/Indicator-WeightedClose.md
+136
View File
@@ -0,0 +1,136 @@
# WeightedClose
> Weighted Close — the bar's `(high + low + 2·close) / 4`, a per-bar price
> that gives the close double weight.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `Candle` (uses `high`, `low`, `close`) |
| Output type | `f64` |
| Output range | unbounded (price scale) |
| Default parameters | none (no parameters) |
| Warmup period | `1` |
| Interpretation | A representative per-bar price that leans on the close. |
## Formula
```
WeightedClose = (high + low + 2·close) / 4
```
Like the [`TypicalPrice`](../price-statistics/Indicator-TypicalPrice.md), the weighted close
collapses an OHLC bar to one number — but it counts the close twice, so the
result sits closer to where the bar settled than to its range. Reach for it
when the closing print carries more signal than the extremes.
## Parameters
`WeightedClose` takes **no parameters** — `WeightedClose::new()` in Rust,
`wickra.WeightedClose()` in Python, `new ta.WeightedClose()` in Node.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/weighted_close.rs`:
```rust
impl Indicator for WeightedClose {
type Input = Candle;
type Output = f64;
// update(&mut self, input: Candle) -> Option<f64>
}
```
`WeightedClose` is a **candle-input** indicator that reads `high`, `low` and
`close`. In Python the streaming `update` accepts a 6-tuple or a dict; the
batch helper takes `high`, `low`, `close` numpy arrays. Node and WASM expose
`update(high, low, close)` and the matching `batch`.
## Warmup
`WeightedClose::new().warmup_period() == 1`. It is a stateless per-bar
transform — it emits a value from the very first candle.
## Edge cases
- **No warmup.** Every candle produces a value immediately.
- **Reset.** `wc.reset()` only clears the `is_ready` flag; there is no
rolling state to discard.
## Examples
### Rust
```rust
use wickra::{Candle, Indicator, WeightedClose};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut wc = WeightedClose::new();
let v = wc.update(Candle::new(10.0, 12.0, 8.0, 11.0, 1.0, 0)?);
println!("{:?}", v);
Ok(())
}
```
Output:
```
Some(10.5)
```
`(12 + 8 + 2·11) / 4 = 42 / 4 = 10.5`. This matches the `reference_value`
test in `crates/wickra-core/src/indicators/weighted_close.rs`.
### Python
```python
import numpy as np
import wickra as ta
wc = ta.WeightedClose()
print(wc.batch(np.array([12.0]), np.array([8.0]), np.array([11.0])))
```
Output:
```
[10.5]
```
### Node
```javascript
const ta = require('wickra');
const wc = new ta.WeightedClose();
console.log(wc.batch([12], [8], [11]));
```
Output:
```
[ 10.5 ]
```
## Interpretation
The weighted close sits on the spectrum between the raw close and the
[`TypicalPrice`](../price-statistics/Indicator-TypicalPrice.md): closer to the close, but still
nudged by the bar's range. Use it as a drop-in close replacement when you want
the settlement to dominate without ignoring the extremes entirely.
## Common pitfalls
- **Feeding it scalar prices.** It needs the full `high`/`low`/`close` bar.
## References
The Weighted Close; the `(H + L + 2C) / 4` definition is standard (TA-Lib's
`WCLPRICE`).
## See also
- [Indicator-TypicalPrice.md](../price-statistics/Indicator-TypicalPrice.md) — `(H + L + C) / 3`.
- [Indicator-MedianPrice.md](../price-statistics/Indicator-MedianPrice.md) — `(H + L) / 2`.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
docs/wiki/indicators/price-statistics/Indicator-ZScore.md
+139
View File
@@ -0,0 +1,139 @@
# ZScore
> Z-Score — how many standard deviations the latest price sits from its
> rolling mean.
## Quick reference
| Field | Value |
|-------|-------|
| Family | Price Statistics |
| Input type | `f64` (price) |
| Output type | `f64` |
| Output range | unbounded around zero (standard deviations) |
| Default parameters | `period = 20` (Python) |
| Warmup period | `period` |
| Interpretation | Large magnitude = stretched; a return toward `0` = reversion. |
## Formula
```
ZScore = (price − SMA(price, n)) / population_stddev(price, n)
```
The Z-Score normalises price against its own recent behaviour: it subtracts
the rolling mean and divides by the rolling population standard deviation. A
reading of `+2` means price is two standard deviations above its `n`-bar
average — statistically stretched to the upside; `−2` is the mirror. It is the
standard input to mean-reversion strategies.
## Parameters
`period` — the rolling window for the mean and standard deviation. The Python
binding defaults it to `20`; the Rust and Node constructors require it.
## Inputs / Outputs
From `crates/wickra-core/src/indicators/z_score.rs`:
```rust
impl Indicator for ZScore {
type Input = f64;
type Output = f64;
// update(&mut self, input: f64) -> Option<f64>
}
```
`ZScore` is a **scalar** indicator: it consumes one `f64` price per step.
Because `Input = f64` it can sit inside a [`Chain`](../../Indicator-Chaining.md).
## Warmup
`ZScore::new(20).warmup_period() == 20`. The first value lands once the window
holds a full `period` prices.
## Edge cases
- **Zero dispersion.** A flat window has a zero standard deviation; `ZScore`
is defined as `0` rather than dividing by zero.
- **Rising series.** A monotonically rising price always scores above its
trailing mean (positive).
- **Reset.** `z.reset()` clears the rolling window.
## Examples
### Rust
```rust
use wickra::{BatchExt, Indicator, ZScore};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut z = ZScore::new(2)?;
// Window [1, 3]: mean 2, population stddev 1; latest 3 -> (3 - 2) / 1.
println!("{:?}", z.batch(&[1.0, 3.0]));
Ok(())
}
```
Output:
```
[None, Some(1.0)]
```
### Python
```python
import numpy as np
import wickra as ta
z = ta.ZScore(2)
print(z.batch(np.array([1.0, 3.0])))
```
Output:
```
[nan 1.]
```
### Node
```javascript
const ta = require('wickra');
const z = new ta.ZScore(2);
console.log(z.batch([1, 3]));
```
Output:
```
[ NaN, 1 ]
```
## Interpretation
Z-Score is the workhorse of mean-reversion: a common rule enters against the
move when `|ZScore| > 2` and exits as it crosses back through `0`. Read
together with a trend filter — a high Z-Score in a strong trend is often
continuation, not exhaustion, so the reversion edge is best in ranging
regimes.
## Common pitfalls
- **Trading extremes blindly.** A trending market can hold a high Z-Score for
a long time; pair it with a regime filter.
- **Tiny periods.** A short window makes the mean and stddev jumpy.
## References
The standard statistical Z-Score (standard score) applied to a rolling price
window.
## See also
- [Indicator-StdDev.md](../volatility-bands/Indicator-StdDev.md) — the rolling
standard deviation in the denominator.
- [Indicator-LinearRegression.md](../price-statistics/Indicator-LinearRegression.md) — another
rolling statistical fit.
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.