quantwave_core/indicators/
kama.rs

1use crate::indicators::metadata::{IndicatorMetadata, ParamDef};
2use crate::traits::Next;
3use std::collections::VecDeque;
4
5/// Kaufman's Adaptive Moving Average (KAMA)
6///
7/// KAMA is an adaptive moving average that adjusts its smoothing based on the 
8/// efficiency of price movement (signal-to-noise ratio).
9#[derive(Debug, Clone)]
10pub struct Kama {
11    period: usize,
12    fast_sc: f64,
13    slow_sc: f64,
14    window: VecDeque<f64>,
15    prev_kama: Option<f64>,
16}
17
18impl Kama {
19    pub fn new(period: usize, fast_period: usize, slow_period: usize) -> Self {
20        let fast_sc = 2.0 / (fast_period as f64 + 1.0);
21        let slow_sc = 2.0 / (slow_period as f64 + 1.0);
22        
23        Self {
24            period,
25            fast_sc,
26            slow_sc,
27            window: VecDeque::with_capacity(period + 1),
28            prev_kama: None,
29        }
30    }
31}
32
33impl Default for Kama {
34    fn default() -> Self {
35        Self::new(10, 2, 30)
36    }
37}
38
39impl Next<f64> for Kama {
40    type Output = f64;
41
42    fn next(&mut self, input: f64) -> Self::Output {
43        self.window.push_front(input);
44        if self.window.len() > self.period + 1 {
45            self.window.pop_back();
46        }
47
48        if self.window.len() <= self.period {
49            if self.prev_kama.is_none() {
50                self.prev_kama = Some(input);
51            }
52            return input;
53        }
54
55        // Efficiency Ratio (ER)
56        // Signal = abs(Price - Price[N])
57        let signal = (input - self.window.back().unwrap()).abs();
58        
59        // Noise = sum(abs(Price - Price[1]), N)
60        let mut noise = 0.0;
61        for i in 0..self.period {
62            noise += (self.window[i] - self.window[i+1]).abs();
63        }
64        
65        let er = if noise != 0.0 { signal / noise } else { 0.0 };
66        
67        // Smoothing Constant (SC)
68        let sc = (er * (self.fast_sc - self.slow_sc) + self.slow_sc).powi(2);
69        
70        // KAMA
71        let prev = self.prev_kama.unwrap_or(input);
72        let kama = prev + sc * (input - prev);
73        self.prev_kama = Some(kama);
74        
75        kama
76    }
77}
78
79pub const KAMA_METADATA: IndicatorMetadata = IndicatorMetadata {
80    name: "KAMA",
81    description: "Kaufman's Adaptive Moving Average adjusts its sensitivity based on market volatility.",
82    usage: "Use as an adaptive moving average that is fast in trending markets and slow in choppy, sideways conditions. Reduces whipsaws that plague fixed-period moving averages in ranging markets.",
83    keywords: &["moving-average", "adaptive", "smoothing", "classic"],
84    ehlers_summary: "Perry Kaufman designed KAMA using an Efficiency Ratio that measures how directionally price has moved versus total path length. A high ratio (strong trend) produces a fast-reacting EMA; a low ratio (choppy market) produces a near-flat line, dramatically reducing false signals during consolidation. — New Trading Systems and Methods, 4th ed.",
85    params: &[
86        ParamDef { name: "period", default: "10", description: "Efficiency Ratio lookback period" },
87        ParamDef { name: "fast_period", default: "2", description: "Fastest smoothing period" },
88        ParamDef { name: "slow_period", default: "30", description: "Slowest smoothing period" },
89    ],
90    formula_source: "https://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:kaufman_s_adaptive_moving_average",
91    formula_latex: r#"
92\[
93ER = \frac{|Price - Price_{t-n}|}{\sum |Price - Price_{t-1}|}
94\]
95\[
96SC = [ER(FastSC - SlowSC) + SlowSC]^2
97\]
98\[
99KAMA = KAMA_{t-1} + SC(Price - KAMA_{t-1})
100\]
101"#,
102    gold_standard_file: "kama.json",
103    category: "Classic",
104};
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109    use crate::traits::Next;
110    use proptest::prelude::*;
111
112    #[test]
113    fn test_kama_basic() {
114        let mut kama = Kama::new(10, 2, 30);
115        let inputs = vec![10.0, 11.0, 10.5, 12.0, 13.0, 14.0, 13.5, 15.0, 16.0, 17.0, 18.0, 19.0];
116        for input in inputs {
117            let res = kama.next(input);
118            assert!(!res.is_nan());
119        }
120    }
121
122    proptest! {
123        #[test]
124        fn test_kama_parity(
125            inputs in prop::collection::vec(1.0..100.0, 50..100),
126        ) {
127            let period = 10;
128            let mut kama = Kama::new(period, 2, 30);
129            let streaming_results: Vec<f64> = inputs.iter().map(|&x| kama.next(x)).collect();
130
131            let mut prev_kama = None;
132            let fast_sc = 2.0 / (2.0 + 1.0);
133            let slow_sc = 2.0 / (30.0 + 1.0);
134            
135            for (i, &input) in inputs.iter().enumerate() {
136                if i < period {
137                    if prev_kama.is_none() { prev_kama = Some(input); }
138                    approx::assert_relative_eq!(streaming_results[i], input, epsilon = 1e-10);
139                    continue;
140                }
141                
142                let signal = (input - inputs[i - period]).abs();
143                let mut noise = 0.0;
144                for j in 0..period {
145                    noise += (inputs[i-j] - inputs[i-j-1]).abs();
146                }
147                
148                let er = if noise != 0.0 { signal / noise } else { 0.0 };
149                let sc = (er * (fast_sc - slow_sc) + slow_sc).powi(2);
150                let current_kama = prev_kama.unwrap() + sc * (input - prev_kama.unwrap());
151                
152                approx::assert_relative_eq!(streaming_results[i], current_kama, epsilon = 1e-10);
153                prev_kama = Some(current_kama);
154            }
155        }
156    }
157}
quantwave_core/indicators/kama.rs

quantwave_core/indicators/
kama.rs
