Usage Guide
Basic Syntax
covtobed [options] [BAM_files...]
Input Requirements
BAM File Requirements
- Sorted BAM files: Input must be coordinate-sorted
- Index not required: BAM index (.bai) is not needed
- Stream support: Can read from STDIN for pipeline integration
- Multiple files: Can process multiple BAM files simultaneously
Filtering Options
Coverage Filtering
Minimum Coverage Filter
# Only output regions with coverage >= 10
covtobed -m 10 input.bam
# Detect low coverage regions (coverage < 5)
covtobed -x 5 input.bam
Coverage Range Filter
# Output regions with coverage between 10 and 100
covtobed -m 10 -x 100 input.bam
Quality Filtering
Mapping Quality Filter
# Only consider alignments with mapping quality >= 20
covtobed -q 20 input.bam
Alignment Validity Filtering (v1.4.0+)
⚠️ Breaking Change in v1.4.0
Invalid alignments (duplicates, failed QC, non-primary) are now discarded by default.
Default Behavior (v1.4.0+)
# Automatically discards invalid alignments
covtobed input.bam
# Equivalent explicit command
covtobed -d input.bam
Legacy Behavior
# Keep all alignments (pre-v1.4.0 behavior)
covtobed --keep-invalid-alignments input.bam
Length and Reference Filtering
Minimum Feature Length
# Only output features with length >= 50bp
covtobed -l 50 input.bam
Skip Short Contigs
# Skip reference sequences shorter than 1000bp
covtobed -z 1000 input.bam
Output Formats
BED Format (Default)
covtobed input.bam
Output format:
chr1 100 200 10
chr1 200 300 15
chr1 300 400 8
Counts Format
covtobed --format counts input.bam
Output format:
>chr1
10 100
15 100
8 100
Strand-Specific Output
covtobed --output-strands input.bam
Output format (forward, reverse coverage):
chr1 100 200 6 4
chr1 200 300 8 7
chr1 300 400 5 3
Special Coverage Modes
Physical Coverage
For paired-end sequencing, physical coverage represents the span between read pairs.
Calculate Physical Coverage
# Requires properly paired reads
covtobed --physical-coverage paired_end.bam
Pipeline Integration
Reading from STDIN
Complete Pipeline
# Alignment, sorting, and coverage in one pipeline
bwa mem genome.fa reads_1.fq reads_2.fq | \
samtools view -bS | \
samtools sort | \
covtobed --min-cov 5 > coverage.bed
Low Coverage Detection Pipeline
# Find regions with coverage < 10 and merge adjacent regions
covtobed --max-cov 10 input.bam | \
bedtools merge -d 100 > low_coverage_regions.bed
Suppress Startup Message
When reading from STDIN, covtobed shows a startup message. To suppress it:
export COVTOBED_QUIET=1
samtools view -b input.sam | covtobed
Performance Tips
🚀 Optimization Guidelines
- Pre-sort BAM files: Ensures optimal performance
- Use quality filters:
-q 20reduces noise - Filter early: Apply upstream filters with samtools when possible
- Stream processing: Use pipes to avoid intermediate files
- Skip small contigs: Use
-zfor fragmented assemblies
Common Use Cases
Quality Control
# Detect regions with no coverage
covtobed -x 1 input.bam > uncovered.bed
# Find high-coverage regions (potential duplicates)
covtobed -m 100 input.bam > high_coverage.bed
Target Enrichment Analysis
# Check target coverage
covtobed -m 20 enriched.bam > well_covered_targets.bed
# Intersect with target regions
bedtools intersect -a targets.bed -b well_covered_targets.bed
Strand Bias Detection
# Output strand-specific coverage for analysis
covtobed --output-strands input.bam | \
awk 'abs($4-$5) > 10' > strand_biased_regions.bed
Assembly Quality Assessment
# Physical coverage for mate-pair libraries
covtobed --physical-coverage mate_pairs.bam > assembly_coverage.bed
# Skip small contigs in fragmented assemblies
covtobed -z 1000 assembly_reads.bam > contig_coverage.bed
Error Handling
Common Errors and Solutions
- "BAM not sorted": Sort BAM with
samtools sort - "Cannot read BAM": Check file permissions and format
- "Coverage not zero at end": Run
samtools fixmate - Conflicting flags: Don't use both
-dand--keep-invalid-alignments