longitudinal-analysis
縦断的/パネルデータに対して、再現可能なマルチステップ解析を実行する自己完結型スキルです。各ステップは独立して有効化・監査可能。統計的な負荷の高い処理はR（lme4 / lavaan）が担当し、Python側はオーケストレーションとR不在時のグレースフルデグラデーションを行います。
必須ワークフロー
依存関係のブートストラップ（初回使用時に実行）
初回実行前に、このスキルのランタイム依存関係を確認します。
- 必須（Python）:
pandas、PyYAML。 - オプション（Python）:
statsmodels、scipy（操作チェックステップ用）。 - 必須（外部）:
R >= 4.0とlme4、lavaan、emmeans、jsonliteが PATH 上にあること —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をユーザーに示します。
使用タイミング
- ユーザーがパネル/反復測定データ（被験者ごとに1回以上のセッション、被験者間条件あり）を持ち、一回限りの計算ではなく再現可能な解析を希望する場合。
- リクエストに「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）はローカルにインストールされている必要があります。Rscriptが PATH 上にない場合、パイプラインは R に依存するステップをスキップし、監査ログにその理由を記録します。 - メディエーションのブートストラップはユーザーが選択可能（デフォルトは5000）で、実行時間はサンプルサイズに比例して増加します。