pacsomatic

O que pacsomatic faz?

Visão Geral

Esta skill fornece um fluxo de trabalho de execução reproduzível para o nf-core/pacsomatic, centrado em um único ponto de entrada helper que lida com validação, geração de artefatos e execução opcional.

Ponto de entrada primário:

• scripts/run_pacsomatic.py

O script helper:

• valida identificadores obrigatórios, arquivos, modo de referência e pré-requisitos de tempo de execução
• escreve uma amostra compatível com pacsomatic (patient,sample,status,bam,pbi)
• gera um YAML de parâmetros e script de lançamento para reexecuções reproduzíveis
• suporta caminhos de execução de simulação (dry-run) e execução real

Use esta skill como o caminho padrão para operações pacsomatic. Não a contorne com comandos nextflow run nf-core/pacsomatic montados manualmente, a menos que o usuário solicite explicitamente a construção manual do comando.

Quando Usar Esta Skill

Invoque esta skill quando o usuário pedir para:

• executar análise tumor-normal pareada a partir de arquivos BAM
• gerar ou corrigir a amostra e artefatos de lançamento do pacsomatic
• executar localmente ou submeter a agendadores (LSF/Slurm/PBS/SGE)
• realizar validação de simulação (dry-run) antes da execução
• solucionar falhas de lançamento ou resumir resultados de execução

Não use esta skill para:

• interpretação biológica profunda além de verificações de sanidade em nível de execução
• edição de internals do pipeline, a menos que solicitado explicitamente

Frases de gatilho típicas:

• "executar nf-core/pacsomatic para este par tumor-normal"
• "preparar amostra e script de lançamento do pacsomatic"
• "fazer uma simulação primeiro e me dizer o que está faltando"
• "submeter pacsomatic para slurm/lsf e retornar o ID do job"
• "por que a submissão do pacsomatic falhou"

Regras de Roteamento e Execução

1. Sempre coletar as entradas de execução necessárias primeiro.
2. Sempre rotear através de scripts/run_pacsomatic.py para validação e geração de artefatos.
3. Padrão para --dry-run quando o usuário pedir apenas verificações/validação.
4. Usar --run somente quando o usuário pedir para executar/submeter.
5. Para modos de agendador, incluir argumentos de recurso específicos do executor e retornar o ID do job detectado quando disponível.
6. Se a execução falhar, relatar o primeiro ponto de falha e o próximo alvo de triagem (.nextflow.log, pipeline_info, logs de tarefas com falha).

Entradas Necessárias

Obrigatórias:

• caminho do BAM tumoral
• caminho do BAM normal
• ID do paciente
• ID da amostra tumoral
• ID da amostra normal
• diretório de saída
• exatamente um modo de referência: --fasta ou --genome

Opcionais:

• perfil, recursos, conta/fila do agendador
• versão do pipeline (-r)
• flags de arquivo de parâmetros, resume/report/dag
• --dry-run e/ou --run

Fluxo de Trabalho

1. Validar identidade e restrições de entrada.
2. Validar caminhos locais obrigatórios (BAM, PBI opcional, FASTA opcional).
3. Resolver verificações de tempo de execução e dependências.
4. Construir amostra e YAML de parâmetros gerados.
5. Gerar script de lançamento para o executor selecionado.
6. Se --dry-run e não --run, parar após a geração de artefatos.
7. Se --run, executar localmente ou submeter ao agendador.
8. Retornar caminho do comando/script, status da validação e ID do job (se detectado).

Contrato de Resposta do Agente

Toda resposta após a invocação deve incluir:

• comando exato usado ou caminho do script gerado
• confirmação de que as verificações de validação foram executadas
• tipo de execução (dry-run vs run)
• ID do job do agendador quando disponível
• um próximo passo concreto para validação/triagem

Início Rápido

Simulação (dry-run):

python scripts/run_pacsomatic.py \
  --tumor-bam /caminho/para/tumor.bam \
  --normal-bam /caminho/para/normal.bam \
  --patient-id P001 \
  --tumor-sample-id P001_T \
  --normal-sample-id P001_N \
  --outdir /caminho/para/saida \
  --genome GRCh38 \
  --profile singularity,sanger \
  --dry-run

Exemplo de execução em agendador (Slurm):

python scripts/run_pacsomatic.py \
  --tumor-bam /caminho/para/tumor.bam \
  --normal-bam /caminho/para/normal.bam \
  --patient-id P001 \
  --tumor-sample-id P001_T \
  --normal-sample-id P001_N \
  --outdir /caminho/para/saida \
  --genome GRCh38 \
  --profile singularity,sanger \
  --executor slurm \
  --queue compute \
  --project my_account \
  --cpus 16 \
  --memory-gb 64 \
  --walltime 48:00 \
  --run

Configuração

Use config.yaml como base para os padrões de perfil/executor/tempo de execução. Substitua no momento da invocação quando os requisitos do usuário diferirem.

Testes

Execute testes unitários a partir da raiz da skill:

python -m unittest discover -s tests/pacsomatic -v

Referências

• references/agent-playbook.md
• references/config-and-output.md
• references/pacsomatic_guide.md
• scripts/run_pacsomatic.py