wickra_core/indicators/
tick_bars.rs

1//! Tick bar builder — aggregate a fixed number of candles into one OHLCV bar.
2
3use crate::error::{Error, Result};
4use crate::ohlcv::Candle;
5use crate::traits::BarBuilder;
6
7/// One completed tick bar (an OHLCV aggregate of `ticks` input candles).
8#[derive(Debug, Clone, Copy, PartialEq)]
9pub struct TickBar {
10    /// Open of the first candle in the group.
11    pub open: f64,
12    /// Highest high across the group.
13    pub high: f64,
14    /// Lowest low across the group.
15    pub low: f64,
16    /// Close of the last candle in the group.
17    pub close: f64,
18    /// Summed volume across the group.
19    pub volume: f64,
20}
21
22/// Tick bar builder — emits one OHLCV bar for every `ticks` input candles.
23///
24/// Classic time bars (1-minute, 1-hour) sample the market on a clock; tick bars
25/// sample it on *activity* by grouping a fixed number of trades — here modelled as a
26/// fixed number of input candles. In fast markets a tick bar closes quickly; in
27/// quiet markets it takes longer, so each bar carries roughly equal information
28/// content. This is the simplest of the information-driven bar types; the
29/// [`VolumeBars`](crate::VolumeBars) and [`DollarBars`](crate::DollarBars) builders
30/// extend the idea to equal traded volume and equal traded value respectively.
31///
32/// The open is the first candle's open, the high and low are the extremes across the
33/// group, the close is the last candle's close, and the volume is the group sum.
34/// Exactly one bar completes every `ticks` candles, so [`BarBuilder::update`]
35/// returns either an empty vector or a single [`TickBar`].
36///
37/// # Example
38///
39/// ```
40/// use wickra_core::{BarBuilder, Candle, TickBars};
41///
42/// let c = |o, h, l, cl, v| Candle::new(o, h, l, cl, v, 0).unwrap();
43/// let mut bars = TickBars::new(3).unwrap();
44/// assert!(bars.update(c(10.0, 11.0, 9.0, 10.5, 100.0)).is_empty());
45/// assert!(bars.update(c(10.5, 12.0, 10.0, 11.0, 150.0)).is_empty());
46/// let out = bars.update(c(11.0, 11.5, 10.8, 11.2, 120.0));
47/// assert_eq!(out.len(), 1);
48/// assert_eq!(out[0].volume, 370.0);
49/// ```
50#[derive(Debug, Clone)]
51pub struct TickBars {
52    ticks: usize,
53    count: usize,
54    open: f64,
55    high: f64,
56    low: f64,
57    close: f64,
58    volume: f64,
59}
60
61impl TickBars {
62    /// Construct a tick-bar builder that groups `ticks` candles per bar.
63    ///
64    /// # Errors
65    ///
66    /// Returns [`Error::PeriodZero`] if `ticks == 0`.
67    pub fn new(ticks: usize) -> Result<Self> {
68        if ticks == 0 {
69            return Err(Error::PeriodZero);
70        }
71        Ok(Self {
72            ticks,
73            count: 0,
74            open: 0.0,
75            high: 0.0,
76            low: 0.0,
77            close: 0.0,
78            volume: 0.0,
79        })
80    }
81
82    /// Configured number of candles per bar.
83    pub const fn ticks(&self) -> usize {
84        self.ticks
85    }
86
87    /// Number of candles accumulated into the in-progress bar.
88    pub const fn count(&self) -> usize {
89        self.count
90    }
91}
92
93impl BarBuilder for TickBars {
94    type Bar = TickBar;
95
96    fn update(&mut self, candle: Candle) -> Vec<TickBar> {
97        if self.count == 0 {
98            self.open = candle.open;
99            self.high = candle.high;
100            self.low = candle.low;
101            self.volume = 0.0;
102        } else {
103            self.high = self.high.max(candle.high);
104            self.low = self.low.min(candle.low);
105        }
106        self.close = candle.close;
107        self.volume += candle.volume;
108        self.count += 1;
109        if self.count < self.ticks {
110            return Vec::new();
111        }
112        self.count = 0;
113        vec![TickBar {
114            open: self.open,
115            high: self.high,
116            low: self.low,
117            close: self.close,
118            volume: self.volume,
119        }]
120    }
121
122    fn reset(&mut self) {
123        self.count = 0;
124        self.volume = 0.0;
125    }
126
127    fn name(&self) -> &'static str {
128        "TickBars"
129    }
130}
131
132#[cfg(test)]
133mod tests {
134    use super::*;
135    use approx::assert_relative_eq;
136
137    fn candle(open: f64, high: f64, low: f64, close: f64, volume: f64) -> Candle {
138        Candle::new(open, high, low, close, volume, 0).unwrap()
139    }
140
141    #[test]
142    fn rejects_zero_ticks() {
143        assert!(matches!(TickBars::new(0), Err(Error::PeriodZero)));
144    }
145
146    #[test]
147    fn accessors_and_metadata() {
148        let bars = TickBars::new(5).unwrap();
149        assert_eq!(bars.ticks(), 5);
150        assert_eq!(bars.count(), 0);
151        assert_eq!(bars.name(), "TickBars");
152    }
153
154    #[test]
155    fn emits_every_n_candles() {
156        let mut bars = TickBars::new(2).unwrap();
157        assert!(bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0)).is_empty());
158        assert_eq!(bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0)).len(), 1);
159        assert!(bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0)).is_empty());
160        assert_eq!(bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0)).len(), 1);
161    }
162
163    #[test]
164    fn aggregates_ohlcv() {
165        let mut bars = TickBars::new(3).unwrap();
166        bars.update(candle(10.0, 11.0, 9.0, 10.5, 100.0));
167        bars.update(candle(10.5, 12.0, 10.0, 11.0, 150.0));
168        let out = bars.update(candle(11.0, 11.5, 10.8, 11.2, 120.0));
169        assert_eq!(out.len(), 1);
170        assert_relative_eq!(out[0].open, 10.0, epsilon = 1e-12);
171        assert_relative_eq!(out[0].high, 12.0, epsilon = 1e-12);
172        assert_relative_eq!(out[0].low, 9.0, epsilon = 1e-12);
173        assert_relative_eq!(out[0].close, 11.2, epsilon = 1e-12);
174        assert_relative_eq!(out[0].volume, 370.0, epsilon = 1e-12);
175    }
176
177    #[test]
178    fn partial_group_emits_nothing() {
179        let mut bars = TickBars::new(4).unwrap();
180        bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0));
181        bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0));
182        assert_eq!(bars.count(), 2);
183    }
184
185    #[test]
186    fn reset_clears_state() {
187        let mut bars = TickBars::new(3).unwrap();
188        bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0));
189        bars.update(candle(10.0, 10.0, 10.0, 10.0, 1.0));
190        bars.reset();
191        assert_eq!(bars.count(), 0);
192        // After reset the next candle starts a fresh group.
193        assert!(bars.update(candle(20.0, 20.0, 20.0, 20.0, 5.0)).is_empty());
194        assert_eq!(bars.count(), 1);
195    }
196
197    #[test]
198    fn batch_concatenates_completed_bars() {
199        let mut bars = TickBars::new(2).unwrap();
200        let candles = [
201            candle(10.0, 10.0, 10.0, 10.0, 1.0),
202            candle(10.0, 10.0, 10.0, 10.0, 1.0),
203            candle(10.0, 10.0, 10.0, 10.0, 1.0),
204            candle(10.0, 10.0, 10.0, 10.0, 1.0),
205        ];
206        let out = bars.batch(&candles);
207        assert_eq!(out.len(), 2);
208    }
209}
wickra_core/indicators/tick_bars.rs

wickra_core/indicators/
tick_bars.rs
