deepTools

deepTools: Kit de Análisis de Datos NGS

Descripción General

deepTools es un conjunto completo de herramientas de línea de comandos de Python diseñado para procesar y analizar datos de secuenciación de alto rendimiento. Utilice deepTools para realizar control de calidad, normalizar datos, comparar muestras y generar visualizaciones de calidad de publicación para experimentos de ChIP-seq, RNA-seq, ATAC-seq, MNase-seq y otros experimentos NGS.

Capacidades principales:

• Convertir alineaciones BAM a pistas de cobertura normalizadas (bigWig/bedGraph)
• Evaluación de control de calidad (huella dactilar, correlación, cobertura)
• Comparación de muestras y análisis de correlación
• Generación de mapas de calor y gráficos de perfil alrededor de regiones genómicas
• Análisis de enriquecimiento y visualización de regiones de picos

Cuándo Usar Esta Habilidad

Esta habilidad se debe usar cuando:

• Conversión de archivos: "Convertir BAM a bigWig", "generar pistas de cobertura", "normalizar datos ChIP-seq"
• Control de calidad: "verificar calidad ChIP", "comparar réplicas", "evaluar profundidad de secuenciación", "análisis QC"
• Visualización: "crear mapa de calor alrededor de TSS", "graficar señal ChIP", "visualizar enriquecimiento", "generar gráfico de perfil"
• Comparación de muestras: "comparar tratamiento vs control", "correlacionar muestras", "análisis PCA"
• Flujos de trabajo de análisis: "analizar datos ChIP-seq", "cobertura RNA-seq", "análisis ATAC-seq", "flujo completo"
• Trabajar con tipos de archivos específicos: archivos BAM, archivos bigWig, archivos BED de regiones en contexto genómico

Inicio Rápido

Para usuarios nuevos en deepTools, comience con la validación de archivos y flujos de trabajo comunes:

1. Validar Archivos de Entrada

Antes de ejecutar cualquier análisis, valide los archivos BAM, bigWig y BED usando el script de validación:

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

Esto verifica la existencia de archivos, índices BAM y corrección de formato.

2. Generar Plantilla de Flujo de Trabajo

Para análisis estándar, use el generador de flujos de trabajo para crear scripts personalizados:

# Listar flujos de trabajo disponibles
python scripts/workflow_generator.py --list

# Generar flujo de trabajo 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

# Hacer ejecutable y ejecutar
chmod +x qc_workflow.sh
./qc_workflow.sh

3. Operaciones Más Comunes

Consulte assets/quick_reference.md para comandos y parámetros de uso frecuente.

Instalación

uv pip install deepTools==3.5.6

Upstream recomienda conda/bioconda para resolución completa de dependencias, especialmente en sistemas HPC compartidos:

conda install -c conda-forge -c bioconda deeptools

En Apple Silicon, upstream documenta tanto la ruta PyPI anterior como un entorno conda osx-64 cuando los paquetes nativos de conda no están disponibles.

Flujos de Trabajo Principales y Categorías de Herramientas

Las secuencias de comandos completas para QC de ChIP-seq, análisis completo de ChIP-seq, cobertura de RNA-seq y análisis de ATAC-seq — además del procesamiento de BAM/bigWig, control de calidad y visualización categorías de herramientas — están en references/core_workflows.md y references/workflows.md. Las opciones por herramienta están en references/tools_reference.md.

Métodos de Normalización

Elegir la normalización correcta es crítico para comparaciones válidas. Consulte references/normalization_methods.md para una guía completa.

Guía de selección rápida:

• Cobertura ChIP-seq: Use RPGC o CPM
• Comparación ChIP-seq: Use bamCompare con log2 y readCount
• Bins de RNA-seq: Use CPM
• Genes de RNA-seq: Use RPKM (considera la longitud del gen)
• ATAC-seq: Use RPGC o CPM

Métodos de normalización:

• RPGC: Cobertura 1× del genoma (requiere --effectiveGenomeSize)
• CPM: Cuentas por millón de lecturas mapeadas
• RPKM: Lecturas por kb por millón (escalado por longitud de bin y tamaño de librería)
• BPM: Bins por millón, análogo al escalado TPM sobre señal en bins
• Ninguno: Cuentas brutas (no recomendado para comparaciones)

Explicación completa: references/normalization_methods.md

Tamaños de Genoma Efectivos

La normalización RPGC requiere el tamaño efectivo del genoma. Valores comunes:

Organismo	Ensamblaje	Tamaño	Uso
Humano	GRCh38/hg38	2,913,022,398	--effectiveGenomeSize 2913022398
Humano	T2T/CHM13CAT_v2	3,117,292,070	--effectiveGenomeSize 3117292070
Ratón	GRCm39/mm39	2,654,621,783	--effectiveGenomeSize 2654621783
Ratón	GRCm38/mm10	2,652,783,500	--effectiveGenomeSize 2652783500
Pez cebra	GRCz11	1,368,780,147	--effectiveGenomeSize 1368780147
Drosophila	dm6	142,573,017	--effectiveGenomeSize 142573017
C. elegans	ce10/ce11	100,286,401	--effectiveGenomeSize 100286401

Tabla completa con valores específicos por longitud de lectura: references/effective_genome_sizes.md

Parámetros Comunes Entre Herramientas

Muchos comandos de deepTools comparten estas opciones:

Rendimiento:

• --numberOfProcessors, -p: Habilitar procesamiento en paralelo (use siempre los núcleos disponibles)
• max / max/2: Valores admitidos para --numberOfProcessors; útiles con planificadores porque versiones recientes de deepTools detectan la afinidad de CPU con más cuidado
• --region: Procesar regiones específicas para pruebas (ej., chr1:1-1000000)

Filtrado de Lecturas:

• --ignoreDuplicates: Eliminar duplicados de PCR (recomendado para la mayoría de análisis)
• --minMappingQuality: Filtrar por calidad de alineación (ej., --minMappingQuality 10)
• --minFragmentLength / --maxFragmentLength: Límites de longitud de fragmento
• --samFlagInclude / --samFlagExclude: Filtrado por bandera SAM

Procesamiento de Lecturas:

• --extendReads: Extender a longitud de fragmento (ChIP-seq: SÍ, RNA-seq: NO)
• --centerReads: Centrar en el punto medio del fragmento para señales más nítidas

Mejores Prácticas

Validación de Archivos

Valide siempre los archivos primero usando scripts/validate_files.py para verificar:

• Existencia y legibilidad del archivo
• Índices BAM presentes (archivos .bai)
• Corrección del formato BED
• Tamaños de archivo razonables

Estrategia de Análisis

1. Comience con QC: Ejecute análisis de correlación, cobertura y huella dactilar antes de proceder
2. Pruebe en regiones pequeñas: Use --region chr1:1-10000000 para pruebas de parámetros
3. Documente comandos: Guarde líneas de comando completas para reproducibilidad
4. Use normalización consistente: Aplique el mismo método en todas las muestras en comparaciones
5. Verifique ensamblaje del genoma: Asegúrese de que los archivos BAM y BED usen construcciones de genoma coincidentes

Específico para ChIP-seq

• Extienda siempre las lecturas para ChIP-seq: --extendReads 200
• Elimine duplicados: Use --ignoreDuplicates en la mayoría de los casos
• Verifique enriquecimiento primero: Ejecute plotFingerprint antes del análisis detallado
• Corrección GC: Solo aplicar si se detecta sesgo significativo; nunca use --ignoreDuplicates después de la corrección GC

Específico para RNA-seq

• Nunca extienda lecturas para RNA-seq (cruzarían uniones de splicing)
• Específico de cadena: Use --filterRNAstrand forward/reverse para librerías de cadena comunes de tipo dUTP; confirme la orientación de la librería antes de interpretar las etiquetas de cadena
• Normalización: CPM para bins, RPKM para genes

Específico para ATAC-seq

• Aplique corrección Tn5: Use alignmentSieve con --ATACshift
• Use solo pares correctos para desplazamiento: --ATACshift es equivalente a --shift 4 -5 5 -4 y filtra a fragmentos correctamente emparejados
• Filtrado de fragmentos: Establezca longitudes mín/máx de fragmento apropiadas
• Verifique patrón de nucleosomas: El gráfico de tamaño de fragmento debe mostrar un patrón de escalera

Optimización de Rendimiento

1. Use múltiples procesadores: --numberOfProcessors 8 (o núcleos disponibles)
2. Aumente el tamaño de bin para procesamiento más rápido y archivos más pequeños
3. Procese cromosomas por separado para sistemas con memoria limitada
4. Prefiltre archivos BAM usando alignmentSieve para crear archivos filtrados reutilizables
5. Use bigWig en lugar de bedGraph: Comprimido y más rápido de procesar

Resolución de Problemas

Problemas Comunes

Falta índice BAM:

samtools index input.bam

Memoria insuficiente: Procese cromosomas individualmente usando --region:

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

Procesamiento lento: Aumente --numberOfProcessors y/o aumente --binSize

Archivos bigWig demasiado grandes: Aumente el tamaño de bin: --binSize 50 o más grande

Errores de Validación

Ejecute el script de validación para identificar problemas:

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

Errores comunes y soluciones explicados en la salida del script.

Documentación de Referencia

Esta habilidad incluye documentación de referencia completa:

references/tools_reference.md

Documentación completa de todos los comandos de deepTools organizados por categoría:

• Herramientas de procesamiento de BAM y bigWig (9 herramientas)
• Herramientas de control de calidad (6 herramientas)
• Herramientas de visualización (3 herramientas)
• Herramientas misceláneas (3 herramientas, incluyendo bigwigAverage)

Cada herramienta incluye:

• Propósito y descripción general
• Parámetros clave con explicaciones
• Ejemplos de uso
• Notas importantes y mejores prácticas

Use esta referencia cuando: Los usuarios pregunten sobre herramientas específicas, parámetros o uso detallado.

references/workflows.md

Ejemplos completos de flujos de trabajo para análisis comunes:

• Flujo de trabajo de control de calidad para ChIP-seq
• Flujo de trabajo de análisis completo de ChIP-seq
• Flujo de trabajo de cobertura de RNA-seq
• Flujo de trabajo de análisis de ATAC-seq
• Flujo de trabajo de comparación de múltiples muestras
• Flujo de trabajo de análisis de regiones de picos
• Consejos de resolución de problemas y rendimiento

Use esta referencia cuando: Los usuarios necesiten pipelines de análisis completos o ejemplos de flujos de trabajo.

references/normalization_methods.md

Guía completa de métodos de normalización:

• Explicación detallada de cada método (RPGC, CPM, RPKM, BPM, etc.)
• Cuándo usar cada método
• Fórmulas e interpretación
• Guía de selección por tipo de experimento
• Errores comunes y soluciones
• Tabla de referencia rápida

Use esta referencia cuando: Los usuarios pregunten sobre normalización, comparación de muestras o qué método usar.

references/effective_genome_sizes.md

Valores de tamaño de genoma efectivo y uso:

• Valores de organismos comunes (humano, ratón, mosca, gusano, pez cebra)
• Valores específicos por longitud de lectura
• Métodos de cálculo
• Cuándo y cómo usar en comandos
• Instrucciones de cálculo para genomas personalizados

Use esta referencia cuando: Los usuarios necesiten el tamaño del genoma para normalización RPGC o corrección de sesgo GC.

Scripts Auxiliares

scripts/validate_files.py

Valida archivos BAM, bigWig y BED para análisis con deepTools. Verifica existencia de archivos, índices y formato.

Uso:

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

Cuándo usarlo: Antes de comenzar cualquier análisis, o al solucionar errores.

scripts/workflow_generator.py

Genera plantillas de scripts bash personalizables para flujos de trabajo comunes de deepTools.

Flujos de trabajo disponibles:

• chipseq_qc: Control de calidad para ChIP-seq
• chipseq_analysis: Análisis completo de ChIP-seq
• rnaseq_coverage: Cobertura de RNA-seq específica de cadena
• atacseq: ATAC-seq con corrección Tn5

Uso:

# Listar flujos de trabajo
python scripts/workflow_generator.py --list

# Generar flujo de trabajo
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

# Ejecutar flujo de trabajo generado
chmod +x qc.sh
./qc.sh

Cuándo usarlo: Los usuarios solicitan flujos de trabajo estándar o necesitan scripts de plantilla para personalizar.

Assets

assets/quick_reference.md

Tarjeta de referencia rápida con los comandos más comunes, tamaños de genoma efectivos y patrón de flujo de trabajo típico.

Cuándo usarlo: Los usuarios necesitan ejemplos rápidos de comandos sin documentación detallada.

Manejo de Solicitudes de Usuarios

Para Usuarios Nuevos

1. Comience con verificación de instalación
2. Valide archivos de entrada usando scripts/validate_files.py
3. Recomiende el flujo de trabajo apropiado según el tipo de experimento
4. Genere plantilla de flujo de trabajo usando scripts/workflow_generator.py
5. Guíe la personalización y ejecución

Para Usuarios Experimentados

1. Proporcione comandos de herramientas específicos para las operaciones solicitadas
2. Refiera a las secciones apropiadas en references/tools_reference.md
3. Sugiera optimizaciones y mejores prácticas
4. Ofrezca resolución de problemas para problemas

Para Tareas Específicas

"Convertir BAM a bigWig":

• Use bamCoverage con normalización apropiada
• Recomiende RPGC o CPM según el caso de uso
• Proporcione el tamaño de genoma efectivo para el organismo
• Sugiera parámetros relevantes (extendReads, ignoreDuplicates, binSize)

"Verificar calidad ChIP":

• Ejecute el flujo de trabajo completo de QC o use plotFingerprint específicamente
• Explique la interpretación de resultados
• Sugiera acciones de seguimiento basadas en resultados

"Crear mapa de calor":

• Guíe a través del proceso de dos pasos: computeMatrix → plotHeatmap
• Ayude a elegir el modo de matriz apropiado (reference-point vs scale-regions)
• Sugiera parámetros de visualización y opciones de agrupación

"Comparar muestras":

• Recomiende bamCompare para comparación de dos muestras
• Sugiera multiBamSummary + plotCorrelation para múltiples muestras
• Guíe la selección del método de normalización

Referencia a Documentación

Cuando los usuarios necesiten información detallada:

• Detalles de herramientas: Dirija a secciones específicas en references/tools_reference.md
• Flujos de trabajo: Use references/workflows.md para pipelines de análisis completos
• Normalización: Consulte references/normalization_methods.md para selección de método
• Tamaños de genoma: Refiera a references/effective_genome_sizes.md

Ejemplos de Interacciones

Usuario: "Necesito analizar mis datos ChIP-seq"

Enfoque de respuesta:

1. Pregunte sobre los archivos disponibles (archivos BAM, picos, genes)
2. Valide archivos usando el script de validación
3. Genere plantilla de flujo de trabajo chipseq_analysis
4. Personalice para sus archivos y organismo específicos
5. Explique cada paso mientras se ejecuta el script

Usuario: "¿Qué normalización debo usar?"

Enfoque de respuesta:

1. Pregunte sobre el tipo de experimento (ChIP-seq, RNA-seq, etc.)
2. Pregunte sobre el objetivo de la comparación (dentro de la muestra o entre muestras)
3. Consulte la guía de selección en references/normalization_methods.md
4. Recomiende el método apropiado con justificación
5. Proporcione ejemplo de comando con parámetros

Usuario: "Crear un mapa de calor alrededor de TSS"

Enfoque de respuesta:

1. Verifique archivos bigWig y g...