fin_primitives/signals/indicators/
bar_range_std_dev.rs

1//! Bar Range Standard Deviation indicator.
2
3use crate::error::FinError;
4use crate::signals::{BarInput, Signal, SignalValue};
5use rust_decimal::prelude::{FromPrimitive, ToPrimitive};
6use rust_decimal::Decimal;
7use std::collections::VecDeque;
8
9/// Bar Range Standard Deviation — the population standard deviation of the
10/// `high - low` range over the last `period` bars.
11///
12/// This measures how consistent bar sizes are. A low value indicates uniform
13/// range (orderly market); a high value indicates range is erratic.
14///
15/// Returns [`SignalValue::Unavailable`] until `period` bars have been seen.
16///
17/// # Example
18/// ```rust
19/// use fin_primitives::signals::indicators::BarRangeStdDev;
20/// use fin_primitives::signals::Signal;
21///
22/// let brsd = BarRangeStdDev::new("brsd", 20).unwrap();
23/// assert_eq!(brsd.period(), 20);
24/// ```
25pub struct BarRangeStdDev {
26    name: String,
27    period: usize,
28    ranges: VecDeque<Decimal>,
29}
30
31impl BarRangeStdDev {
32    /// Constructs a new `BarRangeStdDev`.
33    ///
34    /// # Errors
35    /// Returns [`FinError::InvalidPeriod`] if `period < 2`.
36    pub fn new(name: impl Into<String>, period: usize) -> Result<Self, FinError> {
37        if period < 2 {
38            return Err(FinError::InvalidPeriod(period));
39        }
40        Ok(Self {
41            name: name.into(),
42            period,
43            ranges: VecDeque::with_capacity(period),
44        })
45    }
46}
47
48impl Signal for BarRangeStdDev {
49    fn name(&self) -> &str { &self.name }
50    fn period(&self) -> usize { self.period }
51    fn is_ready(&self) -> bool { self.ranges.len() >= self.period }
52
53    fn update(&mut self, bar: &BarInput) -> Result<SignalValue, FinError> {
54        let range = bar.high - bar.low;
55        self.ranges.push_back(range);
56        if self.ranges.len() > self.period { self.ranges.pop_front(); }
57
58        if self.ranges.len() < self.period {
59            return Ok(SignalValue::Unavailable);
60        }
61
62        let vals: Vec<f64> = self.ranges.iter().filter_map(|r| r.to_f64()).collect();
63        if vals.len() != self.period {
64            return Ok(SignalValue::Unavailable);
65        }
66
67        let nf = vals.len() as f64;
68        let mean = vals.iter().sum::<f64>() / nf;
69        let var = vals.iter().map(|v| { let d = v - mean; d * d }).sum::<f64>() / nf;
70
71        match Decimal::from_f64(var.sqrt()) {
72            Some(v) => Ok(SignalValue::Scalar(v)),
73            None => Ok(SignalValue::Unavailable),
74        }
75    }
76
77    fn reset(&mut self) {
78        self.ranges.clear();
79    }
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85    use crate::ohlcv::OhlcvBar;
86    use crate::signals::Signal;
87    use crate::types::{NanoTimestamp, Price, Quantity, Symbol};
88    use rust_decimal_macros::dec;
89
90    fn bar(h: &str, l: &str) -> OhlcvBar {
91        let hp = Price::new(h.parse().unwrap()).unwrap();
92        let lp = Price::new(l.parse().unwrap()).unwrap();
93        OhlcvBar {
94            symbol: Symbol::new("X").unwrap(),
95            open: lp, high: hp, low: lp, close: hp,
96            volume: Quantity::zero(),
97            ts_open: NanoTimestamp::new(0),
98            ts_close: NanoTimestamp::new(1),
99            tick_count: 1,
100        }
101    }
102
103    #[test]
104    fn test_brsd_invalid_period() {
105        assert!(BarRangeStdDev::new("brsd", 0).is_err());
106        assert!(BarRangeStdDev::new("brsd", 1).is_err());
107    }
108
109    #[test]
110    fn test_brsd_unavailable_before_warm_up() {
111        let mut brsd = BarRangeStdDev::new("brsd", 3).unwrap();
112        for _ in 0..2 {
113            assert_eq!(brsd.update_bar(&bar("110", "90")).unwrap(), SignalValue::Unavailable);
114        }
115    }
116
117    #[test]
118    fn test_brsd_constant_range_gives_zero() {
119        // All bars have the same range → std dev = 0
120        let mut brsd = BarRangeStdDev::new("brsd", 3).unwrap();
121        let mut last = SignalValue::Unavailable;
122        for _ in 0..3 {
123            last = brsd.update_bar(&bar("110", "90")).unwrap(); // range=20
124        }
125        assert_eq!(last, SignalValue::Scalar(dec!(0)));
126    }
127
128    #[test]
129    fn test_brsd_varying_range_positive() {
130        let mut brsd = BarRangeStdDev::new("brsd", 3).unwrap();
131        let mut last = SignalValue::Unavailable;
132        for &(h, l) in &[("110", "90"), ("130", "80"), ("105", "100")] {
133            last = brsd.update_bar(&bar(h, l)).unwrap();
134        }
135        if let SignalValue::Scalar(v) = last {
136            assert!(v > dec!(0), "varying ranges should give positive std dev: {}", v);
137        } else {
138            panic!("expected Scalar");
139        }
140    }
141
142    #[test]
143    fn test_brsd_reset() {
144        let mut brsd = BarRangeStdDev::new("brsd", 3).unwrap();
145        for _ in 0..3 { brsd.update_bar(&bar("110", "90")).unwrap(); }
146        assert!(brsd.is_ready());
147        brsd.reset();
148        assert!(!brsd.is_ready());
149    }
150}
fin_primitives/signals/indicators/bar_range_std_dev.rs

fin_primitives/signals/indicators/
bar_range_std_dev.rs
