kingchenc
d2f99efd78
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.
171 lines
5.4 KiB
Markdown
171 lines
5.4 KiB
Markdown
# SMMA
|
||
|
||
> Smoothed Moving Average — Wilder's running moving average (RMA): an
|
||
> SMA-seeded exponential average with a slow `1 / period` smoothing factor.
|
||
|
||
## Quick reference
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| Family | Moving Averages |
|
||
| Input type | `f64` (single close) |
|
||
| Output type | `f64` |
|
||
| Output range | unbounded; tracks the input price scale |
|
||
| Default parameters | `period` is required (no default in either binding) |
|
||
| Warmup period | `period` |
|
||
| Interpretation | Heavily smoothed price level; the average underlying Wilder's RSI and ATR. |
|
||
|
||
## Formula
|
||
|
||
```
|
||
SMMA_period = SMA(price_1 … price_period) (seed)
|
||
SMMA_t = (SMMA_{t-1} * (period - 1) + price_t) / period (t > period)
|
||
```
|
||
|
||
This is algebraically an exponential moving average with smoothing factor
|
||
`alpha = 1 / period` — substantially slower than the `Ema` factor of
|
||
`2 / (period + 1)` at the same `period`. The recurrence is O(1): each
|
||
`update` touches only the previous value.
|
||
|
||
## Parameters
|
||
|
||
| Name | Type | Default | Valid range | Description |
|
||
|----------|---------|---------|-------------|-------------|
|
||
| `period` | `usize` | none | `>= 1` | Smoothing length. `period = 0` errors with `Error::PeriodZero`. `period = 1` is a pass-through. |
|
||
|
||
There is no Python `#[pyo3(signature = …)]` default for `SMMA`, so
|
||
`wickra.SMMA(period)` requires the period explicitly.
|
||
|
||
## Inputs / Outputs
|
||
|
||
From `crates/wickra-core/src/indicators/smma.rs`:
|
||
|
||
```rust
|
||
impl Indicator for Smma {
|
||
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` (streaming) or a `numpy.ndarray` with `NaN` warmup rows
|
||
(batch); Node maps it to `number | null` / `Array<number>` with `NaN`
|
||
warmup.
|
||
|
||
## Warmup
|
||
|
||
`Smma::new(period).warmup_period() == period`. The first `period - 1`
|
||
inputs are buffered while the seed accumulates; the `period`-th `update()`
|
||
emits the simple average of those inputs as `SMMA_period`. Every later
|
||
input applies the `(prev·(n−1)+x)/n` recurrence.
|
||
|
||
## Edge cases
|
||
|
||
- **Constant series.** Feeding `[7.0; n]` returns `Some(7.0)` from input
|
||
`period` onward — the recurrence is a fixed point for constants
|
||
(`constant_series_yields_the_constant` pins this).
|
||
- **NaN / infinity inputs.** The first line of `update` is
|
||
`if !input.is_finite() { return self.current; }`. Non-finite inputs are
|
||
**silently dropped** — they neither advance the seed nor perturb the
|
||
recurrence, and the previous valid value (if any) is returned.
|
||
- **Reset.** `smma.reset()` clears the seed buffer and the current value,
|
||
restarting the warmup countdown.
|
||
|
||
## Examples
|
||
|
||
### Rust
|
||
|
||
```rust
|
||
use wickra::{BatchExt, Indicator, Smma};
|
||
|
||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||
let mut smma = Smma::new(3)?;
|
||
let out: Vec<Option<f64>> = smma.batch(&[1.0, 2.0, 3.0, 4.0, 5.0]);
|
||
println!("{:?}", out);
|
||
println!("warmup_period = {}", smma.warmup_period());
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
Output:
|
||
|
||
```
|
||
[None, None, Some(2.0), Some(2.6666666666666665), Some(3.4444444444444446)]
|
||
warmup_period = 3
|
||
```
|
||
|
||
The third input emits the seed `(1 + 2 + 3) / 3 = 2.0`; the fourth applies
|
||
`(2.0·2 + 4) / 3 = 8/3`; the fifth `(8/3·2 + 5) / 3 = 31/9`. This matches
|
||
the `warmup_then_recurrence` test in
|
||
`crates/wickra-core/src/indicators/smma.rs`.
|
||
|
||
### Python
|
||
|
||
```python
|
||
import numpy as np
|
||
import wickra as ta
|
||
|
||
smma = ta.SMMA(3)
|
||
print(smma.batch(np.array([1.0, 2.0, 3.0, 4.0, 5.0])))
|
||
print("warmup_period =", smma.warmup_period())
|
||
```
|
||
|
||
Output:
|
||
|
||
```
|
||
[ nan nan 2. 2.6666667 3.4444444]
|
||
warmup_period = 3
|
||
```
|
||
|
||
### Node
|
||
|
||
```javascript
|
||
const ta = require('wickra');
|
||
const smma = new ta.SMMA(3);
|
||
console.log(smma.batch([1, 2, 3, 4, 5]));
|
||
console.log('warmupPeriod:', smma.warmupPeriod());
|
||
```
|
||
|
||
Output:
|
||
|
||
```
|
||
[ NaN, NaN, 2, 2.6666666666666665, 3.4444444444444446 ]
|
||
warmupPeriod: 3
|
||
```
|
||
|
||
## Interpretation
|
||
|
||
`Smma` is a very smooth, lag-heavy price level. Because its smoothing
|
||
factor is `1 / period` rather than `2 / (period + 1)`, an `Smma(n)` is
|
||
roughly as smooth as an `Ema(2n − 1)` — useful when you want maximum
|
||
noise rejection from a single line. Its main role in this library,
|
||
however, is structural: it is the exact smoothing kernel inside
|
||
[`Rsi`](../momentum-oscillators/Indicator-Rsi.md) and [`Atr`](../volatility-bands/Indicator-Atr.md),
|
||
so reaching for `Smma` directly lets you reproduce Wilder-style averages
|
||
on any series.
|
||
|
||
## Common pitfalls
|
||
|
||
- **Confusing it with `Ema` at the same period.** `Smma(n)` and `Ema(n)`
|
||
are *not* interchangeable — `Smma` lags far more. Match `Ema(2n − 1)`
|
||
if you need comparable smoothness.
|
||
- **Treating `period = 0` as "use a default".** `Smma::new(0)` returns
|
||
`Err(Error::PeriodZero)` in Rust and a `ValueError` in Python; pass an
|
||
explicit period.
|
||
|
||
## References
|
||
|
||
The smoothed moving average is J. Welles Wilder Jr.'s running average
|
||
from *New Concepts in Technical Trading Systems* (1978); it is the
|
||
averaging step in his RSI, ATR and ADX. The implementation here follows
|
||
the standard SMA-seeded formulation, matching TA-Lib's `RMA`.
|
||
|
||
## See also
|
||
|
||
- [Indicator-Ema.md](../moving-averages/Indicator-Ema.md) — faster exponential average.
|
||
- [Indicator-Sma.md](../moving-averages/Indicator-Sma.md) — the equal-weighted mean used as
|
||
the SMMA seed.
|
||
- [Indicator-Trima.md](../moving-averages/Indicator-Trima.md) — the other F1 average.
|
||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|