alignment-amplicon-clipping

Name: alignment-amplicon-clipping
Author: GPTomics

1.1kstars185forks

How to install alignment-amplicon-clipping?

gptomics/bioskills/alignment-amplicon-clipping

$npx -y skills add GPTomics/bioSkills --skill alignment-amplicon-clipping

Installs into the current project.

Summary

Trim PCR primers from aligned reads in amplicon-panel BAMs using samtools ampliconclip. Use when processing SARS-CoV-2 ARTIC, hereditary cancer panels, ctDNA hot-spot panels, or any amplicon assay where primer-derived bases would falsely confirm reference at primer footprints.

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: samtools 1.19+, pysam 0.22+
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 Amplicon Clipping
13
14	"Trim primer-derived bases from amplicon BAM" -> Soft- or hard-clip the 5' primer footprint after alignment using a primer BED, then repair fixmate/MD/NM tags.
15	- CLI: `samtools ampliconclip -b primers.bed input.bam -o clipped.bam` (since samtools 1.11)
16	- Alternative: `iVar trim`, `BAMClipper`, `fgbio ClipBam`
17
18	## Why Primer Trimming After Alignment
19
20	Amplicon panels (SARS-CoV-2 ARTIC, hereditary cancer panels, ctDNA hot-spot panels, fusion panels, 16S rRNA) use designed PCR primers for enrichment. Primer-derived bases at read 5' ends do NOT reflect biological sequence -- they reflect the primer template. Without trimming:
21	- False reference confirmation at primer footprint positions.
22	- Variant allele frequency suppressed at variants under primers (the primer sequence cannot capture the variant base).
23	- Strand bias artifacts (primers are typically one-strand).
24
25	Standard amplicon BAMs should NEVER be processed by `samtools markdup` -- by design every read at a primer location is a "duplicate" by coordinate. See duplicate-handling for the assay-aware decision.
26
27	## Tool Selection
28
29	\| Tool \| When \| Notes \|
30	\|------\|------\|-------\|
31	\| `samtools ampliconclip` \| Default for amplicon panels (since 1.11) \| Soft- or hard-clip from BED; modifies CIGAR; invalidates MD/NM \|
32	\| `iVar trim` \| Illumina SARS-CoV-2 / PrimalSeq route (Andersen lab) \| Coordinates by primer name/position; soft-clips only + quality sliding-window \|
33	\| `BAMClipper` \| Capture / hybrid panels with primer overlap \| 5'-end clipping with overlap handling \|
34	\| `fgbio ClipBam` \| When read-pair coordination matters \| Soft/hard-clip with mate-aware end adjustment \|
35	\| `cutadapt` (pre-alignment) \| Legacy / when alignment is downstream \| Trims at FASTQ stage; less precise for amplicon \|
36
37	## Soft-Clip vs Hard-Clip
38
39	Goal: Decide whether trimmed bases are kept in the BAM (reversible) or discarded (irreversible).
40
41	Approach: Soft-clip is the safe default; hard-clip only when archiving and disk is constrained.
42
43	\| Mode \| Flag \| What it does \| Reversible? \|
44	\|------\|------\|--------------\|-------------\|
45	\| Soft-clip \| (default) / `--soft-clip` \| Bases kept in SEQ; CIGAR uses `S`; bases not aligned \| Yes (CIGAR can be re-extended) \|
46	\| Hard-clip \| `--hard-clip` \| Bases removed from SEQ; CIGAR uses `H` \| No (bases lost) \|
47
48	Soft-clip is the recommended default. Hard-clip is irreversible -- once applied, the trimmed bases cannot be recovered for re-analysis with different primer coordinates.
49
50	## Basic ampliconclip Workflow
51
52	Goal: Trim primers from a coordinate-sorted, indexed amplicon BAM and produce a downstream-ready BAM.
53
54	Approach: Run `ampliconclip` with primer BED, choosing either `--strand` (5' strand-aware) or `--both-ends` (read-through amplicons; note `--both-ends` overrides `--strand`), then re-fixmate (CIGAR changed) and re-calmd (MD/NM tags invalidated by clip).
55
56	```bash
57	# 1. Soft-clip primers (default; reversible). --strand clips only the designed strand.
58	samtools ampliconclip --strand --soft-clip \
59	-b primers.bed input.bam -o clipped.bam
60
61	# 2. Re-pair tags (CIGARs changed -- mate info needs refresh)
62	samtools sort -n clipped.bam \| \
63	samtools fixmate -m - - \| \
64	samtools sort -o sorted.bam -
65
66	# 3. Repair MD/NM tags (invalidated by clip; required by mpileup BAQ and IGV)
67	samtools calmd -b sorted.bam reference.fa > clipped_final.bam
68	samtools index clipped_final.bam
69	```
70
71	### Strand-Aware Clipping
72
73	`--strand` clips primer bases only on the strand the primer is designed for. Without `--strand`, both strands are clipped at the primer site, removing valid biological sequence on the off-strand.
74
75	### Both-End Clipping
76
77	`--both-ends` allows clipping at both 5' and 3' positions of the read (some primers can appear at either end after alignment). Necessary for amplicon designs where reads can read through the entire amplicon. When `--both-ends` is set, `--strand` is ignored -- primer sites at both ends are clipped regardless of the BED strand column:
78
79	```bash
80	samtools ampliconclip --both-ends --soft-clip -b primers.bed input.bam -o clipped.bam
81	```
82
83	## Primer BED Format
84
85	```
86	# tab-separa

People who liked this also viewed

6 picks

Type

alignment-amplicon-clipping

1.1kstars185forks

View on GitHub

How to install alignment-amplicon-clipping?

gptomics/bioskills/alignment-amplicon-clipping

$npx -y skills add GPTomics/bioSkills --skill alignment-amplicon-clipping

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Version Compatibility
2
3	Reference examples tested with: samtools 1.19+, pysam 0.22+
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 Amplicon Clipping
13
14	"Trim primer-derived bases from amplicon BAM" -> Soft- or hard-clip the 5' primer footprint after alignment using a primer BED, then repair fixmate/MD/NM tags.
15	- CLI: `samtools ampliconclip -b primers.bed input.bam -o clipped.bam` (since samtools 1.11)
16	- Alternative: `iVar trim`, `BAMClipper`, `fgbio ClipBam`
17
18	## Why Primer Trimming After Alignment
19
20	Amplicon panels (SARS-CoV-2 ARTIC, hereditary cancer panels, ctDNA hot-spot panels, fusion panels, 16S rRNA) use designed PCR primers for enrichment. Primer-derived bases at read 5' ends do NOT reflect biological sequence -- they reflect the primer template. Without trimming:
21	- False reference confirmation at primer footprint positions.
22	- Variant allele frequency suppressed at variants under primers (the primer sequence cannot capture the variant base).
23	- Strand bias artifacts (primers are typically one-strand).
24
25	Standard amplicon BAMs should NEVER be processed by `samtools markdup` -- by design every read at a primer location is a "duplicate" by coordinate. See duplicate-handling for the assay-aware decision.
26
27	## Tool Selection
28
29	\| Tool \| When \| Notes \|
30	\|------\|------\|-------\|
31	\| `samtools ampliconclip` \| Default for amplicon panels (since 1.11) \| Soft- or hard-clip from BED; modifies CIGAR; invalidates MD/NM \|
32	\| `iVar trim` \| Illumina SARS-CoV-2 / PrimalSeq route (Andersen lab) \| Coordinates by primer name/position; soft-clips only + quality sliding-window \|
33	\| `BAMClipper` \| Capture / hybrid panels with primer overlap \| 5'-end clipping with overlap handling \|
34	\| `fgbio ClipBam` \| When read-pair coordination matters \| Soft/hard-clip with mate-aware end adjustment \|
35	\| `cutadapt` (pre-alignment) \| Legacy / when alignment is downstream \| Trims at FASTQ stage; less precise for amplicon \|
36
37	## Soft-Clip vs Hard-Clip
38
39	Goal: Decide whether trimmed bases are kept in the BAM (reversible) or discarded (irreversible).
40
41	Approach: Soft-clip is the safe default; hard-clip only when archiving and disk is constrained.
42
43	\| Mode \| Flag \| What it does \| Reversible? \|
44	\|------\|------\|--------------\|-------------\|
45	\| Soft-clip \| (default) / `--soft-clip` \| Bases kept in SEQ; CIGAR uses `S`; bases not aligned \| Yes (CIGAR can be re-extended) \|
46	\| Hard-clip \| `--hard-clip` \| Bases removed from SEQ; CIGAR uses `H` \| No (bases lost) \|
47
48	Soft-clip is the recommended default. Hard-clip is irreversible -- once applied, the trimmed bases cannot be recovered for re-analysis with different primer coordinates.
49
50	## Basic ampliconclip Workflow
51
52	Goal: Trim primers from a coordinate-sorted, indexed amplicon BAM and produce a downstream-ready BAM.
53
54	Approach: Run `ampliconclip` with primer BED, choosing either `--strand` (5' strand-aware) or `--both-ends` (read-through amplicons; note `--both-ends` overrides `--strand`), then re-fixmate (CIGAR changed) and re-calmd (MD/NM tags invalidated by clip).
55
56	```bash
57	# 1. Soft-clip primers (default; reversible). --strand clips only the designed strand.
58	samtools ampliconclip --strand --soft-clip \
59	-b primers.bed input.bam -o clipped.bam
60
61	# 2. Re-pair tags (CIGARs changed -- mate info needs refresh)
62	samtools sort -n clipped.bam \| \
63	samtools fixmate -m - - \| \
64	samtools sort -o sorted.bam -
65
66	# 3. Repair MD/NM tags (invalidated by clip; required by mpileup BAQ and IGV)
67	samtools calmd -b sorted.bam reference.fa > clipped_final.bam
68	samtools index clipped_final.bam
69	```
70
71	### Strand-Aware Clipping
72
73	`--strand` clips primer bases only on the strand the primer is designed for. Without `--strand`, both strands are clipped at the primer site, removing valid biological sequence on the off-strand.
74
75	### Both-End Clipping
76
77	`--both-ends` allows clipping at both 5' and 3' positions of the read (some primers can appear at either end after alignment). Necessary for amplicon designs where reads can read through the entire amplicon. When `--both-ends` is set, `--strand` is ignored -- primer sites at both ends are clipped regardless of the BED strand column:
78
79	```bash
80	samtools ampliconclip --both-ends --soft-clip -b primers.bed input.bam -o clipped.bam
81	```
82
83	## Primer BED Format
84
85	```
86	# tab-separa

People who liked this also viewed

6 picks

Type