wickra_core/indicators/
kama.rs

1//! Kaufman's Adaptive Moving Average (KAMA).
2
3use std::collections::VecDeque;
4
5use crate::error::{Error, Result};
6use crate::traits::Indicator;
7
8/// Kaufman's Adaptive Moving Average.
9///
10/// KAMA adapts its smoothing constant to volatility: efficient (trending) markets
11/// get a fast smoothing constant, choppy markets get a slow one. Parameters are
12/// the efficiency-ratio lookback (`er_period`, default 10), the fast EMA period
13/// (`fast`, default 2) and the slow EMA period (`slow`, default 30).
14///
15/// # Example
16///
17/// ```
18/// use wickra_core::{Indicator, Kama};
19///
20/// let mut indicator = Kama::new(10, 2, 30).unwrap();
21/// let mut last = None;
22/// for i in 0..80 {
23///     last = indicator.update(100.0 + f64::from(i));
24/// }
25/// assert!(last.is_some());
26/// ```
27#[derive(Debug, Clone)]
28pub struct Kama {
29    er_period: usize,
30    fast_sc: f64,
31    slow_sc: f64,
32    window: VecDeque<f64>,
33    state: Option<f64>,
34}
35
36impl Kama {
37    /// # Errors
38    /// Returns [`Error::PeriodZero`] / [`Error::InvalidPeriod`] for bad parameters.
39    pub fn new(er_period: usize, fast: usize, slow: usize) -> Result<Self> {
40        if er_period == 0 || fast == 0 || slow == 0 {
41            return Err(Error::PeriodZero);
42        }
43        if fast >= slow {
44            return Err(Error::InvalidPeriod {
45                message: "KAMA fast period must be strictly less than slow",
46            });
47        }
48        let fast_sc = 2.0 / (fast as f64 + 1.0);
49        let slow_sc = 2.0 / (slow as f64 + 1.0);
50        Ok(Self {
51            er_period,
52            fast_sc,
53            slow_sc,
54            window: VecDeque::with_capacity(er_period + 1),
55            state: None,
56        })
57    }
58
59    /// Classic Kaufman parameters: (10, 2, 30).
60    pub fn classic() -> Self {
61        Self::new(10, 2, 30).expect("classic KAMA parameters are valid")
62    }
63
64    /// Configured `(er_period, fast, slow)` periods.
65    pub fn periods(&self) -> (usize, f64, f64) {
66        (self.er_period, self.fast_sc, self.slow_sc)
67    }
68}
69
70impl Indicator for Kama {
71    type Input = f64;
72    type Output = f64;
73
74    fn update(&mut self, input: f64) -> Option<f64> {
75        if !input.is_finite() {
76            return self.state;
77        }
78        if self.window.len() == self.er_period + 1 {
79            self.window.pop_front();
80        }
81        self.window.push_back(input);
82
83        if self.window.len() < self.er_period + 1 {
84            return None;
85        }
86
87        let first = *self.window.front().expect("non-empty");
88        let last = *self.window.back().expect("non-empty");
89        let direction = (last - first).abs();
90        let volatility: f64 = self
91            .window
92            .iter()
93            .zip(self.window.iter().skip(1))
94            .map(|(a, b)| (b - a).abs())
95            .sum();
96
97        let er = if volatility == 0.0 {
98            0.0
99        } else {
100            direction / volatility
101        };
102        let sc = (er * (self.fast_sc - self.slow_sc) + self.slow_sc).powi(2);
103
104        let prev = self.state.unwrap_or(first);
105        let new = prev + sc * (input - prev);
106        self.state = Some(new);
107        Some(new)
108    }
109
110    fn reset(&mut self) {
111        self.window.clear();
112        self.state = None;
113    }
114
115    fn warmup_period(&self) -> usize {
116        self.er_period + 1
117    }
118
119    fn is_ready(&self) -> bool {
120        self.state.is_some()
121    }
122
123    fn name(&self) -> &'static str {
124        "KAMA"
125    }
126}
127
128#[cfg(test)]
129mod tests {
130    use super::*;
131    use crate::traits::BatchExt;
132    use approx::assert_relative_eq;
133
134    /// Cover the `periods` accessor (65-67) and the Indicator-impl
135    /// `warmup_period` (115-117) + `name` (123-125). Existing tests
136    /// inspect KAMA output but never query the metadata.
137    #[test]
138    fn accessors_and_metadata() {
139        let k = Kama::classic();
140        let (er, fast, slow) = k.periods();
141        assert_eq!(er, 10);
142        assert!((fast - 2.0 / (2.0 + 1.0)).abs() < 1e-12);
143        assert!((slow - 2.0 / (30.0 + 1.0)).abs() < 1e-12);
144        assert_eq!(k.warmup_period(), 11);
145        assert_eq!(k.name(), "KAMA");
146    }
147
148    #[test]
149    fn constant_series_yields_constant_kama() {
150        let mut k = Kama::classic();
151        let out = k.batch(&[100.0_f64; 100]);
152        let last = out.iter().rev().flatten().next().unwrap();
153        assert_relative_eq!(*last, 100.0, epsilon = 1e-9);
154    }
155
156    #[test]
157    fn rejects_invalid_periods() {
158        assert!(Kama::new(0, 2, 30).is_err());
159        assert!(Kama::new(10, 30, 2).is_err()); // fast >= slow
160        assert!(Kama::new(10, 2, 2).is_err()); // fast == slow
161    }
162
163    #[test]
164    fn batch_equals_streaming() {
165        let prices: Vec<f64> = (1..=120)
166            .map(|i| (f64::from(i) * 0.2).sin() * 5.0 + f64::from(i) * 0.1)
167            .collect();
168        let mut a = Kama::classic();
169        let mut b = Kama::classic();
170        assert_eq!(
171            a.batch(&prices),
172            prices.iter().map(|p| b.update(*p)).collect::<Vec<_>>()
173        );
174    }
175
176    #[test]
177    fn reset_clears_state() {
178        let mut k = Kama::classic();
179        k.batch(&(1..=50).map(f64::from).collect::<Vec<_>>());
180        assert!(k.is_ready());
181        k.reset();
182        assert!(!k.is_ready());
183    }
184
185    #[test]
186    fn ignores_non_finite_input() {
187        let mut k = Kama::classic();
188        k.batch(&(1..=40).map(f64::from).collect::<Vec<_>>());
189        let before = k.update(41.0);
190        assert!(before.is_some());
191        // Non-finite inputs return the last state without sliding the window.
192        assert_eq!(k.update(f64::NAN), before);
193        assert_eq!(k.update(f64::INFINITY), before);
194    }
195}
wickra_core/indicators/kama.rs

wickra_core/indicators/
kama.rs
