1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
//! Coefficient of determination R² for the rolling OLS fit.
use std::collections::VecDeque;
use crate::error::{Error, Result};
use crate::traits::Indicator;
/// R² (coefficient of determination) of the rolling least-squares fit.
///
/// Over the trailing window indexed `x = 0, 1, …, period − 1` the OLS line
/// `y = a + b·x` is fitted and the ratio of variance explained by the line
/// to total variance is reported:
///
/// ```text
/// slope = (n·Σxy − Σx·Σy) / (n·Σxx − (Σx)²)
/// SS_total = Σy² − n·ȳ²
/// SS_explained = slope² · ( denom / n )
/// R² = SS_explained / SS_total if SS_total > 0
/// = 1 otherwise (flat window)
/// ```
///
/// A reading of `1.0` means the window lies on a straight line — perfect
/// linear fit. `0.0` means the slope is irrelevant; the trend explains none
/// of the variance. Mid-range values quantify how trending the recent price
/// action is, independent of the slope's sign or magnitude. Use it as a
/// trend-quality filter: a strategy that needs a clear trend can require
/// `R² > 0.7`, while a mean-reversion strategy can prefer `R² < 0.3`.
///
/// A flat window has `SS_total = 0`; the line is also flat and the fit is
/// trivially perfect, so the indicator returns `1.0` rather than dividing
/// by zero.
///
/// Each `update` is O(1) via the same rolling sums as
/// [`crate::LinearRegression`], plus a running `Σy²`. The output is
/// clamped to `[0, 1]` to absorb tiny floating-point cancellation.
///
/// # Example
///
/// ```
/// use wickra_core::{Indicator, RSquared};
///
/// let mut indicator = RSquared::new(14).unwrap();
/// let mut last = None;
/// for i in 0..40 {
/// last = indicator.update(f64::from(i));
/// }
/// assert!(last.is_some());
/// ```
#[derive(Debug, Clone)]
pub struct RSquared {
period: usize,
window: VecDeque<f64>,
sum_x: f64,
/// `n·Σxx − (Σx)²` — OLS denominator, constant in `period`.
denom: f64,
sum_y: f64,
sum_xy: f64,
sum_y_sq: f64,
}
impl RSquared {
/// Construct a new rolling R² over `period` inputs.
///
/// # Errors
/// Returns [`Error::InvalidPeriod`] if `period < 2` — a regression line
/// is undefined for fewer than two points.
pub fn new(period: usize) -> Result<Self> {
if period < 2 {
return Err(Error::InvalidPeriod {
message: "R² needs period >= 2",
});
}
let n = period as f64;
let sum_x = n * (n - 1.0) / 2.0;
let sum_xx = (n - 1.0) * n * (2.0 * n - 1.0) / 6.0;
Ok(Self {
period,
window: VecDeque::with_capacity(period),
sum_x,
denom: n * sum_xx - sum_x * sum_x,
sum_y: 0.0,
sum_xy: 0.0,
sum_y_sq: 0.0,
})
}
/// Configured period.
pub const fn period(&self) -> usize {
self.period
}
}
impl Indicator for RSquared {
type Input = f64;
type Output = f64;
fn update(&mut self, value: f64) -> Option<f64> {
if self.window.len() == self.period {
let y0 = self.window.pop_front().expect("non-empty");
self.sum_xy = self.sum_xy - self.sum_y + y0;
self.sum_y -= y0;
self.sum_y_sq -= y0 * y0;
}
let k = self.window.len() as f64;
self.window.push_back(value);
self.sum_y += value;
self.sum_xy += k * value;
self.sum_y_sq += value * value;
if self.window.len() < self.period {
return None;
}
let n = self.period as f64;
let slope = (n * self.sum_xy - self.sum_x * self.sum_y) / self.denom;
let mean_y = self.sum_y / n;
let ss_total = (self.sum_y_sq - n * mean_y * mean_y).max(0.0);
let s_xx = self.denom / n;
let ss_explained = slope * slope * s_xx;
if ss_total <= 0.0 {
// Flat window: the fit is trivially perfect.
return Some(1.0);
}
Some((ss_explained / ss_total).clamp(0.0, 1.0))
}
fn reset(&mut self) {
self.window.clear();
self.sum_y = 0.0;
self.sum_xy = 0.0;
self.sum_y_sq = 0.0;
}
fn warmup_period(&self) -> usize {
self.period
}
fn is_ready(&self) -> bool {
self.window.len() == self.period
}
fn name(&self) -> &'static str {
"RSquared"
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::traits::BatchExt;
use approx::assert_relative_eq;
#[test]
fn rejects_period_below_two() {
assert!(RSquared::new(0).is_err());
assert!(RSquared::new(1).is_err());
assert!(RSquared::new(2).is_ok());
}
#[test]
fn accessors_and_metadata() {
let r = RSquared::new(14).unwrap();
assert_eq!(r.period(), 14);
assert_eq!(r.warmup_period(), 14);
assert_eq!(r.name(), "RSquared");
}
#[test]
fn perfect_line_is_one() {
let prices: Vec<f64> = (0..30).map(|i| 2.0 * f64::from(i) + 5.0).collect();
let mut r = RSquared::new(10).unwrap();
for v in r.batch(&prices).into_iter().flatten() {
assert_relative_eq!(v, 1.0, epsilon = 1e-9);
}
}
#[test]
fn constant_series_is_one() {
// SS_total is zero; the indicator must return 1 instead of NaN.
let mut r = RSquared::new(5).unwrap();
for v in r.batch(&[42.0; 20]).into_iter().flatten() {
assert_relative_eq!(v, 1.0, epsilon = 1e-12);
}
}
#[test]
fn output_stays_in_zero_one_range() {
let prices: Vec<f64> = (0..120)
.map(|i| 100.0 + (f64::from(i) * 0.4).sin() * 5.0 + (f64::from(i) * 0.07).cos() * 12.0)
.collect();
let mut r = RSquared::new(20).unwrap();
for v in r.batch(&prices).into_iter().flatten() {
assert!((0.0..=1.0).contains(&v), "R² out of range: {v}");
}
}
#[test]
fn reset_clears_state() {
let mut r = RSquared::new(5).unwrap();
r.batch(&[1.0, 2.0, 3.0, 4.0, 5.0]);
assert!(r.is_ready());
r.reset();
assert!(!r.is_ready());
assert_eq!(r.update(1.0), None);
}
#[test]
fn batch_equals_streaming() {
let prices: Vec<f64> = (0..60)
.map(|i| 50.0 + (f64::from(i) * 0.3).sin() * 10.0)
.collect();
let batch = RSquared::new(14).unwrap().batch(&prices);
let mut b = RSquared::new(14).unwrap();
let streamed: Vec<_> = prices.iter().map(|p| b.update(*p)).collect();
assert_eq!(batch, streamed);
}
}