samtools-ampliconclip(1)

📦
version 1.24 · 10 versions
, in epel 10, nixpkgs unstable

💅 samtools-ampliconclip(1) — the clip different 💅

okay bestie, so this is the samtools ampliconclip page, from the samtools(1) manual family, and it's genuinely one of the most useful little gremlins in the whole toolbox. Sit down, hydrate, let's go 🫶

✨ NAME ✨

samtools ampliconclip — clip reads using a BED file. that's it, that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

samtools ampliconclip [-o out.file] [-f stat.file] [--soft-clip]
[--hard-clip] [--both-ends] [--strand] [--clipped] [--fail] [--filter-
len INT] [--fail-len INT] [--unmap-len INT] [--no-excluded] [--rejects-
file rejects.file] [--original] [--keep-tag] [--tolerance] [--no-PG]
[-u] -b bed.file in.file

like, feed it a BED file and a file of reads and it does its thing. iconic. 💅

🦋 DESCRIPTION 🦋

okay so what it actually does: it clips the ends of read alignments if they intersect with regions defined in a BED file. that's the whole bit. and even though this tool was originally written for clipping read alignment positions which correspond to amplicon primer locations, it can also be used in other contexts. so don't feel boxed in, bestie — it's versatile 💖

the BED file entries it uses are chrom, chromStart, chromEnd and, optionally, strand. standard BED file format must be used, so if strand is needed then the name and score fields must also be present (even though ampliconclip does not read them — they're literally just standing there for format compliance, main character energy of them tbh). there is a default tolerance of 5 bases when matching chromStart and chromEnd to alignments.

by default the reads are soft clipped and the clip is only done from the 5' end. the way that 5'-end-only default just keeps things chill 😌

now the things to be aware of section, and ngl, this part matters:

  • while ordering is not significant, adjustments to the left most mapping position (POS) will mean that coordinate sorted files will need resorting. in such cases the sorting order in the header is set to unknown. so like, heads up 🫠
  • clipping of reads results in template length (TLEN) being incorrect. this can be corrected by samtools fixmates.
  • any MD and NM aux tags will also be incorrect, which can be fixed by samtools calmd. by default MD and NM tags are removed though, if the output is in CRAM format these tags will be automatically regenerated. cute little regeneration moment ✨
💀 real talk: those TLEN and MD/NM caveats are not optional reading. if you skip them and then act surprised about your stats, that's on you, bestie. fix your mates, run your calmd, be free.

🔥 OPTIONS 🔥

  • -b FILE — BED file of regions (e.g. amplicon primers) to be removed. this one's not really optional, it's the whole point.
  • -o FILE — output file name (defaults to stdout). no file, no problem, it'll just scream into your terminal.
  • -f FILE — file to write stats to (defaults to stderr).
  • -u — output uncompressed SAM, BAM or CRAM. raw, unfiltered, no compression, we love a low-key chaotic choice.
  • --soft-clip — soft clip reads (default). the OG behavior, the standard, the moment.
  • --hard-clip — hard clip reads. gone gone, not just flagged. 💀
  • --both-ends — clip at both the 5' and the 3' ends where regions match. when using this option the --strand option is ignored. so like, don't bother passing both, it won't listen.
  • --strand — use the strand entry from the BED file to clip on the matching forward or reverse alignment. directional girlie behavior 🧚
  • --clipped — only output clipped reads. filter all others. if it wasn't clipped, it's not invited to the party 🙈
  • --fail — mark unclipped reads as QC fail. instead of ghosting them, you're publicly labeling them 💅
  • --filter-len INT — filter out reads of INT size or shorter. in this case soft clips are not counted toward read length. an INT of 0 will filter out reads with no matching bases. so 0 basically means "if it's not matching anything, it's out."
  • --fail-len INT — as --filter-len but mark as QC fail rather then filter out. same energy, different exit strategy.
  • --unmap-len INT — as --filter-len but mark as unmapped. default is 0 (no matching reads). -1 will disable. so -1 is the "actually never mind" setting.
  • --no-excluded — filter out any reads that are marked as QCFAIL or are unmapped. this works on the state of the reads before clipping takes place. important detail, don't forget it.
  • --rejects-file FILE — write any filtered reads out to a file. the rejected get their own little club 🌈
  • --primer-counts FILE — file to write with read counts per bed entry (bedgraph format). stats girlies, this one's for you 🍓
  • --original — add an OA tag with the original data for clipped files. receipts, kept 🎀
  • --keep-tag — in clipped reads, keep the possibly invalid NM and MD tags. by default these tags are deleted. (see the description — they're wrong anyway, so like, choose consciously 👀)
  • --tolerance INT — the amount of latitude given in matching regions to alignments. default 5 bases. be as generous or as strict as you want ✨
  • --no-PG — do not at a PG line to the header. (that typo is in the original, we're keeping it, it's part of the lore 💖)

👑 AUTHOR 👑

written by Andrew Whitwham and Rob Davies, both from the Sanger Institute. legends, honestly. 🫶

⭐ SEE ALSO ⭐

samtools website: <http://www.htslib.org/> 🌐

okay and the cute little sign-off: this was samtools-1.24, dated 9 July 2026, and it's the samtools-ampliconclip(1) page in all its glory. go clip something, bestie — and remember to fix your mates after 😭💜

📦 where this page comes from