Skip to main content

ferrochart_core/transform/
range_bars.rs

1//! Range Bars (rules in `docs/book/src/series.md`).
2
3use crate::error::Result;
4use crate::frame::SeriesKind;
5use crate::plugin::{InputBar, SeriesTransform, TransformBar, TransformOutput};
6
7use super::{bar_kind, emit, fresh_volume, positive};
8
9/// Bars whose high and low are a fixed distance apart. The last bar is
10/// forming.
11///
12/// # Examples
13///
14/// ```
15/// use ferrochart_core::chart::SeriesOptions;
16/// use ferrochart_core::transform::RangeBars;
17/// use ferrochart_core::{Chart, ChartOptions};
18///
19/// let mut chart = Chart::new(ChartOptions::default());
20/// chart.add_transform_series(
21///     chart.main_pane(),
22///     Box::new(RangeBars::new(0.5)?),
23///     SeriesOptions::default(),
24/// )?;
25/// # Ok::<(), ferrochart_core::Error>(())
26/// ```
27#[derive(Clone, Debug)]
28pub struct RangeBars {
29    range: f64,
30    kind: SeriesKind,
31    /// The forming bar.
32    bar: Option<TransformBar>,
33}
34
35impl RangeBars {
36    /// Bars of `range` from high to low.
37    ///
38    /// # Errors
39    ///
40    /// [`crate::Error::InvalidArgument`] unless `range` is finite and positive.
41    pub fn new(range: f64) -> Result<Self> {
42        Ok(Self {
43            range: positive(range, "the range must be positive")?,
44            kind: SeriesKind::Candlestick,
45            bar: None,
46        })
47    }
48
49    /// Drawn as `kind` (`Candlestick`, the default, or `OhlcBar`).
50    ///
51    /// # Errors
52    ///
53    /// [`crate::Error::InvalidArgument`] for other kinds.
54    pub fn with_kind(mut self, kind: SeriesKind) -> Result<Self> {
55        self.kind = bar_kind(kind)?;
56        Ok(self)
57    }
58
59    /// Moves the forming bar `b` to price `p`; `false` if the output is full.
60    fn walk(
61        &self,
62        b: &mut Option<TransformBar>,
63        p: f64,
64        v: f64,
65        out: &mut TransformOutput,
66    ) -> bool {
67        let Some(cur) = b.as_mut() else {
68            *b = Some(TransformBar {
69                open: p,
70                high: p,
71                low: p,
72                close: p,
73                volume: fresh_volume(v),
74                flag: 0,
75            });
76            return true;
77        };
78        let r = self.range;
79        loop {
80            let q = if p > cur.low + r {
81                let q = cur.low + r;
82                cur.high = q;
83                q
84            } else if p < cur.high - r {
85                let q = cur.high - r;
86                cur.low = q;
87                q
88            } else {
89                break;
90            };
91            cur.close = q;
92            if !emit(out, *cur) {
93                return false;
94            }
95            *cur = TransformBar {
96                open: q,
97                high: q,
98                low: q,
99                close: q,
100                volume: fresh_volume(v),
101                flag: 0,
102            };
103        }
104        cur.high = cur.high.max(p);
105        cur.low = cur.low.min(p);
106        cur.close = p;
107        true
108    }
109
110    fn step(&self, b: &mut Option<TransformBar>, bar: InputBar, out: &mut TransformOutput) {
111        let path = if bar.close >= bar.open {
112            [bar.open, bar.low, bar.high, bar.close]
113        } else {
114            [bar.open, bar.high, bar.low, bar.close]
115        };
116        for p in path {
117            if !self.walk(b, p, bar.volume, out) {
118                return;
119            }
120        }
121        if let Some(cur) = b.as_mut() {
122            cur.volume += bar.volume;
123        }
124    }
125}
126
127impl SeriesTransform for RangeBars {
128    fn name(&self) -> &'static str {
129        "range_bars"
130    }
131
132    fn output_kind(&self) -> SeriesKind {
133        self.kind
134    }
135
136    fn push(&mut self, bar: InputBar, out: &mut TransformOutput) {
137        let mut b = self.bar;
138        self.step(&mut b, bar, out);
139        self.bar = b;
140    }
141
142    fn peek(&self, bar: InputBar, out: &mut TransformOutput) {
143        let mut b = self.bar;
144        self.step(&mut b, bar, out);
145        if let Some(cur) = b {
146            emit(out, cur);
147        }
148    }
149
150    fn reset(&mut self) {
151        self.bar = None;
152    }
153}
154
155#[cfg(test)]
156#[allow(clippy::float_cmp)]
157mod tests {
158    use super::*;
159    use crate::transform::tests::{run, tick};
160
161    fn ohlc(b: &TransformBar) -> [f64; 4] {
162        [b.open, b.high, b.low, b.close]
163    }
164
165    #[test]
166    fn bars_close_at_the_range() {
167        let mut r = RangeBars::new(1.0).unwrap();
168        let bars = [tick(0, 10.0), tick(1, 10.6), tick(2, 12.3), tick(3, 11.8)];
169        let out = run(&mut r, &bars);
170        let got: Vec<_> = out.iter().map(ohlc).collect();
171        assert_eq!(
172            got,
173            [
174                [10.0, 11.0, 10.0, 11.0],
175                [11.0, 12.0, 11.0, 12.0],
176                // Forming: opened at 12, up to 12.3, back to 11.8.
177                [12.0, 12.3, 11.8, 11.8],
178            ]
179        );
180        assert_eq!(out[2].volume, 2.0);
181    }
182
183    #[test]
184    fn bars_follow_the_intrabar_path() {
185        let mut r = RangeBars::new(1.0).unwrap();
186        // Up bar: open 10, low 9.5, high 11, close 10.8.
187        let bar = InputBar {
188            time: 0,
189            open: 10.0,
190            high: 11.0,
191            low: 9.5,
192            close: 10.8,
193            volume: 4.0,
194        };
195        let out = run(&mut r, &[bar]);
196        let got: Vec<_> = out.iter().map(ohlc).collect();
197        assert_eq!(got, [[10.0, 10.5, 9.5, 10.5], [10.5, 11.0, 10.5, 10.8]]);
198        assert_eq!(out[0].volume, 0.0);
199        assert_eq!(out[1].volume, 4.0);
200    }
201}