Skip to main content

ferrochart_core/transform/
point_figure.rs

1//! Point & Figure (rules in `docs/book/src/series.md`).
2
3use crate::error::{Error, Result};
4use crate::frame::SeriesKind;
5use crate::plugin::{InputBar, SeriesTransform, TransformBar, TransformOutput};
6
7use super::{emit, fresh_volume, positive};
8
9/// A column of boxes `lo..=hi`.
10#[derive(Clone, Copy, Debug, PartialEq)]
11struct Column {
12    lo: i64,
13    hi: i64,
14    x: bool,
15    volume: f64,
16}
17
18#[derive(Clone, Copy, Debug, PartialEq)]
19struct State {
20    /// The box of the first close.
21    k0: Option<i64>,
22    column: Option<Column>,
23    /// Volume before the first column.
24    volume: f64,
25}
26
27const START: State = State {
28    k0: None,
29    column: None,
30    volume: 0.0,
31};
32
33/// Point & Figure columns of X (rising) and O (falling) boxes. The last
34/// column is forming.
35///
36/// # Examples
37///
38/// ```
39/// use ferrochart_core::chart::SeriesOptions;
40/// use ferrochart_core::transform::PointFigure;
41/// use ferrochart_core::{Chart, ChartOptions};
42///
43/// let mut chart = Chart::new(ChartOptions::default());
44/// chart.add_transform_series(
45///     chart.main_pane(),
46///     Box::new(PointFigure::new(1.0, 3)?),
47///     SeriesOptions::default(),
48/// )?;
49/// # Ok::<(), ferrochart_core::Error>(())
50/// ```
51#[derive(Clone, Debug)]
52pub struct PointFigure {
53    size: f64,
54    reversal: i64,
55    state: State,
56}
57
58impl PointFigure {
59    /// Boxes of `size`; a new column needs `reversal` boxes.
60    ///
61    /// # Errors
62    ///
63    /// [`Error::InvalidArgument`] unless `size` is finite and positive and
64    /// `reversal` at least 1.
65    pub fn new(size: f64, reversal: u32) -> Result<Self> {
66        if reversal == 0 {
67            return Err(Error::InvalidArgument(
68                "the reversal must be at least 1 box",
69            ));
70        }
71        Ok(Self {
72            size: positive(size, "the box size must be positive")?,
73            reversal: i64::from(reversal),
74            state: START,
75        })
76    }
77
78    /// Highest box reached going up (its top at or below `c`).
79    fn up(&self, c: f64) -> i64 {
80        (c / self.size).floor() as i64 - 1
81    }
82
83    /// Lowest box reached going down (its bottom at or above `c`).
84    fn down(&self, c: f64) -> i64 {
85        (c / self.size).ceil() as i64
86    }
87
88    fn element(&self, col: &Column) -> TransformBar {
89        let (low, high) = (col.lo as f64 * self.size, (col.hi + 1) as f64 * self.size);
90        let (open, close) = if col.x { (low, high) } else { (high, low) };
91        TransformBar {
92            open,
93            high,
94            low,
95            close,
96            volume: col.volume,
97            flag: u8::from(col.x),
98        }
99    }
100
101    fn step(&self, s: &mut State, bar: InputBar, out: &mut TransformOutput) {
102        let c = bar.close;
103        let v = bar.volume;
104        let Some(k0) = s.k0 else {
105            s.k0 = Some((c / self.size).floor() as i64);
106            s.volume += v;
107            return;
108        };
109        let (up, down) = (self.up(c), self.down(c));
110        let Some(col) = s.column.as_mut() else {
111            s.volume += v;
112            let first = if up >= k0 {
113                Some((k0, up, true))
114            } else if down <= k0 {
115                Some((down, k0, false))
116            } else {
117                None
118            };
119            if let Some((lo, hi, x)) = first {
120                s.column = Some(Column {
121                    lo,
122                    hi,
123                    x,
124                    volume: s.volume,
125                });
126            }
127            return;
128        };
129        let next = if col.x {
130            if up > col.hi {
131                col.hi = up;
132                None
133            } else if col.hi - down >= self.reversal {
134                Some((down, col.hi - 1, false))
135            } else {
136                None
137            }
138        } else if down < col.lo {
139            col.lo = down;
140            None
141        } else if up - col.lo >= self.reversal {
142            Some((col.lo + 1, up, true))
143        } else {
144            None
145        };
146        if let Some((lo, hi, x)) = next {
147            if !emit(out, self.element(col)) {
148                return;
149            }
150            *col = Column {
151                lo,
152                hi,
153                x,
154                volume: fresh_volume(v),
155            };
156        }
157        col.volume += v;
158    }
159}
160
161impl SeriesTransform for PointFigure {
162    fn name(&self) -> &'static str {
163        "point_figure"
164    }
165
166    fn output_kind(&self) -> SeriesKind {
167        SeriesKind::PointFigure
168    }
169
170    fn push(&mut self, bar: InputBar, out: &mut TransformOutput) {
171        let mut s = self.state;
172        self.step(&mut s, bar, out);
173        self.state = s;
174    }
175
176    fn peek(&self, bar: InputBar, out: &mut TransformOutput) {
177        let mut s = self.state;
178        self.step(&mut s, bar, out);
179        if out.check().is_ok()
180            && let Some(col) = s.column
181        {
182            emit(out, self.element(&col));
183        }
184    }
185
186    fn reset(&mut self) {
187        self.state = START;
188    }
189
190    fn box_size(&self) -> Option<f64> {
191        Some(self.size)
192    }
193}
194
195#[cfg(test)]
196#[allow(clippy::float_cmp)]
197mod tests {
198    use super::*;
199    use crate::transform::tests::{run, tick};
200
201    /// `(low, high, x)` of each column.
202    fn cols(bars: &[TransformBar]) -> Vec<(f64, f64, bool)> {
203        bars.iter().map(|b| (b.low, b.high, b.flag == 1)).collect()
204    }
205
206    #[test]
207    fn columns_reverse_after_three_boxes() {
208        let mut p = PointFigure::new(1.0, 3).unwrap();
209        // Start in box 10. 12.2 reaches box 11 (top 12): X 10..=11.
210        // 14.5: X up to box 13. 12.0: 13 - 12 = 1 < 3. 10.9: 13 - 11 = 2.
211        // 10.0: 13 - 10 = 3: O boxes 10..=12.
212        let prices = [10.5, 12.2, 14.5, 12.0, 10.9, 10.0];
213        let bars: Vec<_> = prices
214            .iter()
215            .enumerate()
216            .map(|(i, &x)| tick(i as i64, x))
217            .collect();
218        let out = run(&mut p, &bars);
219        assert_eq!(cols(&out), [(10.0, 14.0, true), (10.0, 13.0, false)]);
220        assert_eq!((out[0].open, out[0].close), (10.0, 14.0));
221        assert_eq!((out[1].open, out[1].close), (13.0, 10.0));
222        assert_eq!(p.box_size(), Some(1.0));
223    }
224
225    #[test]
226    fn first_column_can_fall() {
227        let mut p = PointFigure::new(2.0, 2).unwrap();
228        // Box 5 (10..12); 9.5 is below its bottom: O column of box 5.
229        let out = run(&mut p, &[tick(0, 11.0), tick(1, 9.5)]);
230        assert_eq!(cols(&out), [(10.0, 12.0, false)]);
231        // Back up: X needs up(c) - 5 >= 2, i.e. box 7 (top 16).
232        let out = run(&mut p, &[tick(0, 11.0), tick(1, 9.5), tick(2, 15.9)]);
233        assert_eq!(out.len(), 1);
234        let out = run(&mut p, &[tick(0, 11.0), tick(1, 9.5), tick(2, 16.0)]);
235        assert_eq!(cols(&out), [(10.0, 12.0, false), (12.0, 16.0, true)]);
236    }
237}