F13a: add Accelerator Oscillator, Balance of Power, Choppiness Index and Vertical Horizontal Filter

First half of the eight indicators that fill out the new family taxonomy. - Rust core: accelerator_oscillator.rs (AcceleratorOscillator — AO minus a short SMA of itself), balance_of_power.rs (BalanceOfPower — per-bar (close-open)/(high-low)), choppiness_index.rs (ChoppinessIndex — summed true range over the high-low span, log-scaled) and vertical_horizontal_filter.rs (VerticalHorizontalFilter — net move over total move). Each with a full Indicator impl, runnable doctest and reference / property / warmup / reset / batch==streaming tests. - Python / Node / WASM: classes wired through all three bindings (BalanceOfPower carries an explicit open column; VHF rides the scalar macros) plus .pyi stubs and __init__.py / __all__ entries. - Wiki: four new Indicator-*.md pages. The eight-family taxonomy restructure (Overview / Home / README / folder layout) lands in F13c once F13b's four indicators are in. cargo fmt + clippy (core/wickra/data/wasm/node) clean; 481 core tests, 25 data tests and 70 doctests green.
2026-05-22 20:57:52 +02:00
parent 27f37f5347
commit e452d35a27
16 changed files with 2001 additions and 11 deletions
@@ -0,0 +1,144 @@
+# AcceleratorOscillator
+
+> Accelerator Oscillator (AC) — Bill Williams' measure of how fast
+> momentum itself is changing.
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Price Oscillators |
+| Input type | `Candle` (uses `high`, `low`) |
+| Output type | `f64` |
+| Output range | unbounded around zero |
+| Default parameters | `ao_fast = 5`, `ao_slow = 34`, `signal_period = 5` (Python) |
+| Warmup period | `ao_slow + signal_period − 1` |
+| Interpretation | Acceleration of momentum; zero-line crossings lead the Awesome Oscillator. |
+
+## Formula
+
+```
+AO = SMA(median, ao_fast) − SMA(median, ao_slow)   (the Awesome Oscillator)
+AC = AO − SMA(AO, signal_period)
+```
+
+Where the [`AwesomeOscillator`](Indicator-AwesomeOscillator.md) measures
+momentum, the Accelerator measures the *change* in momentum — it is the AO
+minus a short moving average of itself. Because acceleration leads speed, the
+`AC` tends to turn before the `AO` does. Bill Williams' classic configuration
+is the `(5, 34)` AO with a `5`-period signal average.
+
+## Parameters
+
+- `ao_fast`, `ao_slow` — the underlying Awesome Oscillator periods (`5`, `34`).
+- `signal_period` — the moving average of the AO subtracted from it (`5`).
+
+`AcceleratorOscillator::classic()` returns the `(5, 34, 5)` configuration.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/accelerator_oscillator.rs`:
+
+```rust
+impl Indicator for AcceleratorOscillator {
+    type Input = Candle;
+    type Output = f64;
+    // update(&mut self, input: Candle) -> Option<f64>
+}
+```
+
+It is a **candle-input** indicator — the inner Awesome Oscillator reads the
+median price `(high + low) / 2`. Python's 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
+
+`AcceleratorOscillator::classic().warmup_period() == 38`. The AO first emits at
+candle `ao_slow`; the signal average then needs `signal_period` AO values.
+
+## Edge cases
+
+- **Flat market.** A flat series gives `AO = 0`, so `AC = 0` throughout.
+- **`ao_fast >= ao_slow`.** Rejected at construction.
+- **Reset.** `ac.reset()` clears the AO and the signal average.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{BatchExt, Candle, Indicator, AcceleratorOscillator};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut ac = AcceleratorOscillator::classic();
+    let candles: Vec<Candle> = (0..60)
+        .map(|i| Candle::new(10.0, 11.0, 9.0, 10.0, 1.0, i).unwrap())
+        .collect();
+    println!("{:?}", ac.batch(&candles).last().unwrap());
+    Ok(())
+}
+```
+
+Output:
+
+```
+Some(0.0)
+```
+
+A flat market produces a flat AO and therefore a zero Accelerator.
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+ac = ta.AcceleratorOscillator(5, 34, 5)
+n = 60
+print(ac.batch(np.full(n, 11.0), np.full(n, 9.0))[-1])
+```
+
+Output:
+
+```
+0.0
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const ac = new ta.AcceleratorOscillator(5, 34, 5);
+const out = ac.batch(Array(60).fill(11), Array(60).fill(9));
+console.log(out[out.length - 1]);
+```
+
+Output:
+
+```
+0
+```
+
+## Interpretation
+
+Trade the Accelerator like a momentum-acceleration gauge: bars rising above
+the zero line mean momentum is building, bars falling below mean it is fading.
+Because it leads the Awesome Oscillator, a colour change in the AC is an early
+warning that the AO — and price momentum — is about to turn.
+
+## Common pitfalls
+
+- **Reading the level.** Only the sign and the slope matter; the magnitude
+  scales with the instrument.
+- **Feeding it scalar prices.** It needs the `high`/`low` bar.
+
+## References
+
+Bill Williams' Accelerator Oscillator, from *Trading Chaos*.
+
+## See also
+
+- [Indicator-AwesomeOscillator.md](Indicator-AwesomeOscillator.md) — the
+  momentum oscillator the Accelerator is built on.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
@@ -0,0 +1,138 @@
+# BalanceOfPower
+
+> Balance of Power (BOP) — where the bar closed within its range relative
+> to where it opened.
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Price Oscillators |
+| Input type | `Candle` (uses `open`, `high`, `low`, `close`) |
+| Output type | `f64` |
+| Output range | `[−1, +1]` |
+| Default parameters | none (no parameters) |
+| Warmup period | `1` |
+| Interpretation | Intrabar buyer/seller control; `+1` buyers, `−1` sellers. |
+
+## Formula
+
+```
+BOP = (close − open) / (high − low)
+```
+
+Balance of Power asks a single question per bar: did buyers or sellers win it?
+A bar that opened on its low and closed on its high scores `+1` (buyers in
+total control); the mirror image scores `−1`. It is a stateless per-bar
+reading. A zero-range bar carries no information and yields `0`.
+
+## Parameters
+
+`BalanceOfPower` takes **no parameters** — `BalanceOfPower::new()` in Rust,
+`wickra.BalanceOfPower()` in Python, `new ta.BalanceOfPower()` in Node.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/balance_of_power.rs`:
+
+```rust
+impl Indicator for BalanceOfPower {
+    type Input = Candle;
+    type Output = f64;
+    // update(&mut self, input: Candle) -> Option<f64>
+}
+```
+
+`BalanceOfPower` is a **candle-input** indicator that reads all four of
+`open`, `high`, `low`, `close`. Python's streaming `update` accepts a 6-tuple
+or a dict; the batch helper takes `open`, `high`, `low`, `close` numpy arrays.
+Node and WASM expose `update(open, high, low, close)` and the matching
+`batch`.
+
+## Warmup
+
+`BalanceOfPower::new().warmup_period() == 1`. It is a stateless per-bar
+transform — it emits a value from the very first candle.
+
+## Edge cases
+
+- **Zero-range bar.** `high == low` yields `0` instead of dividing by zero.
+- **Close on high, open on low.** Scores exactly `+1`.
+- **Reset.** `bop.reset()` only clears the `is_ready` flag.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{Candle, Indicator, BalanceOfPower};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut bop = BalanceOfPower::new();
+    // open 10, high 14, low 10, close 12 -> (12 - 10) / (14 - 10) = 0.5.
+    let v = bop.update(Candle::new(10.0, 14.0, 10.0, 12.0, 1.0, 0)?);
+    println!("{:?}", v);
+    Ok(())
+}
+```
+
+Output:
+
+```
+Some(0.5)
+```
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+bop = ta.BalanceOfPower()
+print(bop.batch(
+    np.array([10.0]), np.array([14.0]), np.array([10.0]), np.array([12.0])
+))
+```
+
+Output:
+
+```
+[0.5]
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const bop = new ta.BalanceOfPower();
+console.log(bop.batch([10], [14], [10], [12]));
+```
+
+Output:
+
+```
+[ 0.5 ]
+```
+
+## Interpretation
+
+A BOP holding above zero says buyers are consistently winning the bars — a
+healthy uptrend; below zero is the seller's mirror. Because the raw per-bar
+value is noisy, it is commonly smoothed with a short moving average before
+trading the zero-line crossings, or read for divergence against price.
+
+## Common pitfalls
+
+- **Using the raw value as a trend signal.** Per-bar BOP whipsaws; smooth it.
+- **Feeding it scalar prices.** It needs the full OHLC bar — including `open`.
+
+## References
+
+Balance of Power, popularised by Igor Livshin; the `(close − open) /
+(high − low)` definition is the standard one.
+
+## See also
+
+- [Indicator-AwesomeOscillator.md](Indicator-AwesomeOscillator.md) — another
+  Bill Williams-era price oscillator.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
@@ -0,0 +1,146 @@
+# ChoppinessIndex
+
+> Choppiness Index — is the market trending or just chopping sideways?
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Trend & Directional |
+| Input type | `Candle` (uses `high`, `low`, `close`) |
+| Output type | `f64` |
+| Output range | `[0, 100]` (typical) |
+| Default parameters | `period = 14` (Python) |
+| Warmup period | `period` |
+| Interpretation | High = choppy/ranging, low = trending; `61.8` / `38.2` thresholds. |
+
+## Formula
+
+```
+CI = 100 · log10( Σ(TR, n) / (highest_high(n) − lowest_low(n)) ) / log10(n)
+```
+
+The ratio compares the distance price *actually travelled* (the summed true
+range) with the *net ground it covered* (the high-low span of the window). A
+clean trend travels almost exactly its span, so the ratio is near `1` and `CI`
+near `0`; a choppy market criss-crosses far more than its span, so the ratio
+is large and `CI` climbs toward `100`. The conventional reading is `CI > 61.8`
+ranging, `CI < 38.2` trending.
+
+## Parameters
+
+`period` — the lookback window. Must be at least `2` (the `log10(period)`
+denominator is zero for `period == 1`). The Python binding defaults it to `14`.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/choppiness_index.rs`:
+
+```rust
+impl Indicator for ChoppinessIndex {
+    type Input = Candle;
+    type Output = f64;
+    // update(&mut self, input: Candle) -> Option<f64>
+}
+```
+
+`ChoppinessIndex` is a **candle-input** indicator that reads `high`, `low` and
+`close` (the close drives the true range across bar gaps). Python's 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
+
+`ChoppinessIndex::new(14).warmup_period() == 14`. The first value lands once
+the window holds a full `period` bars.
+
+## Edge cases
+
+- **Flat window.** A window with `high == low` everywhere has a zero span;
+  `CI` is defined as `100` (maximal choppiness).
+- **Steady trend.** A one-directional march reads well below `50`.
+- **`period < 2`.** Rejected at construction.
+- **Reset.** `ci.reset()` clears the true-range and high/low windows.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{BatchExt, Candle, Indicator, ChoppinessIndex};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut ci = ChoppinessIndex::new(2)?;
+    // Two H=11 L=9 C=10 bars: ΣTR = 4, span = 2 -> CI = 100·log10(2)/log10(2).
+    let out = ci.batch(&[
+        Candle::new(10.0, 11.0, 9.0, 10.0, 1.0, 0)?,
+        Candle::new(10.0, 11.0, 9.0, 10.0, 1.0, 1)?,
+    ]);
+    println!("{:?}", out);
+    Ok(())
+}
+```
+
+Output:
+
+```
+[None, Some(100.0)]
+```
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+ci = ta.ChoppinessIndex(2)
+high = np.array([11.0, 11.0])
+low = np.array([9.0, 9.0])
+close = np.array([10.0, 10.0])
+print(ci.batch(high, low, close))
+```
+
+Output:
+
+```
+[ nan 100.]
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const ci = new ta.ChoppinessIndex(2);
+console.log(ci.batch([11, 11], [9, 9], [10, 10]));
+```
+
+Output:
+
+```
+[ NaN, 100 ]
+```
+
+## Interpretation
+
+The Choppiness Index is not directional — it does not say *which way* price is
+going, only *whether* it is going anywhere. Use it as a regime filter: above
+`61.8` favour mean-reversion / range tactics; below `38.2` favour
+trend-following. It pairs naturally with a directional indicator that picks
+the side once a trend is confirmed.
+
+## Common pitfalls
+
+- **Expecting a direction.** It has none — combine it with a trend indicator.
+- **Tiny periods.** `period = 2` is allowed but noisy; `14` is conventional.
+
+## References
+
+E. W. Dreiss' Choppiness Index; the summed-true-range formulation here is the
+standard one.
+
+## See also
+
+- [Indicator-VerticalHorizontalFilter.md](Indicator-VerticalHorizontalFilter.md)
+  — the same trending-vs-ranging question on an inverted scale.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
@@ -0,0 +1,140 @@
+# VerticalHorizontalFilter
+
+> Vertical Horizontal Filter (VHF) — net distance covered divided by total
+> distance walked; a trend-versus-range gauge.
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Trend & Directional |
+| Input type | `f64` (close price) |
+| Output type | `f64` |
+| Output range | `[0, 1]` |
+| Default parameters | `period = 28` (Python) |
+| Warmup period | `period + 1` |
+| Interpretation | Near `1` = trending, near `0` = choppy. |
+
+## Formula
+
+```
+VHF = (highest_close(n) − lowest_close(n)) / Σ|close − close_prev|(n)
+```
+
+The numerator is the *net* distance price covered over the window; the
+denominator is the *total* distance it walked. Their ratio lives in `[0, 1]`:
+a clean trend walks almost only in its net direction, so `VHF` approaches `1`;
+a choppy market doubles back constantly, inflating the denominator and pushing
+`VHF` toward `0`. It answers the same question as the
+[`ChoppinessIndex`](Indicator-ChoppinessIndex.md) on an inverted scale.
+
+## Parameters
+
+`period` — the lookback window. The Python binding defaults it to `28`; the
+Rust and Node constructors require it explicitly.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/vertical_horizontal_filter.rs`:
+
+```rust
+impl Indicator for VerticalHorizontalFilter {
+    type Input = f64;
+    type Output = f64;
+    // update(&mut self, input: f64) -> Option<f64>
+}
+```
+
+`VerticalHorizontalFilter` is a **scalar** indicator: it consumes one `f64`
+close per step. Because `Input = f64` it can sit inside a
+[`Chain`](../../Indicator-Chaining.md).
+
+## Warmup
+
+`VerticalHorizontalFilter::new(28).warmup_period() == 29`. The high/low window
+fills at `period` closes, but the `period`-th difference needs one extra input
+because the first close has nothing to diff against.
+
+## Edge cases
+
+- **Flat series.** A window that walked nowhere has a zero denominator; `VHF`
+  is defined as `0`.
+- **Pure trend.** A series rising by a fixed step reads `(period − 1) / period`.
+- **Choppy series.** An oscillating series reads near `0`.
+- **Reset.** `vhf.reset()` clears the close and difference windows.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{BatchExt, Indicator, VerticalHorizontalFilter};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut vhf = VerticalHorizontalFilter::new(5)?;
+    // Closes 1..6: each diff is 1 (Σ = 5), the 5-close span is 4 -> 4/5.
+    let out = vhf.batch(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
+    println!("{:?}", out);
+    Ok(())
+}
+```
+
+Output:
+
+```
+[None, None, None, None, None, Some(0.8)]
+```
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+vhf = ta.VerticalHorizontalFilter(5)
+print(vhf.batch(np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])))
+```
+
+Output:
+
+```
+[ nan  nan  nan  nan  nan 0.8]
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const vhf = new ta.VerticalHorizontalFilter(5);
+console.log(vhf.batch([1, 2, 3, 4, 5, 6]));
+```
+
+Output:
+
+```
+[ NaN, NaN, NaN, NaN, NaN, 0.8 ]
+```
+
+## Interpretation
+
+Use the VHF as a regime filter: a high, rising VHF says a trend is in force —
+favour trend-following entries; a low VHF says price is ranging — favour
+mean-reversion. A VHF turning down from a high level is an early hint the
+trend is losing its grip.
+
+## Common pitfalls
+
+- **Expecting a direction.** Like the Choppiness Index it is non-directional —
+  pair it with a trend indicator.
+- **Reading a single bar.** It is a regime gauge; read its level and slope.
+
+## References
+
+Adam White's Vertical Horizontal Filter; the net-over-total formulation here
+is the standard one.
+
+## See also
+
+- [Indicator-ChoppinessIndex.md](Indicator-ChoppinessIndex.md) — the same
+  trending-vs-ranging question on an inverted `[0, 100]` scale.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.