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,178 @@
|
||||
# UltimateOscillator
|
||||
|
||||
> Ultimate Oscillator — Larry Williams' momentum oscillator that blends
|
||||
> three lookback periods into one bounded `[0, 100]` reading.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Momentum Oscillators |
|
||||
| Input type | `Candle` (uses `high`, `low`, `close`) |
|
||||
| Output type | `f64` |
|
||||
| Output range | `[0, 100]` |
|
||||
| Default parameters | `(short = 7, mid = 14, long = 28)` (Python) |
|
||||
| Warmup period | `max(short, mid, long) + 1` |
|
||||
| Interpretation | Weighted three-timeframe buying pressure; `50` is neutral. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
true_low_t = min(low_t, close_{t−1})
|
||||
BP_t = close_t − true_low_t (buying pressure)
|
||||
TR_t = max(high_t, close_{t−1}) − true_low_t (true range)
|
||||
avg_n = Σ BP over n / Σ TR over n
|
||||
UO = 100 · (4·avg_short + 2·avg_mid + avg_long) / 7
|
||||
```
|
||||
|
||||
A single-timeframe momentum oscillator can show false divergences when
|
||||
its lookback does not match the swing being measured. The Ultimate
|
||||
Oscillator averages buying pressure over *three* windows and weights the
|
||||
fastest (`4×`) above the medium (`2×`) and slow (`1×`), which damps those
|
||||
false signals while keeping the response quick.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|---------|---------|---------------|-------------|-------------|
|
||||
| `short` | `usize` | `7` (Python) | `>= 1` | Fast lookback (weight `4`). `0` errors with `Error::PeriodZero`. |
|
||||
| `mid` | `usize` | `14` (Python) | `>= 1` | Medium lookback (weight `2`). |
|
||||
| `long` | `usize` | `28` (Python) | `>= 1` | Slow lookback (weight `1`). |
|
||||
|
||||
The Python binding defaults the trio to `(7, 14, 28)` via
|
||||
`#[pyo3(signature = (short=7, mid=14, long=28))]`. Node and WASM take all
|
||||
three explicitly. The `periods` property returns `(short, mid, long)`.
|
||||
`UltimateOscillator::classic()` is the conventional `(7, 14, 28)`.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/ultimate_oscillator.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for UltimateOscillator {
|
||||
type Input = Candle;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: Candle) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
`UltimateOscillator` 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
|
||||
|
||||
`warmup_period() == max(short, mid, long) + 1`. The first bar has no
|
||||
previous close, so the first `BP`/`TR` pair forms on bar 2; the longest
|
||||
window must then fill, so the first non-`None` output lands on input
|
||||
`max(short, mid, long) + 1`.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Pure uptrend.** Bars that each close higher have `BP == TR`, so every
|
||||
ratio is `1` and UO saturates at `100`
|
||||
(`pure_uptrend_saturates_at_100` pins this).
|
||||
- **Pure downtrend.** Bars that each close lower have `BP == 0`, so UO is
|
||||
`0` (`pure_downtrend_saturates_at_0` pins this).
|
||||
- **Flat market.** Identical bars have zero true range; each window
|
||||
contributes the neutral ratio `0.5`, so UO reads `50`
|
||||
(`flat_market_reads_50` pins this).
|
||||
- **Bounds.** The output is always within `[0, 100]`
|
||||
(`output_stays_within_0_100` pins this).
|
||||
- **Candle validation.** `Candle::new` rejects NaN/infinite fields, so
|
||||
`update` never sees an invalid bar.
|
||||
- **Reset.** `uo.reset()` clears the previous close, the rolling window
|
||||
and all six running sums.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Candle, Indicator, UltimateOscillator};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut uo = UltimateOscillator::classic(); // (7, 14, 28)
|
||||
// 30 flat candles, each closing one tick higher than the last.
|
||||
let candles: Vec<Candle> = (0..40)
|
||||
.map(|i| {
|
||||
let p = 100.0 + f64::from(i);
|
||||
Candle::new(p, p, p, p, 1.0, i64::from(i)).unwrap()
|
||||
})
|
||||
.collect();
|
||||
let out = uo.batch(&candles);
|
||||
println!("warmup_period = {}", uo.warmup_period());
|
||||
println!("last = {:?}", out.last().unwrap());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
warmup_period = 29
|
||||
last = Some(100.0)
|
||||
```
|
||||
|
||||
Every bar closes higher with `BP == TR`, so UO saturates at `100`. This
|
||||
matches the `pure_uptrend_saturates_at_100` test in
|
||||
`crates/wickra-core/src/indicators/ultimate_oscillator.rs`.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
uo = ta.UltimateOscillator() # (7, 14, 28)
|
||||
high = np.full(40, 100.0)
|
||||
low = np.full(40, 100.0)
|
||||
close = np.full(40, 100.0) # perfectly flat market
|
||||
print(uo.batch(high, low, close)[-1])
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
50.0
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const uo = new ta.UltimateOscillator(7, 14, 28);
|
||||
const flat = Array.from({ length: 40 }, () => 100);
|
||||
console.log(uo.batch(flat, flat, flat).at(-1)); // 50
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`UltimateOscillator` is read with the usual overbought/oversold lens —
|
||||
above `70` is stretched, below `30` is washed out — but Larry Williams'
|
||||
canonical signal is *divergence with confirmation*: price makes a new
|
||||
extreme while UO does not, then UO breaks the level of the divergence.
|
||||
The three-timeframe blend makes those divergences more reliable than a
|
||||
single-period oscillator.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Feeding it scalar prices.** It needs `high`/`low`/`close`; it takes a
|
||||
`Candle`, not an `f64`.
|
||||
- **Reordering the periods.** The `4 / 2 / 1` weights assume `short` is
|
||||
the fastest window — keep `short < mid < long`. Any positive periods
|
||||
are accepted, but mis-ordering them inverts the intended weighting.
|
||||
|
||||
## References
|
||||
|
||||
Larry Williams, "The Ultimate Oscillator", *Technical Analysis of Stocks
|
||||
& Commodities* (1985). The buying-pressure / true-range definition and the
|
||||
`4 / 2 / 1` weighting follow Williams' original.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Stochastic.md](../momentum-oscillators/Indicator-Stochastic.md) — single-timeframe
|
||||
bounded oscillator.
|
||||
- [Indicator-Rsi.md](../momentum-oscillators/Indicator-Rsi.md) — the canonical momentum oscillator.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user