JiamingShi-JsPhys/agent-skills

Pipeline de análise estatística longitudinal. Use quando o usuário tiver dados de painel / medidas repetidas (uma ou mais sessões por sujeito, com condições entre sujeitos) e desejar executar uma análise reproduzível: estatísticas descritivas, verificação de manipulação, modelo misto linear, mediador defasado ou análise de sensibilidade sobre estruturas de efeitos aleatórios / covariância.

O que é agent-skills?

Esta skill executa um pipeline de análise estatística reproduzível para dados longitudinais ou de painel. É acionada por frases como "LMM", "mixed model", "repeated measures" ou "longitudinal analysis". Quando ativada, carrega uma configuração YAML que lista as etapas habilitadas, executa o pipeline e reporta os resultados por etapa, além dos CSVs gerados. A skill suporta etapas Python (descritivas, verificação de manipulação) e etapas que dependem de R (modelo misto linear, mediação defasada, análise de sensibilidade). Se o R ou pacotes R estiverem ausentes, as etapas correspondentes são ignoradas e registradas no log de auditoria. Os resultados são salvos em `results/tables/*.csv` e o histórico de auditoria em `results/logs/analysis_log.jsonl`. A skill é auto-contida, exigindo Python (pandas, PyYAML) e opcionalmente R com pacotes lme4, lavaan, emmeans e jsonlite.

Funciona com~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/JiamingShi-JsPhys/agent-skills/tree/HEAD/skills/longitudinal-analysis

Documentação

longitudinal-analysis

Uma skill auto-contida que executa uma análise reproduzível de múltiplas etapas em dados longitudinais / de painel. Cada etapa é habilitada e auditada independentemente; o R (lme4 / lavaan) é invocado para o trabalho estatístico pesado e o lado Python orquestra e degrada graciosamente quando o R está ausente.

FLUXO DE TRABALHO OBRIGATÓRIO

Bootstrap de dependências (executar no primeiro uso)

Antes da primeira execução, verifique as dependências de tempo de execução desta skill:

Obrigatório (Python): pandas, PyYAML.
Opcional (Python): statsmodels, scipy (etapa de verificação de manipulação).
Obrigatório (externo): R >= 4.0 com lme4, lavaan, emmeans, jsonlite no PATH — necessário para as etapas lmm, mediation e sensitivity.

Comportamento:

Dependências Python ausentes -> informar ao usuário quais estão faltando e perguntar se deseja executar python -m pip install pandas pyyaml (adicionar statsmodels scipy para a verificação de manipulação). Instalar somente após confirmação; preferir um venv local ao projeto.
R ou pacotes R ausentes -> não tentar instalar o R. Listar os pacotes R exatos que estão faltando, pular as etapas que dependem de R, registrar o motivo no log de auditoria e entregar as etapas somente Python que forem executadas.

Carregar a configuração YAML (config/examples/behavior_2x2x2.yaml como referência).
Confirmar que data.input existe e que id_column / time_column estão presentes.
Executar python -m src.cli run --config <caminho> [--step <nome>].
Reportar o status de cada etapa; etapas puladas significam que o R não está instalado — listar os pacotes faltantes e parar (não tentar instalar).
Apontar o usuário para results/tables/*.csv e results/logs/analysis_log.jsonl.

Quando usar

O usuário tem dados de painel / medidas repetidas (uma ou mais sessões por sujeito, com condições entre sujeitos) e deseja uma análise reproduzível, em vez de um cálculo único.
A solicitação nomeia uma técnica: "LMM", "mixed model", "repeated measures", "longitudinal analysis", "mediation over time", "lagged mediator" ou "sensitivity analysis of RE structure".
Estatísticas descritivas, verificação de manipulação ou análise de sensibilidade sobre estruturas de efeitos aleatórios / covariância devem ser produzidas com um rastro de auditoria.

Exemplos de uso

# Validar uma configuração e listar as etapas que ela habilita.
python -m src.cli validate --config config/examples/behavior_2x2x2.yaml
python -m src.cli list-steps --config config/examples/behavior_2x2x2.yaml

# Executar o pipeline completo ou uma única etapa nomeada.
python -m src.cli run --config config/examples/behavior_2x2x2.yaml
python -m src.cli run --config config/examples/behavior_2x2x2.yaml --step lmm

# Exportar as tabelas geradas (csv ou docx).
python -m src.cli export --config config/examples/behavior_2x2x2.yaml --format csv

Os resultados vão para results/tables/*.csv; o rastro de auditoria por etapa é results/logs/analysis_log.jsonl.

Tratamento de falhas

Uma etapa reporta skipped - R ou um pacote R está faltando. Listar os pacotes faltantes e parar; não tentar instalar e não substituir por um cálculo manual.
Configuração inválida (validate sai com código diferente de zero) - corrigir o campo reportado (geralmente data.input, id_column ou time_column) e re-validar.
Uma etapa falha no meio do pipeline - as saídas das etapas anteriores são mantidas e auditadas; reportar a etapa com falha literalmente e parar, não executar novamente cegamente.
Código de saída inesperado - reportar a mensagem literalmente.

Etapas do pipeline

Tipo	Módulo	Dependência R
`descriptive`	`src/steps/descriptive.py`	nenhuma
`anova` (verificação de manipulação)	`src/steps/manipulation.py`	nenhuma (statsmodels)
`lmm`	`src/steps/lmm.py`	`R/lmm.R` (lme4 + emmeans)
`mediation` (defasado)	`src/steps/mediation.py`	`R/mediation.R` (lavaan)
`sensitivity`	`src/steps/sensitivity.py`	`R/lmm.R`

Limitações

Os pacotes R (lme4, lavaan, emmeans, jsonlite) devem estar instalados localmente; o pipeline pula as etapas que dependem de R quando Rscript não está no PATH e registra o motivo na auditoria.
A inicialização da mediação é escolha do usuário (padrão 5000); o custo de tempo de execução escala com o tamanho da amostra.