genome-alignment-qc

Files (10)

• SKILL.md
• README.md · agents/
• claude.yaml · agents/
• openai.yaml · agents/
• .gitkeep · assets/
• config.yaml
• README.md · references/
• samtools-mosdepth-picard-qc.md · references/
• batch_run.sh · scripts/
• run.sh · scripts/

SKILL.md (first lines)

# Skill: genome-alignment-qc

## Use When

- User wants to evaluate BAM quality before variant calling.
- User needs to assess coverage depth and uniformity across the genome or target regions.
- User wants to check mapping rate, duplication rate, and insert size distribution.
- User needs to calculate on-target rate for whole-exome sequencing (WES).
- User wants to compare QC metrics across samples to detect batch effects.

## Inputs

- Required:
  - BAM file with index (`.bam` + `.bai`).
- Optional:
  - Target BED file (for WES on-target metrics).
  - Reference FASTA (required for picard metrics).
  - Output directory (default: current directory).
  - Per-base coverage flag (enables mosdepth per-base output; default: off).

## Workflow

1. Run `samtools stats` and `samtools flagstat` for mapping summary.
2. Run `samtools idxstats` for per-chromosome read counts.
3. Run `mosdepth` for coverage distribution (genome-wide, or restricted to target BED).
4. If target BED provided: compute on-target rate and per-target coverage statistics.
5. Run `picard CollectInsertSizeMetrics` for insert size distribution.
6. Run `picard CollectAlignmentSummaryMetrics` for detailed alignment statistics.
7. Compile summary: mapping rate, duplicate rate, mean coverage, coverage uniformity (CV), median insert size, on-target rate (if WES).
8. Flag metrics outside recommended thresholds (see `knowledge/sources/genomics/quality-thresholds.md`).

## Output Contract

- `samtools stats` and `samtools flagstat` output files.
- `mosdepth` coverage files (`.mosdepth.global.dist.txt`, `.per-base.bed.gz` if enabled).
- Picard insert size metrics file and histogram.
- Picard alignment summary metrics file.
- Compiled QC summary with key metrics and threshold flags.

## Limits

- samtools, mosdepth, and picard must be installed and available on `$PATH`.
- mosdepth per-base output can be very large for WGS (~10 GB for 30x human).
- Picard requires a Java runtime (Java 8+).
- Reference FASTA is required for picard metrics but not for samtools/mosdepth.
- This skill reports metrics for a single BAM; multi-sample comparison is out of scope.
- Common failure cases:
  - BAM index (`.bai`) missing or out of date relative to the BAM file.
  - Target BED file using different chromosome naming convention than the BAM (e.g., `chr1` vs `1`).
  - Picard failing due to missing reference FASTA sequence dictionary (`.dict`).

From Scientific-Tooling/structured-intelligence, MIT.

More from Scientific-Tooling/structured-intelligence