quantwave_core/regimes/
volatility_clustering.rs

1//! Volatility Regimes (Prakash et al. 2021)
2//!
3//! Source: Prakash, A., James, N., Menzies, M., & Francis, G. (2021). 
4//! "Structural clustering of volatility regimes for dynamic trading strategies." 
5//! Applied Mathematical Finance, 28(3), 236-274.
6//!
7//! Implementation of structural clustering of volatility regimes using rolling ATR and online K-Means.
8//! This module identifies discrete volatility states (e.g., Low, Medium, High) by clustering
9//! recent ATR values.
10
11use std::collections::VecDeque;
12use crate::indicators::volatility::ATR;
13use crate::traits::Next;
14use crate::regimes::MarketRegime;
15use serde::{Deserialize, Serialize};
16
17/// A streaming volatility clusterer that identifies market regimes based on ATR.
18#[derive(Debug, Clone, Serialize, Deserialize)]
19pub struct VolatilityClusterer {
20    atr: ATR,
21    window: VecDeque<f64>,
22    window_size: usize,
23    k: usize,
24    centroids: Vec<f64>,
25    counts: Vec<usize>,
26    min_observations: usize,
27}
28
29impl VolatilityClusterer {
30    /// Creates a new VolatilityClusterer.
31    ///
32    /// # Arguments
33    /// * `atr_period` - The period for the underlying ATR indicator.
34    /// * `window_size` - The number of recent ATR values to consider for clustering.
35    /// * `k` - The number of volatility regimes to identify (e.g., 3 for Low/Med/High).
36    pub fn new(atr_period: usize, window_size: usize, k: usize) -> Self {
37        Self {
38            atr: ATR::new(atr_period),
39            window: VecDeque::with_capacity(window_size),
40            window_size,
41            k,
42            centroids: vec![0.0; k],
43            counts: vec![0; k],
44            min_observations: window_size.max(k * 10), // Need enough data to stabilize
45        }
46    }
47
48    /// Performs online K-Means update for a single value.
49    fn update_clusters(&mut self, val: f64) -> usize {
50        if self.centroids.iter().all(|&c| c == 0.0) {
51            // Initialization: spread centroids across current range
52            if self.window.len() >= self.k {
53                let mut sorted: Vec<f64> = self.window.iter().copied().collect();
54                sorted.sort_by(|a, b| a.partial_cmp(b).unwrap());
55                for i in 0..self.k {
56                    let idx = (i * (sorted.len() - 1)) / (self.k - 1);
57                    self.centroids[i] = sorted[idx];
58                    self.counts[i] = 1;
59                }
60            }
61        }
62
63        // Find nearest centroid
64        let mut min_dist = f64::MAX;
65        let mut closest_idx = 0;
66
67        for (i, &centroid) in self.centroids.iter().enumerate() {
68            let dist = (val - centroid).abs();
69            if dist < min_dist {
70                min_dist = dist;
71                closest_idx = i;
72            }
73        }
74
75        // Online update of centroid
76        self.counts[closest_idx] += 1;
77        let lr = 1.0 / (self.counts[closest_idx] as f64).sqrt(); // Decaying learning rate
78        self.centroids[closest_idx] += lr * (val - self.centroids[closest_idx]);
79
80        closest_idx
81    }
82}
83
84impl Next<(f64, f64, f64)> for VolatilityClusterer {
85    type Output = MarketRegime;
86
87    fn next(&mut self, input: (f64, f64, f64)) -> Self::Output {
88        let atr_val = self.atr.next(input);
89        
90        if self.window.len() >= self.window_size {
91            self.window.pop_front();
92        }
93        self.window.push_back(atr_val);
94
95        let cluster_idx = self.update_clusters(atr_val);
96
97        if self.window.len() < self.min_observations {
98            return MarketRegime::Steady;
99        }
100
101        // Map cluster index to MarketRegime
102        // We sort centroids to ensure 0 is Low, k-1 is High
103        let mut sorted_indices: Vec<usize> = (0..self.k).collect();
104        sorted_indices.sort_by(|&a, &b| self.centroids[a].partial_cmp(&self.centroids[b]).unwrap());
105
106        let rank = sorted_indices.iter().position(|&i| i == cluster_idx).unwrap_or(0);
107
108        match rank {
109            0 => MarketRegime::Steady, // Lowest vol
110            r if r == self.k - 1 => MarketRegime::Crisis, // Highest vol
111            _ => MarketRegime::Cluster(rank as u8),
112        }
113    }
114}
quantwave_core/regimes/volatility_clustering.rs

quantwave_core/regimes/
volatility_clustering.rs
