coveragelens 0.1.0
Targeted sequencing coverage reporter with CLI and HTML outputs.
License: MIT
Requires Python: >=3.9
Keywords: genomics, coverage, NGS, bioinformatics

# 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
```bash
pip install coveragelens
```

Or from source:
```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

## Quick start
```bash
# 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:
  ```bash
  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:
  ```bash
  coveragelens sample.cram exome_targets.bed \
    --reference GRCh38.fa \
    --threshold 20 50 \
    --json-output sample_coverage.json
  ```

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

## Config file
YAML/JSON config to set defaults:
```yaml
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)
```jsonc
{
  "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.