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:
@@ -0,0 +1,144 @@
|
||||
# AcceleratorOscillator
|
||||
|
||||
> Accelerator Oscillator (AC) — Bill Williams' measure of how fast
|
||||
> momentum itself is changing.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Price Oscillators |
|
||||
| Input type | `Candle` (uses `high`, `low`) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded around zero |
|
||||
| Default parameters | `ao_fast = 5`, `ao_slow = 34`, `signal_period = 5` (Python) |
|
||||
| Warmup period | `ao_slow + signal_period − 1` |
|
||||
| Interpretation | Acceleration of momentum; zero-line crossings lead the Awesome Oscillator. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
AO = SMA(median, ao_fast) − SMA(median, ao_slow) (the Awesome Oscillator)
|
||||
AC = AO − SMA(AO, signal_period)
|
||||
```
|
||||
|
||||
Where the [`AwesomeOscillator`](../momentum-oscillators/Indicator-AwesomeOscillator.md) measures
|
||||
momentum, the Accelerator measures the *change* in momentum — it is the AO
|
||||
minus a short moving average of itself. Because acceleration leads speed, the
|
||||
`AC` tends to turn before the `AO` does. Bill Williams' classic configuration
|
||||
is the `(5, 34)` AO with a `5`-period signal average.
|
||||
|
||||
## Parameters
|
||||
|
||||
- `ao_fast`, `ao_slow` — the underlying Awesome Oscillator periods (`5`, `34`).
|
||||
- `signal_period` — the moving average of the AO subtracted from it (`5`).
|
||||
|
||||
`AcceleratorOscillator::classic()` returns the `(5, 34, 5)` configuration.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/accelerator_oscillator.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for AcceleratorOscillator {
|
||||
type Input = Candle;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: Candle) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
It is a **candle-input** indicator — the inner Awesome Oscillator reads the
|
||||
median price `(high + low) / 2`. Python's streaming `update` accepts a 6-tuple
|
||||
or a dict; the batch helper takes `high`, `low` numpy arrays. Node and WASM
|
||||
expose `update(high, low)` and the matching `batch`.
|
||||
|
||||
## Warmup
|
||||
|
||||
`AcceleratorOscillator::classic().warmup_period() == 38`. The AO first emits at
|
||||
candle `ao_slow`; the signal average then needs `signal_period` AO values.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Flat market.** A flat series gives `AO = 0`, so `AC = 0` throughout.
|
||||
- **`ao_fast >= ao_slow`.** Rejected at construction.
|
||||
- **Reset.** `ac.reset()` clears the AO and the signal average.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Candle, Indicator, AcceleratorOscillator};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut ac = AcceleratorOscillator::classic();
|
||||
let candles: Vec<Candle> = (0..60)
|
||||
.map(|i| Candle::new(10.0, 11.0, 9.0, 10.0, 1.0, i).unwrap())
|
||||
.collect();
|
||||
println!("{:?}", ac.batch(&candles).last().unwrap());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
Some(0.0)
|
||||
```
|
||||
|
||||
A flat market produces a flat AO and therefore a zero Accelerator.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
ac = ta.AcceleratorOscillator(5, 34, 5)
|
||||
n = 60
|
||||
print(ac.batch(np.full(n, 11.0), np.full(n, 9.0))[-1])
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
0.0
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const ac = new ta.AcceleratorOscillator(5, 34, 5);
|
||||
const out = ac.batch(Array(60).fill(11), Array(60).fill(9));
|
||||
console.log(out[out.length - 1]);
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
0
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
Trade the Accelerator like a momentum-acceleration gauge: bars rising above
|
||||
the zero line mean momentum is building, bars falling below mean it is fading.
|
||||
Because it leads the Awesome Oscillator, a colour change in the AC is an early
|
||||
warning that the AO — and price momentum — is about to turn.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Reading the level.** Only the sign and the slope matter; the magnitude
|
||||
scales with the instrument.
|
||||
- **Feeding it scalar prices.** It needs the `high`/`low` bar.
|
||||
|
||||
## References
|
||||
|
||||
Bill Williams' Accelerator Oscillator, from *Trading Chaos*.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-AwesomeOscillator.md](../momentum-oscillators/Indicator-AwesomeOscillator.md) — the
|
||||
momentum oscillator the Accelerator is built on.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
@@ -0,0 +1,138 @@
|
||||
# BalanceOfPower
|
||||
|
||||
> Balance of Power (BOP) — where the bar closed within its range relative
|
||||
> to where it opened.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Price Oscillators |
|
||||
| Input type | `Candle` (uses `open`, `high`, `low`, `close`) |
|
||||
| Output type | `f64` |
|
||||
| Output range | `[−1, +1]` |
|
||||
| Default parameters | none (no parameters) |
|
||||
| Warmup period | `1` |
|
||||
| Interpretation | Intrabar buyer/seller control; `+1` buyers, `−1` sellers. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
BOP = (close − open) / (high − low)
|
||||
```
|
||||
|
||||
Balance of Power asks a single question per bar: did buyers or sellers win it?
|
||||
A bar that opened on its low and closed on its high scores `+1` (buyers in
|
||||
total control); the mirror image scores `−1`. It is a stateless per-bar
|
||||
reading. A zero-range bar carries no information and yields `0`.
|
||||
|
||||
## Parameters
|
||||
|
||||
`BalanceOfPower` takes **no parameters** — `BalanceOfPower::new()` in Rust,
|
||||
`wickra.BalanceOfPower()` in Python, `new ta.BalanceOfPower()` in Node.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/balance_of_power.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for BalanceOfPower {
|
||||
type Input = Candle;
|
||||
type Output = f64;
|
||||
// update(&mut self, input: Candle) -> Option<f64>
|
||||
}
|
||||
```
|
||||
|
||||
`BalanceOfPower` is a **candle-input** indicator that reads all four of
|
||||
`open`, `high`, `low`, `close`. Python's streaming `update` accepts a 6-tuple
|
||||
or a dict; the batch helper takes `open`, `high`, `low`, `close` numpy arrays.
|
||||
Node and WASM expose `update(open, high, low, close)` and the matching
|
||||
`batch`.
|
||||
|
||||
## Warmup
|
||||
|
||||
`BalanceOfPower::new().warmup_period() == 1`. It is a stateless per-bar
|
||||
transform — it emits a value from the very first candle.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Zero-range bar.** `high == low` yields `0` instead of dividing by zero.
|
||||
- **Close on high, open on low.** Scores exactly `+1`.
|
||||
- **Reset.** `bop.reset()` only clears the `is_ready` flag.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{Candle, Indicator, BalanceOfPower};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut bop = BalanceOfPower::new();
|
||||
// open 10, high 14, low 10, close 12 -> (12 - 10) / (14 - 10) = 0.5.
|
||||
let v = bop.update(Candle::new(10.0, 14.0, 10.0, 12.0, 1.0, 0)?);
|
||||
println!("{:?}", v);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
Some(0.5)
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
bop = ta.BalanceOfPower()
|
||||
print(bop.batch(
|
||||
np.array([10.0]), np.array([14.0]), np.array([10.0]), np.array([12.0])
|
||||
))
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[0.5]
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const bop = new ta.BalanceOfPower();
|
||||
console.log(bop.batch([10], [14], [10], [12]));
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[ 0.5 ]
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
A BOP holding above zero says buyers are consistently winning the bars — a
|
||||
healthy uptrend; below zero is the seller's mirror. Because the raw per-bar
|
||||
value is noisy, it is commonly smoothed with a short moving average before
|
||||
trading the zero-line crossings, or read for divergence against price.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Using the raw value as a trend signal.** Per-bar BOP whipsaws; smooth it.
|
||||
- **Feeding it scalar prices.** It needs the full OHLC bar — including `open`.
|
||||
|
||||
## References
|
||||
|
||||
Balance of Power, popularised by Igor Livshin; the `(close − open) /
|
||||
(high − low)` definition is the standard one.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-AwesomeOscillator.md](../momentum-oscillators/Indicator-AwesomeOscillator.md) — another
|
||||
Bill Williams-era price oscillator.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
@@ -0,0 +1,153 @@
|
||||
# Coppock
|
||||
|
||||
> Coppock Curve — a long-horizon momentum indicator: a weighted moving
|
||||
> average of two rates of change, designed to flag major bottoms.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Price Oscillators |
|
||||
| Input type | `f64` (single close) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded around zero |
|
||||
| Default parameters | `(roc_long = 14, roc_short = 11, wma_period = 10)` (Python) |
|
||||
| Warmup period | `max(roc_long, roc_short) + wma_period` |
|
||||
| Interpretation | Long-term momentum; an upturn from below zero is the buy signal. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
Coppock = WMA( ROC(roc_long) + ROC(roc_short), wma_period )
|
||||
```
|
||||
|
||||
Edwin Coppock built this in 1962 as a long-horizon buy signal for stock
|
||||
indices. The two rates of change blend a slightly longer and a slightly
|
||||
shorter momentum horizon; the [`Wma`](../moving-averages/Indicator-Wma.md) smooths
|
||||
their sum. On a **monthly** chart with the conventional
|
||||
`(14, 11, 10)` settings, the curve turning *up from below zero* has
|
||||
historically marked the start of a new bull phase.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|--------------|---------|---------------|-------------|-------------|
|
||||
| `roc_long` | `usize` | `14` (Python) | `>= 1` | Longer ROC period. `0` errors with `Error::PeriodZero`. |
|
||||
| `roc_short` | `usize` | `11` (Python) | `>= 1` | Shorter ROC period. |
|
||||
| `wma_period` | `usize` | `10` (Python) | `>= 1` | WMA smoothing length. |
|
||||
|
||||
The Python binding defaults the trio to `(14, 11, 10)`. The `periods`
|
||||
property returns `(roc_long, roc_short, wma_period)`.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/coppock.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for Coppock {
|
||||
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
|
||||
|
||||
`warmup_period() == max(roc_long, roc_short) + wma_period`. Each ROC emits
|
||||
its first value at input `roc_period + 1`; the longer ROC is the last to
|
||||
become ready, and the WMA then needs `wma_period` of the summed ROC
|
||||
values — so the first non-`None` output lands on input
|
||||
`max(roc_long, roc_short) + wma_period`.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Constant series.** Both ROCs are `0` on a flat series, so the WMA of
|
||||
zeros — and the curve — is `0` (`constant_series_yields_zero` pins
|
||||
this).
|
||||
- **NaN / infinity inputs.** Non-finite inputs are silently dropped; no
|
||||
component is advanced.
|
||||
- **Reset.** `coppock.reset()` clears both ROCs and the WMA.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Indicator, Coppock};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut coppock = Coppock::new(14, 11, 10)?;
|
||||
let prices: Vec<f64> = (1..=120).map(|i| 100.0 * 1.01_f64.powi(i)).collect();
|
||||
let out = coppock.batch(&prices);
|
||||
println!("warmup_period = {}", coppock.warmup_period());
|
||||
println!("last > 0: {}", out.last().unwrap().unwrap() > 0.0);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
warmup_period = 24
|
||||
last > 0: true
|
||||
```
|
||||
|
||||
A steady uptrend keeps both ROCs positive, so the Coppock Curve stays
|
||||
above zero.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
coppock = ta.Coppock() # (roc_long=14, roc_short=11, wma_period=10)
|
||||
prices = np.full(60, 100.0) # flat series
|
||||
print(coppock.batch(prices)[-1]) # ROCs are 0 -> 0
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
0.0
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const coppock = new ta.Coppock(14, 11, 10);
|
||||
const prices = Array.from({ length: 120 }, (_, i) => 100 * 1.01 ** i);
|
||||
console.log('warmupPeriod:', coppock.warmupPeriod());
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`Coppock` is a long-horizon signal, traditionally read on **monthly**
|
||||
data. The canonical rule is a single one: when the curve has been below
|
||||
zero and turns up, that is a long-term buy. It was not designed to give
|
||||
sell signals — Coppock left exits to other tools. On faster timeframes it
|
||||
behaves as a smoothed momentum oscillator, but its statistical edge is
|
||||
specifically the monthly bottom call.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Using it for sell signals.** The Coppock Curve is a buy-only
|
||||
indicator by design; pair it with a separate exit rule.
|
||||
- **Applying it intraday and expecting the historical edge.** The
|
||||
documented behaviour is for monthly index charts.
|
||||
|
||||
## References
|
||||
|
||||
E. S. Coppock, "Practical Relative Strength Charting", *Barron's* (1962).
|
||||
The `WMA(ROC(14) + ROC(11), 10)` construction here is Coppock's original.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Roc.md](../momentum-oscillators/Indicator-Roc.md) — the rate-of-change building block.
|
||||
- [Indicator-Wma.md](../moving-averages/Indicator-Wma.md) — the smoothing average.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
@@ -0,0 +1,161 @@
|
||||
# DPO
|
||||
|
||||
> Detrended Price Oscillator — removes the trend from price by comparing a
|
||||
> shifted past price to the moving average, exposing the underlying cycle.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Price Oscillators |
|
||||
| Input type | `f64` (single close) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded around zero (price-difference scale) |
|
||||
| Default parameters | `period = 20` (Python) |
|
||||
| Warmup period | `max(period, period / 2 + 2)` |
|
||||
| Interpretation | Detrended price; peak-to-peak spacing reveals the cycle length. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
shift = period / 2 + 1
|
||||
DPO_t = price_{t − shift} − SMA(period)_t
|
||||
```
|
||||
|
||||
A normal oscillator compares price to a *current* average and therefore
|
||||
still carries the trend. DPO instead subtracts the average from a price
|
||||
taken `period / 2 + 1` bars **back** — roughly half a cycle. The dominant
|
||||
trend cancels, and what is left swings around zero with the same period
|
||||
as the price's shorter cycles, so the distance between DPO peaks reads off
|
||||
the cycle length directly.
|
||||
|
||||
DPO is **not** a momentum or signal indicator: by construction it is
|
||||
shifted into the past and is not meant to track the latest bar.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|----------|---------|---------------|-------------|-------------|
|
||||
| `period` | `usize` | `20` (Python) | `>= 1` | SMA length; also sets the look-back `shift = period / 2 + 1`. `0` errors with `Error::PeriodZero`. |
|
||||
|
||||
The Python binding defaults `period` to `20`. The derived `shift` is
|
||||
exposed as a read-only property.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/dpo.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for Dpo {
|
||||
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
|
||||
|
||||
`warmup_period() == max(period, period / 2 + 2)`. The output needs both a
|
||||
full `period`-bar SMA window and a price `shift` bars back; the indicator
|
||||
becomes ready once the rolling window holds enough bars for both. For the
|
||||
usual `period >= 4` this simplifies to `period`.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Constant series.** On a flat series the shifted price equals the SMA,
|
||||
so DPO is `0` (`constant_series_yields_zero` pins this).
|
||||
- **NaN / infinity inputs.** Non-finite inputs are silently dropped; the
|
||||
window is not advanced.
|
||||
- **Reset.** `dpo.reset()` clears the window and the rolling sum.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Indicator, Dpo};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut dpo = Dpo::new(4)?;
|
||||
let out: Vec<Option<f64>> = dpo.batch(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
|
||||
println!("{:?}", out);
|
||||
println!("shift = {}, warmup_period = {}", dpo.shift(), dpo.warmup_period());
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[None, None, None, Some(-1.5), Some(-1.5), Some(-1.5)]
|
||||
shift = 3, warmup_period = 4
|
||||
```
|
||||
|
||||
`DPO(4)` has `shift = 3`. At input 4 the SMA of `[1,2,3,4]` is `2.5` and
|
||||
the price 3 bars back is `1`, giving `1 − 2.5 = −1.5`. On a pure ramp the
|
||||
detrended value is constant. This matches the `reference_values` test in
|
||||
`crates/wickra-core/src/indicators/dpo.rs`.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
dpo = ta.DPO(4)
|
||||
print(dpo.batch(np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])))
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[ nan nan nan -1.5 -1.5 -1.5]
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const dpo = new ta.DPO(4);
|
||||
console.log(dpo.batch([1, 2, 3, 4, 5, 6]));
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[ NaN, NaN, NaN, -1.5, -1.5, -1.5 ]
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`Dpo` is a cycle-measurement tool, not a trading trigger. Read it for the
|
||||
*spacing* of its peaks and troughs: regular spacing reveals the dominant
|
||||
cycle length, which you can then feed back into the periods of other
|
||||
indicators. Crossing zero is not a signal — because the series is shifted
|
||||
into the past, the latest DPO value does not correspond to the latest bar.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Trading the zero cross.** DPO is detrended *and* time-shifted; its
|
||||
latest value is historical. Use it to size cycles, not to time entries.
|
||||
- **Reading it as momentum.** It is a detrended price, not a rate of
|
||||
change — see [`Roc`](../momentum-oscillators/Indicator-Roc.md) or [`Mom`](../momentum-oscillators/Indicator-Mom.md) for
|
||||
momentum.
|
||||
|
||||
## References
|
||||
|
||||
The Detrended Price Oscillator is a standard cycle-analysis study; the
|
||||
`period / 2 + 1` look-back shift used here matches the common definition
|
||||
(StockCharts, TA-Lib-compatible implementations).
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-Sma.md](../moving-averages/Indicator-Sma.md) — the moving average DPO
|
||||
detrends against.
|
||||
- [Indicator-Roc.md](../momentum-oscillators/Indicator-Roc.md) — momentum, the indicator DPO is
|
||||
often confused with.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
@@ -0,0 +1,154 @@
|
||||
# PPO
|
||||
|
||||
> Percentage Price Oscillator — MACD expressed as a percentage of the slow
|
||||
> EMA, so readings are comparable across instruments.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Family | Price Oscillators |
|
||||
| Input type | `f64` (single close) |
|
||||
| Output type | `f64` |
|
||||
| Output range | unbounded around zero (percent) |
|
||||
| Default parameters | `(fast = 12, slow = 26)` (Python) |
|
||||
| Warmup period | `slow` |
|
||||
| Interpretation | Percentage gap between a fast and slow EMA; zero-line crosses are signals. |
|
||||
|
||||
## Formula
|
||||
|
||||
```
|
||||
PPO = 100 · (EMA_fast − EMA_slow) / EMA_slow
|
||||
```
|
||||
|
||||
PPO is [`MacdIndicator`](../trend-directional/Indicator-MacdIndicator.md) divided by the slow
|
||||
EMA. That single change makes it **scale-free**: a `PPO` of `1.5` always
|
||||
means "the fast EMA is 1.5 % above the slow EMA", whether the instrument
|
||||
trades at $5 or $5000 — so PPO values can be compared across assets and
|
||||
across time, which raw MACD values cannot. The classic PPO **signal
|
||||
line** is a 9-period EMA of this PPO line; compose it with
|
||||
[`Chain`](../../Indicator-Chaining.md) and an `Ema(9)`.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Name | Type | Default | Valid range | Description |
|
||||
|--------|---------|---------------|------------------|-------------|
|
||||
| `fast` | `usize` | `12` (Python) | `>= 1`, `< slow` | Fast EMA period. |
|
||||
| `slow` | `usize` | `26` (Python) | `> fast` | Slow EMA period. |
|
||||
|
||||
`fast` must be strictly less than `slow` — otherwise `new` returns
|
||||
`Error::InvalidPeriod`. A zero period returns `Error::PeriodZero`. The
|
||||
Python binding defaults the pair to `(12, 26)`; the `periods` property
|
||||
returns `(fast, slow)`.
|
||||
|
||||
## Inputs / Outputs
|
||||
|
||||
From `crates/wickra-core/src/indicators/ppo.rs`:
|
||||
|
||||
```rust
|
||||
impl Indicator for Ppo {
|
||||
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
|
||||
|
||||
`Ppo::new(fast, slow).warmup_period() == slow`. Both EMAs are SMA-seeded;
|
||||
the slow EMA is the last to seed, at input `slow`, which is also when PPO
|
||||
emits its first value.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Constant series.** Both EMAs converge to the constant, so their gap —
|
||||
and PPO — is `0` (`constant_series_yields_zero` pins this).
|
||||
- **Zero slow EMA.** A `0.0` slow EMA would divide by zero; PPO reports
|
||||
`0.0` for that bar instead.
|
||||
- **NaN / infinity inputs.** Non-finite inputs are silently dropped; the
|
||||
EMAs are not advanced.
|
||||
- **Reset.** `ppo.reset()` clears both EMAs and the cached value.
|
||||
|
||||
## Examples
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
use wickra::{BatchExt, Indicator, Ppo};
|
||||
|
||||
fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let mut ppo = Ppo::new(12, 26)?;
|
||||
let prices: Vec<f64> = (1..=80).map(f64::from).collect();
|
||||
let out = ppo.batch(&prices);
|
||||
println!("warmup_period = {}", ppo.warmup_period());
|
||||
println!("last > 0: {}", out.last().unwrap().unwrap() > 0.0);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
warmup_period = 26
|
||||
last > 0: true
|
||||
```
|
||||
|
||||
In a rising series the fast EMA leads the slow EMA, so PPO is positive.
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import wickra as ta
|
||||
|
||||
ppo = ta.PPO() # (fast=12, slow=26)
|
||||
prices = np.full(60, 100.0) # flat series
|
||||
print(ppo.batch(prices)[-1]) # both EMAs equal -> 0
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
0.0
|
||||
```
|
||||
|
||||
### Node
|
||||
|
||||
```javascript
|
||||
const ta = require('wickra');
|
||||
const ppo = new ta.PPO(12, 26);
|
||||
const prices = Array.from({ length: 80 }, (_, i) => 100 + i);
|
||||
console.log('warmupPeriod:', ppo.warmupPeriod());
|
||||
```
|
||||
|
||||
## Interpretation
|
||||
|
||||
`Ppo` is read exactly like MACD: the zero-line cross (fast EMA crossing
|
||||
the slow EMA), the signal-line cross (PPO crossing its own 9-EMA), and
|
||||
histogram-style divergence. Its advantage over MACD is comparability — a
|
||||
PPO scan across a watchlist ranks instruments by *relative* trend
|
||||
strength, which a MACD scan cannot do because MACD is in each
|
||||
instrument's own price units.
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- **Expecting a bundled signal line.** `Ppo` here is the single PPO line;
|
||||
add `Ema(9)` via `Chain` for the signal line and histogram.
|
||||
- **`fast >= slow`.** The constructor rejects it — the fast EMA must be
|
||||
the faster one.
|
||||
|
||||
## References
|
||||
|
||||
Gerald Appel's MACD, re-expressed as a percentage. The implementation
|
||||
follows the standard PPO definition and matches TA-Lib's `PPO`.
|
||||
|
||||
## See also
|
||||
|
||||
- [Indicator-MacdIndicator.md](../trend-directional/Indicator-MacdIndicator.md) — the price-unit
|
||||
original, with a bundled signal line and histogram.
|
||||
- [Indicator-Ema.md](../moving-averages/Indicator-Ema.md) — the underlying average.
|
||||
- [Indicators-Overview.md](../../Indicators-Overview.md) — the full taxonomy.
|
||||
Reference in New Issue
Block a user