alignment-filtering

Name: alignment-filtering
Author: GPTomics

1.1kstars185forks

How to install alignment-filtering?

gptomics/bioskills/alignment-filtering

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

Installs into the current project.

Summary

Filter alignments by flags, mapping quality, and regions using samtools view and pysam. Use when extracting specific reads, removing low-quality alignments, or subsetting to target regions.

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	# Alignment Filtering
13
14	"Filter my BAM file to keep only high-quality reads" -> Select reads by FLAG bits, mapping quality, and genomic regions using samtools view or pysam.
15	- CLI: `samtools view` with `-F`/`-f`/`-q`/`-L` flags (samtools)
16	- Python: `pysam.AlignmentFile` iteration with attribute filters (pysam)
17
18	Filter alignments by flags, quality, and regions using samtools and pysam.
19
20	## Filter Flags
21
22	\| Option \| Description \|
23	\|--------\|-------------\|
24	\| `-f FLAG` \| Include reads with ALL bits set \|
25	\| `-F FLAG` \| Exclude reads with ANY bits set \|
26	\| `-G FLAG` \| Exclude reads with ALL bits set \|
27	\| `-q MAPQ` \| Minimum mapping quality \|
28	\| `-L BED` \| Include reads overlapping regions \|
29
30	## Common FLAG Values
31
32	\| Flag \| Hex \| Meaning \|
33	\|------\|-----\|---------\|
34	\| 1 \| 0x1 \| Paired \|
35	\| 2 \| 0x2 \| Proper pair \|
36	\| 4 \| 0x4 \| Unmapped \|
37	\| 8 \| 0x8 \| Mate unmapped \|
38	\| 16 \| 0x10 \| Reverse strand \|
39	\| 32 \| 0x20 \| Mate reverse strand \|
40	\| 64 \| 0x40 \| First in pair (read1) \|
41	\| 128 \| 0x80 \| Second in pair (read2) \|
42	\| 256 \| 0x100 \| Secondary alignment \|
43	\| 512 \| 0x200 \| Failed QC \|
44	\| 1024 \| 0x400 \| Duplicate \|
45	\| 2048 \| 0x800 \| Supplementary \|
46
47	## Filter by FLAG
48
49	### Keep Only Mapped Reads
50	```bash
51	samtools view -F 4 -o mapped.bam input.bam
52	```
53
54	### Keep Only Unmapped Reads
55	```bash
56	samtools view -f 4 -o unmapped.bam input.bam
57	```
58
59	### Keep Only Properly Paired
60	```bash
61	samtools view -f 2 -o proper.bam input.bam
62	```
63
64	### Remove Duplicates
65	```bash
66	samtools view -F 1024 -o nodup.bam input.bam
67	```
68
69	### Remove Secondary and Supplementary
70	```bash
71	samtools view -F 2304 -o primary.bam input.bam
72	```
73
74	### Keep Only Primary Alignments
75	```bash
76	samtools view -F 256 -F 2048 -o primary.bam input.bam
77	# Or combined: -F 2304
78	```
79
80	### Keep Read1 Only
81	```bash
82	samtools view -f 64 -o read1.bam input.bam
83	```
84
85	### Keep Read2 Only
86	```bash
87	samtools view -f 128 -o read2.bam input.bam
88	```
89
90	### Forward Strand Only
91	```bash
92	samtools view -F 16 -o forward.bam input.bam
93	```
94
95	### Reverse Strand Only
96	```bash
97	samtools view -f 16 -o reverse.bam input.bam
98	```
99
100	## Filter by Mapping Quality
101
102	### Minimum MAPQ
103	```bash
104	samtools view -q 30 -o highqual.bam input.bam
105	```
106
107	### MAPQ and Mapped
108	```bash
109	samtools view -F 4 -q 30 -o filtered.bam input.bam
110	```
111
112	### Aligner-Aware MAPQ Thresholds
113
114	MAPQ scales differ by aligner; the same `-q 30` filter does different things. See sam-bam-basics for the full MAPQ-by-aligner table. Filtering recommendations:
115
116	\| Aligner \| "Drop ambiguous" \| "High confidence" \|
117	\|---------\|------------------\|-------------------\|
118	\| BWA-MEM / BWA-MEM2 \| `-q 1` \| `-q 30` (or `-q 60` for unique only) \|
119	\| Bowtie2 \| `-q 1` \| `-q 23` (Bowtie2 MAPQ maxes at 42 end-to-end; 23 is a community "uniquely mapped" convention derived from analysis of Bowtie2's MAPQ scoring, not stated in the official manual) \|
120	\| STAR \| `-q 255` \| `-q 255` (STAR emits only MAPQ 0/1/3/255, 255 = unique; `-q 60` is therefore equivalent to `-q 255` -- there are no values between 3 and 255) \|
121	\| HISAT2 \| `-q 1` \| `-q 60` \|
122	\| minimap2 (DNA, long-read) \| `-q 1` \| `-q 60` \|
123	\| pbmm2 (PacBio) \| `-q 1` \| `-q 60` \|
124
125	For Phred-scaled aligners (BWA, minimap2), MAPQ Q maps to ~10^(-Q/10) probability of wrong mapping. For STAR, the only emitted values are 0/1/3/255 (sentinels, not probabilities).
126
127	### Drop Ambiguous Across Aligners (Universal)
128	```bash
129	samtools view -q 1 in.bam # exclude MAPQ=0; works for all aligners
130	```
131
132	## Filter by Region
133
134	### Single Region
135	```bash
136	samtools view -o region.bam input.bam chr1:1000000-2000000
137	```
138
139	### Multiple Regions
140	```bash
141	samtools view -o regions.bam input.bam chr1:1000-2000 chr2:3000-4000
142	```
143
144	### Regions from BED File
145	```bash
146	samtools view -L targets.bed -o targets.bam input.bam
147	```
148
149	### Combine Region and Quality
150	```bash
151	samtools view -q 30 -L targets.bed -o filtered.bam input.bam
152	```
153
154	## Combined Filters
155
156	### Standard Quality Filter
157
158	Goal: Produce a clean BAM containing only primary, mapped, non-duplicate reads with high mapping confidence.
159
160	Approach: Combine FLAG exclusion (-F for unmapped + secondary + duplicate + supplementary) with a MAPQ threshold.
161
162	Reference (samtools 1.19+):
163	```bash
164	samtools view -F 3332 -q 30 -o filtered.bam input.bam
165	# 3332 = 4 (unmapped) + 256 (secondary) + 1024 (duplicate) + 2048 (supp

People who liked this also viewed

6 picks

Type

alignment-filtering

1.1kstars185forks

View on GitHub

How to install alignment-filtering?

gptomics/bioskills/alignment-filtering

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

Installs into the current project.

Summary

Filter alignments by flags, mapping quality, and regions using samtools view and pysam. Use when extracting specific reads, removing low-quality alignments, or subsetting to target regions.

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	# Alignment Filtering
13
14	"Filter my BAM file to keep only high-quality reads" -> Select reads by FLAG bits, mapping quality, and genomic regions using samtools view or pysam.
15	- CLI: `samtools view` with `-F`/`-f`/`-q`/`-L` flags (samtools)
16	- Python: `pysam.AlignmentFile` iteration with attribute filters (pysam)
17
18	Filter alignments by flags, quality, and regions using samtools and pysam.
19
20	## Filter Flags
21
22	\| Option \| Description \|
23	\|--------\|-------------\|
24	\| `-f FLAG` \| Include reads with ALL bits set \|
25	\| `-F FLAG` \| Exclude reads with ANY bits set \|
26	\| `-G FLAG` \| Exclude reads with ALL bits set \|
27	\| `-q MAPQ` \| Minimum mapping quality \|
28	\| `-L BED` \| Include reads overlapping regions \|
29
30	## Common FLAG Values
31
32	\| Flag \| Hex \| Meaning \|
33	\|------\|-----\|---------\|
34	\| 1 \| 0x1 \| Paired \|
35	\| 2 \| 0x2 \| Proper pair \|
36	\| 4 \| 0x4 \| Unmapped \|
37	\| 8 \| 0x8 \| Mate unmapped \|
38	\| 16 \| 0x10 \| Reverse strand \|
39	\| 32 \| 0x20 \| Mate reverse strand \|
40	\| 64 \| 0x40 \| First in pair (read1) \|
41	\| 128 \| 0x80 \| Second in pair (read2) \|
42	\| 256 \| 0x100 \| Secondary alignment \|
43	\| 512 \| 0x200 \| Failed QC \|
44	\| 1024 \| 0x400 \| Duplicate \|
45	\| 2048 \| 0x800 \| Supplementary \|
46
47	## Filter by FLAG
48
49	### Keep Only Mapped Reads
50	```bash
51	samtools view -F 4 -o mapped.bam input.bam
52	```
53
54	### Keep Only Unmapped Reads
55	```bash
56	samtools view -f 4 -o unmapped.bam input.bam
57	```
58
59	### Keep Only Properly Paired
60	```bash
61	samtools view -f 2 -o proper.bam input.bam
62	```
63
64	### Remove Duplicates
65	```bash
66	samtools view -F 1024 -o nodup.bam input.bam
67	```
68
69	### Remove Secondary and Supplementary
70	```bash
71	samtools view -F 2304 -o primary.bam input.bam
72	```
73
74	### Keep Only Primary Alignments
75	```bash
76	samtools view -F 256 -F 2048 -o primary.bam input.bam
77	# Or combined: -F 2304
78	```
79
80	### Keep Read1 Only
81	```bash
82	samtools view -f 64 -o read1.bam input.bam
83	```
84
85	### Keep Read2 Only
86	```bash
87	samtools view -f 128 -o read2.bam input.bam
88	```
89
90	### Forward Strand Only
91	```bash
92	samtools view -F 16 -o forward.bam input.bam
93	```
94
95	### Reverse Strand Only
96	```bash
97	samtools view -f 16 -o reverse.bam input.bam
98	```
99
100	## Filter by Mapping Quality
101
102	### Minimum MAPQ
103	```bash
104	samtools view -q 30 -o highqual.bam input.bam
105	```
106
107	### MAPQ and Mapped
108	```bash
109	samtools view -F 4 -q 30 -o filtered.bam input.bam
110	```
111
112	### Aligner-Aware MAPQ Thresholds
113
114	MAPQ scales differ by aligner; the same `-q 30` filter does different things. See sam-bam-basics for the full MAPQ-by-aligner table. Filtering recommendations:
115
116	\| Aligner \| "Drop ambiguous" \| "High confidence" \|
117	\|---------\|------------------\|-------------------\|
118	\| BWA-MEM / BWA-MEM2 \| `-q 1` \| `-q 30` (or `-q 60` for unique only) \|
119	\| Bowtie2 \| `-q 1` \| `-q 23` (Bowtie2 MAPQ maxes at 42 end-to-end; 23 is a community "uniquely mapped" convention derived from analysis of Bowtie2's MAPQ scoring, not stated in the official manual) \|
120	\| STAR \| `-q 255` \| `-q 255` (STAR emits only MAPQ 0/1/3/255, 255 = unique; `-q 60` is therefore equivalent to `-q 255` -- there are no values between 3 and 255) \|
121	\| HISAT2 \| `-q 1` \| `-q 60` \|
122	\| minimap2 (DNA, long-read) \| `-q 1` \| `-q 60` \|
123	\| pbmm2 (PacBio) \| `-q 1` \| `-q 60` \|
124
125	For Phred-scaled aligners (BWA, minimap2), MAPQ Q maps to ~10^(-Q/10) probability of wrong mapping. For STAR, the only emitted values are 0/1/3/255 (sentinels, not probabilities).
126
127	### Drop Ambiguous Across Aligners (Universal)
128	```bash
129	samtools view -q 1 in.bam # exclude MAPQ=0; works for all aligners
130	```
131
132	## Filter by Region
133
134	### Single Region
135	```bash
136	samtools view -o region.bam input.bam chr1:1000000-2000000
137	```
138
139	### Multiple Regions
140	```bash
141	samtools view -o regions.bam input.bam chr1:1000-2000 chr2:3000-4000
142	```
143
144	### Regions from BED File
145	```bash
146	samtools view -L targets.bed -o targets.bam input.bam
147	```
148
149	### Combine Region and Quality
150	```bash
151	samtools view -q 30 -L targets.bed -o filtered.bam input.bam
152	```
153
154	## Combined Filters
155
156	### Standard Quality Filter
157
158	Goal: Produce a clean BAM containing only primary, mapped, non-duplicate reads with high mapping confidence.
159
160	Approach: Combine FLAG exclusion (-F for unmapped + secondary + duplicate + supplementary) with a MAPQ threshold.
161
162	Reference (samtools 1.19+):
163	```bash
164	samtools view -F 3332 -q 30 -o filtered.bam input.bam
165	# 3332 = 4 (unmapped) + 256 (secondary) + 1024 (duplicate) + 2048 (supp

People who liked this also viewed

6 picks

Type