alignment-validation

Name: alignment-validation
Author: GPTomics

1.1kstars185forks

How to install alignment-validation?

gptomics/bioskills/alignment-validation

$npx -y skills add GPTomics/bioSkills --skill alignment-validation

Installs into the current project.

Summary

Validate alignment quality with insert size distribution, proper pairing rates, GC bias, strand balance, and other post-alignment metrics. Use when verifying alignment data quality before variant calling or quantification.

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: matplotlib 3.8+, numpy 1.26+, picard 3.1+, pysam 0.22+, samtools 1.19+
4
5	Before using code patterns, verify installed versions match. If versions differ:
6	- Python: `pip show <package>` then `help(module.function)` to check signatures
7	- CLI: `<tool> --version` then `<tool> --help` to confirm flags
8
9	If code throws ImportError, AttributeError, or TypeError, introspect the installed
10	package and adapt the example to match the actual API rather than retrying.
11
12	# Alignment Validation
13
14	Post-alignment quality control to verify alignment quality and identify issues.
15
16	"Check alignment quality" -> Compute post-alignment QC metrics (mapping rate, pairing, insert size, strand balance) to identify issues before downstream analysis.
17	- CLI: `samtools flagstat`, `samtools stats`, Picard `CollectAlignmentSummaryMetrics`
18	- Python: `pysam.AlignmentFile` iteration with metric calculations
19
20	## Two Different Validations
21
22	\| Concern \| Tools \| What it catches \|
23	\|---------\|-------\|-----------------\|
24	\| File integrity \| `samtools quickcheck`, `picard ValidateSamFile` \| Truncation, missing EOF, malformed records, wrong CIGAR, MAPQ out of range \|
25	\| Sequence dictionary identity \| `samtools dict` + M5 diff \| BAM aligned to wrong reference flavor / different decoy / chr vs no-chr \|
26	\| QC metrics \| `samtools stats`, `flagstat`, `mosdepth`, Picard `CollectMultipleMetrics` / `CollectHsMetrics` / `CollectWgsMetrics` \| Are the data biologically reasonable for the assay? \|
27	\| Contamination / sample swap \| `verifybamid2`, `somalier`, Picard `CrosscheckFingerprints` \| Cross-sample contamination, tumor-normal swap, mislabeled sample \|
28
29	A file can pass `quickcheck` and still be malformed in ways that crash GATK three hours into HaplotypeCaller. Conversely, a QC-poor BAM can be structurally valid.
30
31	### File Integrity
32	```bash
33	# Fast: header + EOF block check (misses mid-file truncation, invalid CIGAR)
34	samtools quickcheck -v in.bam \|\| echo "QUICKCHECK FAILED"
35	samtools quickcheck -v *.bam > bad_bams.fofn # one fail-line per bad file
36
37	# Slow but thorough: structural validation
38	picard ValidateSamFile I=in.bam MODE=SUMMARY R=ref.fa
39
40	# Production: ignore expected-but-noisy
41	picard ValidateSamFile I=in.bam MODE=SUMMARY R=ref.fa \
42	IGNORE=INVALID_MAPPING_QUALITY \
43	IGNORE=MISMATCH_FLAG_MATE_NEG_STRAND
44	```
45
46	CI-safe one-liner:
47	```bash
48	test -s in.bam \
49	&& samtools quickcheck -v in.bam \
50	&& [ $(samtools view -c -F 2304 in.bam) -gt 1000 ] \
51	\|\| { echo "BAM failed integrity"; exit 1; }
52	```
53
54	### Sequence Dictionary Cross-Validation (M5)
55	```bash
56	# Compare per-contig MD5 between BAM and reference
57	diff \
58	<(samtools view -H in.bam \| grep '^@SQ' \| tr '\t' '\n' \| grep '^M5:' \| sort) \
59	<(samtools dict ref.fa \| grep '^@SQ' \| tr '\t' '\n' \| grep '^M5:' \| sort)
60	```
61
62	If M5s differ, the BAM was aligned to a different sequence than the current reference (even if contig names match). Concrete failure modes: GRCh38 vs GRCh38.p13 vs GRCh38_no_alt (alt contigs differ); UCSC `chr1` vs Ensembl `1` (names differ, M5s match -- pure renaming); soft-masked vs unmasked (M5 matches -- case is normalized to uppercase before hashing, so lowercase soft-masking is invisible to M5). Note hard-masking is different: it replaces bases with `N`, changing the sequence, so its M5 does NOT match the unmasked reference. The M5 tag is the only definitive identity check.
63
64	### Contamination and Sample Swap
65
66	No alignment QC is complete without these in production:
67	```bash
68	# Cross-sample contamination
69	verifybamid2 --SVDPrefix /resources/1000g.b38.vcf.gz.SVD \
70	--Reference ref.fa --BamFile sample.bam --Output sample.contam
71	# FREEMIX > 0.03 is the commonly used contamination-concern threshold; values escalate from there.
72
73	# Relatedness, sex check, sample swap detection
74	somalier extract -d extracted/ -s /resources/sites.GRCh38.vcf.gz \
75	-f ref.fa sample.bam
76	somalier relate --infer extracted/*.somalier
77
78	# Tumor/normal pairing verification
79	picard CrosscheckFingerprints I=tumor.bam I=normal.bam \
80	HAPLOTYPE_MAP=Homo_sapiens_assembly38.haplotype_database.txt
81	# LOD > 5 = same individual; < -5 = different
82	```
83
84	Sample-swap rates of 0.5-1% in production cohorts are typical. Without `somalier` or `CrosscheckFingerprints`, swaps are detected only when a downstream finding contradicts clinical expectation.
85
86	## Insert Size Distribution
87
88	Goal: Verify that the fragment length distribution matches the library preparation protocol.
89
90	Approach: Extract template_length from properly paired reads and compare the distribution to expected values for the library type.
91
92	### samtools stats
93
94	```bash
95	samtools stats inpu

People who liked this also viewed

6 picks

Type

alignment-validation

1.1kstars185forks

View on GitHub

How to install alignment-validation?

gptomics/bioskills/alignment-validation

$npx -y skills add GPTomics/bioSkills --skill alignment-validation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: matplotlib 3.8+, numpy 1.26+, picard 3.1+, pysam 0.22+, samtools 1.19+
4
5	Before using code patterns, verify installed versions match. If versions differ:
6	- Python: `pip show <package>` then `help(module.function)` to check signatures
7	- CLI: `<tool> --version` then `<tool> --help` to confirm flags
8
9	If code throws ImportError, AttributeError, or TypeError, introspect the installed
10	package and adapt the example to match the actual API rather than retrying.
11
12	# Alignment Validation
13
14	Post-alignment quality control to verify alignment quality and identify issues.
15
16	"Check alignment quality" -> Compute post-alignment QC metrics (mapping rate, pairing, insert size, strand balance) to identify issues before downstream analysis.
17	- CLI: `samtools flagstat`, `samtools stats`, Picard `CollectAlignmentSummaryMetrics`
18	- Python: `pysam.AlignmentFile` iteration with metric calculations
19
20	## Two Different Validations
21
22	\| Concern \| Tools \| What it catches \|
23	\|---------\|-------\|-----------------\|
24	\| File integrity \| `samtools quickcheck`, `picard ValidateSamFile` \| Truncation, missing EOF, malformed records, wrong CIGAR, MAPQ out of range \|
25	\| Sequence dictionary identity \| `samtools dict` + M5 diff \| BAM aligned to wrong reference flavor / different decoy / chr vs no-chr \|
26	\| QC metrics \| `samtools stats`, `flagstat`, `mosdepth`, Picard `CollectMultipleMetrics` / `CollectHsMetrics` / `CollectWgsMetrics` \| Are the data biologically reasonable for the assay? \|
27	\| Contamination / sample swap \| `verifybamid2`, `somalier`, Picard `CrosscheckFingerprints` \| Cross-sample contamination, tumor-normal swap, mislabeled sample \|
28
29	A file can pass `quickcheck` and still be malformed in ways that crash GATK three hours into HaplotypeCaller. Conversely, a QC-poor BAM can be structurally valid.
30
31	### File Integrity
32	```bash
33	# Fast: header + EOF block check (misses mid-file truncation, invalid CIGAR)
34	samtools quickcheck -v in.bam \|\| echo "QUICKCHECK FAILED"
35	samtools quickcheck -v *.bam > bad_bams.fofn # one fail-line per bad file
36
37	# Slow but thorough: structural validation
38	picard ValidateSamFile I=in.bam MODE=SUMMARY R=ref.fa
39
40	# Production: ignore expected-but-noisy
41	picard ValidateSamFile I=in.bam MODE=SUMMARY R=ref.fa \
42	IGNORE=INVALID_MAPPING_QUALITY \
43	IGNORE=MISMATCH_FLAG_MATE_NEG_STRAND
44	```
45
46	CI-safe one-liner:
47	```bash
48	test -s in.bam \
49	&& samtools quickcheck -v in.bam \
50	&& [ $(samtools view -c -F 2304 in.bam) -gt 1000 ] \
51	\|\| { echo "BAM failed integrity"; exit 1; }
52	```
53
54	### Sequence Dictionary Cross-Validation (M5)
55	```bash
56	# Compare per-contig MD5 between BAM and reference
57	diff \
58	<(samtools view -H in.bam \| grep '^@SQ' \| tr '\t' '\n' \| grep '^M5:' \| sort) \
59	<(samtools dict ref.fa \| grep '^@SQ' \| tr '\t' '\n' \| grep '^M5:' \| sort)
60	```
61
62	If M5s differ, the BAM was aligned to a different sequence than the current reference (even if contig names match). Concrete failure modes: GRCh38 vs GRCh38.p13 vs GRCh38_no_alt (alt contigs differ); UCSC `chr1` vs Ensembl `1` (names differ, M5s match -- pure renaming); soft-masked vs unmasked (M5 matches -- case is normalized to uppercase before hashing, so lowercase soft-masking is invisible to M5). Note hard-masking is different: it replaces bases with `N`, changing the sequence, so its M5 does NOT match the unmasked reference. The M5 tag is the only definitive identity check.
63
64	### Contamination and Sample Swap
65
66	No alignment QC is complete without these in production:
67	```bash
68	# Cross-sample contamination
69	verifybamid2 --SVDPrefix /resources/1000g.b38.vcf.gz.SVD \
70	--Reference ref.fa --BamFile sample.bam --Output sample.contam
71	# FREEMIX > 0.03 is the commonly used contamination-concern threshold; values escalate from there.
72
73	# Relatedness, sex check, sample swap detection
74	somalier extract -d extracted/ -s /resources/sites.GRCh38.vcf.gz \
75	-f ref.fa sample.bam
76	somalier relate --infer extracted/*.somalier
77
78	# Tumor/normal pairing verification
79	picard CrosscheckFingerprints I=tumor.bam I=normal.bam \
80	HAPLOTYPE_MAP=Homo_sapiens_assembly38.haplotype_database.txt
81	# LOD > 5 = same individual; < -5 = different
82	```
83
84	Sample-swap rates of 0.5-1% in production cohorts are typical. Without `somalier` or `CrosscheckFingerprints`, swaps are detected only when a downstream finding contradicts clinical expectation.
85
86	## Insert Size Distribution
87
88	Goal: Verify that the fragment length distribution matches the library preparation protocol.
89
90	Approach: Extract template_length from properly paired reads and compare the distribution to expected values for the library type.
91
92	### samtools stats
93
94	```bash
95	samtools stats inpu

People who liked this also viewed

6 picks

Type