F5: add PPO, DPO and Coppock Curve price oscillators
Completes the F5 family (Price oscillators) end to end: - Rust core: ppo.rs (Percentage Price Oscillator — MACD as a percentage of the slow EMA), dpo.rs (Detrended Price Oscillator — shifted price minus its SMA), coppock.rs (Coppock Curve — WMA of two summed ROCs). Each with a full Indicator impl, runnable doctest and reference / constant-series / warmup / reset / batch==streaming / non-finite tests. - Python: PyPpo / PyDpo / PyCoppock PyO3 classes + module registration + .pyi stubs (defaults PPO=(12,26), DPO=20, Coppock=(14,11,10)). - Node: DpoNode via the scalar macro, explicit PpoNode and CoppockNode; index.d.ts and index.js updated. - WASM: WasmDpo / WasmPpo / WasmCoppock via the scalar macro. - Wiki: Indicator-Ppo/Dpo/Coppock.md plus rows in Indicators-Overview.md and entries in Home.md. cargo fmt + clippy (core/wickra/data/wasm/node) clean; 300 core tests, 25 data tests and 42 doctests green.
This commit is contained in:
kingchenc
@@ -0,0 +1,205 @@
|
||||
//! Percentage Price Oscillator.
|
||||
|
||||
use crate::error::{Error, Result};
|
||||
use crate::traits::Indicator;
|
||||
|
||||
use super::Ema;
|
||||
|
||||
/// Percentage Price Oscillator — MACD expressed as a percentage.
|
||||
///
|
||||
/// PPO is the gap between a fast and a slow EMA, divided by the slow EMA and
|
||||
/// scaled to a percentage:
|
||||
///
|
||||
/// ```text
|
||||
/// PPO = 100 · (EMA_fast − EMA_slow) / EMA_slow
|
||||
/// ```
|
||||
///
|
||||
/// Dividing by the slow EMA makes PPO **scale-free**: a `PPO` of `1.5` means
|
||||
/// "the fast EMA is 1.5 % above the slow EMA" on any instrument, so PPO
|
||||
/// readings *are* comparable across assets — unlike the raw price-unit
|
||||
/// [`MacdIndicator`](crate::MacdIndicator). The classic PPO **signal line** is
|
||||
/// a 9-period EMA of this PPO line; compose it with [`Chain`](crate::Chain)
|
||||
/// and an [`Ema`] if you need it.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```
|
||||
/// use wickra_core::{Indicator, Ppo};
|
||||
///
|
||||
/// let mut indicator = Ppo::new(12, 26).unwrap();
|
||||
/// let mut last = None;
|
||||
/// for i in 0..80 {
|
||||
/// last = indicator.update(100.0 + f64::from(i));
|
||||
/// }
|
||||
/// assert!(last.is_some());
|
||||
/// ```
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Ppo {
|
||||
fast: usize,
|
||||
slow: usize,
|
||||
ema_fast: Ema,
|
||||
ema_slow: Ema,
|
||||
current: Option<f64>,
|
||||
}
|
||||
|
||||
impl Ppo {
|
||||
/// Construct a new PPO with the `fast` and `slow` EMA periods.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`Error::PeriodZero`] if either period is `0`, or
|
||||
/// [`Error::InvalidPeriod`] if `fast >= slow`.
|
||||
pub fn new(fast: usize, slow: usize) -> Result<Self> {
|
||||
if fast == 0 || slow == 0 {
|
||||
return Err(Error::PeriodZero);
|
||||
}
|
||||
if fast >= slow {
|
||||
return Err(Error::InvalidPeriod {
|
||||
message: "PPO fast period must be < slow period",
|
||||
});
|
||||
}
|
||||
Ok(Self {
|
||||
fast,
|
||||
slow,
|
||||
ema_fast: Ema::new(fast)?,
|
||||
ema_slow: Ema::new(slow)?,
|
||||
current: None,
|
||||
})
|
||||
}
|
||||
|
||||
/// The `(fast, slow)` periods.
|
||||
pub const fn periods(&self) -> (usize, usize) {
|
||||
(self.fast, self.slow)
|
||||
}
|
||||
|
||||
/// Current value if available.
|
||||
pub const fn value(&self) -> Option<f64> {
|
||||
self.current
|
||||
}
|
||||
}
|
||||
|
||||
impl Indicator for Ppo {
|
||||
type Input = f64;
|
||||
type Output = f64;
|
||||
|
||||
fn update(&mut self, input: f64) -> Option<f64> {
|
||||
if !input.is_finite() {
|
||||
// Non-finite input is ignored; the EMAs are not advanced.
|
||||
return self.current;
|
||||
}
|
||||
let fast = self.ema_fast.update(input);
|
||||
let slow = self.ema_slow.update(input);
|
||||
match (fast, slow) {
|
||||
(Some(f), Some(s)) => {
|
||||
let ppo = if s == 0.0 {
|
||||
// Undefined ratio against a zero slow EMA: report flat.
|
||||
0.0
|
||||
} else {
|
||||
100.0 * (f - s) / s
|
||||
};
|
||||
self.current = Some(ppo);
|
||||
Some(ppo)
|
||||
}
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
fn reset(&mut self) {
|
||||
self.ema_fast.reset();
|
||||
self.ema_slow.reset();
|
||||
self.current = None;
|
||||
}
|
||||
|
||||
fn warmup_period(&self) -> usize {
|
||||
// The slow EMA is the last to seed.
|
||||
self.slow
|
||||
}
|
||||
|
||||
fn is_ready(&self) -> bool {
|
||||
self.current.is_some()
|
||||
}
|
||||
|
||||
fn name(&self) -> &'static str {
|
||||
"PPO"
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::traits::BatchExt;
|
||||
use approx::assert_relative_eq;
|
||||
|
||||
#[test]
|
||||
fn new_rejects_zero_period() {
|
||||
assert!(matches!(Ppo::new(0, 26), Err(Error::PeriodZero)));
|
||||
assert!(matches!(Ppo::new(12, 0), Err(Error::PeriodZero)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn new_rejects_fast_not_less_than_slow() {
|
||||
assert!(matches!(Ppo::new(26, 12), Err(Error::InvalidPeriod { .. })));
|
||||
assert!(matches!(Ppo::new(12, 12), Err(Error::InvalidPeriod { .. })));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn first_emission_at_warmup_period() {
|
||||
let mut ppo = Ppo::new(3, 6).unwrap();
|
||||
assert_eq!(ppo.warmup_period(), 6);
|
||||
let out = ppo.batch(&(1..=30).map(f64::from).collect::<Vec<_>>());
|
||||
for v in out.iter().take(5) {
|
||||
assert!(v.is_none());
|
||||
}
|
||||
assert!(out[5].is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn constant_series_yields_zero() {
|
||||
// Both EMAs converge to the constant, so their gap is zero.
|
||||
let mut ppo = Ppo::new(3, 6).unwrap();
|
||||
let out = ppo.batch(&[100.0; 60]);
|
||||
for v in out.iter().skip(5).flatten() {
|
||||
assert_relative_eq!(*v, 0.0, epsilon = 1e-9);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn uptrend_is_positive() {
|
||||
// In a rising series the fast EMA leads the slow EMA, so PPO > 0.
|
||||
let mut ppo = Ppo::new(5, 12).unwrap();
|
||||
let out = ppo.batch(&(1..=80).map(f64::from).collect::<Vec<_>>());
|
||||
let last = out.iter().rev().flatten().next().unwrap();
|
||||
assert!(*last > 0.0, "uptrend PPO should be positive, got {last}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ignores_non_finite_input() {
|
||||
let mut ppo = Ppo::new(3, 6).unwrap();
|
||||
let out = ppo.batch(&(1..=30).map(f64::from).collect::<Vec<_>>());
|
||||
let last = *out.last().unwrap();
|
||||
assert!(last.is_some());
|
||||
assert_eq!(ppo.update(f64::NAN), last);
|
||||
assert_eq!(ppo.update(f64::INFINITY), last);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn reset_clears_state() {
|
||||
let mut ppo = Ppo::new(3, 6).unwrap();
|
||||
ppo.batch(&(1..=30).map(f64::from).collect::<Vec<_>>());
|
||||
assert!(ppo.is_ready());
|
||||
ppo.reset();
|
||||
assert!(!ppo.is_ready());
|
||||
assert_eq!(ppo.update(1.0), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn batch_equals_streaming() {
|
||||
let prices: Vec<f64> = (1..=120)
|
||||
.map(|i| 100.0 + (f64::from(i) * 0.25).sin() * 9.0)
|
||||
.collect();
|
||||
let batch = Ppo::new(12, 26).unwrap().batch(&prices);
|
||||
let mut b = Ppo::new(12, 26).unwrap();
|
||||
let streamed: Vec<_> = prices.iter().map(|p| b.update(*p)).collect();
|
||||
assert_eq!(batch, streamed);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user