quantwave_core/indicators/
conventions.rs

1//! Machine-readable convention notes for indicators whose name does not fully
2//! determine their formula (quantwave-xnaf / quantwave-l2n4).
3//!
4//! Some indicator slugs are ambiguous in the wild: "ATR" can mean Wilder's RMA
5//! (TA-Lib, TradingView, Wilder 1978) or a plain EMA of true range; "stddev" can
6//! be population (`ddof=0`) or sample (`ddof=1`); "roc" can be a percentage or a
7//! plain ratio. Prose in a docs page is easy to miss, so the convention actually
8//! implemented is recorded here as data and surfaced through the Python
9//! `metadata()` / `boundary_info()` discovery API.
10//!
11//! PROCESS RULE (AGENTS.md): the *source* of every calculation must be recorded
12//! and never assumed. `source` below is the recorded provenance for the
13//! convention that is actually implemented. Where no authoritative source has
14//! been found for the implemented variant, `source` says so explicitly rather
15//! than naming a plausible-looking one.
16
17/// One convention that a caller could plausibly get wrong.
18#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
19pub struct ConventionNote {
20    /// Indicator slug this note applies to (matches `metadata_registry`).
21    pub slug: &'static str,
22    /// What aspect of the calculation is ambiguous, e.g. "smoothing", "scaling".
23    pub aspect: &'static str,
24    /// The convention this implementation actually follows.
25    pub convention: &'static str,
26    /// Widely used conventions this implementation does *not* follow.
27    pub differs_from: &'static str,
28    /// Recorded provenance for the implemented convention, or an explicit
29    /// statement that no source has been established.
30    pub source: &'static str,
31    /// What a caller should do about it.
32    pub guidance: &'static str,
33}
34
35/// Slugs whose implemented convention differs from what the bare name implies.
36///
37/// Keep this sorted by slug. Mirrored on the Python side in
38/// `quantwave/_metadata.py::_CONVENTION_NOTES`.
39pub const CONVENTION_NOTES: &[ConventionNote] = &[
40    ConventionNote {
41        slug: "alma",
42        aspect: "warmup",
43        convention: "During the initial warmup window (< period bars), ALMA normalizes a partial slice of Gaussian weights over available bars, returning finite values immediately from bar 0.",
44        differs_from: "Implementations that emit NaN until the full period of bars has accumulated.",
45        source: "ProRealTime Arnaud Legoux Moving Average specification.",
46        guidance: "To match NaN-warmup implementations, use WarmupPolicy::Nan or mask the first period-1 bars.",
47    },
48    ConventionNote {
49        slug: "atr",
50        aspect: "smoothing",
51        convention: "Exponential moving average of true range, alpha = 2/(period+1), \
52                     seeded from the first bar's true range (high - low, no prior close) \
53                     with no NaN warmup. Applies to the `Atr` streaming class and the \
54                     `atr(period, high, low, close)` native batch function.",
55        differs_from: "Wilder's RMA (alpha = 1/period, SMA-seeded over the first `period` \
56                       true ranges, NaN during warmup) as used by TA-Lib, TradingView's \
57                       Pine `ta.atr`, and pandas `ewm(alpha=1/period, adjust=False)`. \
58                       Also differs from a simple rolling mean of true range. At period=14 \
59                       the EMA variant typically runs a few tenths of a percent to several \
60                       percent away from Wilder on the same input.",
61        source: "NONE RECORDED for the EMA-smoothed variant. The metadata `formula_source` \
62                 for this indicator (Investopedia ATR) and its LaTeX formula both describe \
63                 Wilder's RMA, which is what `ta_atr` implements — not this one. Treated as \
64                 an undocumented divergence pending review (quantwave-xnaf).",
65        guidance: "For TA-Lib/TradingView-identical ATR use `ta_atr` (Rust `TaATR`, Polars \
66                   `.ta.ta_atr()` / `lf.ta().ta_atr()`). Note that the Polars plugin \
67                   `pl.col(close).ta.atr(high, low)` and `quantwave.talib.ATR` are ALREADY \
68                   Wilder — only the streaming class and native batch function are not.",
69    },
70    ConventionNote {
71        slug: "atr_ts",
72        aspect: "smoothing",
73        convention: "ATR trailing stop built on the EMA-smoothed `Atr` (alpha = 2/(period+1)).",
74        differs_from: "TradingView ATR trailing stops, which use Wilder's RMA.",
75        source: "NONE RECORDED for the EMA smoothing. Metadata `formula_source` points at \
76                 TradingView's ATR page, which specifies Wilder. Inherited from `atr`.",
77        guidance: "Stop distances differ from a TradingView-equivalent ATR trailing stop. \
78                   See quantwave-xnaf before using for live risk sizing.",
79    },
80    ConventionNote {
81        slug: "keltner",
82        aspect: "smoothing",
83        convention: "Channel width uses the EMA-smoothed `Atr` (alpha = 2/(period+1)); \
84                     the basis is a plain EMA of close.",
85        differs_from: "The Investopedia / Chester Keltner formulation and most charting \
86                       platforms, which use Wilder-smoothed ATR for the band width.",
87        source: "NONE RECORDED for the EMA smoothing. Inherited from `atr`.",
88        guidance: "Band widths differ from a Wilder-ATR Keltner channel.",
89    },
90    ConventionNote {
91        slug: "roc",
92        aspect: "scaling",
93        convention: "Percentage: (price / price[-period] - 1) * 100, matching TA-Lib `ROC`.",
94        differs_from: "pandas `pct_change(period)` and TA-Lib `ROCP`, which return the \
95                       plain ratio (no x100).",
96        source: "TA-Lib ROC/ROCP definitions.",
97        guidance: "Use `rocp` for the unscaled ratio. Mixing the two is a silent 100x error.",
98    },
99    ConventionNote {
100        slug: "stddev",
101        aspect: "degrees of freedom",
102        convention: "Population standard deviation, ddof = 0, matching TA-Lib `STDDEV`.",
103        differs_from: "pandas `Series.std()` and numpy `ndarray.std(ddof=1)` defaults, \
104                       which use the sample estimator ddof = 1.",
105        source: "TA-Lib STDDEV definition.",
106        guidance: "Values differ by a factor of sqrt(N / (N - 1)); rescale if you are \
107                   reconciling against pandas.",
108    },
109    ConventionNote {
110        slug: "supertrend",
111        aspect: "smoothing",
112        convention: "Bands are built on the EMA-smoothed `Atr` (alpha = 2/(period+1)).",
113        differs_from: "TradingView's SuperTrend, which uses Pine `ta.atr` — Wilder's RMA.",
114        source: "NONE RECORDED for the EMA smoothing. Metadata `formula_source` points at \
115                 a TradingView SuperTrend script, which uses Wilder. Inherited from `atr`.",
116        guidance: "Flip points can differ from a TradingView SuperTrend on the same inputs.",
117    },
118    ConventionNote {
119        slug: "ttm_squeeze",
120        aspect: "smoothing",
121        convention: "The Keltner leg of the squeeze test uses the EMA-smoothed `Atr`.",
122        differs_from: "Implementations that use Wilder-smoothed ATR for the Keltner leg.",
123        source: "NONE RECORDED for the EMA smoothing. Inherited from `atr`.",
124        guidance: "Squeeze on/off transitions can differ near the threshold.",
125    },
126    ConventionNote {
127        slug: "vpn",
128        aspect: "smoothing",
129        convention: "The volume-positive-negative threshold uses the EMA-smoothed `Atr`.",
130        differs_from: "Implementations that use Wilder-smoothed ATR for the threshold.",
131        source: "NONE RECORDED for the EMA smoothing. Inherited from `atr`.",
132        guidance: "Threshold crossings can differ from a Wilder-ATR VPN.",
133    },
134];
135
136/// Convention notes recorded for `slug`, if any.
137///
138/// ```
139/// use quantwave_core::indicators::conventions::convention_notes;
140/// let notes = convention_notes("atr");
141/// assert_eq!(notes.len(), 1);
142/// assert_eq!(notes[0].aspect, "smoothing");
143/// ```
144pub fn convention_notes(slug: &str) -> Vec<&'static ConventionNote> {
145    CONVENTION_NOTES.iter().filter(|n| n.slug == slug).collect()
146}
147
148/// Every slug that carries at least one convention note, sorted and deduplicated.
149pub fn slugs_with_conventions() -> Vec<&'static str> {
150    let mut slugs: Vec<&'static str> = CONVENTION_NOTES.iter().map(|n| n.slug).collect();
151    slugs.sort_unstable();
152    slugs.dedup();
153    slugs
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159    use crate::indicators::metadata_registry::ALL_REGISTERED;
160
161    #[test]
162    fn notes_are_sorted_by_slug() {
163        let slugs: Vec<&str> = CONVENTION_NOTES.iter().map(|n| n.slug).collect();
164        let mut sorted = slugs.clone();
165        sorted.sort_unstable();
166        assert_eq!(slugs, sorted, "CONVENTION_NOTES must be sorted by slug");
167    }
168
169    #[test]
170    fn every_note_targets_a_registered_slug() {
171        for note in CONVENTION_NOTES {
172            assert!(
173                ALL_REGISTERED.iter().any(|r| r.slug == note.slug),
174                "convention note for unregistered slug {:?}",
175                note.slug
176            );
177        }
178    }
179
180    #[test]
181    fn every_note_is_fully_populated() {
182        for note in CONVENTION_NOTES {
183            for (field, value) in [
184                ("aspect", note.aspect),
185                ("convention", note.convention),
186                ("differs_from", note.differs_from),
187                ("source", note.source),
188                ("guidance", note.guidance),
189            ] {
190                assert!(
191                    !value.trim().is_empty(),
192                    "convention note {:?} has empty {field}",
193                    note.slug
194                );
195            }
196        }
197    }
198
199    #[test]
200    fn atr_family_divergence_is_recorded() {
201        // The ATR-composed indicators all inherit the EMA smoothing; if one of
202        // them is ever switched to Wilder, this test forces the note to be updated.
203        for slug in [
204            "atr",
205            "atr_ts",
206            "keltner",
207            "supertrend",
208            "ttm_squeeze",
209            "vpn",
210        ] {
211            let notes = convention_notes(slug);
212            assert_eq!(notes.len(), 1, "expected exactly one note for {slug}");
213            assert_eq!(notes[0].aspect, "smoothing");
214        }
215    }
216
217    #[test]
218    fn lookup_of_unknown_slug_is_empty() {
219        assert!(convention_notes("rsi").is_empty());
220        assert!(convention_notes("not_a_real_slug").is_empty());
221    }
222}
quantwave_core/indicators/conventions.rs

quantwave_core/indicators/
conventions.rs
