纵向分析
一个自包含的技能，用于对纵向/面板数据运行可复现的多步骤分析。 每个步骤独立启用并可审计；R（lme4 / lavaan）负责统计核心计算， Python端负责编排，并在R缺失时优雅降级。
强制工作流程
依赖引导（首次使用运行）
首次运行前，探测本技能的运行时依赖：
- 必需（Python）：
pandas、PyYAML。 - 可选（Python）：
statsmodels、scipy（操纵检验步骤）。 - 必需（外部）：路径中需包含
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 <路径> [--step <名称>]。 -
报告每个步骤的状态；跳过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）必须在本地安装；当Rscript不在路径中时，流水线会跳过R相关步骤，并在审计日志中记录原因。 - 中介自举（bootstrap）由用户选择（默认5000次）；运行时间随样本量增加而增加。