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,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.
|
||||
Reference in New Issue
Block a user