longitudinal-analysis
一個自成一體的分析技能，用於對縱向/面板資料執行可重複的多步驟分析。每個步驟可獨立啟用並稽核；統計重計算部分由 R（lme4 / lavaan）負責，Python 端負責協調，並在 R 缺失時優雅降級。
強制工作流程
依賴項引導（首次使用時執行）
在首次執行前，探查此技能的執行時期依賴項：
- 必要（Python）：
pandas、PyYAML。 - 選用（Python）：
statsmodels、scipy（用於操弄檢核步驟）。 - 必要（外部）：位於 PATH 上的
R >= 4.0與lme4、lavaan、emmeans、jsonlite—lmm、mediation和sensitivity步驟需要這些套件。
行為：
- 缺少 Python 依賴項 -> 告知使用者缺少哪些套件，並詢問是否要執行
python -m pip install pandas pyyaml（若要進行操弄檢核則加入statsmodels scipy）。僅在使用者確認後才進行安裝；建議使用專案本機的虛擬環境。 - 缺少 R 或 R 套件 -> 請勿嘗試安裝 R。列出確切缺少的 R 套件，跳過所有依賴 R 的步驟，在稽核日誌中記錄原因，並交付有實際執行的 Python 步驟結果。
- 載入 YAML 設定檔（參考
config/examples/behavior_2x2x2.yaml）。 - 確認
data.input存在，且id_column/time_column都存在。 - 執行
python -m src.cli run --config <path> [--step <name>]。 - 回報每個步驟的狀態；被跳過的 R 步驟表示未安裝 R — 列出缺少的套件並停止（請勿嘗試安裝）。
- 引導使用者前往
results/tables/*.csv與results/logs/analysis_log.jsonl。
何時使用
- 使用者擁有面板/重複測量資料（每位受試者一或多個測量時間點，且有組間條件），並希望進行可重複的分析，而非一次性計算。
- 使用者提出的技術名稱包含：「LMM」、「mixed model」、「repeated measures」、「longitudinal analysis」、「mediation over time」、「lagged mediator」或「sensitivity analysis of RE structure」。
- 需要產出包含稽核軌跡的描述統計、操弄檢核或隨機效應/共變異數結構的敏感度分析。
使用範例
# 驗證設定檔並列出其啟用的步驟。
python -m src.cli validate --config config/examples/behavior_2x2x2.yaml
python -m src.cli list-steps --config config/examples/behavior_2x2x2.yaml
# 執行完整管線，或只執行一個指定步驟。
python -m src.cli run --config config/examples/behavior_2x2x2.yaml
python -m src.cli run --config config/examples/behavior_2x2x2.yaml --step lmm
# 匯出產出的表格（csv 或 docx）。
python -m src.cli export --config config/examples/behavior_2x2x2.yaml --format csv
結果會儲存在 results/tables/*.csv；每個步驟的稽核軌跡則在 results/logs/analysis_log.jsonl。
錯誤處理
- 某步驟回報
skipped— 表示缺少 R 或某個 R 套件。列出缺少的套件並停止；請勿嘗試安裝，也請勿用手算替代。 - 設定檔無效（
validate回傳非零值） — 修正所回報的欄位（通常是data.input、id_column或time_column）並重新驗證。 - 管線中途發生步驟錯誤 — 保留並稽核先前步驟的輸出；逐字回報失敗的步驟並停止，請勿盲目重新執行。
- 非預期的結束代碼 — 逐字回報錯誤訊息。
管線步驟
| 類型 | 模組 | R 依賴項 |
|---|---|---|
descriptive | src/steps/descriptive.py | 無 |
anova（操弄檢核） | src/steps/manipulation.py | 無（使用 statsmodels） |
lmm | src/steps/lmm.py | R/lmm.R（lme4 + emmeans） |
mediation（滯後中介） | src/steps/mediation.py | R/mediation.R（lavaan） |
sensitivity | src/steps/sensitivity.py | R/lmm.R |
限制
- R 套件（
lme4、lavaan、emmeans、jsonlite）必須在本機安裝；若 PATH 上找不到Rscript，管線會跳過依賴 R 的步驟，並在稽核日誌中記錄原因。 - 中介效應的拔靴法（bootstrap）由使用者選擇（預設 5000 次）；實際耗時會隨著樣本數增加而增加。