# Time Series Decomposer > Decompose time series into trend, seasonal, and residual components. Use for forecasting, pattern analysis, and seasonality detection. - Skill: `majiayu000/time-series-decomposer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add majiayu000/time-series-decomposer` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/time-series-decomposer/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/time-series-decomposer --- # Time Series Decomposer Extract trend, seasonal, and residual components from time series data with visualization and basic forecasting. ## Features - **Decomposition**: Additive and multiplicative models - **Trend Extraction**: Moving averages, polynomial fitting - **Seasonality Detection**: Auto-detect and extract periodic patterns - **Residual Analysis**: Identify anomalies in residuals - **Visualization**: Component plots, ACF/PACF - **Basic Forecasting**: Trend extrapolation, seasonal naive ## Quick Start ```python from ts_decomposer import TimeSeriesDecomposer decomposer = TimeSeriesDecomposer() decomposer.load_csv("sales.csv", date_col="date", value_col="revenue") # Decompose result = decomposer.decompose(period=12) # Monthly seasonality print(f"Trend strength: {result['trend_strength']:.2f}") print(f"Seasonal strength: {result['seasonal_strength']:.2f}") # Plot components decomposer.plot_components("decomposition.png") ``` ## CLI Usage ```bash # Basic decomposition python ts_decomposer.py --input data.csv --date date --value sales --period 12 # Multiplicative model python ts_decomposer.py --input data.csv --date date --value sales --period 12 --model multiplicative # With forecast python ts_decomposer.py --input data.csv --date date --value sales --period 12 --forecast 6 # Auto-detect period python ts_decomposer.py --input data.csv --date date --value sales --auto-period # Generate plots python ts_decomposer.py --input data.csv --date date --value sales --period 12 --plot components.png # Output JSON python ts_decomposer.py --input data.csv --date date --value sales --period 12 --json ``` ## API Reference ### TimeSeriesDecomposer Class ```python class TimeSeriesDecomposer: def __init__(self) # Data loading def load_csv(self, filepath: str, date_col: str, value_col: str, date_format: str = None) -> 'TimeSeriesDecomposer' def load_series(self, series: pd.Series) -> 'TimeSeriesDecomposer' def load_dataframe(self, df: pd.DataFrame, date_col: str, value_col: str) -> 'TimeSeriesDecomposer' # Decomposition def decompose(self, period: int = None, model: str = "additive") -> dict def detect_period(self) -> int def extract_trend(self, method: str = "moving_average", window: int = None) -> pd.Series def extract_seasonal(self, period: int) -> pd.Series # Analysis def analyze_trend(self) -> dict def analyze_seasonality(self) -> dict def analyze_residuals(self) -> dict def detect_anomalies(self, threshold: float = 2.0) -> pd.DataFrame # Forecasting def forecast(self, periods: int, method: str = "trend") -> pd.DataFrame # Visualization def plot_components(self, output: str) -> str def plot_acf_pacf(self, output: str, lags: int = 40) -> str def plot_seasonal(self, output: str) -> str # Export def to_dataframe(self) -> pd.DataFrame def summary(self) -> str ``` ## Decomposition Models ### Additive Model Y(t) = Trend(t) + Seasonal(t) + Residual(t) Best when seasonal variations are roughly constant. ```python result = decomposer.decompose(period=12, model="additive") ``` ### Multiplicative Model Y(t) = Trend(t) * Seasonal(t) * Residual(t) Best when seasonal variations scale with the level of the series. ```python result = decomposer.decompose(period=12, model="multiplicative") ``` ## Output Format ### Decomposition Result ```python { "model": "additive", "period": 12, "trend_strength": 0.85, # 0-1, higher = stronger trend "seasonal_strength": 0.72, # 0-1, higher = stronger seasonality "components": { "observed": [...], # Original values "trend": [...], # Trend component "seasonal": [...], # Seasonal component "residual": [...] # Residual component }, "seasonal_pattern": { # Average seasonal effect by period 1: 0.12, 2: -0.05, ... }, "statistics": { "trend_slope": 0.023, "trend_r_squared": 0.91, "residual_std": 0.15, "residual_mean": 0.002 } } ``` ## Trend Analysis ```python trend_info = decomposer.analyze_trend() # Returns: { "direction": "increasing", # "increasing", "decreasing", "flat" "slope": 0.023, "r_squared": 0.91, "change_points": [ # Detected trend changes {"index": 24, "date": "2023-01-01", "direction": "up"}, {"index": 48, "date": "2025-01-01", "direction": "down"} ], "growth_rate": 0.028, # Compound growth rate "volatility": 0.12 } ``` ## Seasonality Analysis ```python seasonal_info = decomposer.analyze_seasonality() # Returns: { "detected_period": 12, "strength": 0.72, "pattern": { 1: {"value": 0.12, "label": "Jan", "rank": 3}, 2: {"value": -0.05, "label": "Feb", "rank": 8}, ... }, "peak_period": 12, # Period with highest seasonal effect "trough_period": 2, # Period with lowest seasonal effect "seasonal_range": 0.35 # Max - Min seasonal effect } ``` ## Period Detection Auto-detect the seasonal period: ```python # Automatic detection using ACF period = decomposer.detect_period() print(f"Detected period: {period}") # Or with decomposition result = decomposer.decompose() # Auto-detects period ``` ## Anomaly Detection Find outliers in residuals: ```python anomalies = decomposer.detect_anomalies(threshold=2.0) # Returns DataFrame with anomalous points: # date value residual zscore anomaly_type # 0 2023-03-15 1250.5 450.2 3.2 high # 1 2023-08-22 320.1 -380.5 -2.8 low ``` ## Basic Forecasting ```python # Trend extrapolation forecast = decomposer.forecast(periods=12, method="trend") # Seasonal naive (last season's values) forecast = decomposer.forecast(periods=12, method="seasonal_naive") # Trend + Seasonal forecast = decomposer.forecast(periods=12, method="combined") # Returns: # date forecast lower_bound upper_bound # 0 2024-01-01 1050.2 920.5 1180.0 # 1 2024-02-01 1080.5 945.2 1215.8 ``` ## Visualization ### Component Plot ```python decomposer.plot_components("components.png") ``` Generates a 4-panel plot: 1. Original series 2. Trend 3. Seasonal 4. Residuals ### ACF/PACF Plot ```python decomposer.plot_acf_pacf("acf_pacf.png", lags=40) ``` Autocorrelation and partial autocorrelation functions. ### Seasonal Plot ```python decomposer.plot_seasonal("seasonal.png") ``` Bar chart of seasonal effects by period. ## Example Workflows ### Sales Analysis ```python decomposer = TimeSeriesDecomposer() decomposer.load_csv("monthly_sales.csv", "month", "revenue") # Auto-detect and decompose result = decomposer.decompose() # Understand patterns print(f"Trend: {decomposer.analyze_trend()['direction']}") print(f"Peak season: Month {decomposer.analyze_seasonality()['peak_period']}") # Plot decomposer.plot_components("sales_analysis.png") ``` ### Anomaly Detection ```python decomposer = TimeSeriesDecomposer() decomposer.load_csv("daily_metrics.csv", "date", "pageviews") decomposer.decompose(period=7) # Weekly pattern # Find unusual days anomalies = decomposer.detect_anomalies(threshold=2.5) print(f"Found {len(anomalies)} anomalous days") ``` ### Forecasting with Seasonality ```python decomposer = TimeSeriesDecomposer() decomposer.load_csv("quarterly_data.csv", "quarter", "value") decomposer.decompose(period=4, model="multiplicative") # Forecast next year forecast = decomposer.forecast(periods=4, method="combined") print(forecast) ``` ## Dependencies - pandas>=2.0.0 - numpy>=1.24.0 - scipy>=1.10.0 - statsmodels>=0.14.0 - matplotlib>=3.7.0