wickra_core/indicators/
keltner.rs

1//! Keltner Channels.
2
3use crate::error::{Error, Result};
4use crate::indicators::atr::Atr;
5use crate::indicators::ema::Ema;
6use crate::ohlcv::Candle;
7use crate::traits::Indicator;
8
9/// Keltner Channels output.
10#[derive(Debug, Clone, Copy, PartialEq)]
11pub struct KeltnerOutput {
12    /// Upper band = middle + multiplier * ATR.
13    pub upper: f64,
14    /// Middle band = EMA of typical price.
15    pub middle: f64,
16    /// Lower band = middle - multiplier * ATR.
17    pub lower: f64,
18}
19
20/// Keltner Channels: an EMA centerline with bands sized by ATR.
21///
22/// # Example
23///
24/// ```
25/// use wickra_core::{Candle, Indicator, Keltner};
26///
27/// let mut indicator = Keltner::new(5, 5, 2.0).unwrap();
28/// let mut last = None;
29/// for i in 0..80 {
30///     let base = 100.0 + f64::from(i);
31///     let candle =
32///         Candle::new(base, base + 2.0, base - 2.0, base + 1.0, 10.0, i64::from(i)).unwrap();
33///     last = indicator.update(candle);
34/// }
35/// assert!(last.is_some());
36/// ```
37#[derive(Debug, Clone)]
38pub struct Keltner {
39    ema: Ema,
40    atr: Atr,
41    multiplier: f64,
42    ema_period: usize,
43    atr_period: usize,
44}
45
46impl Keltner {
47    /// # Errors
48    /// Returns [`Error::PeriodZero`] / [`Error::NonPositiveMultiplier`] on invalid inputs.
49    pub fn new(ema_period: usize, atr_period: usize, multiplier: f64) -> Result<Self> {
50        if !multiplier.is_finite() || multiplier <= 0.0 {
51            return Err(Error::NonPositiveMultiplier);
52        }
53        Ok(Self {
54            ema: Ema::new(ema_period)?,
55            atr: Atr::new(atr_period)?,
56            multiplier,
57            ema_period,
58            atr_period,
59        })
60    }
61
62    /// Classic configuration: EMA(20), ATR(10), 2.0x multiplier.
63    pub fn classic() -> Self {
64        Self::new(20, 10, 2.0).expect("classic Keltner parameters are valid")
65    }
66
67    /// Configured `(ema_period, atr_period, multiplier)`.
68    pub const fn periods(&self) -> (usize, usize, f64) {
69        (self.ema_period, self.atr_period, self.multiplier)
70    }
71}
72
73impl Indicator for Keltner {
74    type Input = Candle;
75    type Output = KeltnerOutput;
76
77    #[inline]
78    fn update(&mut self, candle: Candle) -> Option<KeltnerOutput> {
79        // Feed both sub-indicators on every candle so they warm up in parallel.
80        // Gating `atr.update` behind `ema.update(...)?` would starve the ATR of
81        // every candle consumed during the EMA's warmup, delaying the first
82        // emission past `warmup_period()` and seeding the ATR over the wrong
83        // window.
84        let mid = self.ema.update(candle.typical_price());
85        let atr = self.atr.update(candle);
86        let (mid, atr) = (mid?, atr?);
87        Some(KeltnerOutput {
88            upper: mid + self.multiplier * atr,
89            middle: mid,
90            lower: mid - self.multiplier * atr,
91        })
92    }
93
94    fn reset(&mut self) {
95        self.ema.reset();
96        self.atr.reset();
97    }
98
99    #[inline]
100    fn warmup_period(&self) -> usize {
101        self.ema_period.max(self.atr_period)
102    }
103
104    #[inline]
105    fn is_ready(&self) -> bool {
106        self.ema.is_ready() && self.atr.is_ready()
107    }
108
109    #[inline]
110    fn name(&self) -> &'static str {
111        "KeltnerChannels"
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_market_collapses_bands() {
127        let candles: Vec<Candle> = (0..50).map(|_| c(10.0, 10.0, 10.0)).collect();
128        let mut k = Keltner::new(20, 10, 2.0).unwrap();
129        let last = k.batch(&candles).into_iter().flatten().last().unwrap();
130        assert_relative_eq!(last.upper, last.middle, epsilon = 1e-9);
131        assert_relative_eq!(last.lower, last.middle, epsilon = 1e-9);
132    }
133
134    #[test]
135    fn upper_above_middle_above_lower() {
136        let candles: Vec<Candle> = (0..100)
137            .map(|i| {
138                let m = 100.0 + (f64::from(i) * 0.2).sin() * 5.0;
139                c(m + 1.0, m - 1.0, m)
140            })
141            .collect();
142        let mut k = Keltner::classic();
143        for o in k.batch(&candles).into_iter().flatten() {
144            assert!(o.upper >= o.middle);
145            assert!(o.middle >= o.lower);
146        }
147    }
148
149    #[test]
150    fn batch_equals_streaming() {
151        let candles: Vec<Candle> = (0..50)
152            .map(|i| c(f64::from(i) + 1.0, f64::from(i) - 1.0, f64::from(i)))
153            .collect();
154        let mut a = Keltner::classic();
155        let mut b = Keltner::classic();
156        assert_eq!(
157            a.batch(&candles),
158            candles.iter().map(|x| b.update(*x)).collect::<Vec<_>>()
159        );
160    }
161
162    #[test]
163    fn rejects_invalid_input() {
164        assert!(Keltner::new(0, 10, 2.0).is_err());
165        assert!(Keltner::new(20, 10, 0.0).is_err());
166        assert!(Keltner::new(20, 10, -1.0).is_err());
167    }
168
169    /// Cover the const accessor `periods` (68-70) and the Indicator-impl
170    /// `name` body (106-108). Existing tests inspect band output but
171    /// never query the metadata.
172    #[test]
173    fn accessors_and_metadata() {
174        let k = Keltner::new(20, 10, 2.0).unwrap();
175        let (ema, atr, mult) = k.periods();
176        assert_eq!(ema, 20);
177        assert_eq!(atr, 10);
178        assert!((mult - 2.0).abs() < 1e-12);
179        assert_eq!(k.name(), "KeltnerChannels");
180    }
181
182    #[test]
183    fn reset_clears_state() {
184        let candles: Vec<Candle> = (0..50)
185            .map(|i| c(f64::from(i) + 1.0, f64::from(i) - 1.0, f64::from(i)))
186            .collect();
187        let mut k = Keltner::classic();
188        k.batch(&candles);
189        assert!(k.is_ready());
190        k.reset();
191        assert!(!k.is_ready());
192        assert_eq!(k.update(candles[0]), None);
193    }
194
195    #[test]
196    fn first_emission_matches_warmup_period() {
197        let candles: Vec<Candle> = (0..60)
198            .map(|i| {
199                let base = 100.0 + f64::from(i);
200                c(base + 1.0, base - 1.0, base)
201            })
202            .collect();
203        let mut k = Keltner::classic();
204        let out = k.batch(&candles);
205        let warmup = k.warmup_period();
206        assert_eq!(warmup, 20);
207        for (i, v) in out.iter().enumerate().take(warmup - 1) {
208            assert!(v.is_none(), "index {i} must be None during warmup");
209        }
210        assert!(
211            out[warmup - 1].is_some(),
212            "first KeltnerOutput must land at warmup_period - 1"
213        );
214    }
215
216    #[test]
217    fn matches_independent_ema_and_atr() {
218        // The EMA (on typical price) and the ATR (on the candle) run as
219        // independent siblings; Keltner must equal feeding two standalone
220        // instances and combining them once both are ready.
221        let candles: Vec<Candle> = (0..60)
222            .map(|i| {
223                let m = 100.0 + (f64::from(i) * 0.2).sin() * 5.0;
224                c(m + 1.5, m - 1.5, m)
225            })
226            .collect();
227        let mut k = Keltner::classic();
228        let mut ema = Ema::new(20).unwrap();
229        let mut atr = Atr::new(10).unwrap();
230        for (i, candle) in candles.iter().enumerate() {
231            let got = k.update(*candle);
232            let mid = ema.update(candle.typical_price());
233            let a = atr.update(*candle);
234            match (mid, a) {
235                (Some(m), Some(av)) => {
236                    let o = got.expect("Keltner emits once EMA and ATR are both ready");
237                    assert_relative_eq!(o.middle, m, epsilon = 1e-9);
238                    assert_relative_eq!(o.upper, m + 2.0 * av, epsilon = 1e-9);
239                    assert_relative_eq!(o.lower, m - 2.0 * av, epsilon = 1e-9);
240                }
241                _ => assert!(
242                    got.is_none(),
243                    "Keltner must be None until both ready (i={i})"
244                ),
245            }
246        }
247    }
248}
wickra_core/indicators/keltner.rs

wickra_core/indicators/
keltner.rs
