quantwave_core/indicators/
system_evaluator.rs

1use crate::indicators::metadata::IndicatorMetadata;
2use crate::traits::Next;
3
4/// System Evaluation Metrics
5///
6/// Based on John Ehlers and Ric Way's "Evaluating Trading Systems".
7/// Provides a robust set of statistical performance descriptors for a trading system.
8#[derive(Debug, Clone, Default)]
9pub struct SystemEvaluator {
10    gross_winnings: f64,
11    gross_losses: f64,
12    num_wins: usize,
13    num_losses: usize,
14    count: usize,
15}
16
17#[derive(Debug, Clone, Copy, Default)]
18pub struct SystemEvaluationResults {
19    pub average_win_loss_ratio: f64,
20    pub average_trade: f64,
21    pub profit_factor: f64,
22    pub percent_winners: f64,
23    pub breakeven_profit_factor: f64,
24    pub weighted_average_trade: f64,
25    pub theoretical_consecutive_losers: f64,
26}
27
28impl SystemEvaluator {
29    pub fn new() -> Self {
30        Self::default()
31    }
32}
33
34impl Next<f64> for SystemEvaluator {
35    type Output = SystemEvaluationResults;
36
37    fn next(&mut self, trade_profit: f64) -> Self::Output {
38        self.count += 1;
39        if trade_profit > 0.0 {
40            self.gross_winnings += trade_profit;
41            self.num_wins += 1;
42        } else if trade_profit < 0.0 {
43            self.gross_losses += trade_profit.abs();
44            self.num_losses += 1;
45        }
46
47        let total_trades = (self.num_wins + self.num_losses) as f64;
48        if total_trades == 0.0 {
49            return SystemEvaluationResults::default();
50        }
51
52        let win_ratio = self.num_wins as f64 / total_trades;
53        let loss_ratio = 1.0 - win_ratio;
54        let pf = if self.gross_losses > 0.0 {
55            self.gross_winnings / self.gross_losses
56        } else if self.gross_winnings > 0.0 {
57            100.0 // Cap at 100 for no losses
58        } else {
59            0.0
60        };
61
62        let ave_win = if self.num_wins > 0 { self.gross_winnings / self.num_wins as f64 } else { 0.0 };
63        let ave_loss = if self.num_losses > 0 { self.gross_losses / self.num_losses as f64 } else { 0.0 };
64        
65        let ave_win_loss_ratio = if ave_loss > 0.0 { ave_win / ave_loss } else { 0.0 };
66        let average_trade = (self.gross_winnings - self.gross_losses) / total_trades;
67        
68        let breakeven_pf = if win_ratio > 0.0 { loss_ratio / win_ratio } else { 100.0 };
69        
70        // Weighted Average Trade = AverageTrade * (AveWin / AveLoss)
71        // Note: The paper derives it as T * (AveWin / AveLoss)
72        let weighted_average_trade = average_trade * ave_win_loss_ratio;
73        
74        // N = Log(0.0027) / Log(1 - %)
75        // Where % is the probability of a win.
76        let theoretical_consecutive_losers = if win_ratio < 1.0 {
77            (0.0027f64.ln()) / (1.0 - win_ratio).ln()
78        } else {
79            0.0
80        };
81
82        SystemEvaluationResults {
83            average_win_loss_ratio: ave_win_loss_ratio,
84            average_trade,
85            profit_factor: pf,
86            percent_winners: win_ratio,
87            breakeven_profit_factor: breakeven_pf,
88            weighted_average_trade,
89            theoretical_consecutive_losers,
90        }
91    }
92}
93
94pub const SYSTEM_EVALUATOR_METADATA: IndicatorMetadata = IndicatorMetadata {
95    name: "System Evaluator",
96    description: "Calculates robust statistical performance metrics for a trading system based on a stream of trade profits.",
97    usage: "Use to assess the performance quality of a trading system output using signal processing metrics. Helps distinguish systems with genuine edge from those that merely overfit.",
98    keywords: &["system", "performance", "ehlers", "statistics"],
99    ehlers_summary: "Ehlers applies signal processing metrics to evaluate trading system quality in Cybernetic Analysis. Metrics such as the Signal-to-Noise Ratio of the equity curve quantify whether a system is generating genuine signal above the noise floor of random entry and exit.",
100    params: &[],
101    formula_source: "https://github.com/lavs9/quantwave/blob/main/references/Ehlers%20Papers/SystemEvaluation.pdf",
102    formula_latex: r#"
103\[
104AveTrade = \% \cdot (PF + 1) - 1
105\]
106\[
107PF_{breakeven} = \frac{1 - \%}{\%}
108\]
109\[
110N_{losers} = \frac{\ln(0.0027)}{\ln(1 - \%)}
111\]
112"#,
113    gold_standard_file: "system_evaluation.json",
114    category: "Statistics",
115};
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120    use crate::traits::Next;
121    use proptest::prelude::*;
122
123    #[test]
124    fn test_system_evaluator() {
125        let mut evaluator = SystemEvaluator::new();
126        // A simple system: 2 wins of 200, 1 loss of 100
127        // PF = 400 / 100 = 4.0
128        // % Win = 2 / 3 = 0.666
129        // AveTrade = (400 - 100) / 3 = 100.0
130        evaluator.next(200.0);
131        evaluator.next(-100.0);
132        let res = evaluator.next(200.0);
133
134        approx::assert_relative_eq!(res.profit_factor, 4.0);
135        approx::assert_relative_eq!(res.percent_winners, 0.6666666666666666);
136        approx::assert_relative_eq!(res.average_trade, 100.0);
137        assert!(res.weighted_average_trade > 0.0);
138    }
139
140    proptest! {
141        #[test]
142        fn test_system_evaluator_parity(
143            inputs in prop::collection::vec(-100.0..100.0, 10..100),
144        ) {
145            let mut evaluator = SystemEvaluator::new();
146            let streaming_results: Vec<SystemEvaluationResults> = inputs.iter().map(|&x| evaluator.next(x)).collect();
147
148            let mut evaluator_batch = SystemEvaluator::new();
149            let batch_results: Vec<SystemEvaluationResults> = inputs.iter().map(|&x| evaluator_batch.next(x)).collect();
150
151            for (s, b) in streaming_results.iter().zip(batch_results.iter()) {
152                approx::assert_relative_eq!(s.profit_factor, b.profit_factor, epsilon = 1e-10);
153                approx::assert_relative_eq!(s.average_trade, b.average_trade, epsilon = 1e-10);
154                approx::assert_relative_eq!(s.percent_winners, b.percent_winners, epsilon = 1e-10);
155            }
156        }
157    }
158}
quantwave_core/indicators/system_evaluator.rs

quantwave_core/indicators/
system_evaluator.rs
