# Time Series Analysis

> Skill: time-series-analysis

- Skill: `kaito41418-ux/time-series-analysis` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add kaito41418-ux/time-series-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaito41418-ux/time-series-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kaito41418-ux (https://skillmd.com/u/kaito41418-ux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaito41418-ux/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` | 日期/時間戳 | 觀測時間；需可被 `pd.to_datetime` 解析（例如 `2024-01-15`、`2024-01-15 12:30:00`） |
| `--value` | 數值 | 單變量分析（decompose/arima/anomaly）的目標序列 |
| `--values` | 多個數值欄位 | VAR 多變量分析需 ≥2 個序列 |

資料會被自動按 `--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 字型)