F3: add MOM, CMO, TSI and PMO momentum indicators

Completes the F3 family (Momentum) end to end: - Rust core: mom.rs (raw price-difference momentum), cmo.rs (Chande Momentum Oscillator — unsmoothed gain/loss sum, bounded [-100,100]), tsi.rs (True Strength Index — double-EMA-smoothed momentum ratio), pmo.rs (DecisionPoint Price Momentum Oscillator — doubly-smoothed ROC with the 2/period custom smoothing). Each with a full Indicator impl, runnable doctest and reference-value / saturation / warmup / reset / batch==streaming / non-finite tests. - Python: PyMom / PyCmo / PyTsi / PyPmo PyO3 classes + module registration + .pyi stubs (defaults MOM=10, CMO=14, TSI=(25,13), PMO=(35,20)). - Node: MomNode / CmoNode via the scalar macro, explicit TsiNode and PmoNode; index.d.ts and index.js updated. - WASM: WasmMom / WasmCmo / WasmTsi / WasmPmo via the scalar macro. - Wiki: Indicator-Mom/Cmo/Tsi/Pmo.md plus rows in Indicators-Overview.md and entries in Home.md. cargo fmt + clippy (core/wickra/data/wasm/node) clean; 262 core tests, 25 data tests and 37 doctests green.
2026-05-22 17:53:46 +02:00
parent 780a176072
commit 7728151c87
17 changed files with 1826 additions and 5 deletions
@@ -98,6 +98,10 @@ Rust / Python / Node examples. They are grouped by family, mirroring the
 - [Indicator-Trix.md](indicators/momentum/Indicator-Trix.md)
 - [Indicator-AwesomeOscillator.md](indicators/momentum/Indicator-AwesomeOscillator.md)
 - [Indicator-Aroon.md](indicators/momentum/Indicator-Aroon.md)
+- [Indicator-Mom.md](indicators/momentum/Indicator-Mom.md)
+- [Indicator-Cmo.md](indicators/momentum/Indicator-Cmo.md)
+- [Indicator-Tsi.md](indicators/momentum/Indicator-Tsi.md)
+- [Indicator-Pmo.md](indicators/momentum/Indicator-Pmo.md)

 **Volatility** — envelope width and per-bar dispersion measures.

@@ -1,6 +1,6 @@
 # Indicators Overview

-Wickra ships 30 indicators, organised in source under the four classical
+Wickra ships 34 indicators, organised in source under the four classical
 families — trend, momentum, volatility, volume — that map directly to the
 directory structure of `crates/wickra-core/src/indicators/`. The same family
 labels are used here, plus a second-level grouping that reflects how the
@@ -97,6 +97,10 @@ Centered on zero or driven by raw price differences; no fixed cap.
 | `AwesomeOscillator` | `SMA(median, fast) − SMA(median, slow)`; Bill Williams' zero-line crossover oscillator. | `Candle` | `f64` | unbounded around zero | `(fast=5, slow=34)` (Python) | `slow_period` | [Indicator-AwesomeOscillator.md](indicators/momentum/Indicator-AwesomeOscillator.md) |
 | `WilliamsR`         | `−100 × (high_n − close) / (high_n − low_n)`; same family as Stochastic but inverted to `[−100, 0]`. | `Candle` | `f64` | `[−100, 0]` | `period = 14` (Python) | `period` | [Indicator-WilliamsR.md](indicators/momentum/Indicator-WilliamsR.md) |
 | `Trix`              | `(EMA(EMA(EMA(price))).pct_change × 10000)`; oscillator built from a triple-smoothed EMA. | `f64` | `f64` | unbounded around zero | `period = 15` (Python) | `3·period − 1` | [Indicator-Trix.md](indicators/momentum/Indicator-Trix.md) |
+| `Mom`               | `price − price[period]`; raw price-difference momentum. | `f64` | `f64` | unbounded around zero | `period = 10` (Python) | `period + 1` | [Indicator-Mom.md](indicators/momentum/Indicator-Mom.md) |
+| `Cmo`               | Chande Momentum Oscillator; `100·(Σgain − Σloss)/(Σgain + Σloss)` over `period` changes. | `f64` | `f64` | `[−100, 100]` | `period = 14` (Python) | `period + 1` | [Indicator-Cmo.md](indicators/momentum/Indicator-Cmo.md) |
+| `Tsi`               | True Strength Index; ratio of double-EMA-smoothed momentum to its absolute value. | `f64` | `f64` | ≈ `[−100, 100]` around zero | `(long=25, short=13)` (Python) | `long + short` | [Indicator-Tsi.md](indicators/momentum/Indicator-Tsi.md) |
+| `Pmo`               | DecisionPoint Price Momentum Oscillator; doubly-smoothed rate of change. | `f64` | `f64` | unbounded around zero | `(smoothing1=35, smoothing2=20)` (Python) | `2` | [Indicator-Pmo.md](indicators/momentum/Indicator-Pmo.md) |

 ### Directional

@@ -0,0 +1,156 @@
+# CMO
+
+> Chande Momentum Oscillator — a bounded `[−100, 100]` momentum gauge from
+> the unsmoothed sum of gains versus losses.
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Momentum |
+| Sub-category | Bounded oscillators (−100 … 100) |
+| Input type | `f64` (single close) |
+| Output type | `f64` |
+| Output range | `[−100, 100]` |
+| Default parameters | `period = 14` (Python) |
+| Warmup period | `period + 1` |
+| Interpretation | `+100` pure gains, `−100` pure losses, `0` balanced. |
+
+## Formula
+
+Over the last `period` price *changes*, sum the gains and the losses
+separately:
+
+```
+gain_t = max(price_t − price_{t−1}, 0)
+loss_t = max(price_{t−1} − price_t, 0)
+CMO    = 100 · (Σ gain − Σ loss) / (Σ gain + Σ loss)
+```
+
+Unlike RSI — which Wilder-smooths the gain/loss averages — CMO sums them
+raw, with equal weight on every change in the window. That makes it
+faster and wider-swinging than RSI at the same period.
+
+## Parameters
+
+| Name     | Type    | Default       | Valid range | Description |
+|----------|---------|---------------|-------------|-------------|
+| `period` | `usize` | `14` (Python) | `>= 1`      | Number of price changes summed. `period = 0` errors with `Error::PeriodZero`. |
+
+The Python binding defaults `period` to `14` via `#[pyo3(signature = (period=14))]`.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/cmo.rs`:
+
+```rust
+impl Indicator for Cmo {
+    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
+
+`Cmo::new(period).warmup_period() == period + 1`. The first price change
+needs two inputs, and the gain/loss window must hold `period` changes, so
+the first non-`None` output lands on input `period + 1`.
+
+## Edge cases
+
+- **Pure trend.** A window of only gains returns `+100`; only losses,
+  `−100` (`pure_uptrend_saturates_at_plus_100` /
+  `pure_downtrend_saturates_at_minus_100` pin this).
+- **Constant series.** A flat series has no gains and no losses; 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; state
+  is left untouched.
+- **Reset.** `cmo.reset()` clears the previous price, the gain/loss window
+  and both running sums.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{BatchExt, Indicator, Cmo};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut cmo = Cmo::new(3)?;
+    let out: Vec<Option<f64>> = cmo.batch(&[10.0, 11.0, 10.0, 12.0]);
+    println!("{:?}", out);
+    Ok(())
+}
+```
+
+Output:
+
+```
+[None, None, None, Some(50.0)]
+```
+
+The three changes are `+1, −1, +2`: `Σ gain = 3`, `Σ loss = 1`, so
+`CMO = 100·(3 − 1)/(3 + 1) = 50`. This matches the `reference_value` test
+in `crates/wickra-core/src/indicators/cmo.rs`.
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+cmo = ta.CMO(3)
+print(cmo.batch(np.array([10.0, 11.0, 10.0, 12.0])))
+```
+
+Output:
+
+```
+[nan nan nan 50.]
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const cmo = new ta.CMO(3);
+console.log(cmo.batch([10, 11, 10, 12]));
+```
+
+Output:
+
+```
+[ NaN, NaN, NaN, 50 ]
+```
+
+## Interpretation
+
+`Cmo` is read like other bounded oscillators: readings near `+50` and
+above flag overbought conditions, near `−50` and below oversold, and the
+zero line marks the gain/loss balance point. Because it is unsmoothed it
+reacts a bar or two sooner than RSI but is noisier — pair it with a slower
+filter, or use it for divergence rather than raw threshold triggers.
+
+## Common pitfalls
+
+- **Expecting the `[0, 100]` RSI scale.** `Cmo` is centred on zero and
+  spans `[−100, 100]`; an RSI of `30` corresponds to a `Cmo` near `−40`.
+- **Treating it as a smoothed average.** `Cmo` sums raw changes — it is
+  deliberately not Wilder-smoothed.
+
+## References
+
+Tushar Chande, *The New Technical Trader* (1994). The unsmoothed
+gain/loss sum here matches the original definition and TA-Lib's `CMO`.
+
+## See also
+
+- [Indicator-Rsi.md](Indicator-Rsi.md) — the Wilder-smoothed relative.
+- [Indicator-Mom.md](Indicator-Mom.md) — raw price-difference momentum.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
@@ -0,0 +1,152 @@
+# MOM
+
+> Momentum — the raw price change over a fixed lookback,
+> `price_t − price_{t−period}`, in absolute price units.
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Momentum |
+| Sub-category | Unbounded oscillators |
+| Input type | `f64` (single close) |
+| Output type | `f64` |
+| Output range | unbounded around zero (price-difference scale) |
+| Default parameters | `period = 10` (Python) |
+| Warmup period | `period + 1` |
+| Interpretation | Sign and size of the move over the last `period` bars. |
+
+## Formula
+
+```
+MOM_t = price_t − price_{t−period}
+```
+
+The simplest momentum primitive. Positive output means price is higher
+than it was `period` bars ago, negative means lower, and the magnitude is
+the change in raw price units. [`Roc`](Indicator-Roc.md) is the same idea
+expressed as a percentage of the old price.
+
+## Parameters
+
+| Name     | Type    | Default        | Valid range | Description |
+|----------|---------|----------------|-------------|-------------|
+| `period` | `usize` | `10` (Python)  | `>= 1`      | Lookback distance in bars. `period = 0` errors with `Error::PeriodZero`. |
+
+The Python binding defaults `period` to `10` via `#[pyo3(signature = (period=10))]`.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/mom.rs`:
+
+```rust
+impl Indicator for Mom {
+    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
+
+`Mom::new(period).warmup_period() == period + 1`. The output needs both
+the current price and the price `period` bars back, so the window must
+hold `period + 1` values — the first non-`None` output lands on input
+`period + 1`.
+
+## Edge cases
+
+- **Constant series.** A flat series yields `0.0` from input `period + 1`
+  onward (`constant_series_yields_zero` pins this).
+- **NaN / infinity inputs.** Non-finite inputs are silently dropped: the
+  rolling window is not advanced and the previous value is returned. The
+  next finite input still references the correct historical price.
+- **Reset.** `mom.reset()` clears the window and restarts the warmup.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{BatchExt, Indicator, Mom};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut mom = Mom::new(3)?;
+    let out: Vec<Option<f64>> = mom.batch(&[1.0, 2.0, 3.0, 4.0, 7.0]);
+    println!("{:?}", out);
+    Ok(())
+}
+```
+
+Output:
+
+```
+[None, None, None, Some(3.0), Some(5.0)]
+```
+
+`MOM(3)` first emits on input 4: `4 − 1 = 3`. The fifth input gives
+`7 − 2 = 5`. This matches the `reference_values` test in
+`crates/wickra-core/src/indicators/mom.rs`.
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+mom = ta.MOM(3)
+print(mom.batch(np.array([1.0, 2.0, 3.0, 4.0, 7.0])))
+```
+
+Output:
+
+```
+[nan nan nan  3.  5.]
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const mom = new ta.MOM(3);
+console.log(mom.batch([1, 2, 3, 4, 7]));
+```
+
+Output:
+
+```
+[ NaN, NaN, NaN, 3, 5 ]
+```
+
+## Interpretation
+
+`Mom` is a zero-centred oscillator. The textbook reads are the zero-line
+cross (momentum flipping sign) and divergence (price making a new high
+while `Mom` makes a lower high — a stalling trend). Because the output is
+in price units, `Mom` values are not comparable across instruments at
+different price levels; use [`Roc`](Indicator-Roc.md) when you need a
+scale-free percentage instead.
+
+## Common pitfalls
+
+- **Comparing `Mom` across instruments.** A `Mom` of `5` means very
+  different things on a $10 stock and a $5000 index. Normalise with `Roc`
+  for cross-asset work.
+- **Forgetting the `+1` warmup.** `warmup_period()` is `period + 1`, not
+  `period`.
+
+## References
+
+Momentum is one of the oldest technical studies; the implementation here
+is the standard `price − price[period]` difference, matching TA-Lib's
+`MOM`.
+
+## See also
+
+- [Indicator-Roc.md](Indicator-Roc.md) — the percentage-scaled counterpart.
+- [Indicator-Cmo.md](Indicator-Cmo.md) — bounded momentum from summed changes.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
@@ -0,0 +1,170 @@
+# PMO
+
+> Price Momentum Oscillator — Carl Swenlin's DecisionPoint PMO line: a
+> doubly-smoothed rate of change.
+
+## Quick reference
+
+| Field | Value |
+|-------|-------|
+| Family | Momentum |
+| Sub-category | Unbounded oscillators |
+| Input type | `f64` (single close) |
+| Output type | `f64` |
+| Output range | unbounded around zero |
+| Default parameters | `(smoothing1 = 35, smoothing2 = 20)` (Python) |
+| Warmup period | `2` |
+| Interpretation | Smoothed momentum; zero-line and signal-line crosses are the signals. |
+
+## Formula
+
+```
+roc_t      = (price_t / price_{t−1} − 1) · 100
+smoothed_t = customEMA(roc, smoothing1)_t
+PMO_t      = customEMA(10 · smoothed, smoothing2)_t
+```
+
+`customEMA` is the DecisionPoint smoothing: an exponential average whose
+smoothing constant is `2 / period` (not the textbook `2 / (period + 1)`),
+seeded from its first input. The 1-bar percentage change is smoothed once,
+scaled by `10`, then smoothed again.
+
+The classic PMO **signal line** is a 10-period EMA of this PMO line. It is
+deliberately not bundled in — compose it yourself with
+[`Chain`](../Indicator-Chaining.md) and an `Ema(10)`.
+
+## Parameters
+
+| Name         | Type    | Default       | Valid range | Description |
+|--------------|---------|---------------|-------------|-------------|
+| `smoothing1` | `usize` | `35` (Python) | `>= 2`      | First smoothing period (applied to ROC). `0` errors with `Error::PeriodZero`; `1` with `Error::InvalidPeriod`. |
+| `smoothing2` | `usize` | `20` (Python) | `>= 2`      | Second smoothing period (applied to `10 · smoothed`). Same error rules. |
+
+`smoothing = 1` is rejected because the smoothing constant `2 / 1 = 2`
+would exceed `1`. The Python binding defaults the pair to `(35, 20)` via
+`#[pyo3(signature = (smoothing1=35, smoothing2=20))]`. The `periods`
+property returns `(smoothing1, smoothing2)`.
+
+## Inputs / Outputs
+
+From `crates/wickra-core/src/indicators/pmo.rs`:
+
+```rust
+impl Indicator for Pmo {
+    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
+
+`Pmo::new(s1, s2).warmup_period() == 2`. The first ROC needs a previous
+price, and both `customEMA`s seed from their very first input, so the
+first non-`None` output lands on the **second** `update()`. Note this is
+the first *defined* value; the doubly-smoothed series only stabilises
+after many more bars, so treat early readings as unsettled.
+
+## Edge cases
+
+- **Constant series.** A flat series gives `roc = 0` on every bar, so both
+  smoothings stay at `0` and PMO is `0.0`
+  (`constant_series_yields_zero` pins this).
+- **Zero previous price.** A ratio against a `0.0` prior price is
+  undefined; `roc` is treated as `0` for that bar.
+- **NaN / infinity inputs.** Non-finite inputs are silently dropped; the
+  smoothing chains are not advanced.
+- **Reset.** `pmo.reset()` clears the previous price and both EMAs.
+
+## Examples
+
+### Rust
+
+```rust
+use wickra::{Indicator, Pmo};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut pmo = Pmo::new(35, 20)?;
+    println!("{:?}", pmo.update(100.0)); // no previous price yet
+    println!("{:?}", pmo.update(101.0)); // first defined PMO
+    Ok(())
+}
+```
+
+Output:
+
+```
+None
+Some(10.0)
+```
+
+The first `update` only records the price. The second produces
+`roc = 1.0%`; each `customEMA` seeds from its first input, so the inner
+EMA emits `1.0`, the `×10` scaling gives `10.0`, and the outer EMA seeds
+at `10.0` — hence `PMO = 10.0` on the first defined bar. Early values are
+seed artefacts: the double smoothing only settles after many more bars.
+This matches the `first_emission_at_second_update` test in
+`crates/wickra-core/src/indicators/pmo.rs`.
+
+### Python
+
+```python
+import numpy as np
+import wickra as ta
+
+pmo = ta.PMO()  # (smoothing1=35, smoothing2=20)
+prices = 100.0 * 1.01 ** np.arange(120)  # steady uptrend
+out = pmo.batch(prices)
+print("last > 0:", out[-1] > 0)
+```
+
+Output:
+
+```
+last > 0: True
+```
+
+### Node
+
+```javascript
+const ta = require('wickra');
+const pmo = new ta.PMO(35, 20);
+const prices = Array.from({ length: 120 }, (_, i) => 100 * 1.01 ** i);
+console.log('last:', pmo.batch(prices).at(-1));
+```
+
+## Interpretation
+
+`Pmo` is a smoothed momentum line. The DecisionPoint reads are: PMO
+crossing its zero line (momentum changing sign), PMO crossing its signal
+line (a 10-EMA of PMO — build it with `Chain`), and PMO turning up/down
+from an extreme. Because the rate of change is taken in percentage terms,
+PMO values *are* comparable across instruments — unlike raw
+[`Mom`](Indicator-Mom.md).
+
+## Common pitfalls
+
+- **Trusting the first few values.** `warmup_period()` is `2`, but that is
+  only the first *defined* output — the double smoothing needs many bars
+  to settle. Discard the early ramp.
+- **Expecting a bundled signal line.** PMO here is the single PMO line;
+  add `Ema(10)` via `Chain` for the signal.
+
+## References
+
+Carl Swenlin, DecisionPoint Price Momentum Oscillator. The
+`2 / period` "custom smoothing", the `×10` scaling and the conventional
+`(35, 20)` periods follow the published DecisionPoint definition.
+
+## See also
+
+- [Indicator-Roc.md](Indicator-Roc.md) — the raw rate of change PMO smooths.
+- [Indicator-Tsi.md](Indicator-Tsi.md) — another double-smoothed momentum
+  oscillator.
+- [Indicator-Chaining.md](../Indicator-Chaining.md) — how to add the
+  signal-line EMA.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
@@ -0,0 +1,160 @@
+# 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 |
+| Sub-category | Unbounded 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](Indicator-Mom.md) — the raw momentum TSI smooths.
+- [Indicator-MacdIndicator.md](Indicator-MacdIndicator.md) — another
+  EMA-difference momentum oscillator with a signal line.
+- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.