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,159 @@
|
||||
# TSI
|
||||
|
||||
> True Strength Index — a double-smoothed momentum oscillator that strips
|
||||
> noise while keeping a clean, zero-centred read on trend pressure.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Momentum Oscillators |
|
||||
| Input type | `f64` (single close) |
|
||||
| Output type | `f64` |
|
||||
| Output range | roughly `[−100, 100]`, centred on zero |
|
||||
| Default parameters | `(long = 25, short = 13)` (Python) |
|
||||
| Warmup period | `long + short` |
|
||||
| Interpretation | Positive = net upward pressure, negative = net downward. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
momentum_t = price_t − price_{t−1}
|
||||
TSI = 100 · EMA_short(EMA_long(momentum)) / EMA_short(EMA_long(|momentum|))
|
||||
```
|
||||
|
||||
The 1-bar momentum and its absolute value are each smoothed twice — first
|
||||
with an EMA of length `long`, then with an EMA of length `short`. The
|
||||
ratio of the two double-smoothed series normalises the result: when every
|
||||
recent move is up, numerator and denominator are equal and TSI saturates
|
||||
at `+100`; when every move is down, at `−100`.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|---------|---------|---------------|-------------|-------------|
|
||||
| `long` | `usize` | `25` (Python) | `>= 1` | First (slow) smoothing length. `0` errors with `Error::PeriodZero`. |
|
||||
| `short` | `usize` | `13` (Python) | `>= 1` | Second (fast) smoothing length. `0` errors with `Error::PeriodZero`. |
|
||||
|
||||
The Python binding defaults the pair to `(25, 13)` via
|
||||
`#[pyo3(signature = (long=25, short=13))]`. Node and WASM take both
|
||||
explicitly. The `periods` property returns `(long, short)`.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/tsi.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for Tsi {
|
||||
type Input = f64;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: f64) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
A single `f64` close in, an `Option<f64>` out. Python maps this to
|
||||
`float | None` / `numpy.ndarray` (NaN warmup); Node to `number | null` /
|
||||
`Array<number>` (NaN warmup).
|
||||
|
||||
## Warmup
|
||||
|
||||
`Tsi::new(long, short).warmup_period() == long + short`. The momentum
|
||||
series starts on input 2; the SMA-seeded `long` EMA seeds at input
|
||||
`long + 1`, and the `short` EMA stacked on top seeds `short − 1` inputs
|
||||
later, so the first non-`None` output lands on input `long + short`.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Pure trend.** A monotone rising series saturates at `+100`, a falling
|
||||
one at `−100` — `|momentum|` equals `momentum` (or its negative), so the
|
||||
ratio is `±1` (`pure_uptrend_saturates_at_plus_100` /
|
||||
`pure_downtrend_saturates_at_minus_100` pin this).
|
||||
- **Constant series.** Every momentum is `0`; the `0 / 0` is guarded and
|
||||
the output is `0.0` (`constant_series_yields_zero` pins this).
|
||||
- **NaN / infinity inputs.** Non-finite inputs are silently dropped; the
|
||||
smoothing chains are not advanced.
|
||||
- **Reset.** `tsi.reset()` clears the previous price and all four EMAs.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Indicator, Tsi};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let prices: Vec<f64> = (1..=40).map(f64::from).collect();
|
||||
let mut tsi = Tsi::new(5, 3)?;
|
||||
let out = tsi.batch(&prices);
|
||||
println!("warmup_period = {}", tsi.warmup_period());
|
||||
println!("last = {:?}", out.last().unwrap());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
warmup_period = 8
|
||||
last = Some(100.0)
|
||||
```
|
||||
|
||||
A pure ramp has a constant `+1` momentum, so the double-smoothed ratio is
|
||||
exactly `1` and TSI saturates at `+100`. This matches the
|
||||
`pure_uptrend_saturates_at_plus_100` test in
|
||||
`crates/wickra-core/src/indicators/tsi.rs`.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
tsi = ta.TSI() # (long=25, short=13)
|
||||
prices = np.linspace(100.0, 80.0, 60) # steady downtrend
|
||||
out = tsi.batch(prices)
|
||||
print("last =", out[-1])
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
last = -100.0
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const tsi = new ta.TSI(25, 13);
|
||||
const prices = Array.from({ length: 60 }, (_, i) => 100 + i);
|
||||
console.log('last:', tsi.batch(prices).at(-1));
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`Tsi` is a low-noise momentum oscillator. The standard signals are the
|
||||
zero-line cross (momentum changing sign), overbought/oversold extremes
|
||||
near `±25` for the default settings, and a signal-line cross — many
|
||||
traders overlay an EMA of TSI and trade the crossover. The double
|
||||
smoothing makes divergences unusually clean compared with raw momentum.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Reading it as a `[0, 100]` oscillator.** TSI is centred on zero and
|
||||
signed; `+25` is "strong up", not "mid-range".
|
||||
- **Under-budgeting warmup.** Warmup is `long + short` — for the default
|
||||
`(25, 13)` that is 38 bars.
|
||||
|
||||
## References
|
||||
|
||||
William Blau, "True Strength Index", *Technical Analysis of Stocks &
|
||||
Commodities* (1991), and *Momentum, Direction, and Divergence* (1995).
|
||||
The double-EMA-of-momentum definition here follows Blau's original.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Mom.md](../momentum-oscillators/Indicator-Mom.md) — the raw momentum TSI smooths.
|
||||
- [Indicator-MacdIndicator.md](../trend-directional/Indicator-MacdIndicator.md) — another
|
||||
EMA-difference momentum oscillator with a signal line.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user