A fast, reproducible Snakemake workflow for QC of BAMs — alignment stats, binned-coverage metrics, library complexity, and optional Ashley’s QC.

Highlights

• 🧬 Alfred alignment + error metrics
• 🧊 Bedtools → binned coverage entropy, spikiness, gini, GC bias
• 📈 Preseq library complexity curves
• 🧠 ASHLEYS QC: auto-merge existing labels/features or predict
• 🖼️ Plots: per-library PDFs + run summary
• 🗂️ Clean outputs with consistent join key Library

Clone the repo into your work folder:

git clone https://github.com/pweidner/bamqc-pipeline.git
cd bamqc-pipeline

You will need the same minimal snakemake env as for running mosaicatcher (you can also use that if you already have it, then just activate):

mamba create -n snakemake snakemake=7.32.0 -y
conda activate snakemake

Tools used by rules are auto-installed from workflow/envs/*.yaml on first run.

ref: hg38
reference_path: /ref/dir               # contains hg38.fa (+.fai)
data_location:  /path/to/input         # FLAT: *.sort.mdup.bam; HIER: <sample>/bam/*.sort.mdup.bam
output_location: /path/to/output
window: 200000
plot: true

bam_ext: ".sort.mdup.bam"
tmp_dir: /tmp

ashleys:
  enabled: true
  bin: /abs/path/ashleys-qc/bin/ashleys.py
  model_path: /abs/path/ashleys-qc/models/svc_default.pkl
  win_sizes: [5000000,2000000,1000000,800000,600000,400000,200000]
  threads: 32
  mem_mb: 200000
  conda_env: envs/ashleys.yaml

Discovery modes

• FLAT: data_location/*.sort.mdup.bam
• HIER: data_location/<SAMPLE>/bam/*.sort.mdup.bam
  → auto-detected.

snakemake --config data_location=/data/runA output_location=/data/runA/bamqc --profile workflow/profiles --keep-going

output_location/
├── final_qc.tsv                         # 🧩 Alfred + counts-based + counts.info + preseq QC + Ashley’s columns
│
├── results/                             # 📊 Per tool deliverables
│   ├── final_qc.tsv
│   ├── preseq_metrics.tsv               # Preseq summary stats across libraries
│   └── alignment_summary_metrics.tsv    # Alfred summary across libraries
│
├── metadata/
│   └── library_map.tsv                  # cell <-> Library mapping for sanity checks
│
├── stats-by-lib/
│   └── {Library}.qc.tsv.gz              # per-lib Alfred output
│
├── binned/
│   └── {Library}.bins.tsv.gz            # windowed counts
│
├── qc-from-bins/
│   └── {Library}.counts_qc.tsv          # entropy/spikiness/GC-bias metrics
│
├── preseq/
│   └── {Library}.lc.tsv                 # library complexity curves
│
├── ashleys/
│   ├── features.tsv                     # merged/computed Ashley features
│   ├── features.norm.tsv                # features keyed by Library
│   └── prediction/
│       ├── prediction.tsv               # merged labels or predictions
│       └── prediction.norm.tsv          # normalized to Library
│
└── plots/
    ├── per-lib-qc/{Library}.qc.pdf      # optional per-lib PDF
    └── run_summary.pdf                  # run/cohort summary plots

This pipeline produces per-library QC summaries in two main tables:

• final_qc.tsv — core QC metrics derived from Alfred, bin-wise coverage, and preseq
• final_qc_with_ashleys.tsv — final_qc.tsv plus Ashley’s QC predictions and Ashley feature vectors

All non-identifier columns are prefixed by their producing tool to make provenance explicit.

Metrics derived from alfred qc, summarizing mapping, alignment accuracy, and coverage statistics.

Computed from fixed-size genome windows using bedtools coverage -counts and summarized in qc_from_counts.py.

Derived from preseq lc_extrap, estimating how many unique DNA fragments are present.

Rule of thumb

• preseq_saturation ≈ 1 → sequencing deeper will still yield new information
• preseq_saturation ≈ 0 → sequencing deeper mostly yields duplicates

Generated by ashleys-qc, integrating coverage patterns and strand balance.

Multi-scale Watson-strand bin features and read category fractions.

For each window size (5mb, 2mb, 1mb, 0_8mb, 0_6mb, 0_4mb, 0_2mb):

Interpretation

• Smooth, balanced distributions indicate stable coverage.
• Skewed distributions can indicate CNVs, strand imbalance, or technical artifacts.

• Low complexity → high alf_duplicate_frac, low preseq_saturation
• Uneven coverage → high bin_spikiness, bin_gini, bin_fold80
• GC bias → large |bin_gc_r|
• Mapping problems → low alf_mapped_frac, low alf_mapq_med
• Ashley disagreement → ash_prob low → inspect manually

• Entropy and spikiness reflect coverage evenness (low entropy or high spikiness = uneven).
• Fold80 penalty follows the Picard metric (ideal = 1, higher = less uniform).
• Preseq metrics allow extrapolation of unique reads vs sequencing depth.
• Ashley’s QC integrates pretrained classification of Strand-seq libraries by coverage pattern and W→C balance.
• Mosaicatcher fractions (p_good, etc.) summarize the final usable subset for downstream analyses like count plots and phasing.

• Alfred — Rausch et al., Genome Res (2019)
• preseq — Daley & Smith, Bioinformatics (2013)
• ASHLEYS - Gros et al., Bioinformatics (2021)
• bedtools — Quinlan & Hall, Bioinformatics (2010)
• Snakemake — Köster & Rahmann, Bioinformatics (2012)

• contamination checks
• More GC/coverage plots (Lorenz, violin)
• Optional HTML dashboard

Happy QC’ing! 🧪✨