CoverageLens

Targeted sequencing coverage reporter that turns a BAM/CRAM and a BED of target regions into a concise HTML dashboard plus optional TSV/JSON exports.

Features

• Per-region coverage metrics: mean, min, max depth and percent of bases ≥ configurable thresholds.
• PASS/FAIL call per region based on primary threshold and breadth requirement.
• Summary stats: fraction of targets meeting coverage requirements and overall mean depth.
• Static HTML report with interactive charts and a searchable table (filter by gene/region).
• Optional TSV and JSON exports for downstream QC pipelines.
• CRAM support (with external reference) and configurable BED column mappings.

Installation

pip install coveragelens

Or from source:

python -m venv .venv && source .venv/bin/activate
pip install -e .

Quick start

# Generate HTML report
coveragelens sample.bam targets.bed \
  --threshold 10 --threshold 20 --threshold 50 \
  --html-output coverage_report.html

Open coverage_report.html in your browser to explore summary metrics, charts, and a searchable table by gene or region name.

CLI

coveragelens BAM_OR_CRAM BED \
  [--threshold 10 --threshold 20 ...] \
  [--primary-threshold 20] \
  [--breadth-requirement 0.95] \
  [--gene-column 3 --name-column 3] \
  [--config config.yaml] \
  [--reference reference.fa] \
  [--chunk-size 50000] \
  [--html-output report.html] \
  [--json-output metrics.json] \
  [--tsv-output metrics.tsv]

• Coverage breadth is reported as the percent of bases in a region meeting each threshold.
• Regions are considered passing if breadth at the primary threshold is at least the breadth requirement (default 95%); this is shown as a PASS/FAIL pill per region and summarized in the donut chart.
• JSON output includes both per-region metrics and a summary block with regions_meeting, regions_failing, and fraction_meeting.
• Provide --reference when reading CRAM files that do not embed reference sequences.

Example commands

• Panel with typical thresholds:

  coveragelens tumor.bam panel.bed \
    --threshold 10 20 50 \
    --primary-threshold 20 \
    --breadth-requirement 0.95 \
    --html-output tumor_panel_coverage.html
  

• CRAM with external reference and JSON export:

  coveragelens sample.cram exome_targets.bed \
    --reference GRCh38.fa \
    --threshold 20 50 \
    --json-output sample_coverage.json
  

Testing

python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
pytest

Config file

YAML/JSON config to set defaults:

thresholds: [10, 20, 50]
primary_threshold: 20          # default uses the highest threshold
breadth_requirement: 0.95      # fraction of bases
chunk_size: 50000              # bases per count_coverage call
bed_delimiter: "\t"
bed_columns:
  chrom: 0
  start: 1
  end: 2
  name: 3
  gene: 3
sample_name: "Patient_01"

JSON output schema (high level)

{
  "summary": {
    "total_regions": 1234,
    "primary_threshold": 20,
    "breadth_requirement": 0.95,
    "regions_meeting": 1200,
    "regions_failing": 34,
    "fraction_meeting": 0.972,
    "mean_depth_overall": 142.3,
    "sample_name": "Patient_01"
  },
  "regions": [
    {
      "chrom": "chr1",
      "start": 100000,
      "end": 100150,
      "length": 150,
      "name": "EXON1",
      "gene": "GENE1",
      "mean_depth": 135.2,
      "min_depth": 52,
      "max_depth": 212,
      "status": "PASS",
      "pct_ge_10": 100.0,
      "pct_ge_20": 100.0,
      "pct_ge_50": 97.3
    }
  ]
}

Notes

• Coverage is computed with pysam.count_coverage in chunks to handle large panels efficiently.
• BED parsing is tolerant of comments/blank lines and lets you remap gene/region columns via CLI flags or config.
• The HTML report is fully static; no server is required.