Decompose Time Series Data

This skill acts as an expert in time series decomposition, breaking temporal data into interpretable components - trend, seasonality, cyclical variation, and residual/noise - using classical statistical methods, modern signal processing, and machine learning approaches. It works with both additive (Y(t) = Trend + Seasonal + Residual) and multiplicative (Y(t) = Trend x Seasonal x Residual) models, choosing the right one for the data's structure.

For classical decomposition it applies statsmodels' seasonal_decompose and STL (Seasonal and Trend decomposition using Loess), the latter with tunable seasonal/trend smoother lengths and robustness to outliers:

from statsmodels.tsa.seasonal import STL

def stl_decompose(ts, seasonal=7, trend=None, robust=True):
    """
    STL decomposition with flexible parameters
    """
    stl = STL(
        ts,
        seasonal=seasonal,  # Length of seasonal smoother
        trend=trend,        # Length of trend smoother
        robust=robust       # Robust to outliers
    )
    
    result = stl.fit()
    
    return {
        'original': result.observed,
        'trend': result.trend,
        'seasonal': result.seasonal,
        'residual': result.resid
    }

For advanced cases it applies X-13ARIMA-SEATS for economic/business data needing trading-day adjustment and automatic outlier detection, Empirical Mode Decomposition (EMD/EEMD via PyEMD) for non-linear, non-stationary series, and wavelet decomposition (pywt) for multi-resolution and time-frequency analysis. Decomposition quality is assessed with reconstruction MSE/MAE, a Ljung-Box test for residual white noise, a Shapiro normality test, and explicit seasonal-strength and trend-strength scores - plus a standard four-panel plot (original, trend, seasonal, residual) for visual validation.

Use Classical/STL decomposition for regular, stable seasonality with minimal outliers; X-13ARIMA-SEATS for economic or business data requiring trading-day adjustments; EMD/EEMD for non-linear, non-stationary data with complex patterns; and wavelet decomposition for multi-scale analysis, especially financial or engineering data. When seasonal strength scores below 0.3, consider a trend-only model instead of forcing a seasonal component; for high-noise series, prefer robust methods like STL with robust=True or EEMD.

X-13ARIMA-SEATS requires the separate X-13ARIMA-SEATS software to be installed and falls back to STL automatically if it isn't available.

Input is a time series (a pandas Series with a datetime index, or a raw numeric array). Output is a dictionary of components (trend, seasonal, residual/original, or IMFs and wavelet coefficients depending on method) plus diagnostic metrics for validating the decomposition's quality. Suggested parameter defaults: STL seasonal parameter as an odd integer, typically 7-15 for strong seasonality; db4 wavelet for general use, haar for sharp changes, coif2 for smooth data; EMD max_imf starting around data_length/10.

Data scientists and analysts working with temporal data - forecasting, anomaly detection, or seasonal adjustment - who need to separate trend, seasonality, and noise using the method best suited to their data's linearity, stationarity, and noise level.