JiamingShi-JsPhys/agent-skills

---

name: longitudinal-analysis

description: "Longitudinal statistical analysis pipeline. Use when the user has panel / repeated-measures data (one or more sessions per subject, with between-subject conditions) and wants to run a reproducible analysis: descriptive stats, a manipulation check, a linear mixed model, a lagged mediator, or a sensitivity analysis over random-effects / covariance structures. Triggers on any of the phrases "LMM", "mixed model", "repeated measures", "longitudinal analysis", "mediation over time", "lagged mediator", "sensitivity analysis of RE structure". When fired, load the YAML config that lists the enabled steps, run the pipeline, and report the per-step results plus the generated CSVs."

metadata: author: Jiaming Shi version: 1.0.0 license: MIT entry_point: python -m longitudinal_analysis python_requires: '>=3.9' python_dependencies: - 'numpy>=1.24' - 'pandas>=2.0' - 'PyYAML>=6.0' - 'statsmodels>=0.14' - 'scipy>=1.10' optional_dependencies: - 'python-docx>=0.8.11' platforms: - windows - macos - linux legacy_name: longitudinal-analysis

longitudinal-analysis

A self-contained skill that runs a **reproducible multi-step analysis on

longitudinal / panel data**. Each step is independently enabled and

audited; R (lme4 / lavaan) is invoked for the statistical heavy lifting

and the Python side orchestrates + degrades gracefully when R is absent.

MANDATORY WORKFLOW

Dependency bootstrap (run on first use)

Before the first run, probe the runtime deps for this skill:

• Required (Python): pandas, PyYAML.
• Optional (Python): statsmodels, scipy (manipulation-check step).
• Required (external): R >= 4.0 with lme4, lavaan, emmeans, jsonlite on PATH — needed for the lmm, mediation, and sensitivity steps.

Behavior:

• Missing Python deps -> tell the user which are absent and ask whether to python -m pip install pandas pyyaml (add statsmodels scipy for the manipulation check). Install only after they confirm; prefer a project-local venv.
• Missing R or R packages -> do not attempt to install R. List the exact missing R packages, skip the R-backed steps, record the reason in the audit log, and deliver the Python-only steps that do run.

1. Load the YAML config (config/examples/behavior_2x2x2.yaml as reference).

2. Confirm data.input exists and the id_column / time_column are

   present.

3. python -m src.cli run --config <path> [--step <name>].

4. Report the per-step status; skipped R steps mean R is not installed

   • list the missing packages and stop (do not attempt an install).

5. Point the user at results/tables/*.csv and

   results/logs/analysis_log.jsonl.

When to use

• The user has panel / repeated-measures data (one or more sessions per

  subject, with between-subject conditions) and wants a reproducible

  analysis rather than a one-off calculation.

• The request names a technique: "LMM", "mixed model", "repeated

  measures", "longitudinal analysis", "mediation over time", "lagged

  mediator", or "sensitivity analysis of RE structure".

• Descriptive stats, a manipulation check, or a sensitivity analysis over

  random-effects / covariance structures must be produced with an audit

  trail.

Usage examples

# Validate a config and list the steps it enables.



python -m src.cli validate --config config/examples/behavior_2x2x2.yaml



python -m src.cli list-steps --config config/examples/behavior_2x2x2.yaml







# Run the full pipeline, or a single named step.



python -m src.cli run --config config/examples/behavior_2x2x2.yaml



python -m src.cli run --config config/examples/behavior_2x2x2.yaml --step lmm







# Export the generated tables (csv or docx).



python -m src.cli export --config config/examples/behavior_2x2x2.yaml --format csv

Results land in results/tables/*.csv; the per-step audit trail is

results/logs/analysis_log.jsonl.

Failure handling

• A step reports skipped - R or an R package is missing. List the

  missing packages and stop; do not attempt an install and do not

  substitute a hand-rolled computation.

• Config invalid (validate exits non-zero) - fix the reported field

  (usually data.input, id_column, or time_column) and re-validate.

• A step errors mid-pipeline - earlier steps' outputs are kept and

  audited; report the failing step verbatim and stop, do not re-run

  blindly.

• Unexpected exit code - report the message verbatim.

Pipeline steps

| Type | Module | R dependency |

| --- | --- | --- |

| descriptive | src/steps/descriptive.py | none |

| anova (manipulation check) | src/steps/manipulation.py | none (statsmodels) |

| lmm | src/steps/lmm.py | R/lmm.R (lme4 + emmeans) |

| mediation (lagged) | src/steps/mediation.py | R/mediation.R (lavaan) |

| sensitivity | src/steps/sensitivity.py | R/lmm.R |

Limitations

• R packages (lme4, lavaan, emmeans, jsonlite) must be installed

  locally; the pipeline skips R-backed steps when Rscript is not on

  PATH and logs the reason in the audit.

• The mediation bootstrap is the user's choice (default 5000); wall-clock

  cost scales with sample size.