shards.info
sa-check
sa-check
Check whether SA:Z tags in a coordinate-sorted BAM can recover the mapped primary + supplementary alignments for each sampled read. A name-sorted BAM from the same alignment set provides the reference. Secondary and unmapped alignments are excluded from the comparison.
Build
Requires Crystal, Shards, and HTSlib available through pkg-config. Use samtools to prepare the input BAMs.
shards install
shards build --release
Prepare inputs
Create both BAMs from the same file, without filtering one independently:
samtools sort -N -@ 8 -o reads.name.bam reads.bam
samtools sort -@ 8 -o reads.coord.bam reads.bam
samtools index -@ 8 reads.coord.bam
The coordinate BAM needs a BAI or CSI index. Use --coord-index PATH if the index is stored elsewhere.
Run
Start with the first 1,000 reads that have supplementary alignments:
bin/sa-check --name-bam reads.name.bam --coord-bam reads.coord.bam \
--first 1000 -@ 8 -v
For a broader check, sample 10,000 reads and save the report:
bin/sa-check --name-bam reads.name.bam --coord-bam reads.coord.bam \
--sample 10000 -@ 8 --json report.json --tsv report.tsv
--sample 10000 is the default. It scans the entire name-sorted BAM while keeping only the sampled groups in memory. Results describe the sample.
| Option | Use |
|---|---|
--first N |
Check the first N eligible reads and stop early. |
--sample N |
Randomly sample N eligible reads; scan to EOF. |
--qnames FILE |
Check listed read names, one per line; ignores the supplementary-only filter. Blank lines and # comments are skipped. |
--max-groups N |
Limit the scan to N QNAME groups, including ineligible groups. |
--all-groups |
Include reads without supplementary alignments in sampling. |
--strict-nm, --strict-mapq |
Also require matching NM or MAPQ in seed identity and SA matching. |
--seed N |
Set the random sampling seed (default: 1). |
Run bin/sa-check --help for all options. Reports are always printed to stdout; --json and --tsv also write files.
Read the results
| Metric | Meaning |
|---|---|
canonical_recall |
Fraction of reference alignments recovered. |
canonical_precision |
Fraction of recovered alignments present in the reference. |
sa_resolution_rate |
Fraction of SA entries resolving to exactly one record. |
groups_full |
Reads whose alignment set was recovered exactly. |
groups_seed_not_found |
Reads whose starting alignment was absent; check that the BAMs contain the same alignments. |
sa_parse_errors |
Malformed SA tags or SA CIGARs encountered. |
verdict summarizes the check:
usable-for-sa-expansion: recall, precision, and SA resolution are all at least 99.5%, and at least 99% of groups with a found seed are fully recovered.partial: recall, precision, and SA resolution are all at least 95%.unsafe: lower rates, or any SA parse error.not-applicable: no canonical alignments were sampled, or no SA entries were found without parse errors.
Inspect the diagnostic notes if recovery is poor. Filtering, changed CIGARs, or stale SA tags can prevent reconstruction. A verdict is a report value; successful runs return exit status 0 regardless of the verdict.
sa-check
- 0
- 0
- 0
- 0
- 1
- about 7 hours ago
- September 18, 2026
MIT License
Fri, 18 Sep 2026 09:23:49 GMT