fdars_core/fts/
mod.rs

1//! Functional time series serial-dependence diagnostics.
2//!
3//! # R baselines
4//!
5//! * [`functional_acf`] / [`functional_pacf`] — `fdaACF::facf`
6//!   (Mestre et al. 2021, *Computational Statistics & Data Analysis*).
7//! * [`stationarity_test`] — `ftsa::T_stationary`
8//!   (Horváth, Kokoszka, Rice 2014, *Journal of Econometrics* 179:66–82).
9//! * [`long_run_covariance`] — `ftsa::long_run_covariance_estimation`
10//!   (Bartlett HAC kernel-sandwich estimator).
11//! * [`functional_difference`] — `ftsa::diff.fts` (functional first-difference).
12//!
13//! # Conventions
14//!
15//! Entry points take an explicit deterministic `seed` (`StdRng::seed_from_u64(seed)`)
16//! and default Monte-Carlo replications of 999. All public functions return
17//! `Result<_, FdarError>` and validate inputs at entry. Result structs derive
18//! `Debug, Clone, PartialEq` and are serde-gated.
19
20mod acf;
21mod forecast;
22
23pub use acf::{
24    functional_acf, functional_difference, functional_pacf, long_run_covariance, stationarity_test,
25};
26pub use forecast::{fplsr, ftsm, ftsm_forecast, ftsm_forecast_multistep, ftsm_update};
27
28/// Result of functional ACF/PACF estimation.
29///
30/// Produced by [`functional_acf`] and [`functional_pacf`].
31/// Lag values run from 1 to `max_lag`; `acf`, `pacf`, and `upper_band`
32/// all have length `max_lag`.
33#[derive(Debug, Clone, PartialEq)]
34#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
35#[non_exhaustive]
36pub struct FacfResult {
37    /// Lag values (1..=max_lag).
38    pub lags: Vec<u32>,
39    /// Functional autocorrelation ρ_h at each lag (L2-norm, fdaACF convention).
40    pub acf: Vec<f64>,
41    /// Functional partial autocorrelation (scalar Durbin-Levinson approximation).
42    pub pacf: Vec<f64>,
43    /// Upper confidence band under the strong-white-noise null (Monte-Carlo quantile).
44    pub upper_band: Vec<f64>,
45}
46
47/// Result of the functional stationarity test.
48///
49/// Produced by `stationarity_test` (plan 34-02).
50#[derive(Debug, Clone, PartialEq)]
51#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
52#[non_exhaustive]
53pub struct StationarityResult {
54    /// Test statistic T (KPSS-style partial-sum L2 norm).
55    pub statistic: f64,
56    /// Monte-Carlo permutation p-value.
57    pub p_value: f64,
58    /// Number of permutations used.
59    pub n_perm: usize,
60}
61
62/// Result of the Bartlett kernel-sandwich long-run covariance estimator.
63///
64/// Produced by `long_run_covariance` (plan 34-02).
65#[derive(Debug, Clone, PartialEq)]
66#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
67#[non_exhaustive]
68pub struct LongRunCovResult {
69    /// Estimated m×m long-run covariance matrix (column-major flat Vec).
70    pub cov_matrix: Vec<f64>,
71    /// Grid dimension m (cov_matrix is m×m).
72    pub m: usize,
73    /// Bandwidth used.
74    pub bandwidth: usize,
75    /// Number of curves N.
76    pub n_curves: usize,
77}
78
79/// Diagnostics for a single fitted FPC-score AR(p) model.
80///
81/// One per retained component in [`FtsmResult::ar_models`]. Produced by [`ftsm`].
82#[derive(Debug, Clone, PartialEq)]
83#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
84#[non_exhaustive]
85pub struct ArModelResult {
86    /// Selected AR order p (0 = white noise), chosen by AIC.
87    pub order: usize,
88    /// AR coefficients phi_1..phi_p (0-indexed: `phi[0]` is the lag-1 coefficient).
89    pub phi: Vec<f64>,
90    /// Innovation (residual) variance from the Yule-Walker fit.
91    pub sigma2: f64,
92}
93
94/// Result of fitting the FPCA-based functional time-series model.
95///
96/// Produced by [`ftsm`]. Carries the FPCA decomposition (mean, loadings,
97/// score-time-series, reconstructed fitted curves, integration weights) plus the
98/// per-component AR-model diagnostics used for forecasting.
99#[derive(Debug, Clone, PartialEq)]
100#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
101#[non_exhaustive]
102pub struct FtsmResult {
103    /// Mean curve μ(u), length m.
104    pub mean: Vec<f64>,
105    /// FPC loadings φ_k, shape m × ncomp.
106    pub rotation: crate::matrix::FdMatrix,
107    /// FPC score time-series β_{t,k}, shape n × ncomp.
108    pub scores: crate::matrix::FdMatrix,
109    /// Reconstructed fitted curves, shape n × m.
110    pub fitted: crate::matrix::FdMatrix,
111    /// Simpson integration weights, length m.
112    pub weights: Vec<f64>,
113    /// Effective number of retained components (clamped to min(ncomp, n, m)).
114    pub ncomp: usize,
115    /// Per-component fitted AR-model diagnostics (length = ncomp).
116    pub ar_models: Vec<ArModelResult>,
117}
118
119/// Result of an FPC-score-AR curve forecast.
120///
121/// Produced by [`ftsm_forecast`]. `forecast` is an h × m matrix whose row `i`
122/// holds the forecast curve for horizon `i + 1`.
123#[derive(Debug, Clone, PartialEq)]
124#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
125#[non_exhaustive]
126pub struct FtsmForecastResult {
127    /// Forecast curves, shape h × m (row i = horizon i+1).
128    pub forecast: crate::matrix::FdMatrix,
129    /// Forecast horizon (number of steps ahead).
130    pub h: usize,
131}
132
133/// Result of the functional PLS forecasting variant.
134///
135/// Produced by [`fplsr`]. A lag-1 PLS design (predictor = current curve,
136/// response = next curve) yields a one-step-ahead forecast curve plus the
137/// in-sample lag-1 fitted curves.
138#[derive(Debug, Clone, PartialEq)]
139#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
140#[non_exhaustive]
141pub struct FplsrResult {
142    /// One-step-ahead forecast of the next curve, shape 1 × m.
143    pub forecast: crate::matrix::FdMatrix,
144    /// In-sample lag-1 fitted curves, shape (n-1) × m.
145    pub fitted: crate::matrix::FdMatrix,
146    /// Number of PLS components used (clamped to min(ncomp, n-1, m)).
147    pub ncomp: usize,
148}
fdars_core/fts/mod.rs

fdars_core/fts/
mod.rs
