use ndarray::Array1;
use solow_core::error::{Error, Result};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SeasonalModel {
Additive,
Multiplicative,
}
impl SeasonalModel {
pub fn parse(s: &str) -> Result<Self> {
if s.starts_with('a') {
Ok(SeasonalModel::Additive)
} else if s.starts_with('m') {
Ok(SeasonalModel::Multiplicative)
} else {
Err(Error::Value(format!("unknown model '{s}'")))
}
}
}
#[derive(Debug, Clone)]
pub struct DecomposeResult {
pub trend: Array1<f64>,
pub seasonal: Array1<f64>,
pub resid: Array1<f64>,
}
fn nanmean(values: &[f64]) -> f64 {
let mut sum = 0.0;
let mut count = 0usize;
for &v in values {
if v.is_finite() {
sum += v;
count += 1;
}
}
if count == 0 {
f64::NAN
} else {
sum / count as f64
}
}
fn centered_trend(x: &Array1<f64>, period: usize) -> Array1<f64> {
let n = x.len();
let filt: Vec<f64> = if period % 2 == 0 {
let mut f = vec![1.0 / period as f64; period + 1];
f[0] = 0.5 / period as f64;
f[period] = 0.5 / period as f64;
f
} else {
vec![1.0 / period as f64; period]
};
let nf = filt.len();
let ceil_half = nf.div_ceil(2);
let trim_head = ceil_half - 1;
let trim_tail = ceil_half - (nf % 2);
let mut trend = Array1::<f64>::from_elem(n, f64::NAN);
let last = n.saturating_sub(trim_tail);
for i in trim_head..last {
let mut acc = 0.0;
for (k, &w) in filt.iter().enumerate() {
acc += w * x[i - trim_head + k];
}
trend[i] = acc;
}
trend
}
pub fn seasonal_decompose(
x: &Array1<f64>,
period: usize,
model: SeasonalModel,
) -> Result<DecomposeResult> {
let n = x.len();
if period < 2 {
return Err(Error::Value("period must be at least 2".into()));
}
if n < 2 * period {
return Err(Error::Value(
"x must have 2 complete cycles (len >= 2 * period)".into(),
));
}
if !x.iter().all(|v| v.is_finite()) {
return Err(Error::Value(
"This function does not handle missing values".into(),
));
}
if model == SeasonalModel::Multiplicative && x.iter().any(|&v| v <= 0.0) {
return Err(Error::Value(
"Multiplicative seasonality is not appropriate for zero and negative values".into(),
));
}
let trend = centered_trend(x, period);
let detrended: Array1<f64> = match model {
SeasonalModel::Additive => x - &trend,
SeasonalModel::Multiplicative => x / &trend,
};
let mut period_averages = vec![0.0_f64; period];
for (p, avg) in period_averages.iter_mut().enumerate() {
let phase: Vec<f64> = (p..n).step_by(period).map(|i| detrended[i]).collect();
*avg = nanmean(&phase);
}
match model {
SeasonalModel::Additive => {
let m = period_averages.iter().sum::<f64>() / period as f64;
for v in period_averages.iter_mut() {
*v -= m;
}
}
SeasonalModel::Multiplicative => {
let m = period_averages.iter().sum::<f64>() / period as f64;
for v in period_averages.iter_mut() {
*v /= m;
}
}
}
let seasonal = Array1::from_shape_fn(n, |i| period_averages[i % period]);
let resid: Array1<f64> = match model {
SeasonalModel::Additive => &detrended - &seasonal,
SeasonalModel::Multiplicative => x / &seasonal / &trend,
};
Ok(DecomposeResult {
trend,
seasonal,
resid,
})
}
#[cfg(test)]
mod tests {
use super::*;
use ndarray::Array1;
#[test]
fn additive_recovers_seasonality() {
let pattern = [2.0, -1.0, -3.0, 2.0];
let n = 24;
let x = Array1::from_shape_fn(n, |i| 10.0 + 0.5 * i as f64 + pattern[i % 4]);
let r = seasonal_decompose(&x, 4, SeasonalModel::Additive).unwrap();
let s: f64 = (0..4).map(|i| r.seasonal[i]).sum();
assert!(s.abs() < 1e-9);
assert!(r.trend[0].is_nan());
assert!(r.trend[n / 2].is_finite());
}
#[test]
fn rejects_short_series() {
let x = Array1::from_vec(vec![1.0, 2.0, 3.0]);
assert!(seasonal_decompose(&x, 4, SeasonalModel::Additive).is_err());
}
#[test]
fn rejects_nonpositive_multiplicative() {
let x = Array1::from_shape_fn(12, |i| if i == 3 { -1.0 } else { 1.0 + i as f64 });
assert!(seasonal_decompose(&x, 4, SeasonalModel::Multiplicative).is_err());
}
}