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
Physical coverage illustration

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 20 reduces noise
  • Filter early: Apply upstream filters with samtools when possible
  • Stream processing: Use pipes to avoid intermediate files
  • Skip small contigs: Use -z for 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 -d and --keep-invalid-alignments