219 lines
6.6 KiB
Rust
219 lines
6.6 KiB
Rust
|
//! Volume Zone Oscillator (Walid Khalil).
|
|||
|
|
|
|||
|
|
use crate::error::{Error, Result};
|
|||
|
|
use crate::indicators::ema::Ema;
|
|||
|
|
use crate::ohlcv::Candle;
|
|||
|
|
use crate::traits::Indicator;
|
|||
|
|
|
|||
|
|
/// Walid Khalil's Volume Zone Oscillator — a normalised version of OBV-style
|
|||
|
|
/// volume flow that swings within `[−100, 100]`.
|
|||
|
|
///
|
|||
|
|
/// Each bar contributes a *signed volume*: `+volume` on an up day, `−volume` on
|
|||
|
|
/// a down day, `0` on an unchanged close. The VZO is the ratio of an EMA of
|
|||
|
|
/// that signed volume to an EMA of the absolute volume, scaled by `100`:
|
|||
|
|
///
|
|||
|
|
/// ```text
|
|||
|
|
/// R_t = sign(close_t − close_{t−1}) · volume_t
|
|||
|
|
/// VP_t = EMA(R, period)_t (smoothed signed volume)
|
|||
|
|
/// TV_t = EMA(volume, period)_t (smoothed absolute volume)
|
|||
|
|
/// VZO_t = 100 · VP_t / TV_t
|
|||
|
|
/// ```
|
|||
|
|
///
|
|||
|
|
/// Khalil's interpretation: `VZO > +60` overbought, `< −60` oversold, with the
|
|||
|
|
/// zero line acting as a trend filter. The first bar only seeds the previous
|
|||
|
|
/// close; both EMAs then need `period` samples to seed, so the first emission
|
|||
|
|
/// lands at bar `period + 1`. A `TV_t == 0` (every bar had zero volume)
|
|||
|
|
/// collapses the output to `0` instead of NaN.
|
|||
|
|
///
|
|||
|
|
/// # Example
|
|||
|
|
///
|
|||
|
|
/// ```
|
|||
|
|
/// use wickra_core::{Candle, Indicator, Vzo};
|
|||
|
|
///
|
|||
|
|
/// let mut indicator = Vzo::new(14).unwrap();
|
|||
|
|
/// let mut last = None;
|
|||
|
|
/// for i in 0..80 {
|
|||
|
|
/// let base = 100.0 + f64::from(i);
|
|||
|
|
/// let candle =
|
|||
|
|
/// Candle::new(base, base + 2.0, base - 2.0, base + 1.0, 50.0, i64::from(i)).unwrap();
|
|||
|
|
/// last = indicator.update(candle);
|
|||
|
|
/// }
|
|||
|
|
/// assert!(last.is_some());
|
|||
|
|
/// ```
|
|||
|
|
#[derive(Debug, Clone)]
|
|||
|
|
pub struct Vzo {
|
|||
|
|
period: usize,
|
|||
|
|
vp: Ema,
|
|||
|
|
tv: Ema,
|
|||
|
|
prev_close: Option<f64>,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
impl Vzo {
|
|||
|
|
/// Construct a new VZO with the given EMA smoothing period.
|
|||
|
|
///
|
|||
|
|
/// # Errors
|
|||
|
|
/// Returns [`Error::PeriodZero`] if `period == 0`.
|
|||
|
|
pub fn new(period: usize) -> Result<Self> {
|
|||
|
|
if period == 0 {
|
|||
|
|
return Err(Error::PeriodZero);
|
|||
|
|
}
|
|||
|
|
Ok(Self {
|
|||
|
|
period,
|
|||
|
|
vp: Ema::new(period)?,
|
|||
|
|
tv: Ema::new(period)?,
|
|||
|
|
prev_close: None,
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/// Configured EMA smoothing period.
|
|||
|
|
pub const fn period(&self) -> usize {
|
|||
|
|
self.period
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
impl Indicator for Vzo {
|
|||
|
|
type Input = Candle;
|
|||
|
|
type Output = f64;
|
|||
|
|
|
|||
|
|
fn update(&mut self, candle: Candle) -> Option<f64> {
|
|||
|
|
let signed_volume = match self.prev_close {
|
|||
|
|
None => {
|
|||
|
|
self.prev_close = Some(candle.close);
|
|||
|
|
return None;
|
|||
|
|
}
|
|||
|
|
Some(prev) => {
|
|||
|
|
if candle.close > prev {
|
|||
|
|
candle.volume
|
|||
|
|
} else if candle.close < prev {
|
|||
|
|
-candle.volume
|
|||
|
|
} else {
|
|||
|
|
0.0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
self.prev_close = Some(candle.close);
|
|||
|
|
let vp = self.vp.update(signed_volume);
|
|||
|
|
let tv = self.tv.update(candle.volume);
|
|||
|
|
let (vp_v, tv_v) = (vp?, tv?);
|
|||
|
|
if tv_v == 0.0 {
|
|||
|
|
// No volume in the smoothing window -> ratio undefined; report 0.
|
|||
|
|
return Some(0.0);
|
|||
|
|
}
|
|||
|
|
Some(100.0 * vp_v / tv_v)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fn reset(&mut self) {
|
|||
|
|
self.vp.reset();
|
|||
|
|
self.tv.reset();
|
|||
|
|
self.prev_close = None;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fn warmup_period(&self) -> usize {
|
|||
|
|
// One seed bar plus the EMA seed.
|
|||
|
|
self.period + 1
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fn is_ready(&self) -> bool {
|
|||
|
|
self.vp.is_ready() && self.tv.is_ready()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
fn name(&self) -> &'static str {
|
|||
|
|
"VZO"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[cfg(test)]
|
|||
|
|
mod tests {
|
|||
|
|
use super::*;
|
|||
|
|
use crate::traits::BatchExt;
|
|||
|
|
use approx::assert_relative_eq;
|
|||
|
|
|
|||
|
|
fn c(close: f64, volume: f64, ts: i64) -> Candle {
|
|||
|
|
Candle::new(close, close, close, close, volume, ts).unwrap()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn rejects_zero_period() {
|
|||
|
|
assert!(matches!(Vzo::new(0), Err(Error::PeriodZero)));
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn accessors_and_metadata() {
|
|||
|
|
let v = Vzo::new(14).unwrap();
|
|||
|
|
assert_eq!(v.period(), 14);
|
|||
|
|
assert_eq!(v.name(), "VZO");
|
|||
|
|
assert_eq!(v.warmup_period(), 15);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn strictly_rising_series_saturates_to_plus_100() {
|
|||
|
|
// Every bar is an up-day with identical volume -> signed_volume == volume
|
|||
|
|
// on every bar -> VP and TV EMAs are equal -> ratio = 1 -> VZO = +100.
|
|||
|
|
let candles: Vec<Candle> = (0..60i64).map(|i| c(10.0 + i as f64, 100.0, i)).collect();
|
|||
|
|
let mut v = Vzo::new(5).unwrap();
|
|||
|
|
let out = v.batch(&candles);
|
|||
|
|
let last = out.iter().filter_map(|x| *x).next_back().unwrap();
|
|||
|
|
assert_relative_eq!(last, 100.0, epsilon = 1e-9);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn strictly_falling_series_saturates_to_minus_100() {
|
|||
|
|
let candles: Vec<Candle> = (0..60i64).map(|i| c(200.0 - i as f64, 100.0, i)).collect();
|
|||
|
|
let mut v = Vzo::new(5).unwrap();
|
|||
|
|
let out = v.batch(&candles);
|
|||
|
|
let last = out.iter().filter_map(|x| *x).next_back().unwrap();
|
|||
|
|
assert_relative_eq!(last, -100.0, epsilon = 1e-9);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn flat_close_yields_zero() {
|
|||
|
|
// signed_volume = 0 forever -> VP_EMA stays at 0 -> ratio = 0.
|
|||
|
|
let candles: Vec<Candle> = (0..40).map(|i| c(10.0, 100.0, i)).collect();
|
|||
|
|
let mut v = Vzo::new(5).unwrap();
|
|||
|
|
for x in v.batch(&candles).into_iter().flatten() {
|
|||
|
|
assert_relative_eq!(x, 0.0, epsilon = 1e-9);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn zero_volume_window_yields_zero() {
|
|||
|
|
// All bars carry zero volume -> tv_v == 0 -> defensive branch fires.
|
|||
|
|
let candles: Vec<Candle> = (0..20i64).map(|i| c(10.0 + i as f64, 0.0, i)).collect();
|
|||
|
|
let mut v = Vzo::new(3).unwrap();
|
|||
|
|
let out = v.batch(&candles);
|
|||
|
|
let last = out.iter().filter_map(|x| *x).next_back().unwrap();
|
|||
|
|
assert_relative_eq!(last, 0.0, epsilon = 1e-12);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn batch_equals_streaming() {
|
|||
|
|
let candles: Vec<Candle> = (0..100i64)
|
|||
|
|
.map(|i| {
|
|||
|
|
let f = i as f64;
|
|||
|
|
c(
|
|||
|
|
100.0 + (f * 0.3).sin() * 5.0,
|
|||
|
|
50.0 + (i % 7) as f64 * 10.0,
|
|||
|
|
i,
|
|||
|
|
)
|
|||
|
|
})
|
|||
|
|
.collect();
|
|||
|
|
let mut a = Vzo::new(14).unwrap();
|
|||
|
|
let mut b = Vzo::new(14).unwrap();
|
|||
|
|
assert_eq!(
|
|||
|
|
a.batch(&candles),
|
|||
|
|
candles.iter().map(|x| b.update(*x)).collect::<Vec<_>>()
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
#[test]
|
|||
|
|
fn reset_clears_state() {
|
|||
|
|
let candles: Vec<Candle> = (0..40i64).map(|i| c(10.0 + i as f64, 100.0, i)).collect();
|
|||
|
|
let mut v = Vzo::new(5).unwrap();
|
|||
|
|
v.batch(&candles);
|
|||
|
|
assert!(v.is_ready());
|
|||
|
|
v.reset();
|
|||
|
|
assert!(!v.is_ready());
|
|||
|
|
assert_eq!(v.update(candles[0]), None);
|
|||
|
|
}
|
|||
|
|
}
|