alterlab-deeptools

Files (10)

• SKILL.md
• quick_reference.md · assets/
• evals.json · evals/
• effective_genome_sizes.md · references/
• normalization_methods.md · references/
• tools_reference.md · references/
• usage_playbook.md · references/
• workflows.md · references/
• validate_files.py · scripts/
• workflow_generator.py · scripts/

SKILL.md (first lines)

# deepTools: NGS Data Analysis Toolkit

## Overview

deepTools is a comprehensive suite of Python command-line tools designed for processing and analyzing high-throughput sequencing data. Use deepTools to perform quality control, normalize data, compare samples, and generate publication-quality visualizations for ChIP-seq, RNA-seq, ATAC-seq, MNase-seq, and other NGS experiments.

**Core capabilities:**
- Convert BAM alignments to normalized coverage tracks (bigWig/bedGraph)
- Quality control assessment (fingerprint, correlation, coverage)
- Sample comparison and correlation analysis
- Heatmap and profile plot generation around genomic features
- Enrichment analysis and peak region visualization

## When to Use This Skill

This skill should be used when:

- **File conversion**: "Convert BAM to bigWig", "generate coverage tracks", "normalize ChIP-seq data"
- **Quality control**: "check ChIP quality", "compare replicates", "assess sequencing depth", "QC analysis"
- **Visualization**: "create heatmap around TSS", "plot ChIP signal", "visualize enrichment", "generate profile plot"
- **Sample comparison**: "compare treatment vs control", "correlate samples", "PCA analysis"
- **Analysis workflows**: "analyze ChIP-seq data", "RNA-seq coverage", "ATAC-seq analysis", "complete workflow"
- **Working with specific file types**: BAM files, bigWig files, BED region files in genomics context

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Per-read access: CIGAR strings, MAPQ, pileups, read filtering in Python | `alterlab-pysam` |
| Interval arithmetic on BED/peak sets (overlaps, Jaccard) or region embeddings | `alterlab-gtars`, `alterlab-geniml` |
| Scanning peaks for transcription-factor motifs | `alterlab-jaspar` |
| Counting reads per gene for differential expression | `alterlab-rnaseq-quant` → `alterlab-pydeseq2` |
| Variant calling from the same BAMs | `alterlab-nf-core-sarek` |

## Quick Start

For users new to deepTools, start with file validation and common workflows:

### 1. Validate Input Files

Before running any analysis, validate BAM, bigWig, and BED files using the validation script:

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

This checks file existence, BAM indices, and format correctness.

### 2. Generate Workflow Template

For standard analyses, use the workflow generator to create customized scripts:

```bash
# List available workflows
python scripts/workflow_generator.py --list

# Generate ChIP-seq QC workflow
python scripts/workflow_generator.py chipseq_qc -o qc_workflow.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398

# Make executable and run
chmod +x qc_workflow.sh
./qc_workflow.sh
```

### 3. Most Common Operations

See `assets/quick_reference.md` for frequently used commands and parameters.

## Installation

```bash
uv pip install deeptools          # 4.0.0 as of 2026-09 (needs Python >= 3.12)
# or: conda install -c bioconda deeptools
```

### What changed in deepTools 4.0

`bamCoverage`, `bamCompare`, `computeMatrix`, `alignmentSieve` and `multiBamSummary` were
rewritten with a Rust core (rayon threading, bigtools bigWig I/O). The old Python
implementations remain for now as `bamCoverage_old`, `bamCompare_old`, `computeMatrix_old`,
`alignmentSieve_old` and `multiBamSummary_old`, and are slated for removal.

Flags that changed, and what to do instead:

| Gone in 4.0 | Replacement |
|-------------|-------------|
| `--ignoreDuplicates` on **bamCoverage / bamCompare** | `--samFlagExclude 1024` (the BAM must have duplicates marked, e.g. by `samtools markdup`). The flag is still valid on `alignmentSieve`, `plotFingerprint`, `plotCoverage`, `multiBamSummary` and `estimateReadFiltering`. |
| `--exactScaling` | removed — the new backend always scales exactly |
| `--plotFileFormat plotly` and the plotly backend | matplotlib output only; `--ggplot` offers a ggplot-like theme |

Also new: gzipped GTF/BED region and blacklist files are accepted by the Rust-backed tools,
and `plotPCA` now uses a scipy/numpy SVD with correct `--transpose`, `--log2`/`--rowCenter`
and `--ntop` handling.

## Core Workflows

deepTools workflows typically follow this pattern: **QC → Normalization → Comparison/Visualization**

### ChIP-seq Quality Control Workflow

When users request ChIP-seq QC or quality assessment:

1. **Generate workflow script** using `scripts/workflow_generator.py chipseq_qc`
2. **Key QC steps**:
   - Sample correlation (multiBamSummary + plotCorrelation)
   - PCA analysis (plotPCA)
   - Coverage assessment (plotCoverage)
   - Fragment size validation (bamPEFragmentSize)
   - ChIP enrichment strength (plotFingerprint)

**Interpreting results:**
- **Correlation**: Replicates should cluster together with high correlation (>0.9)
- **Fingerprint**: Strong ChIP shows steep rise; flat diagonal indicates poor enrichment
- **Coverage**: Assess if sequencing depth is adequate for analysis

Full workflow details in `references/workflows.md` → "ChIP-seq Quality Control Workflow"

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills