Time Series Analysis

Skill: time-series-analysis

時間序列分析（STL / ARIMA / ETS / Anomaly / VAR）與 Word 報告匯出。

Metadata

• Description: 對時間序列資料執行 STL 分解 + 平穩性檢驗、ARIMA/ETS 建模與預測、STL 殘差異常點偵測、多變量 VAR 模型與 Granger 因果檢驗；輸出趨勢/季節/殘差分解圖、ACF/PACF、預測圖 + CI、異常點標註圖、IRF 冲激響應圖。
• Version: 1.0.0
• Entrypoint: orchestrator.py（CLI: --source {local,sql,hadoop} + --time <col> + --analysis {decompose,arima,anomaly,var} + 對應模式參數）
• Related:
  • 假設檢驗：advanced-data-analytics
  • 迴歸建模：regression-analytics
  • 因素分析：factor-analysis
  • 多因子 ANOVA：factorial-anova
  • 多變量分析（PCA/Cluster/MANOVA）：multivariate-analysis
  • 生存分析：survival-analysis

資料規格

時間序列資料每列代表一個時間點的觀測值：

資料會被自動按 --time 升序排序；含 NA 的列會被 listwise 刪除。

Analysis Modes

1. decompose — STL 分解與平穩性檢驗

• 輸入: --time + --value + --freq（可選）
• 決策流程:
  1. ts() 構造時序物件（依 --freq 或自動推斷週期長度）
  2. STL 分解：趨勢 (trend) + 季節 (seasonal) + 殘差 (remainder)
  3. 平穩性檢驗:
     • ADF (Augmented Dickey-Fuller)：tseries::adf.test，p<0.05 → 拒絕單根 → 平穩
     • KPSS：tseries::kpss.test，p>0.05 → 未拒絕平穩 → 平穩
  4. ACF / PACF：forecast::ggAcf / forecast::ggPacf
• 輸出:
  • 分解表（trend / seasonal / remainder 前 20 筆）
  • ADF / KPSS 統計量與 p 值 + 平穩性判定
  • 分解圖 decompose.png
  • ACF/PACF 併圖 acf_pacf.png

2. arima — ARIMA / ETS 建模與預測

• 輸入: --time + --value + --freq（可選）+ --h（預測步數，預設 12）+ --engine {arima,ets}（預設 arima）
• 決策流程:
  1. arima 引擎 → forecast::auto.arima（自動選 (p,d,q)(P,D,Q)m，允許 seasonal）
  2. ets 引擎 → forecast::ets（自動選誤差 / 趨勢 / 季節結構）
  3. 模型摘要：階數 / AIC / BIC / σ²
  4. 殘差診斷：Box.test（Ljung-Box）；p>0.05 → 殘差為白噪聲、模型已捕捉結構
  5. 預測：forecast::forecast(fit, h=h)，輸出點估計 + 80% / 95% 信賴區間
• 輸出:
  • 模型階數與資訊準則表
  • 係數表（含 SE、z、p）
  • Ljung-Box 殘差檢驗表
  • 預測表（h 步預測值 + 80/95 CI）
  • 預測圖 forecast.png（歷史 + 預測 + 兩層陰影）
  • 殘差圖 residuals.png（殘差時序 + ACF）

3. anomaly — STL 殘差異常點偵測

• 輸入: --time + --value + --freq（可選）
• 決策流程:
  1. 對原序列做 STL 分解
  2. forecast::tsoutliers 找 IQR 型異常殘差
  3. 對每個異常點回填 observed / expected / residual
• 輸出:
  • 異常點總數與比例
  • 異常點明細表（time / observed / expected / residual）
  • 標註圖 anomaly.png（原序列 + 異常點紅色標記）

4. var — 多變量 VAR 與 Granger 因果

• 輸入: --time + --values Y1 Y2 [Y3 ...] + --freq（可選）+ --h（IRF 步數，預設 12）
• 決策流程:
  1. ts(cbind(...)) 構造多變量時序
  2. vars::VARselect(lag.max=10) 由 AIC / BIC / HQ 決定最佳 lag
  3. vars::VAR(p=selected) 拟合
  4. lmtest::grangertest 兩兩檢驗 Y_i 是否 Granger-cause Y_j
  5. vars::irf(n.ahead=h) 冲激響應
• 輸出:
  • VARselect 表（AIC / BIC / HQ / FPE 建議的 lag）
  • Granger 因果 p 值矩陣（含顯著標記）
  • IRF 圖 var_irf.png（k×k 網格，每格一個 shock→response 曲線 + CI 陰影）

Output Location

預設輸出目錄：./outcome-temp/

• fetched_data.csv：資料快照
• TimeSeries_Report.docx：Word 報告
• decompose.png / acf_pacf.png：decompose 模式
• forecast.png / residuals.png：arima 模式
• anomaly.png：anomaly 模式
• var_irf.png：var 模式

Workflow (SOP)

1. fetch: schema 校驗（time 可轉時間戳、value/values 為數值、無零方差）+ 排序 + listwise 刪除 NA + 週期自動推斷
2. execute: 依 analysis mode 分派到對應 R body
3. render: 依 analysis mode 動態組裝章節
4. 交付: .docx 落地在 output-dir

Constraints

• --time 需可 pd.to_datetime；不能有大量重複時間戳
• decompose/arima/anomaly: --value 為連續數值、非常數
• var: --values 至少 2 個、每個都連續數值
• 若時間戳非等距且未指定 --freq，直接報錯（避免 STL 崩潰或給出誤導性結果）
• --freq 未指定時，依 median time diff 自動推斷：hourly=24 / daily=7 / weekly=52 / monthly=12 / quarterly=4 / yearly=1
• Listwise deletion：[time, value(s)] 任一為 NA 的列丟棄

Dependencies

• Python 3.10+: pandas numpy sqlalchemy python-docx openpyxl pyhive thrift thrift-sasl pure-sasl
• R 4.x:
  • 必要: ggplot2 jsonlite forecast tseries urca
  • VAR 專用: vars lmtest
  • 可選: showtext sysfonts (CJK 字型)