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:
kingchenc
@@ -0,0 +1,143 @@
|
||||
# NATR
|
||||
|
||||
> Normalized Average True Range — ATR expressed as a percentage of price, so
|
||||
> volatility is comparable across instruments.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Volatility & Bands |
|
||||
| Input type | `Candle` (uses `high`, `low`, `close`) |
|
||||
| Output type | `f64` |
|
||||
| Output range | `[0, ∞)` (percent) |
|
||||
| Default parameters | `period = 14` (Python) |
|
||||
| Warmup period | `period` |
|
||||
| Interpretation | Average true range as a percent of the close. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
NATR = 100 · ATR(period) / close
|
||||
```
|
||||
|
||||
[`Atr`](../volatility-bands/Indicator-Atr.md) measures volatility in raw price units — a `2.0`
|
||||
ATR is large on a $10 stock and tiny on a $5000 index. Dividing by the
|
||||
current close converts it to a percentage, so a NATR of `2.0` always
|
||||
means "the average true range is 2 % of price". That makes NATR readings
|
||||
comparable across a portfolio, and stop or position-size rules expressed
|
||||
as a NATR multiple behave consistently regardless of price level.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|----------|---------|---------------|-------------|-------------|
|
||||
| `period` | `usize` | `14` (Python) | `>= 1` | Wilder smoothing period of the underlying ATR. `0` errors with `Error::PeriodZero`. |
|
||||
|
||||
The Python binding defaults `period` to `14`.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/natr.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for Natr {
|
||||
type Input = Candle;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: Candle) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
`NATR` is a **candle-input** indicator: it 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 `batch(high, low, close)`.
|
||||
|
||||
## Warmup
|
||||
|
||||
`Natr::new(period).warmup_period() == period` — identical to the
|
||||
underlying `Atr`, which is Wilder-seeded over `period` true ranges.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Flat market.** A market with no range has `ATR = 0`, so `NATR = 0`
|
||||
(`flat_market_yields_zero` pins this).
|
||||
- **Zero close.** NATR is undefined against a `0.0` close; the indicator
|
||||
reports `0.0` for that bar.
|
||||
- **Identity.** NATR equals `100 · ATR / close` bar for bar
|
||||
(`natr_is_atr_over_close_as_percent` pins this).
|
||||
- **Reset.** `natr.reset()` clears the underlying ATR.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Candle, Indicator, Natr};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut natr = Natr::new(14)?;
|
||||
let candles: Vec<Candle> = (0..40)
|
||||
.map(|i| {
|
||||
let p = 100.0 + f64::from(i);
|
||||
Candle::new(p, p + 2.0, p - 2.0, p, 10.0, i64::from(i)).unwrap()
|
||||
})
|
||||
.collect();
|
||||
let out = natr.batch(&candles);
|
||||
println!("warmup_period = {}", natr.warmup_period());
|
||||
println!("last = {:?}", out.last().unwrap());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
natr = ta.NATR(14)
|
||||
high = np.arange(102.0, 142.0)
|
||||
low = high - 4.0
|
||||
close = high - 2.0
|
||||
print(natr.batch(high, low, close)[-1])
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const natr = new ta.NATR(14);
|
||||
const high = Array.from({ length: 40 }, (_, i) => 102 + i);
|
||||
const low = high.map((h) => h - 4);
|
||||
const close = high.map((h) => h - 2);
|
||||
console.log(natr.batch(high, low, close).at(-1));
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`Natr` is the tool of choice whenever an ATR-based rule must work across
|
||||
instruments or across long stretches of time where the price level
|
||||
drifts. A volatility filter like "skip entries when NATR > 5" or a stop
|
||||
at "entry − 3 × NATR %" stays meaningful on any symbol. Use raw
|
||||
[`Atr`](../volatility-bands/Indicator-Atr.md) only when you specifically want the answer in
|
||||
price units (e.g. to place a stop a fixed number of points away).
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Feeding it scalar prices.** It needs `high`/`low`/`close`.
|
||||
- **Confusing it with ATR.** NATR is a percentage; an ATR-multiple stop
|
||||
and a NATR-multiple stop are different distances.
|
||||
|
||||
## References
|
||||
|
||||
NATR is the percentage-normalised ATR as implemented by TA-Lib (`NATR`);
|
||||
the underlying ATR is Wilder's from *New Concepts in Technical Trading
|
||||
Systems* (1978).
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Atr.md](../volatility-bands/Indicator-Atr.md) — the price-unit original.
|
||||
- [Indicator-HistoricalVolatility.md](../volatility-bands/Indicator-HistoricalVolatility.md) —
|
||||
return-based annualised volatility.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user