deepTools

deepTools: Conjunto de Ferramentas para Análise de Dados NGS

Visão Geral

deepTools é um conjunto abrangente de ferramentas de linha de comando em Python projetadas para processar e analisar dados de sequenciamento de alto rendimento. Use deepTools para realizar controle de qualidade, normalizar dados, comparar amostras e gerar visualizações prontas para publicação para experimentos de ChIP-seq, RNA-seq, ATAC-seq, MNase-seq e outros experimentos de NGS.

Capacidades principais:

• Converter alinhamentos BAM em trilhas de cobertura normalizadas (bigWig/bedGraph)
• Avaliação de controle de qualidade (impressão digital, correlação, cobertura)
• Comparação de amostras e análise de correlação
• Geração de mapas de calor e gráficos de perfil ao redor de características genômicas
• Análise de enriquecimento e visualização de regiões de pico

Quando Usar Esta Habilidade

Esta habilidade deve ser usada quando:

• Conversão de arquivos: "Converter BAM para bigWig", "gerar trilhas de cobertura", "normalizar dados de ChIP-seq"
• Controle de qualidade: "verificar qualidade de ChIP", "comparar réplicas", "avaliar profundidade de sequenciamento", "análise de QC"
• Visualização: "criar mapa de calor ao redor do TSS", "plotar sinal de ChIP", "visualizar enriquecimento", "gerar gráfico de perfil"
• Comparação de amostras: "comparar tratamento vs controle", "correlacionar amostras", "análise de PCA"
• Fluxos de trabalho de análise: "analisar dados de ChIP-seq", "cobertura de RNA-seq", "análise de ATAC-seq", "fluxo de trabalho completo"
• Trabalhando com tipos específicos de arquivos: arquivos BAM, arquivos bigWig, arquivos BED de regiões em contexto genômico

Início Rápido

Para usuários novos no deepTools, comece com a validação de arquivos e fluxos de trabalho comuns:

1. Validar Arquivos de Entrada

Antes de executar qualquer análise, valide arquivos BAM, bigWig e BED usando o script de validação:

python scripts/validate_files.py --bam sample1.bam sample2.bam --bed regions.bed

Isso verifica a existência dos arquivos, índices BAM e correção do formato.

2. Gerar Modelo de Fluxo de Trabalho

Para análises padrão, use o gerador de fluxo de trabalho para criar scripts personalizados:

# Listar fluxos de trabalho disponíveis
python scripts/workflow_generator.py --list

# Gerar fluxo de trabalho de QC para ChIP-seq
python scripts/workflow_generator.py chipseq_qc -o qc_workflow.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398

# Tornar executável e executar
chmod +x qc_workflow.sh
./qc_workflow.sh

3. Operações Mais Comuns

Veja assets/quick_reference.md para comandos e parâmetros usados com frequência.

Instalação

uv pip install deepTools==3.5.6

A fonte oficial recomenda conda/bioconda para resolução completa de dependências, especialmente em sistemas HPC compartilhados:

conda install -c conda-forge -c bioconda deeptools

No Apple Silicon, a documentação oficial indica a rota PyPI acima ou um ambiente conda osx-64 quando pacotes conda nativos não estão disponíveis.

Fluxos de Trabalho Principais e Categorias de Ferramentas

Sequências de comandos completas para QC de ChIP-seq, análise completa de ChIP-seq, cobertura de RNA-seq e análise de ATAC-seq — além das categorias de ferramentas de processamento BAM/bigWig, controle de qualidade e visualização — estão em references/core_workflows.md e references/workflows.md. Opções por ferramenta estão em references/tools_reference.md.

Métodos de Normalização

Escolher a normalização correta é crítico para comparações válidas. Consulte references/normalization_methods.md para orientação abrangente.

Guia de seleção rápida:

• Cobertura ChIP-seq: Use RPGC ou CPM
• Comparação ChIP-seq: Use bamCompare com log2 e readCount
• Bins RNA-seq: Use CPM
• Genes RNA-seq: Use RPKM (considera comprimento do gene)
• ATAC-seq: Use RPGC ou CPM

Métodos de normalização:

• RPGC: Cobertura de 1× genoma (requer --effectiveGenomeSize)
• CPM: Contagens por milhão de reads mapeados
• RPKM: Reads por kb por milhão (escalonamento de comprimento por bin e tamanho da biblioteca)
• BPM: Bins por milhão, análogo ao escalonamento estilo TPM sobre sinal binned
• Nenhum: Contagens brutas (não recomendado para comparações)

Explicação completa: references/normalization_methods.md

Tamanhos Efetivos de Genoma

A normalização RPGC requer o tamanho efetivo do genoma. Valores comuns:

Organismo	Montagem	Tamanho	Uso
Humano	GRCh38/hg38	2.913.022.398	--effectiveGenomeSize 2913022398
Humano	T2T/CHM13CAT_v2	3.117.292.070	--effectiveGenomeSize 3117292070
Camundongo	GRCm39/mm39	2.654.621.783	--effectiveGenomeSize 2654621783
Camundongo	GRCm38/mm10	2.652.783.500	--effectiveGenomeSize 2652783500
Peixe-zebra	GRCz11	1.368.780.147	--effectiveGenomeSize 1368780147
Drosophila	dm6	142.573.017	--effectiveGenomeSize 142573017
C. elegans	ce10/ce11	100.286.401	--effectiveGenomeSize 100286401

Tabela completa com valores específicos para comprimento de leitura: references/effective_genome_sizes.md

Parâmetros Comuns Entre Ferramentas

Muitos comandos do deepTools compartilham estas opções:

Desempenho:

• --numberOfProcessors, -p: Ativar processamento paralelo (sempre use núcleos disponíveis)
• max / max/2: Valores suportados para --numberOfProcessors; útil em agendadores porque versões recentes do deepTools detectam afinidade de CPU com mais cuidado
• --region: Processar regiões específicas para teste (ex.: chr1:1-1000000)

Filtragem de Reads:

• --ignoreDuplicates: Remover duplicatas de PCR (recomendado para a maioria das análises)
• --minMappingQuality: Filtrar por qualidade de alinhamento (ex.: --minMappingQuality 10)
• --minFragmentLength / --maxFragmentLength: Limites de comprimento de fragmento
• --samFlagInclude / --samFlagExclude: Filtragem por flag SAM

Processamento de Reads:

• --extendReads: Estender até o comprimento do fragmento (ChIP-seq: SIM, RNA-seq: NÃO)
• --centerReads: Centralizar no ponto médio do fragmento para sinais mais nítidos

Melhores Práticas

Validação de Arquivos

Sempre valide os arquivos primeiro usando scripts/validate_files.py para verificar:

• Existência e legibilidade dos arquivos
• Índices BAM presentes (arquivos .bai)
• Correção do formato BED
• Tamanhos de arquivo razoáveis

Estratégia de Análise

1. Comece com QC: Execute análise de correlação, cobertura e impressão digital antes de prosseguir
2. Teste em pequenas regiões: Use --region chr1:1-10000000 para teste de parâmetros
3. Documente comandos: Salve linhas de comando completas para reprodutibilidade
4. Use normalização consistente: Aplique o mesmo método entre amostras em comparações
5. Verifique a montagem do genoma: Garanta que arquivos BAM e BED usem montagens de genoma correspondentes

Específico para ChIP-seq

• Sempre estenda reads para ChIP-seq: --extendReads 200
• Remova duplicatas: Use --ignoreDuplicates na maioria dos casos
• Verifique enriquecimento primeiro: Execute plotFingerprint antes da análise detalhada
• Correção de GC: Aplique apenas se viés significativo for detectado; nunca use --ignoreDuplicates após correção de GC

Específico para RNA-seq

• Nunca estenda reads para RNA-seq (abrangeria junções de splicing)
• Strand-specific: Use --filterRNAstrand forward/reverse para bibliotecas stranded comuns do tipo dUTP; confirme a orientação da biblioteca antes de interpretar rótulos de fita
• Normalização: CPM para bins, RPKM para genes

Específico para ATAC-seq

• Aplique correção Tn5: Use alignmentSieve com --ATACshift
• Use apenas pares próprios para deslocamento: --ATACshift é equivalente a --shift 4 -5 5 -4 e filtra para fragmentos pareados propriamente
• Filtragem de fragmentos: Defina comprimentos mínimo/máximo de fragmento apropriados
• Verifique padrão de nucleossomo: O gráfico de tamanho de fragmento deve mostrar um padrão de escada

Otimização de Desempenho

1. Use múltiplos processadores: --numberOfProcessors 8 (ou núcleos disponíveis)
2. Aumente o tamanho do bin para processamento mais rápido e arquivos menores
3. Processe cromossomos separadamente para sistemas com memória limitada
4. Pré-filtre arquivos BAM usando alignmentSieve para criar arquivos filtrados reutilizáveis
5. Use bigWig em vez de bedGraph: Comprimido e mais rápido de processar

Solução de Problemas

Problemas Comuns

Índice BAM ausente:

samtools index input.bam

Memória insuficiente: Processe cromossomos individualmente usando --region:

bamCoverage --bam input.bam -o chr1.bw --region chr1

Processamento lento: Aumente --numberOfProcessors e/ou aumente --binSize

Arquivos bigWig muito grandes: Aumente o tamanho do bin: --binSize 50 ou maior

Erros de Validação

Execute o script de validação para identificar problemas:

python scripts/validate_files.py --bam *.bam --bed regions.bed

Erros comuns e soluções explicados na saída do script.

Documentação de Referência

Esta habilidade inclui documentação de referência abrangente:

references/tools_reference.md

Documentação completa de todos os comandos deepTools organizados por categoria:

• Ferramentas de processamento BAM e bigWig (9 ferramentas)
• Ferramentas de controle de qualidade (6 ferramentas)
• Ferramentas de visualização (3 ferramentas)
• Ferramentas diversas (3 ferramentas, incluindo bigwigAverage)

Cada ferramenta inclui:

• Propósito e visão geral
• Parâmetros principais com explicações
• Exemplos de uso
• Notas importantes e melhores práticas

Use esta referência quando: Usuários perguntarem sobre ferramentas específicas, parâmetros ou uso detalhado.

references/workflows.md

Exemplos completos de fluxo de trabalho para análises comuns:

• Fluxo de trabalho de controle de qualidade para ChIP-seq
• Fluxo de trabalho de análise completa de ChIP-seq
• Fluxo de trabalho de cobertura de RNA-seq
• Fluxo de trabalho de análise de ATAC-seq
• Fluxo de trabalho de comparação multi-amostra
• Fluxo de trabalho de análise de região de pico
• Dicas de solução de problemas e desempenho

Use esta referência quando: Usuários precisarem de pipelines de análise completos ou exemplos de fluxo de trabalho.

references/normalization_methods.md

Guia abrangente sobre métodos de normalização:

• Explicação detalhada de cada método (RPGC, CPM, RPKM, BPM, etc.)
• Quando usar cada método
• Fórmulas e interpretação
• Guia de seleção por tipo de experimento
• Armadilhas comuns e soluções
• Tabela de referência rápida

Use esta referência quando: Usuários perguntarem sobre normalização, comparação de amostras ou qual método usar.

references/effective_genome_sizes.md

Valores de tamanho efetivo de genoma e uso:

• Valores comuns de organismos (humano, camundongo, mosca, verme, peixe-zebra)
• Valores específicos para comprimento de leitura
• Métodos de cálculo
• Quando e como usar em comandos
• Instruções de cálculo para genomas personalizados

Use esta referência quando: Usuários precisarem do tamanho do genoma para normalização RPGC ou correção de viés GC.

Scripts Auxiliares

scripts/validate_files.py

Valida arquivos BAM, bigWig e BED para análise deepTools. Verifica existência, índices e formato.

Uso:

python scripts/validate_files.py --bam sample1.bam sample2.bam \
    --bed peaks.bed --bigwig signal.bw

Quando usar: Antes de iniciar qualquer análise, ou ao solucionar erros.

scripts/workflow_generator.py

Gera modelos de script bash personalizáveis para fluxos de trabalho comuns do deepTools.

Fluxos de trabalho disponíveis:

• chipseq_qc: Controle de qualidade para ChIP-seq
• chipseq_analysis: Análise completa de ChIP-seq
• rnaseq_coverage: Cobertura de RNA-seq específica de fita
• atacseq: ATAC-seq com correção Tn5

Uso:

# Listar fluxos de trabalho
python scripts/workflow_generator.py --list

# Gerar fluxo de trabalho
python scripts/workflow_generator.py chipseq_qc -o qc.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398 --threads 8

# Executar fluxo de trabalho gerado
chmod +x qc.sh
./qc.sh

Quando usar: Usuários solicitarem fluxos de trabalho padrão ou precisarem de scripts modelo para personalizar.

Ativos

assets/quick_reference.md

Cartão de referência rápida com os comandos mais comuns, tamanhos efetivos de genoma e padrão típico de fluxo de trabalho.

Quando usar: Usuários precisarem de exemplos de comando rápidos sem documentação detalhada.

Lidando com Solicitações de Usuários

Para Novos Usuários

1. Comece com verificação de instalação
2. Valide arquivos de entrada usando scripts/validate_files.py
3. Recomende o fluxo de trabalho apropriado com base no tipo de experimento
4. Gere modelo de fluxo de trabalho usando scripts/workflow_generator.py
5. Guie na personalização e execução

Para Usuários Experientes

1. Forneça comandos de ferramentas específicos para as operações solicitadas
2. Consulte seções apropriadas em references/tools_reference.md
3. Sugira otimizações e melhores práticas
4. Ofereça solução de problemas para problemas

Para Tarefas Específicas

"Converter BAM para bigWig":

• Use bamCoverage com normalização apropriada
• Recomende RPGC ou CPM com base no caso de uso
• Forneça tamanho efetivo do genoma para o organismo
• Sugira parâmetros relevantes (extendReads, ignoreDuplicates, binSize)

"Verificar qualidade de ChIP":

• Execute fluxo de trabalho completo de QC ou use plotFingerprint especificamente
• Explique interpretação dos resultados
• Sugira ações de acompanhamento com base nos resultados

"Criar mapa de calor":

• Guie pelo processo de duas etapas: computeMatrix → plotHeatmap
• Ajude a escolher o modo de matriz apropriado (reference-point vs scale-regions)
• Sugira parâmetros de visualização e opções de agrupamento

"Comparar amostras":

• Recomende bamCompare para comparação de duas amostras
• Sugira multiBamSummary + plotCorrelation para múltiplas amostras
• Guie a seleção do método de normalização

Referenciando Documentação

Quando usuários precisarem de informações detalhadas:

• Detalhes da ferramenta: Direcione para seções específicas em references/tools_reference.md
• Fluxos de trabalho: Use references/workflows.md para pipelines de análise completos
• Normalização: Consulte references/normalization_methods.md para seleção de método
• Tamanhos de genoma: Consulte references/effective_genome_sizes.md

Exemplos de Interação

Usuário: "Preciso analisar meus dados de ChIP-seq"

Abordagem de resposta:

1. Pergunte sobre arquivos disponíveis (arquivos BAM, picos, genes)
2. Valide arquivos usando script de validação
3. Gere modelo de fluxo de trabalho chipseq_analysis
4. Personalize para seus arquivos e organismo específicos
5. Explique cada etapa à medida que o script executa

Usuário: "Qual normalização devo usar?"

Abordagem de resposta:

1. Pergunte sobre tipo de experimento (ChIP-seq, RNA-seq, etc.)
2. Pergunte sobre objetivo da comparação (dentro da amostra ou entre amostras)
3. Consulte o guia de seleção em references/normalization_methods.md
4. Recomende o método apropriado com justificativa
5. Forneça exemplo de comando com parâmetros

Usuário: "Crie um mapa de calor ao redor do TSS"

Abordagem de resposta:

1. Verifique quais arquivos bigWig e BED (ou GTF) o usuário possui