covtobed

A tool to generate BED coverage tracks from BAM files

covtobed workflow
Bioconda Build Status License

Features

🚀 Stream Processing

Read BAM files from streams and pipes, perfect for bioinformatics pipelines

🧎 Strand-specific Analysis

Output coverage separately for forward and reverse strands

📊 Physical Coverage

Calculate physical coverage for paired-end and mate-pair libraries

⚡ High Performance

Faster than bedtools with memory-efficient algorithms

🔧 Flexible Filtering

Filter by coverage, quality, length, and alignment validity

📝 Multiple Formats

Output in BED format or counts format for different use cases

Installation

ðŸ“Ķ Conda (Recommended)

conda install -c bioconda covtobed

ðŸģ Docker

docker pull andreatelatin/covtobed
docker run --rm -ti andreatelatin/covtobed covtobed -h

ðŸ”Ļ Compile from Source

Dependencies:

# Ubuntu/Debian
sudo apt install build-essential libbamtools-dev libjsoncpp-dev zlib1g-dev

# Compile
c++ -std=c++11 *.cpp -I/usr/include/bamtools -lbamtools -o covtobed -lz

Usage

Basic Usage

covtobed [options] [BAM]...

Common Examples

Basic Coverage

covtobed demo.bam > coverage.bed

Filter Low Coverage

covtobed -m 10 demo.bam > high_coverage.bed

Strand-specific Coverage

covtobed --output-strands demo.bam > stranded_coverage.bed

Physical Coverage

covtobed --physical-coverage paired.bam > physical_coverage.bed

Pipeline Usage

bwa mem genome.fa reads.fq | samtools view -bS | \
  samtools sort | covtobed --max-cov 5 | \
  bedtools merge > low_coverage.bed

Command-line Options

Option Description Default
-h, --help Show help message and exit -
--version Show program version -
-q MINQ, --min-mapq=MINQ Skip alignments with mapping quality less than MINQ 0
-m MINCOV, --min-cov=MINCOV Print BED feature only if coverage â‰Ĩ MINCOV 0
-x MAXCOV, --max-cov=MAXCOV Print BED feature only if coverage < MAXCOV 100000
-l MINLEN, --min-len=MINLEN Print BED feature only if length â‰Ĩ MINLEN 1
-z MINCTG, --min-ctg-len=MINCTG Skip reference sequences shorter than MINCTG -
-d, --discard-invalid-alignments Skip duplicates, failed QC, non-primary alignments ✅ Default in v1.4.0+
--keep-invalid-alignments Keep duplicates, failed QC, non-primary alignments Legacy behavior
--physical-coverage Compute physical coverage (paired alignments) false
--output-strands Output coverage separately for each strand false
--format=CHOICE Output format: bed or counts bed

⚠ïļ Version 1.4.0 Breaking Change

As of version 1.4.0, invalid alignments are discarded by default (duplicates, failed QC, non-primary). Use --keep-invalid-alignments for legacy behavior.

Testing

Continuous Integration

GitHub Actions

This repository is automatically tested at each release by GitHub Actions.

Enhanced Test Suite (v1.4.0+)

covtobed includes a comprehensive testing framework:

# Run all tests (unit, integration, benchmarks)
cd test
bash run_tests.sh --all

# Run specific test types
bash run_tests.sh --unit        # Unit tests with Catch2
bash run_tests.sh --integration # Enhanced integration tests
bash run_tests.sh --benchmark   # Performance benchmarks

Testing Components:

  • Unit tests: Using Catch2 framework for core classes
  • Integration tests: Comprehensive functional testing with colored output
  • Benchmarks: Performance testing with Google Benchmark
  • Test data generation: Synthetic BAM/SAM file creation

Performance

covtobed is generally faster than bedtools genomecov while providing additional features.

Benchmark Results

Operation Time Description
Coverage Increment 1.39 ns Core coverage calculation
Priority Queue (100 items) 4.5 Ξs Alignment end tracking
Interval Intersection 0.167 ns Genomic interval operations

For detailed performance comparisons and benchmarking data, see the benchmark directory.

Version History

Version 1.4.0 🆕

Breaking change: Default behavior now discards invalid alignments. Added --keep-invalid-alignments flag for legacy behavior. Improved error checking for conflicting flags.

Version 1.3.x

Enhanced filtering and output options

Version 1.2.0

Introduced the -z flag to skip reference shorter than a specified length (useful in fragmented metagenomic datasets)

Version 1.1.0

New feature: -d, --discard-invalid-alignments flag to discard invalid alignments (PCR duplicates, failing QC, supplementary)