Wickra 0.1.0: streaming-first technical indicators

A multi-language technical analysis library: 25 indicators across trend, momentum, volatility, and volume families, every one a state machine with O(1) per-tick updates. Batch evaluation is provided by a blanket extension trait over the streaming primitive, so live trading bots and historical backtests run the same code path. What ships in this initial drop: crates/wickra-core - 25 indicators, Indicator/BatchExt/Chain traits, OHLCV types with validation; 171 unit tests, property tests, Wilder/Bollinger textbook tests. crates/wickra - top-level facade + criterion benches for every indicator at 1K/10K/100K series sizes. crates/wickra-data - streaming CSV reader, tick-to-candle aggregator, multi-timeframe resampler, Binance Spot kline WebSocket adapter behind feature live-binance; 11 unit + 1 doctest. bindings/python - PyO3 + maturin, NumPy I/O, type stubs (.pyi), 56 pytest tests including streaming==batch equivalence, Wilder reference values, lifecycle. bindings/node - napi-rs native module, TypeScript .d.ts auto-generated, 7 node --test cases. bindings/wasm - wasm-bindgen ES module for browser/bundler/Node; interactive HTML demo at examples/index.html. examples/ - Python and Rust scripts: backtest, live trading, parallel multi-asset, multi-timeframe, Binance. benchmarks/ - cross-library comparison against TA-Lib, pandas-ta, finta, talipp; Wickra wins every category by 11-1030x (batch) and 17x+ streaming. .github/workflows/ - CI matrix (Rust + Python + Node + WASM on Linux/macOS/Windows), release pipeline for PyPI wheels and npm. Indicators (25): Trend SMA EMA WMA DEMA TEMA HMA KAMA Momentum RSI MACD Stochastic CCI ROC WilliamsR ADX MFI TRIX AwesomeOscillator Aroon Volatility BollingerBands ATR Keltner Donchian PSAR Volume OBV VWAP (cumulative + rolling) cargo clippy --workspace --all-targets -D warnings is clean. License: Apache-2.0.
2026-05-21 17:50:45 +02:00
commit 3be267cb03
81 changed files with 14453 additions and 0 deletions
@@ -0,0 +1,243 @@
+//! Bollinger Bands.
+
+use std::collections::VecDeque;
+
+use crate::error::{Error, Result};
+use crate::traits::Indicator;
+
+/// Bollinger Bands output.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct BollingerOutput {
+    /// Upper band: `middle + multiplier * stddev`.
+    pub upper: f64,
+    /// Middle band: SMA over the window.
+    pub middle: f64,
+    /// Lower band: `middle − multiplier * stddev`.
+    pub lower: f64,
+    /// Sample standard deviation (denominator `period`, population stddev) used to build
+    /// the bands. Reported separately because some callers compute their own bands.
+    pub stddev: f64,
+}
+
+/// Bollinger Bands with SMA middle band and population standard deviation envelopes.
+///
+/// Standard parameters are `period = 20`, `multiplier = 2.0`. Bollinger's original
+/// publication uses population (not sample) standard deviation, which matches every
+/// reference implementation (TA-Lib, pandas-ta, etc.).
+#[derive(Debug, Clone)]
+pub struct BollingerBands {
+    period: usize,
+    multiplier: f64,
+    window: VecDeque<f64>,
+    sum: f64,
+    sum_sq: f64,
+}
+
+impl BollingerBands {
+    /// Construct a new Bollinger Bands indicator.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::PeriodZero`] for `period == 0` and
+    /// [`Error::NonPositiveMultiplier`] for `multiplier <= 0`.
+    pub fn new(period: usize, multiplier: f64) -> Result<Self> {
+        if period == 0 {
+            return Err(Error::PeriodZero);
+        }
+        if !multiplier.is_finite() || multiplier <= 0.0 {
+            return Err(Error::NonPositiveMultiplier);
+        }
+        Ok(Self {
+            period,
+            multiplier,
+            window: VecDeque::with_capacity(period),
+            sum: 0.0,
+            sum_sq: 0.0,
+        })
+    }
+
+    /// Classic configuration: `period = 20`, `multiplier = 2.0`.
+    pub fn classic() -> Self {
+        Self::new(20, 2.0).expect("classic Bollinger parameters are valid")
+    }
+
+    /// Configured period.
+    pub const fn period(&self) -> usize {
+        self.period
+    }
+
+    /// Configured multiplier.
+    pub const fn multiplier(&self) -> f64 {
+        self.multiplier
+    }
+
+    fn current(&self) -> Option<BollingerOutput> {
+        if self.window.len() != self.period {
+            return None;
+        }
+        let n = self.period as f64;
+        let mean = self.sum / n;
+        // Population variance: E[x^2] - (E[x])^2. Clamp small negative values that arise
+        // from catastrophic cancellation on near-constant inputs.
+        let var = (self.sum_sq / n - mean * mean).max(0.0);
+        let stddev = var.sqrt();
+        Some(BollingerOutput {
+            upper: mean + self.multiplier * stddev,
+            middle: mean,
+            lower: mean - self.multiplier * stddev,
+            stddev,
+        })
+    }
+}
+
+impl Indicator for BollingerBands {
+    type Input = f64;
+    type Output = BollingerOutput;
+
+    fn update(&mut self, input: f64) -> Option<BollingerOutput> {
+        if !input.is_finite() {
+            return self.current();
+        }
+        if self.window.len() == self.period {
+            let old = self.window.pop_front().expect("non-empty");
+            self.sum -= old;
+            self.sum_sq -= old * old;
+        }
+        self.window.push_back(input);
+        self.sum += input;
+        self.sum_sq += input * input;
+        self.current()
+    }
+
+    fn reset(&mut self) {
+        self.window.clear();
+        self.sum = 0.0;
+        self.sum_sq = 0.0;
+    }
+
+    fn warmup_period(&self) -> usize {
+        self.period
+    }
+
+    fn is_ready(&self) -> bool {
+        self.window.len() == self.period
+    }
+
+    fn name(&self) -> &'static str {
+        "BollingerBands"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::traits::BatchExt;
+    use approx::assert_relative_eq;
+
+    fn naive(prices: &[f64], period: usize, mult: f64) -> Option<BollingerOutput> {
+        if prices.len() < period {
+            return None;
+        }
+        let w = &prices[prices.len() - period..];
+        let mean = w.iter().sum::<f64>() / period as f64;
+        let var = w.iter().map(|x| (x - mean).powi(2)).sum::<f64>() / period as f64;
+        let s = var.sqrt();
+        Some(BollingerOutput {
+            upper: mean + mult * s,
+            middle: mean,
+            lower: mean - mult * s,
+            stddev: s,
+        })
+    }
+
+    #[test]
+    fn rejects_zero_period() {
+        assert!(matches!(
+            BollingerBands::new(0, 2.0),
+            Err(Error::PeriodZero)
+        ));
+    }
+
+    #[test]
+    fn rejects_non_positive_multiplier() {
+        assert!(matches!(
+            BollingerBands::new(20, 0.0),
+            Err(Error::NonPositiveMultiplier)
+        ));
+        assert!(matches!(
+            BollingerBands::new(20, -1.0),
+            Err(Error::NonPositiveMultiplier)
+        ));
+        assert!(matches!(
+            BollingerBands::new(20, f64::NAN),
+            Err(Error::NonPositiveMultiplier)
+        ));
+    }
+
+    #[test]
+    fn warmup_returns_none() {
+        let mut bb = BollingerBands::new(5, 2.0).unwrap();
+        for v in [1.0, 2.0, 3.0, 4.0] {
+            assert!(bb.update(v).is_none());
+        }
+        assert!(bb.update(5.0).is_some());
+    }
+
+    #[test]
+    fn constant_series_yields_zero_stddev() {
+        let mut bb = BollingerBands::new(10, 2.0).unwrap();
+        let out = bb.batch(&[5.0_f64; 30]);
+        let last = out.iter().rev().flatten().next().unwrap();
+        assert_relative_eq!(last.middle, 5.0, epsilon = 1e-12);
+        assert_relative_eq!(last.stddev, 0.0, epsilon = 1e-12);
+        assert_relative_eq!(last.upper, 5.0, epsilon = 1e-12);
+        assert_relative_eq!(last.lower, 5.0, epsilon = 1e-12);
+    }
+
+    #[test]
+    fn matches_naive_definition() {
+        let prices: Vec<f64> = (1..=60)
+            .map(|i| (f64::from(i) * 0.3).sin() * 10.0 + 50.0)
+            .collect();
+        let mut bb = BollingerBands::new(20, 2.0).unwrap();
+        let out = bb.batch(&prices);
+        for i in 19..prices.len() {
+            let got = out[i].unwrap();
+            let want = naive(&prices[..=i], 20, 2.0).unwrap();
+            assert_relative_eq!(got.middle, want.middle, epsilon = 1e-9);
+            assert_relative_eq!(got.stddev, want.stddev, epsilon = 1e-9);
+            assert_relative_eq!(got.upper, want.upper, epsilon = 1e-9);
+            assert_relative_eq!(got.lower, want.lower, epsilon = 1e-9);
+        }
+    }
+
+    #[test]
+    fn upper_above_middle_above_lower() {
+        let prices: Vec<f64> = (1..=100).map(f64::from).collect();
+        let mut bb = BollingerBands::new(20, 2.0).unwrap();
+        for o in bb.batch(&prices).into_iter().flatten() {
+            assert!(o.upper >= o.middle);
+            assert!(o.middle >= o.lower);
+        }
+    }
+
+    #[test]
+    fn batch_equals_streaming() {
+        let prices: Vec<f64> = (1..=50).map(|i| f64::from(i) * 0.7).collect();
+        let mut a = BollingerBands::new(10, 2.0).unwrap();
+        let mut b = BollingerBands::new(10, 2.0).unwrap();
+        assert_eq!(
+            a.batch(&prices),
+            prices.iter().map(|p| b.update(*p)).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn reset_clears_state() {
+        let mut bb = BollingerBands::new(5, 2.0).unwrap();
+        bb.batch(&[1.0, 2.0, 3.0, 4.0, 5.0]);
+        assert!(bb.is_ready());
+        bb.reset();
+        assert!(!bb.is_ready());
+    }
+}