Skip to main content

ferrochart_core/transform/
kagi.rs

1//! Kagi (rules in `docs/book/src/series.md`).
2
3use crate::error::Result;
4use crate::frame::SeriesKind;
5use crate::plugin::{InputBar, SeriesTransform, TransformOutput};
6
7use super::{element, emit, fresh_volume, positive};
8
9/// The move that starts a new Kagi line.
10#[derive(Clone, Copy, Debug, PartialEq)]
11pub enum Reversal {
12    /// A price distance.
13    Fixed(f64),
14    /// A percentage of the current line's end price.
15    Percent(f64),
16}
17
18/// A Kagi line.
19#[derive(Clone, Copy, Debug, PartialEq)]
20struct Line {
21    open: f64,
22    end: f64,
23    up: bool,
24    /// Thickness at its start (1 thick, 0 thin).
25    start_flag: u8,
26    volume: f64,
27}
28
29#[derive(Clone, Copy, Debug, PartialEq)]
30struct State {
31    /// The first close.
32    start: Option<f64>,
33    line: Option<Line>,
34    /// Start of the previous line (the last shoulder or waist).
35    prev_open: Option<f64>,
36    /// Volume before the first line.
37    volume: f64,
38}
39
40const START: State = State {
41    start: None,
42    line: None,
43    prev_open: None,
44    volume: 0.0,
45};
46
47/// Kagi lines: a new line starts when the price reverses by the reversal
48/// amount; lines are thick (yang) after rising above the previous shoulder
49/// and thin (yin) after falling below the previous waist. The last line is
50/// forming.
51///
52/// # Examples
53///
54/// ```
55/// use ferrochart_core::chart::SeriesOptions;
56/// use ferrochart_core::transform::{Kagi, Reversal};
57/// use ferrochart_core::{Chart, ChartOptions};
58///
59/// let mut chart = Chart::new(ChartOptions::default());
60/// chart.add_transform_series(
61///     chart.main_pane(),
62///     Box::new(Kagi::new(Reversal::Percent(1.0))?),
63///     SeriesOptions::default(),
64/// )?;
65/// # Ok::<(), ferrochart_core::Error>(())
66/// ```
67#[derive(Clone, Debug)]
68pub struct Kagi {
69    reversal: Reversal,
70    state: State,
71}
72
73impl Kagi {
74    /// Kagi lines with `reversal`.
75    ///
76    /// # Errors
77    ///
78    /// [`crate::Error::InvalidArgument`] unless the amount is finite and
79    /// positive.
80    pub fn new(reversal: Reversal) -> Result<Self> {
81        let msg = "the reversal amount must be positive";
82        let reversal = match reversal {
83            Reversal::Fixed(x) => Reversal::Fixed(positive(x, msg)?),
84            Reversal::Percent(p) => Reversal::Percent(positive(p, msg)?),
85        };
86        Ok(Self {
87            reversal,
88            state: START,
89        })
90    }
91
92    fn rev(&self, at: f64) -> f64 {
93        match self.reversal {
94            Reversal::Fixed(x) => x,
95            Reversal::Percent(p) => at.abs() * p / 100.0,
96        }
97    }
98
99    /// Thickness at the end of `line`.
100    fn flag(line: &Line, prev_open: Option<f64>) -> u8 {
101        match prev_open {
102            Some(s) if line.up && line.end > s => 1,
103            Some(s) if !line.up && line.end < s => 0,
104            _ => line.start_flag,
105        }
106    }
107
108    fn element(line: &Line, prev_open: Option<f64>) -> crate::plugin::TransformBar {
109        element(
110            line.open,
111            line.end,
112            line.volume,
113            Self::flag(line, prev_open),
114        )
115    }
116
117    fn step(&self, s: &mut State, bar: InputBar, out: &mut TransformOutput) {
118        let c = bar.close;
119        let v = bar.volume;
120        let Some(start) = s.start else {
121            s.start = Some(c);
122            s.volume += v;
123            return;
124        };
125        let Some(line) = s.line.as_mut() else {
126            s.volume += v;
127            if (c - start).abs() >= self.rev(start) && (c - start).abs() > 0.0 {
128                let up = c > start;
129                s.line = Some(Line {
130                    open: start,
131                    end: c,
132                    up,
133                    start_flag: u8::from(up),
134                    volume: s.volume,
135                });
136            }
137            return;
138        };
139        let extends = if line.up { c > line.end } else { c < line.end };
140        let reverses = if line.up { c < line.end } else { c > line.end };
141        if extends {
142            line.end = c;
143        } else if reverses && (c - line.end).abs() >= self.rev(line.end) {
144            let done = *line;
145            let flag = Self::flag(&done, s.prev_open);
146            if !emit(out, Self::element(&done, s.prev_open)) {
147                return;
148            }
149            s.prev_open = Some(done.open);
150            *line = Line {
151                open: done.end,
152                end: c,
153                up: !done.up,
154                start_flag: flag,
155                volume: fresh_volume(v),
156            };
157        }
158        line.volume += v;
159    }
160}
161
162impl SeriesTransform for Kagi {
163    fn name(&self) -> &'static str {
164        "kagi"
165    }
166
167    fn output_kind(&self) -> SeriesKind {
168        SeriesKind::Kagi
169    }
170
171    fn push(&mut self, bar: InputBar, out: &mut TransformOutput) {
172        let mut s = self.state;
173        self.step(&mut s, bar, out);
174        self.state = s;
175    }
176
177    fn peek(&self, bar: InputBar, out: &mut TransformOutput) {
178        let mut s = self.state;
179        self.step(&mut s, bar, out);
180        if out.check().is_ok()
181            && let Some(line) = s.line
182        {
183            emit(out, Self::element(&line, s.prev_open));
184        }
185    }
186
187    fn reset(&mut self) {
188        self.state = START;
189    }
190}
191
192#[cfg(test)]
193#[allow(clippy::float_cmp)]
194mod tests {
195    use super::*;
196    use crate::transform::tests::{oc, run, tick};
197
198    #[test]
199    fn lines_reverse_and_change_thickness() {
200        let mut k = Kagi::new(Reversal::Fixed(2.0)).unwrap();
201        let prices = [10.0, 11.0, 13.0, 12.0, 10.5, 12.0, 14.0, 9.0];
202        let bars: Vec<_> = prices
203            .iter()
204            .enumerate()
205            .map(|(i, &p)| tick(i as i64, p))
206            .collect();
207        let out = run(&mut k, &bars);
208        assert_eq!(
209            oc(&out),
210            [(10.0, 13.0), (13.0, 10.5), (10.5, 14.0), (14.0, 9.0)]
211        );
212        let flags: Vec<u8> = out.iter().map(|b| b.flag).collect();
213        // Up from 10: thick. Down to 10.5 stays above the start 10: thick.
214        // Up to 14 above the shoulder 13: thick. Down to 9 below the waist
215        // 10.5: thin.
216        assert_eq!(flags, [1, 1, 1, 0]);
217        // Each input's volume goes to the line forming after it: 10, 11,
218        // 13, 12 | 10.5, 12 | 14 | 9.
219        let v: Vec<f64> = out.iter().map(|b| b.volume).collect();
220        assert_eq!(v, [4.0, 2.0, 1.0, 1.0]);
221    }
222
223    #[test]
224    fn percent_reversal_uses_the_end_price() {
225        let mut k = Kagi::new(Reversal::Percent(10.0)).unwrap();
226        let bars = [
227            tick(0, 100.0),
228            tick(1, 111.0),
229            tick(2, 100.5),
230            tick(3, 99.0),
231        ];
232        // 10% of 111 is 11.1: 100.5 does not reverse, 99 does.
233        assert_eq!(oc(&run(&mut k, &bars[..3])), [(100.0, 111.0)]);
234        assert_eq!(oc(&run(&mut k, &bars)), [(100.0, 111.0), (111.0, 99.0)]);
235    }
236}