oxits 0.1.0

Time series classification and transformation library for Rust
Documentation 
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

use crate::approximation::paa::{Paa, PaaConfig};
use crate::core::config::BinStrategy;
use crate::core::traits::Transformer;
use crate::preprocessing::discretizer::{KBinsDiscretizer, KBinsDiscretizerConfig};
use crate::preprocessing::scaler::{StandardScaler, StandardScalerConfig};

/// Symbolic Aggregate approXimation (SAX).
///
/// Pipeline: StandardScaler → PAA → KBinsDiscretizer (normal bins).
/// Output: discretized symbols (as f64 bin indices for trait compat).

#[derive(Debug, Clone)]
pub struct SaxConfig {
    pub n_bins: usize,
    pub strategy: BinStrategy,
    pub output_size: Option<usize>,
}

impl SaxConfig {
    pub fn new(n_bins: usize) -> Self {
        Self {
            n_bins,
            strategy: BinStrategy::Normal,
            output_size: None,
        }
    }
}

pub struct Sax;

impl Transformer for Sax {
    type Config = SaxConfig;

    fn transform(config: &Self::Config, x: &[Vec<f64>]) -> Vec<Vec<f64>> {
        assert!(!x.is_empty(), "Input must have at least one sample");
        assert!(
            config.n_bins >= 2 && config.n_bins <= 26,
            "n_bins must be in [2, 26]"
        );

        let n_timestamps = x[0].len();
        let output_size = config.output_size.unwrap_or(n_timestamps);

        // Step 1: Standardize
        let scaler_config = StandardScalerConfig::new();
        let scaled = StandardScaler::transform(&scaler_config, x);

        // Step 2: PAA
        let paa_result = if output_size < n_timestamps {
            let paa_config = PaaConfig::new(output_size);
            Paa::transform(&paa_config, &scaled)
        } else {
            scaled
        };

        // Step 3: Discretize with normal bins
        let disc_config = KBinsDiscretizerConfig {
            n_bins: config.n_bins,
            strategy: config.strategy,
        };
        let discretized = KBinsDiscretizer::transform(&disc_config, &paa_result);

        // Convert to f64 for trait compatibility
        discretized
            .into_iter()
            .map(|row| row.into_iter().map(|v| v as f64).collect())
            .collect()
    }
}

/// Transform to symbolic u8 output.
pub fn sax_transform_symbolic(config: &SaxConfig, x: &[Vec<f64>]) -> Vec<Vec<u8>> {
    let float_result = Sax::transform(config, x);
    float_result
        .into_iter()
        .map(|row| row.into_iter().map(|v| v as u8).collect())
        .collect()
}

/// Convert bin indices to alphabet characters (a=0, b=1, ...).
pub fn bins_to_alphabet(bins: &[u8]) -> String {
    bins.iter().map(|&b| (b'a' + b) as char).collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_sax_basic() {
        let config = SaxConfig::new(3);
        let x = vec![
            vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0],
            vec![7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0, 0.0],
        ];
        let result = Sax::transform(&config, &x);
        assert_eq!(result.len(), 2);
        assert_eq!(result[0].len(), 8);
        // All values should be in [0, 2]
        for row in &result {
            for &v in row {
                assert!((0.0..=2.0).contains(&v), "Bin {v} out of range");
            }
        }
    }

    #[test]
    fn test_sax_with_paa() {
        let config = SaxConfig {
            n_bins: 3,
            strategy: BinStrategy::Normal,
            output_size: Some(4),
        };
        let x = vec![vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]];
        let result = Sax::transform(&config, &x);
        assert_eq!(result[0].len(), 4);
    }

    #[test]
    fn test_sax_symbolic() {
        let config = SaxConfig::new(3);
        let x = vec![vec![0.0, 1.0, 2.0, 3.0, 4.0]];
        let result = sax_transform_symbolic(&config, &x);
        assert_eq!(result[0].len(), 5);
        for &v in &result[0] {
            assert!(v < 3);
        }
    }

    #[test]
    fn test_bins_to_alphabet() {
        assert_eq!(bins_to_alphabet(&[0, 1, 2]), "abc");
        assert_eq!(bins_to_alphabet(&[0, 0, 1, 1]), "aabb");
    }

    #[test]
    fn test_sax_monotonic() {
        // For a monotonically increasing standardized series,
        // SAX bins should be non-decreasing
        let config = SaxConfig::new(4);
        let x = vec![vec![-3.0, -2.0, -1.0, 0.0, 1.0, 2.0, 3.0, 4.0]];
        let result = Sax::transform(&config, &x);
        for i in 1..result[0].len() {
            assert!(result[0][i] >= result[0][i - 1]);
        }
    }
}