wickra_core/indicators/
inertia.rs

1//! Inertia (Donald Dorsey).
2
3use crate::error::{Error, Result};
4use crate::indicators::linreg::LinearRegression;
5use crate::indicators::rvi::Rvi;
6use crate::ohlcv::Candle;
7use crate::traits::Indicator;
8
9/// Donald Dorsey's Inertia — a Linear-Regression-smoothed `RVI` (Relative Vigor
10/// Index). The endpoint of an `n`-bar least-squares fit of the `RVI` series is
11/// taken as the indicator's reading, smoothing the underlying ratio while
12/// preserving its trend direction.
13///
14/// ```text
15/// Inertia_t = LinearRegression(RVI(close - open, high - low; rvi_period), linreg_period)_t
16/// ```
17///
18/// Dorsey's recommended defaults are `(rvi_period = 14, linreg_period = 20)`.
19///
20/// # Example
21///
22/// ```
23/// use wickra_core::{Candle, Indicator, Inertia};
24///
25/// let mut inertia = Inertia::new(14, 20).unwrap();
26/// let mut last = None;
27/// for i in 0..80 {
28///     let o = 100.0 + f64::from(i);
29///     let c = o + 0.5;
30///     let candle = Candle::new(o, c + 0.2, o - 0.2, c, 1.0, i64::from(i)).unwrap();
31///     last = inertia.update(candle);
32/// }
33/// assert!(last.is_some());
34/// ```
35#[derive(Debug, Clone)]
36pub struct Inertia {
37    rvi_period: usize,
38    linreg_period: usize,
39    rvi: Rvi,
40    linreg: LinearRegression,
41}
42
43impl Inertia {
44    /// # Errors
45    /// Returns [`Error::PeriodZero`] if either period is zero.
46    pub fn new(rvi_period: usize, linreg_period: usize) -> Result<Self> {
47        if rvi_period == 0 || linreg_period == 0 {
48            return Err(Error::PeriodZero);
49        }
50        Ok(Self {
51            rvi_period,
52            linreg_period,
53            rvi: Rvi::new(rvi_period)?,
54            linreg: LinearRegression::new(linreg_period)?,
55        })
56    }
57
58    /// Dorsey's recommended defaults `(rvi_period = 14, linreg_period = 20)`.
59    pub fn classic() -> Self {
60        Self::new(14, 20).expect("classic Inertia parameters are valid")
61    }
62
63    /// Configured `(rvi_period, linreg_period)`.
64    pub const fn periods(&self) -> (usize, usize) {
65        (self.rvi_period, self.linreg_period)
66    }
67}
68
69impl Indicator for Inertia {
70    type Input = Candle;
71    type Output = f64;
72
73    fn update(&mut self, candle: Candle) -> Option<f64> {
74        let rvi = self.rvi.update(candle)?;
75        self.linreg.update(rvi)
76    }
77
78    fn reset(&mut self) {
79        self.rvi.reset();
80        self.linreg.reset();
81    }
82
83    fn warmup_period(&self) -> usize {
84        // RVI emits at `rvi_period` candles; the LinearRegression then needs
85        // `linreg_period − 1` more RVI values to fill its window.
86        self.rvi_period + self.linreg_period - 1
87    }
88
89    fn is_ready(&self) -> bool {
90        self.linreg.is_ready()
91    }
92
93    fn name(&self) -> &'static str {
94        "Inertia"
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101    use crate::traits::BatchExt;
102    use approx::assert_relative_eq;
103
104    fn candle(open: f64, high: f64, low: f64, close: f64, ts: i64) -> Candle {
105        Candle::new(open, high, low, close, 1.0, ts).unwrap()
106    }
107
108    #[test]
109    fn rejects_zero_period() {
110        assert!(matches!(Inertia::new(0, 20), Err(Error::PeriodZero)));
111        assert!(matches!(Inertia::new(14, 0), Err(Error::PeriodZero)));
112    }
113
114    #[test]
115    fn accessors_and_metadata() {
116        let inertia = Inertia::classic();
117        assert_eq!(inertia.periods(), (14, 20));
118        assert_eq!(inertia.warmup_period(), 33);
119        assert_eq!(inertia.name(), "Inertia");
120    }
121
122    #[test]
123    fn classic_factory() {
124        assert_eq!(Inertia::classic().periods(), (14, 20));
125    }
126
127    #[test]
128    fn warmup_emits_first_value_at_warmup_period() {
129        // Smaller periods for a fast test: RVI(3) emits at 3 candles, then
130        // LinReg(4) needs 4 RVI values -> total 3 + 4 - 1 = 6.
131        let mut inertia = Inertia::new(3, 4).unwrap();
132        assert_eq!(inertia.warmup_period(), 6);
133        for i in 0..5 {
134            assert_eq!(inertia.update(candle(10.0, 11.0, 9.0, 10.5, i)), None);
135        }
136        assert!(inertia.update(candle(10.0, 11.0, 9.0, 10.5, 5)).is_some());
137    }
138
139    #[test]
140    fn constant_rvi_yields_constant_inertia() {
141        // Every bar identical -> RVI is constant -> LinReg of a constant
142        // series equals that constant after warmup.
143        let mut inertia = Inertia::new(3, 4).unwrap();
144        let mut last = None;
145        for i in 0..40 {
146            last = inertia.update(candle(10.0, 11.0, 9.0, 10.5, i));
147        }
148        // RVI = SMA(c-o, 3) / SMA(h-l, 3) = 0.5 / 2.0 = 0.25 on every bar.
149        let v = last.unwrap();
150        assert_relative_eq!(v, 0.25, epsilon = 1e-12);
151    }
152
153    #[test]
154    fn batch_equals_streaming() {
155        let candles: Vec<Candle> = (0..80_i64)
156            .map(|i| {
157                let o = 100.0 + (i as f64 * 0.3).sin() * 5.0;
158                let c = o + (i as f64 * 0.1).cos();
159                candle(o, o.max(c) + 0.5, o.min(c) - 0.5, c, i)
160            })
161            .collect();
162        let batch = Inertia::classic().batch(&candles);
163        let mut b = Inertia::classic();
164        let streamed: Vec<_> = candles.iter().map(|c| b.update(*c)).collect();
165        assert_eq!(batch, streamed);
166    }
167
168    #[test]
169    fn reset_clears_state() {
170        let mut inertia = Inertia::classic();
171        for i in 0..50 {
172            inertia.update(candle(10.0, 11.0, 9.0, 10.5, i));
173        }
174        assert!(inertia.is_ready());
175        inertia.reset();
176        assert!(!inertia.is_ready());
177        assert_eq!(inertia.update(candle(10.0, 11.0, 9.0, 10.5, 0)), None);
178    }
179}
wickra_core/indicators/inertia.rs

wickra_core/indicators/
inertia.rs
