mcpField
T
time-series-decomposer

time-series-decomposer

github.com/dkyazzentwatwaデータ・データベース12459 回インストール29 週間前に更新
リポジトリ

time-series-decomposer について

time-series-decomposerは、時系列をトレンド、季節成分、残差に分解するPythonツールです。異常分析や可視化、基本的な予測にも対応し、周期性のあるデータを扱う分析担当者向けです。

主な機能

  1. 01加法・乗法分解
  2. 02トレンドと季節性の分析
  3. 03残差の異常検知
  4. 04成分図とACF/PACF図
  5. 05トレンド・季節予測

活用シーン

  1. 01売上データの傾向と季節性の分析
  2. 02日次指標の異常値検出
  3. 03季節性データから次の期間を予測

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dkyazzentwatwa/chatgpt-skills --skill time-series-decomposer

インストール後、Claude Code で/time-series-decomposerを入力して読み込まれたか確認します。

同梱ファイルscripts/requirements.txtscripts/ts_decomposer.py

詳細

時系列分解器

時系列データからトレンド、季節成分、残差を抽出し、可視化と基本的な予測を行います。

機能

  • 分解：加法モデルと乗法モデル
  • トレンド抽出：移動平均、多項式フィッティング
  • 季節性の検出：周期パターンを自動検出して抽出
  • 残差分析：残差に含まれる異常を特定
  • 可視化：成分プロット、ACF/PACF
  • 基本的な予測：トレンドの外挿、季節ナイーブ予測

クイックスタート

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 の使用方法

# 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 リファレンス

TimeSeriesDecomposer クラス
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

分解モデル

加法モデル

Y(t) = Trend(t) + Seasonal(t) + Residual(t)

季節変動がおおむね一定の場合に最適です。

result = decomposer.decompose(period=12, model="additive")
乗法モデル

Y(t) = Trend(t) * Seasonal(t) * Residual(t)

季節変動が系列の水準に応じて変化する場合に最適です。

result = decomposer.decompose(period=12, model="multiplicative")

出力形式

分解結果
{
    "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_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
}

季節性分析

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
}

周期の検出

季節周期を自動検出します。

# Automatic detection using ACF
period = decomposer.detect_period()
print(f"Detected period: {period}")

# Or with decomposition
result = decomposer.decompose()  # Auto-detects period

異常検出

残差に含まれる外れ値を検出します。

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

基本的な予測

# 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

可視化

成分プロット
decomposer.plot_components("components.png")

4 つのパネルからなるプロットを生成します。

  1. 元の系列
  2. トレンド
  3. 季節成分
  4. 残差
ACF/PACF プロット
decomposer.plot_acf_pacf("acf_pacf.png", lags=40)

自己相関関数と偏自己相関関数です。

季節プロット
decomposer.plot_seasonal("seasonal.png")

周期ごとの季節効果を示す棒グラフです。

ワークフローの例

売上分析
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")
異常検出
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")
季節性を考慮した予測
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)

依存関係

  • pandas>=2.0.0
  • numpy>=1.24.0
  • scipy>=1.10.0
  • statsmodels>=0.14.0
  • matplotlib>=3.7.0

コメント

Markdown 対応