sam-bam-basics

Name: sam-bam-basics
Author: GPTomics

1.1kstars185forks

How to install sam-bam-basics?

gptomics/bioskills/sam-bam-basics

$npx -y skills add GPTomics/bioSkills --skill sam-bam-basics

Installs into the current project.

Summary

View, convert, and understand SAM/BAM/CRAM alignment files using samtools and pysam. Use when inspecting alignments, converting between formats, or understanding alignment file structure.

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: 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	# SAM/BAM/CRAM Basics
13
14	"Read a BAM file" -> Open a binary alignment file and iterate over aligned reads with their mapping coordinates, flags, and quality scores.
15	- Python: `pysam.AlignmentFile()` (pysam)
16	- CLI: `samtools view` (samtools)
17	- R: `scanBam()` (Rsamtools)
18
19	View and convert alignment files using samtools and pysam.
20
21	## Format Overview
22
23	\| Format \| Description \| Use Case \|
24	\|--------\|-------------\|----------\|
25	\| SAM \| Text format, human-readable \| Debugging, small files \|
26	\| BAM \| Binary compressed SAM \| Standard storage format \|
27	\| CRAM \| Reference-based compression \| Long-term archival, smaller than BAM \|
28
29	## SAM Format Structure
30
31	```
32	@HD VN:1.6 SO:coordinate
33	@SQ SN:chr1 LN:248956422
34	@RG ID:sample1 SM:sample1
35	@PG ID:bwa PN:bwa VN:0.7.17
36	read1 0 chr1 100 60 50M * 0 0 ACGT... FFFF... NM:i:0
37	```
38
39	Header lines start with `@`:
40	- `@HD` - Header metadata (version, sort order)
41	- `@SQ` - Reference sequence dictionary
42	- `@RG` - Read group information
43	- `@PG` - Program used to create file
44
45	Alignment fields (tab-separated):
46	1. QNAME - Read name
47	2. FLAG - Bitwise flag
48	3. RNAME - Reference name
49	4. POS - 1-based position
50	5. MAPQ - Mapping quality
51	6. CIGAR - Alignment description
52	7. RNEXT - Mate reference
53	8. PNEXT - Mate position
54	9. TLEN - Template length
55	10. SEQ - Read sequence
56	11. QUAL - Base qualities
57	12. Optional tags (NM:i:0, MD:Z:50, etc.)
58
59	## samtools view
60
61	### View BAM as SAM
62	```bash
63	samtools view input.bam \| head
64	```
65
66	### View with Header
67	```bash
68	samtools view -h input.bam \| head -100
69	```
70
71	### View Header Only
72	```bash
73	samtools view -H input.bam
74	```
75
76	### View Specific Region
77	```bash
78	samtools view input.bam chr1:1000-2000
79	```
80
81	### Count Alignments
82	```bash
83	samtools view -c input.bam
84	```
85
86	## Format Conversion
87
88	Goal: Convert between SAM (text), BAM (binary), and CRAM (reference-compressed) alignment formats.
89
90	Approach: Use `samtools view` with format flags (`-b` for BAM, `-C` for CRAM, `-h` for SAM with header). CRAM requires a reference FASTA with `-T`.
91
92	### BAM to SAM
93	```bash
94	samtools view -h -o output.sam input.bam
95	```
96
97	### SAM to BAM
98	```bash
99	samtools view -b -o output.bam input.sam
100	```
101
102	### BAM to CRAM
103	```bash
104	samtools view -C -T reference.fa -o output.cram input.bam
105	```
106
107	### CRAM to BAM
108	```bash
109	samtools view -b -T reference.fa -o output.bam input.cram
110	```
111
112	### Pipe Conversion
113	```bash
114	samtools view -b input.sam > output.bam
115	```
116
117	## Common Flags
118
119	\| Flag \| Decimal \| Meaning \|
120	\|------\|---------\|---------\|
121	\| 0x1 \| 1 \| Paired \|
122	\| 0x2 \| 2 \| Proper pair \|
123	\| 0x4 \| 4 \| Unmapped \|
124	\| 0x8 \| 8 \| Mate unmapped \|
125	\| 0x10 \| 16 \| Reverse strand \|
126	\| 0x20 \| 32 \| Mate reverse strand \|
127	\| 0x40 \| 64 \| First in pair \|
128	\| 0x80 \| 128 \| Second in pair \|
129	\| 0x100 \| 256 \| Secondary alignment \|
130	\| 0x200 \| 512 \| Failed QC \|
131	\| 0x400 \| 1024 \| PCR duplicate \|
132	\| 0x800 \| 2048 \| Supplementary \|
133
134	### Decode Flags (Bidirectional)
135	```bash
136	# Number to mnemonics
137	samtools flags 147
138	# 0x93 147 PAIRED,PROPER_PAIR,REVERSE,READ2
139
140	# Mnemonics to number
141	samtools flags PAIRED,PROPER_PAIR,REVERSE,READ2 # 147
142	```
143
144	### Secondary vs Supplementary (Different Semantics)
145
146	Two different concepts that are routinely conflated:
147
148	\| Bit \| Name \| Meaning \| Filter implication \|
149	\|-----\|------\|---------\|--------------------\|
150	\| 0x100 (256) \| Secondary \| An alternative candidate alignment for the same read; not the primary location \| `-F 256` is correct for SNV/indel calling on short reads \|
151	\| 0x800 (2048) \| Supplementary \| A piece of a chimeric/split alignment (the read is split across loci) \| Carries SA:Z tag; required by SV callers (Manta, Sniffles, cuteSV, GRIDSS, Delly) \|
152
153	`-F 2304` removes both. Strip supplementary only when downstream is small-variant calling; keep supplementary for SV calling, fusion detection, or any analysis that follows split-reads.
154
155	## MAPQ Is Not Portable Across Aligners
156
157	`samtools view -q 30` does different things depending on what produced the BAM. MAPQ is an aligner-specific scale, not a universal probability:
158
159	\| Aligner \| MAPQ scale \| "Unique" sentinel \| Common gotcha \|
160	\|---------\|-----------\|-------------------\|----------------\|
161	\| BWA-MEM / BWA-MEM2 \| 0-60 \| 60 \| `-q 30` is sensible "high confidence" \|
162	\| minimap2 (DNA / pbmm2) \| 0-60 \| 60 \| Spec-compliant \|
163	\| HISAT2 \| 0-60 \| 60 \| Spec

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

sam-bam-basics

1.1kstars185forks

View on GitHub

How to install sam-bam-basics?

gptomics/bioskills/sam-bam-basics

$npx -y skills add GPTomics/bioSkills --skill sam-bam-basics

Installs into the current project.

Summary

View, convert, and understand SAM/BAM/CRAM alignment files using samtools and pysam. Use when inspecting alignments, converting between formats, or understanding alignment file structure.

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: 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	# SAM/BAM/CRAM Basics
13
14	"Read a BAM file" -> Open a binary alignment file and iterate over aligned reads with their mapping coordinates, flags, and quality scores.
15	- Python: `pysam.AlignmentFile()` (pysam)
16	- CLI: `samtools view` (samtools)
17	- R: `scanBam()` (Rsamtools)
18
19	View and convert alignment files using samtools and pysam.
20
21	## Format Overview
22
23	\| Format \| Description \| Use Case \|
24	\|--------\|-------------\|----------\|
25	\| SAM \| Text format, human-readable \| Debugging, small files \|
26	\| BAM \| Binary compressed SAM \| Standard storage format \|
27	\| CRAM \| Reference-based compression \| Long-term archival, smaller than BAM \|
28
29	## SAM Format Structure
30
31	```
32	@HD VN:1.6 SO:coordinate
33	@SQ SN:chr1 LN:248956422
34	@RG ID:sample1 SM:sample1
35	@PG ID:bwa PN:bwa VN:0.7.17
36	read1 0 chr1 100 60 50M * 0 0 ACGT... FFFF... NM:i:0
37	```
38
39	Header lines start with `@`:
40	- `@HD` - Header metadata (version, sort order)
41	- `@SQ` - Reference sequence dictionary
42	- `@RG` - Read group information
43	- `@PG` - Program used to create file
44
45	Alignment fields (tab-separated):
46	1. QNAME - Read name
47	2. FLAG - Bitwise flag
48	3. RNAME - Reference name
49	4. POS - 1-based position
50	5. MAPQ - Mapping quality
51	6. CIGAR - Alignment description
52	7. RNEXT - Mate reference
53	8. PNEXT - Mate position
54	9. TLEN - Template length
55	10. SEQ - Read sequence
56	11. QUAL - Base qualities
57	12. Optional tags (NM:i:0, MD:Z:50, etc.)
58
59	## samtools view
60
61	### View BAM as SAM
62	```bash
63	samtools view input.bam \| head
64	```
65
66	### View with Header
67	```bash
68	samtools view -h input.bam \| head -100
69	```
70
71	### View Header Only
72	```bash
73	samtools view -H input.bam
74	```
75
76	### View Specific Region
77	```bash
78	samtools view input.bam chr1:1000-2000
79	```
80
81	### Count Alignments
82	```bash
83	samtools view -c input.bam
84	```
85
86	## Format Conversion
87
88	Goal: Convert between SAM (text), BAM (binary), and CRAM (reference-compressed) alignment formats.
89
90	Approach: Use `samtools view` with format flags (`-b` for BAM, `-C` for CRAM, `-h` for SAM with header). CRAM requires a reference FASTA with `-T`.
91
92	### BAM to SAM
93	```bash
94	samtools view -h -o output.sam input.bam
95	```
96
97	### SAM to BAM
98	```bash
99	samtools view -b -o output.bam input.sam
100	```
101
102	### BAM to CRAM
103	```bash
104	samtools view -C -T reference.fa -o output.cram input.bam
105	```
106
107	### CRAM to BAM
108	```bash
109	samtools view -b -T reference.fa -o output.bam input.cram
110	```
111
112	### Pipe Conversion
113	```bash
114	samtools view -b input.sam > output.bam
115	```
116
117	## Common Flags
118
119	\| Flag \| Decimal \| Meaning \|
120	\|------\|---------\|---------\|
121	\| 0x1 \| 1 \| Paired \|
122	\| 0x2 \| 2 \| Proper pair \|
123	\| 0x4 \| 4 \| Unmapped \|
124	\| 0x8 \| 8 \| Mate unmapped \|
125	\| 0x10 \| 16 \| Reverse strand \|
126	\| 0x20 \| 32 \| Mate reverse strand \|
127	\| 0x40 \| 64 \| First in pair \|
128	\| 0x80 \| 128 \| Second in pair \|
129	\| 0x100 \| 256 \| Secondary alignment \|
130	\| 0x200 \| 512 \| Failed QC \|
131	\| 0x400 \| 1024 \| PCR duplicate \|
132	\| 0x800 \| 2048 \| Supplementary \|
133
134	### Decode Flags (Bidirectional)
135	```bash
136	# Number to mnemonics
137	samtools flags 147
138	# 0x93 147 PAIRED,PROPER_PAIR,REVERSE,READ2
139
140	# Mnemonics to number
141	samtools flags PAIRED,PROPER_PAIR,REVERSE,READ2 # 147
142	```
143
144	### Secondary vs Supplementary (Different Semantics)
145
146	Two different concepts that are routinely conflated:
147
148	\| Bit \| Name \| Meaning \| Filter implication \|
149	\|-----\|------\|---------\|--------------------\|
150	\| 0x100 (256) \| Secondary \| An alternative candidate alignment for the same read; not the primary location \| `-F 256` is correct for SNV/indel calling on short reads \|
151	\| 0x800 (2048) \| Supplementary \| A piece of a chimeric/split alignment (the read is split across loci) \| Carries SA:Z tag; required by SV callers (Manta, Sniffles, cuteSV, GRIDSS, Delly) \|
152
153	`-F 2304` removes both. Strip supplementary only when downstream is small-variant calling; keep supplementary for SV calling, fusion detection, or any analysis that follows split-reads.
154
155	## MAPQ Is Not Portable Across Aligners
156
157	`samtools view -q 30` does different things depending on what produced the BAM. MAPQ is an aligner-specific scale, not a universal probability:
158
159	\| Aligner \| MAPQ scale \| "Unique" sentinel \| Common gotcha \|
160	\|---------\|-----------\|-------------------\|----------------\|
161	\| BWA-MEM / BWA-MEM2 \| 0-60 \| 60 \| `-q 30` is sensible "high confidence" \|
162	\| minimap2 (DNA / pbmm2) \| 0-60 \| 60 \| Spec-compliant \|
163	\| HISAT2 \| 0-60 \| 60 \| Spec

People who liked this also viewed

6 picks

Type