fdars-core 0.13.0

Functional Data Analysis algorithms in 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

//! Detrending and decomposition functions for non-stationary functional data.
//!
//! This module provides methods for removing trends from functional data
//! to enable more accurate seasonal analysis. It includes:
//! - Linear detrending (least squares)
//! - Polynomial detrending (QR decomposition)
//! - Differencing (first and second order)
//! - LOESS detrending (local polynomial regression)
//! - Spline detrending (P-splines)
//! - Automatic method selection via AIC

use crate::matrix::FdMatrix;
use std::borrow::Cow;

pub mod auto;
pub mod decompose;
pub mod diff;
pub mod linear;
pub mod loess;
pub mod polynomial;
pub mod stl;

#[cfg(test)]
mod tests;

// ---------------------------------------------------------------------------
// Shared types
// ---------------------------------------------------------------------------

/// Result of detrending operation.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct TrendResult {
    /// Estimated trend values (n x m)
    pub trend: FdMatrix,
    /// Detrended data (n x m)
    pub detrended: FdMatrix,
    /// Method used for detrending
    pub method: Cow<'static, str>,
    /// Polynomial coefficients (for polynomial methods, per sample)
    /// For n samples with polynomial degree d: n x (d+1)
    pub coefficients: Option<FdMatrix>,
    /// Residual sum of squares for each sample
    pub rss: Vec<f64>,
    /// Number of parameters (for AIC calculation)
    pub n_params: usize,
}

impl TrendResult {
    /// Construct a no-op TrendResult (zero trend, data copied to detrended).
    pub(super) fn empty(
        data: &FdMatrix,
        n: usize,
        m: usize,
        method: Cow<'static, str>,
        n_params: usize,
    ) -> Self {
        TrendResult {
            trend: FdMatrix::zeros(n, m),
            detrended: FdMatrix::from_slice(data.as_slice(), n, m)
                .unwrap_or_else(|_| FdMatrix::zeros(n, m)),
            method,
            coefficients: None,
            rss: vec![0.0; n],
            n_params,
        }
    }
}

/// Result of seasonal decomposition.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct DecomposeResult {
    /// Trend component (n x m)
    pub trend: FdMatrix,
    /// Seasonal component (n x m)
    pub seasonal: FdMatrix,
    /// Remainder/residual component (n x m)
    pub remainder: FdMatrix,
    /// Period used for decomposition
    pub period: f64,
    /// Decomposition method ("additive" or "multiplicative")
    pub method: Cow<'static, str>,
}

// ---------------------------------------------------------------------------
// Shared helpers
// ---------------------------------------------------------------------------

/// Reassemble per-curve (trend, detrended, coefficients, rss) results into FdMatrix outputs.
pub(super) fn reassemble_polynomial_results(
    results: Vec<(Vec<f64>, Vec<f64>, Vec<f64>, f64)>,
    n: usize,
    m: usize,
    n_coef: usize,
) -> (FdMatrix, FdMatrix, FdMatrix, Vec<f64>) {
    let mut trend = FdMatrix::zeros(n, m);
    let mut detrended = FdMatrix::zeros(n, m);
    let mut coefficients = FdMatrix::zeros(n, n_coef);
    let mut rss = vec![0.0; n];
    for (i, (t, d, coefs, r)) in results.into_iter().enumerate() {
        for j in 0..m {
            trend[(i, j)] = t[j];
            detrended[(i, j)] = d[j];
        }
        for k in 0..n_coef {
            coefficients[(i, k)] = coefs[k];
        }
        rss[i] = r;
    }
    (trend, detrended, coefficients, rss)
}

/// Reassemble per-curve (trend, detrended, rss) results into FdMatrix outputs.
pub(super) fn reassemble_trend_results(
    results: Vec<(Vec<f64>, Vec<f64>, f64)>,
    n: usize,
    m: usize,
) -> (FdMatrix, FdMatrix, Vec<f64>) {
    let mut trend = FdMatrix::zeros(n, m);
    let mut detrended = FdMatrix::zeros(n, m);
    let mut rss = vec![0.0; n];
    for (i, (t, d, r)) in results.into_iter().enumerate() {
        for j in 0..m {
            trend[(i, j)] = t[j];
            detrended[(i, j)] = d[j];
        }
        rss[i] = r;
    }
    (trend, detrended, rss)
}

// ---------------------------------------------------------------------------
// Re-exports -- preserves the external API
// ---------------------------------------------------------------------------

pub use auto::auto_detrend;
pub use decompose::{decompose_additive, decompose_multiplicative};
pub use diff::detrend_diff;
pub use linear::detrend_linear;
pub use loess::detrend_loess;
pub use polynomial::detrend_polynomial;
pub use stl::{stl_decompose, stl_decompose_with_config, stl_fdata, StlConfig, StlResult};