wickra_core/indicators/
cci.rs

1//! Commodity Channel Index (CCI).
2
3use std::collections::VecDeque;
4
5use crate::error::{Error, Result};
6use crate::ohlcv::Candle;
7use crate::traits::Indicator;
8
9/// Commodity Channel Index.
10///
11/// `CCI = (TP - SMA(TP)) / (0.015 * mean absolute deviation of TP)`, where
12/// `TP = (high + low + close) / 3`.
13///
14/// # Example
15///
16/// ```
17/// use wickra_core::{Candle, Indicator, Cci};
18///
19/// let mut indicator = Cci::new(5).unwrap();
20/// let mut last = None;
21/// for i in 0..80 {
22///     let base = 100.0 + f64::from(i);
23///     let candle =
24///         Candle::new(base, base + 2.0, base - 2.0, base + 1.0, 10.0, i64::from(i)).unwrap();
25///     last = indicator.update(candle);
26/// }
27/// assert!(last.is_some());
28/// ```
29#[derive(Debug, Clone)]
30pub struct Cci {
31    period: usize,
32    factor: f64,
33    window: VecDeque<f64>,
34    sum: f64,
35}
36
37impl Cci {
38    /// Construct a new CCI with the canonical 0.015 scaling factor.
39    ///
40    /// # Errors
41    /// Returns [`Error::PeriodZero`] if `period == 0`.
42    pub fn new(period: usize) -> Result<Self> {
43        Self::with_factor(period, 0.015)
44    }
45
46    /// Construct a CCI with a custom scaling factor (the standard literature
47    /// uses 0.015 to put roughly 70 % of values inside ±100).
48    ///
49    /// # Errors
50    /// Returns [`Error::PeriodZero`] if `period == 0` and
51    /// [`Error::NonPositiveMultiplier`] if `factor <= 0`.
52    pub fn with_factor(period: usize, factor: f64) -> Result<Self> {
53        if period == 0 {
54            return Err(Error::PeriodZero);
55        }
56        if !factor.is_finite() || factor <= 0.0 {
57            return Err(Error::NonPositiveMultiplier);
58        }
59        Ok(Self {
60            period,
61            factor,
62            window: VecDeque::with_capacity(period),
63            sum: 0.0,
64        })
65    }
66
67    /// Configured period.
68    pub const fn period(&self) -> usize {
69        self.period
70    }
71}
72
73impl Indicator for Cci {
74    type Input = Candle;
75    type Output = f64;
76
77    fn update(&mut self, candle: Candle) -> Option<f64> {
78        let tp = candle.typical_price();
79        if self.window.len() == self.period {
80            let old = self.window.pop_front().expect("non-empty");
81            self.sum -= old;
82        }
83        self.window.push_back(tp);
84        self.sum += tp;
85        if self.window.len() < self.period {
86            return None;
87        }
88        let n = self.period as f64;
89        let mean = self.sum / n;
90        let mad: f64 = self.window.iter().map(|v| (v - mean).abs()).sum::<f64>() / n;
91        if mad == 0.0 {
92            return Some(0.0);
93        }
94        Some((tp - mean) / (self.factor * mad))
95    }
96
97    fn reset(&mut self) {
98        self.window.clear();
99        self.sum = 0.0;
100    }
101
102    fn warmup_period(&self) -> usize {
103        self.period
104    }
105
106    fn is_ready(&self) -> bool {
107        self.window.len() == self.period
108    }
109
110    fn name(&self) -> &'static str {
111        "CCI"
112    }
113}
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118    use crate::traits::BatchExt;
119    use approx::assert_relative_eq;
120
121    fn c(h: f64, l: f64, cl: f64) -> Candle {
122        Candle::new(cl, h, l, cl, 1.0, 0).unwrap()
123    }
124
125    #[test]
126    fn flat_candles_yield_zero() {
127        let candles: Vec<Candle> = (0..30).map(|_| c(10.0, 10.0, 10.0)).collect();
128        let mut cci = Cci::new(20).unwrap();
129        for v in cci.batch(&candles).into_iter().flatten() {
130            assert_relative_eq!(v, 0.0, epsilon = 1e-12);
131        }
132    }
133
134    #[test]
135    fn rejects_invalid_input() {
136        assert!(Cci::new(0).is_err());
137        assert!(Cci::with_factor(20, 0.0).is_err());
138        assert!(Cci::with_factor(20, -1.0).is_err());
139    }
140
141    /// Cover the const accessor `period` (68-70) and the Indicator-impl
142    /// `warmup_period` (102-104) + `name` (110-112). Existing tests never
143    /// inspect these metadata methods.
144    #[test]
145    fn accessors_and_metadata() {
146        let cci = Cci::new(20).unwrap();
147        assert_eq!(cci.period(), 20);
148        assert_eq!(cci.warmup_period(), 20);
149        assert_eq!(cci.name(), "CCI");
150    }
151
152    #[test]
153    fn batch_equals_streaming() {
154        let candles: Vec<Candle> = (0..60)
155            .map(|i| {
156                let m = 50.0 + (f64::from(i) * 0.2).sin() * 10.0;
157                c(m + 1.0, m - 1.0, m)
158            })
159            .collect();
160        let mut a = Cci::new(20).unwrap();
161        let mut b = Cci::new(20).unwrap();
162        assert_eq!(
163            a.batch(&candles),
164            candles.iter().map(|x| b.update(*x)).collect::<Vec<_>>()
165        );
166    }
167
168    #[test]
169    fn reset_clears_state() {
170        let candles: Vec<Candle> = (0..30).map(|_| c(10.0, 10.0, 10.0)).collect();
171        let mut cci = Cci::new(20).unwrap();
172        cci.batch(&candles);
173        assert!(cci.is_ready());
174        cci.reset();
175        assert!(!cci.is_ready());
176    }
177}
wickra_core/indicators/cci.rs

wickra_core/indicators/
cci.rs
