//! Keltner Channels. use crate::error::{Error, Result}; use crate::indicators::atr::Atr; use crate::indicators::ema::Ema; use crate::ohlcv::Candle; use crate::traits::Indicator; /// Keltner Channels output. #[derive(Debug, Clone, Copy, PartialEq)] pub struct KeltnerOutput { /// Upper band = middle + multiplier * ATR. pub upper: f64, /// Middle band = EMA of typical price. pub middle: f64, /// Lower band = middle - multiplier * ATR. pub lower: f64, } /// Keltner Channels: an EMA centerline with bands sized by ATR. #[derive(Debug, Clone)] pub struct Keltner { ema: Ema, atr: Atr, multiplier: f64, ema_period: usize, atr_period: usize, } impl Keltner { /// # Errors /// Returns [`Error::PeriodZero`] / [`Error::NonPositiveMultiplier`] on invalid inputs. pub fn new(ema_period: usize, atr_period: usize, multiplier: f64) -> Result { if !multiplier.is_finite() || multiplier <= 0.0 { return Err(Error::NonPositiveMultiplier); } Ok(Self { ema: Ema::new(ema_period)?, atr: Atr::new(atr_period)?, multiplier, ema_period, atr_period, }) } /// Classic configuration: EMA(20), ATR(10), 2.0x multiplier. pub fn classic() -> Self { Self::new(20, 10, 2.0).expect("classic Keltner parameters are valid") } /// Configured `(ema_period, atr_period, multiplier)`. pub const fn periods(&self) -> (usize, usize, f64) { (self.ema_period, self.atr_period, self.multiplier) } } impl Indicator for Keltner { type Input = Candle; type Output = KeltnerOutput; fn update(&mut self, candle: Candle) -> Option { let mid = self.ema.update(candle.typical_price())?; let atr = self.atr.update(candle)?; Some(KeltnerOutput { upper: mid + self.multiplier * atr, middle: mid, lower: mid - self.multiplier * atr, }) } fn reset(&mut self) { self.ema.reset(); self.atr.reset(); } fn warmup_period(&self) -> usize { self.ema_period.max(self.atr_period) } fn is_ready(&self) -> bool { self.ema.is_ready() && self.atr.is_ready() } fn name(&self) -> &'static str { "KeltnerChannels" } } #[cfg(test)] mod tests { use super::*; use crate::traits::BatchExt; use approx::assert_relative_eq; fn c(h: f64, l: f64, cl: f64) -> Candle { Candle::new(cl, h, l, cl, 1.0, 0).unwrap() } #[test] fn flat_market_collapses_bands() { let candles: Vec = (0..50).map(|_| c(10.0, 10.0, 10.0)).collect(); let mut k = Keltner::new(20, 10, 2.0).unwrap(); let last = k.batch(&candles).into_iter().flatten().last().unwrap(); assert_relative_eq!(last.upper, last.middle, epsilon = 1e-9); assert_relative_eq!(last.lower, last.middle, epsilon = 1e-9); } #[test] fn upper_above_middle_above_lower() { let candles: Vec = (0..100) .map(|i| { let m = 100.0 + (f64::from(i) * 0.2).sin() * 5.0; c(m + 1.0, m - 1.0, m) }) .collect(); let mut k = Keltner::classic(); for o in k.batch(&candles).into_iter().flatten() { assert!(o.upper >= o.middle); assert!(o.middle >= o.lower); } } #[test] fn batch_equals_streaming() { let candles: Vec = (0..50) .map(|i| c(f64::from(i) + 1.0, f64::from(i) - 1.0, f64::from(i))) .collect(); let mut a = Keltner::classic(); let mut b = Keltner::classic(); assert_eq!( a.batch(&candles), candles.iter().map(|x| b.update(*x)).collect::>() ); } #[test] fn rejects_invalid_input() { assert!(Keltner::new(0, 10, 2.0).is_err()); assert!(Keltner::new(20, 10, 0.0).is_err()); assert!(Keltner::new(20, 10, -1.0).is_err()); } #[test] fn reset_clears_state() { let candles: Vec = (0..50) .map(|i| c(f64::from(i) + 1.0, f64::from(i) - 1.0, f64::from(i))) .collect(); let mut k = Keltner::classic(); k.batch(&candles); assert!(k.is_ready()); k.reset(); assert!(!k.is_ready()); assert_eq!(k.update(candles[0]), None); } }