F13c: restructure the indicator catalogue into eight families
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:
@@ -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](../trend-directional/Indicator-VerticalHorizontalFilter.md)
|
||||
— the same trending-vs-ranging question on an inverted scale.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user