@synsci/cli-darwin-x64-baseline 1.1.76 → 1.1.78

package/bin/skills/deeptools/references/tools_reference.md

@@ -0,0 +1,533 @@
+# deepTools Complete Tool Reference
+
+This document provides a comprehensive reference for all deepTools command-line utilities organized by category.
+
+## BAM and bigWig File Processing Tools
+
+### multiBamSummary
+
+Computes read coverages for genomic regions across multiple BAM files, outputting compressed numpy arrays for downstream correlation and PCA analysis.
+
+**Modes:**
+- **bins**: Genome-wide analysis using consecutive equal-sized windows (default 10kb)
+- **BED-file**: Restricts analysis to user-specified genomic regions
+
+**Key Parameters:**
+- `--bamfiles, -b`: Indexed BAM files (space-separated, required)
+- `--outFileName, -o`: Output coverage matrix file (required)
+- `--BED`: Region specification file (BED-file mode only)
+- `--binSize`: Window size in bases (default: 10,000)
+- `--labels`: Custom sample identifiers
+- `--minMappingQuality`: Quality threshold for read inclusion
+- `--numberOfProcessors, -p`: Parallel processing cores
+- `--extendReads`: Fragment size extension
+- `--ignoreDuplicates`: Remove PCR duplicates
+- `--outRawCounts`: Export tab-delimited file with coordinate columns and per-sample counts
+
+**Output:** Compressed numpy array (.npz) for plotCorrelation and plotPCA
+
+**Common Usage:**
+```bash
+# Genome-wide comparison
+multiBamSummary bins --bamfiles sample1.bam sample2.bam -o results.npz
+
+# Peak region comparison
+multiBamSummary BED-file --BED peaks.bed --bamfiles sample1.bam sample2.bam -o results.npz
+```
+
+---
+
+### multiBigwigSummary
+
+Similar to multiBamSummary but operates on bigWig files instead of BAM files. Used for comparing coverage tracks across samples.
+
+**Modes:**
+- **bins**: Genome-wide analysis
+- **BED-file**: Region-specific analysis
+
+**Key Parameters:** Similar to multiBamSummary but accepts bigWig files
+
+---
+
+### bamCoverage
+
+Converts BAM alignment files into normalized coverage tracks in bigWig or bedGraph formats. Calculates coverage as number of reads per bin.
+
+**Key Parameters:**
+- `--bam, -b`: Input BAM file (required)
+- `--outFileName, -o`: Output filename (required)
+- `--outFileFormat, -of`: Output type (bigwig or bedgraph)
+- `--normalizeUsing`: Normalization method
+  - **RPKM**: Reads Per Kilobase per Million mapped reads
+  - **CPM**: Counts Per Million mapped reads
+  - **BPM**: Bins Per Million mapped reads
+  - **RPGC**: Reads per genomic content (requires --effectiveGenomeSize)
+  - **None**: No normalization (default)
+- `--effectiveGenomeSize`: Mappable genome size (required for RPGC)
+- `--binSize`: Resolution in base pairs (default: 50)
+- `--extendReads, -e`: Extend reads to fragment length (recommended for ChIP-seq, NOT for RNA-seq)
+- `--centerReads`: Center reads at fragment length for sharper signals
+- `--ignoreDuplicates`: Count identical reads only once
+- `--minMappingQuality`: Filter reads below quality threshold
+- `--minFragmentLength / --maxFragmentLength`: Fragment length filtering
+- `--smoothLength`: Window averaging for noise reduction
+- `--MNase`: Analyze MNase-seq data for nucleosome positioning
+- `--Offset`: Position-specific offsets (useful for RiboSeq, GROseq)
+- `--filterRNAstrand`: Separate forward/reverse strand reads
+- `--ignoreForNormalization`: Exclude chromosomes from normalization (e.g., sex chromosomes)
+- `--numberOfProcessors, -p`: Parallel processing
+
+**Important Notes:**
+- For RNA-seq: Do NOT use --extendReads (would extend over splice junctions)
+- For ChIP-seq: Use --extendReads with smaller bin sizes
+- Never apply --ignoreDuplicates after GC bias correction
+
+**Common Usage:**
+```bash
+# Basic coverage with RPKM normalization
+bamCoverage --bam input.bam --outFileName coverage.bw --normalizeUsing RPKM
+
+# ChIP-seq with extension
+bamCoverage --bam chip.bam --outFileName chip_coverage.bw \
+    --binSize 10 --extendReads 200 --ignoreDuplicates
+
+# Strand-specific RNA-seq
+bamCoverage --bam rnaseq.bam --outFileName forward.bw \
+    --filterRNAstrand forward
+```
+
+---
+
+### bamCompare
+
+Compares two BAM files by generating bigWig or bedGraph files, normalizing for sequencing depth differences. Processes genome in equal-sized bins and performs per-bin calculations.
+
+**Comparison Methods:**
+- **log2** (default): Log2 ratio of samples
+- **ratio**: Direct ratio calculation
+- **subtract**: Difference between files
+- **add**: Sum of samples
+- **mean**: Average across samples
+- **reciprocal_ratio**: Negative inverse for ratios < 0
+- **first/second**: Output scaled signal from single file
+
+**Normalization Methods:**
+- **readCount** (default): Compensates for sequencing depth
+- **SES**: Selective enrichment statistics
+- **RPKM**: Reads per kilobase per million
+- **CPM**: Counts per million
+- **BPM**: Bins per million
+- **RPGC**: Reads per genomic content (requires --effectiveGenomeSize)
+
+**Key Parameters:**
+- `--bamfile1, -b1`: First BAM file (required)
+- `--bamfile2, -b2`: Second BAM file (required)
+- `--outFileName, -o`: Output filename (required)
+- `--outFileFormat`: bigwig or bedgraph
+- `--operation`: Comparison method (see above)
+- `--scaleFactorsMethod`: Normalization method (see above)
+- `--binSize`: Bin width for output (default: 50bp)
+- `--pseudocount`: Avoid division by zero (default: 1)
+- `--extendReads`: Extend reads to fragment length
+- `--ignoreDuplicates`: Count identical reads once
+- `--minMappingQuality`: Quality threshold
+- `--numberOfProcessors, -p`: Parallelization
+
+**Common Usage:**
+```bash
+# Log2 ratio of treatment vs control
+bamCompare -b1 treatment.bam -b2 control.bam -o log2ratio.bw
+
+# Subtract control from treatment
+bamCompare -b1 treatment.bam -b2 control.bam -o difference.bw \
+    --operation subtract --scaleFactorsMethod readCount
+```
+
+---
+
+### correctGCBias / computeGCBias
+
+**computeGCBias:** Identifies GC-content bias from sequencing and PCR amplification.
+
+**correctGCBias:** Corrects BAM files for GC bias detected by computeGCBias.
+
+**Key Parameters (computeGCBias):**
+- `--bamfile, -b`: Input BAM file
+- `--effectiveGenomeSize`: Mappable genome size
+- `--genome, -g`: Reference genome in 2bit format
+- `--fragmentLength, -l`: Fragment length (for single-end)
+- `--biasPlot`: Output diagnostic plot
+
+**Key Parameters (correctGCBias):**
+- `--bamfile, -b`: Input BAM file
+- `--effectiveGenomeSize`: Mappable genome size
+- `--genome, -g`: Reference genome in 2bit format
+- `--GCbiasFrequenciesFile`: Frequencies from computeGCBias
+- `--correctedFile, -o`: Output corrected BAM
+
+**Important:** Never use --ignoreDuplicates after GC bias correction
+
+---
+
+### alignmentSieve
+
+Filters BAM files by various quality metrics on-the-fly. Useful for creating filtered BAM files for specific analyses.
+
+**Key Parameters:**
+- `--bam, -b`: Input BAM file
+- `--outFile, -o`: Output BAM file
+- `--minMappingQuality`: Minimum mapping quality
+- `--ignoreDuplicates`: Remove duplicates
+- `--minFragmentLength / --maxFragmentLength`: Fragment length filters
+- `--samFlagInclude / --samFlagExclude`: SAM flag filtering
+- `--shift`: Shift reads (e.g., for ATACseq Tn5 correction)
+- `--ATACshift`: Automatically shift for ATAC-seq data
+
+---
+
+### computeMatrix
+
+Calculates scores per genomic region and prepares matrices for plotHeatmap and plotProfile. Processes bigWig score files and BED/GTF region files.
+
+**Modes:**
+- **reference-point**: Signal distribution relative to specific position (TSS, TES, or center)
+- **scale-regions**: Signal across regions standardized to uniform lengths
+
+**Key Parameters:**
+- `-R`: Region file(s) in BED/GTF format (required)
+- `-S`: BigWig score file(s) (required)
+- `-o`: Output matrix file (required)
+- `-b`: Upstream distance from reference point
+- `-a`: Downstream distance from reference point
+- `-m`: Region body length (scale-regions only)
+- `-bs, --binSize`: Bin size for averaging scores
+- `--skipZeros`: Skip regions with all zeros
+- `--minThreshold / --maxThreshold`: Filter by signal intensity
+- `--sortRegions`: ascending, descending, keep, no
+- `--sortUsing`: mean, median, max, min, sum, region_length
+- `-p, --numberOfProcessors`: Parallel processing
+- `--averageTypeBins`: Statistical method (mean, median, min, max, sum, std)
+
+**Output Options:**
+- `--outFileNameMatrix`: Export tab-delimited data
+- `--outFileSortedRegions`: Save filtered/sorted BED file
+
+**Common Usage:**
+```bash
+# TSS analysis
+computeMatrix reference-point -S signal.bw -R genes.bed \
+    -o matrix.gz -b 2000 -a 2000 --referencePoint TSS
+
+# Scaled gene body
+computeMatrix scale-regions -S signal.bw -R genes.bed \
+    -o matrix.gz -b 1000 -a 1000 -m 3000
+```
+
+---
+
+## Quality Control Tools
+
+### plotFingerprint
+
+Quality control tool primarily for ChIP-seq experiments. Assesses whether antibody enrichment was successful. Generates cumulative read coverage profiles to distinguish signal from noise.
+
+**Key Parameters:**
+- `--bamfiles, -b`: Indexed BAM files (required)
+- `--plotFile, -plot, -o`: Output image filename (required)
+- `--extendReads, -e`: Extend reads to fragment length
+- `--ignoreDuplicates`: Count identical reads once
+- `--minMappingQuality`: Mapping quality filter
+- `--centerReads`: Center reads at fragment length
+- `--minFragmentLength / --maxFragmentLength`: Fragment filters
+- `--outRawCounts`: Save per-bin read counts
+- `--outQualityMetrics`: Output QC metrics (Jensen-Shannon distance)
+- `--labels`: Custom sample names
+- `--numberOfProcessors, -p`: Parallel processing
+
+**Interpretation:**
+- Ideal control: Straight diagonal line
+- Strong ChIP: Steep rise towards highest rank (concentrated reads in few bins)
+- Weak enrichment: Flatter curve approaching diagonal
+
+**Common Usage:**
+```bash
+plotFingerprint -b input.bam chip1.bam chip2.bam \
+    --labels Input ChIP1 ChIP2 -o fingerprint.png \
+    --extendReads 200 --ignoreDuplicates
+```
+
+---
+
+### plotCoverage
+
+Visualizes average read distribution across the genome. Shows genome coverage and helps determine if sequencing depth is adequate.
+
+**Key Parameters:**
+- `--bamfiles, -b`: BAM files to analyze (required)
+- `--plotFile, -o`: Output plot filename (required)
+- `--ignoreDuplicates`: Remove PCR duplicates
+- `--minMappingQuality`: Quality threshold
+- `--outRawCounts`: Save underlying data
+- `--labels`: Sample names
+- `--numberOfSamples`: Number of positions to sample (default: 1,000,000)
+
+---
+
+### bamPEFragmentSize
+
+Determines fragment length distribution for paired-end sequencing data. Essential QC to verify expected fragment sizes from library preparation.
+
+**Key Parameters:**
+- `--bamfiles, -b`: BAM files (required)
+- `--histogram, -hist`: Output histogram filename (required)
+- `--plotTitle, -T`: Plot title
+- `--maxFragmentLength`: Maximum length to consider (default: 1000)
+- `--logScale`: Use logarithmic Y-axis
+- `--outRawFragmentLengths`: Save raw fragment lengths
+
+---
+
+### plotCorrelation
+
+Analyzes sample correlations from multiBamSummary or multiBigwigSummary outputs. Shows how similar different samples are.
+
+**Correlation Methods:**
+- **Pearson**: Measures metric differences; sensitive to outliers; appropriate for normally distributed data
+- **Spearman**: Rank-based; less influenced by outliers; better for non-normal distributions
+
+**Visualization Options:**
+- **heatmap**: Color intensity with hierarchical clustering (complete linkage)
+- **scatterplot**: Pairwise scatter plots with correlation coefficients
+
+**Key Parameters:**
+- `--corData, -in`: Input matrix from multiBamSummary/multiBigwigSummary (required)
+- `--corMethod`: pearson or spearman (required)
+- `--whatToShow`: heatmap or scatterplot (required)
+- `--plotFile, -o`: Output filename (required)
+- `--skipZeros`: Exclude zero-value regions
+- `--removeOutliers`: Use median absolute deviation (MAD) filtering
+- `--outFileCorMatrix`: Export correlation matrix
+- `--labels`: Custom sample names
+- `--plotTitle`: Plot title
+- `--colorMap`: Color scheme (50+ options)
+- `--plotNumbers`: Display correlation values on heatmap
+
+**Common Usage:**
+```bash
+# Heatmap with Pearson correlation
+plotCorrelation -in readCounts.npz --corMethod pearson \
+    --whatToShow heatmap -o correlation_heatmap.png --plotNumbers
+
+# Scatterplot with Spearman correlation
+plotCorrelation -in readCounts.npz --corMethod spearman \
+    --whatToShow scatterplot -o correlation_scatter.png
+```
+
+---
+
+### plotPCA
+
+Generates principal component analysis plots from multiBamSummary or multiBigwigSummary output. Displays sample relationships in reduced dimensionality.
+
+**Key Parameters:**
+- `--corData, -in`: Coverage file from multiBamSummary/multiBigwigSummary (required)
+- `--plotFile, -o`: Output image (png, eps, pdf, svg) (required)
+- `--outFileNameData`: Export PCA data (loadings/rotation and eigenvalues)
+- `--labels, -l`: Custom sample labels
+- `--plotTitle, -T`: Plot title
+- `--plotHeight / --plotWidth`: Dimensions in centimeters
+- `--colors`: Custom symbol colors
+- `--markers`: Symbol shapes
+- `--transpose`: Perform PCA on transposed matrix (rows=samples)
+- `--ntop`: Use top N variable rows (default: 1000)
+- `--PCs`: Components to plot (default: 1 2)
+- `--log2`: Log2-transform data before analysis
+- `--rowCenter`: Center each row at 0
+
+**Common Usage:**
+```bash
+plotPCA -in readCounts.npz -o PCA_plot.png \
+    -T "PCA of read counts" --transpose
+```
+
+---
+
+## Visualization Tools
+
+### plotHeatmap
+
+Creates genomic region heatmaps from computeMatrix output. Generates publication-quality visualizations.
+
+**Key Parameters:**
+- `--matrixFile, -m`: Matrix from computeMatrix (required)
+- `--outFileName, -o`: Output image (png, eps, pdf, svg) (required)
+- `--outFileSortedRegions`: Save regions after filtering
+- `--outFileNameMatrix`: Export matrix values
+- `--interpolationMethod`: auto, nearest, bilinear, bicubic, gaussian
+  - Default: nearest (≤1000 columns), bilinear (>1000 columns)
+- `--dpi`: Figure resolution
+
+**Clustering:**
+- `--kmeans`: k-means clustering
+- `--hclust`: Hierarchical clustering (slower for >1000 regions)
+- `--silhouette`: Calculate cluster quality metrics
+
+**Visual Customization:**
+- `--heatmapHeight / --heatmapWidth`: Dimensions (3-100 cm)
+- `--whatToShow`: plot, heatmap, colorbar (combinations)
+- `--alpha`: Transparency (0-1)
+- `--colorMap`: 50+ color schemes
+- `--colorList`: Custom gradient colors
+- `--zMin / --zMax`: Intensity scale limits
+- `--boxAroundHeatmaps`: yes/no (default: yes)
+
+**Labels:**
+- `--xAxisLabel / --yAxisLabel`: Axis labels
+- `--regionsLabel`: Region set identifiers
+- `--samplesLabel`: Sample names
+- `--refPointLabel`: Reference point label
+- `--startLabel / --endLabel`: Region boundary labels
+
+**Common Usage:**
+```bash
+# Basic heatmap
+plotHeatmap -m matrix.gz -o heatmap.png
+
+# With clustering and custom colors
+plotHeatmap -m matrix.gz -o heatmap.png \
+    --kmeans 3 --colorMap RdBu --zMin -3 --zMax 3
+```
+
+---
+
+### plotProfile
+
+Generates profile plots showing scores across genomic regions using computeMatrix output.
+
+**Key Parameters:**
+- `--matrixFile, -m`: Matrix from computeMatrix (required)
+- `--outFileName, -o`: Output image (png, eps, pdf, svg) (required)
+- `--plotType`: lines, fill, se, std, overlapped_lines, heatmap
+- `--colors`: Color palette (names or hex codes)
+- `--plotHeight / --plotWidth`: Dimensions in centimeters
+- `--yMin / --yMax`: Y-axis range
+- `--averageType`: mean, median, min, max, std, sum
+
+**Clustering:**
+- `--kmeans`: k-means clustering
+- `--hclust`: Hierarchical clustering
+- `--silhouette`: Cluster quality metrics
+
+**Labels:**
+- `--plotTitle`: Main heading
+- `--regionsLabel`: Region set identifiers
+- `--samplesLabel`: Sample names
+- `--startLabel / --endLabel`: Region boundary labels (scale-regions mode)
+
+**Output Options:**
+- `--outFileNameData`: Export data as tab-separated values
+- `--outFileSortedRegions`: Save filtered/sorted regions as BED
+
+**Common Usage:**
+```bash
+# Line plot
+plotProfile -m matrix.gz -o profile.png --plotType lines
+
+# With standard error shading
+plotProfile -m matrix.gz -o profile.png --plotType se \
+    --colors blue red green
+```
+
+---
+
+### plotEnrichment
+
+Calculates and visualizes signal enrichment across genomic regions. Measures percentage of alignments overlapping region groups. Useful for FRiP (Fragment in Peaks) scores.
+
+**Key Parameters:**
+- `--bamfiles, -b`: Indexed BAM files (required)
+- `--BED`: Region files in BED/GTF format (required)
+- `--plotFile, -o`: Output visualization (png, pdf, eps, svg)
+- `--labels, -l`: Custom sample identifiers
+- `--outRawCounts`: Export numerical data
+- `--perSample`: Group by sample instead of feature (default)
+- `--regionLabels`: Custom region names
+
+**Read Processing:**
+- `--minFragmentLength / --maxFragmentLength`: Fragment filters
+- `--minMappingQuality`: Quality threshold
+- `--samFlagInclude / --samFlagExclude`: SAM flag filters
+- `--ignoreDuplicates`: Remove duplicates
+- `--centerReads`: Center reads for sharper signal
+
+**Common Usage:**
+```bash
+plotEnrichment -b Input.bam H3K4me3.bam \
+    --BED peaks_up.bed peaks_down.bed \
+    --regionLabels "Up regulated" "Down regulated" \
+    -o enrichment.png
+```
+
+---
+
+## Miscellaneous Tools
+
+### computeMatrixOperations
+
+Advanced matrix manipulation tool for combining or subsetting matrices from computeMatrix. Enables complex multi-sample, multi-region analyses.
+
+**Operations:**
+- `cbind`: Combine matrices column-wise
+- `rbind`: Combine matrices row-wise
+- `subset`: Extract specific samples or regions
+- `filterStrand`: Keep only regions on specific strand
+- `filterValues`: Apply signal intensity filters
+- `sort`: Order regions by various criteria
+- `dataRange`: Report min/max values
+
+**Common Usage:**
+```bash
+# Combine matrices
+computeMatrixOperations cbind -m matrix1.gz matrix2.gz -o combined.gz
+
+# Extract specific samples
+computeMatrixOperations subset -m matrix.gz --samples 0 2 -o subset.gz
+```
+
+---
+
+### estimateReadFiltering
+
+Predicts the impact of various filtering parameters without actually filtering. Helps optimize filtering strategies before running full analyses.
+
+**Key Parameters:**
+- `--bamfiles, -b`: BAM files to analyze
+- `--sampleSize`: Number of reads to sample (default: 100,000)
+- `--binSize`: Bin size for analysis
+- `--distanceBetweenBins`: Spacing between sampled bins
+
+**Filtration Options to Test:**
+- `--minMappingQuality`: Test quality thresholds
+- `--ignoreDuplicates`: Assess duplicate impact
+- `--minFragmentLength / --maxFragmentLength`: Test fragment filters
+
+---
+
+## Common Parameters Across Tools
+
+Many deepTools commands share these filtering and performance options:
+
+**Read Filtering:**
+- `--ignoreDuplicates`: Remove PCR duplicates
+- `--minMappingQuality`: Filter by alignment confidence
+- `--samFlagInclude / --samFlagExclude`: SAM format filtering
+- `--minFragmentLength / --maxFragmentLength`: Fragment length bounds
+
+**Performance:**
+- `--numberOfProcessors, -p`: Enable parallel processing
+- `--region`: Process specific genomic regions (chr:start-end)
+
+**Read Processing:**
+- `--extendReads`: Extend to fragment length
+- `--centerReads`: Center at fragment midpoint
+- `--ignoreDuplicates`: Count unique reads only