samtools-samples(1)

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

💅 samtools-samples(1) — the samtools samples page, bestie edition

okay so welcome to the samtools-samples(1) manual page, the one and only 🫶. Yes the manual name is literally samtools-samples(1) and yes we're gonna get through it together. Grab a snack. 🍓

✨ NAME ✨

samtools samples — prints the samples from an alignment file. That's it. That's the whole gig. 💅

🦋 SYNOPSIS 🦋

samtools samples [options] (<input>|stdin)

samtools samples [options] -X f1.bam f2.bam ... f1.bam.bai f2.bam.bai
...

so there's the normal mode, and there's the -X custom-index mode where you just hand it the bam files and their index files all mixed together like a lil charcuterie board 🧚. iykyk.

🌸 DESCRIPTION 🌸

okay so what does this thing actually do. It prints out the sample names it finds in the read-groups, plus the path to the reference genome, straight out of your alignment files. The output is literally designed to be fed into any popular workflow manager — it's giving "let me prep your input files for you, bestie" energy. 👑

The input is a list of SAM/BAM/CRAM files, or you can pipe the paths to those files in via stdin. Both are valid, both slay.

The output is tab-delimited and goes like this:

  • column one: the sample name — main character energy
  • column two: the path to the alignment file
  • column three (optional): the path to the reference genome
  • column four (optional): a single character flag (Y/N) telling you whether the alignment file is indexed or not

couple of little rules, no cap:

  • if no reference is found for an alignment, a dot (.) goes in the reference path column
  • if no sample is available in any read-group header, a dot (.) is used as the sample name
  • if a BAM file contains more than one sample, you get one line printed for each sample — she's thorough 💖

🎀 OPTIONS 🎀

  • -? — print help and exit. the classic "what does anything do" button 🙈
  • -h — print a header. so your columns have names, as they deserve 🌈
  • -i — test if the file is indexed. adds an extra column to the output with a single character value (Y/N) 💫
  • -T TAG — provide the sample tag name from the @RG line [SM]. default is SM, but you can be different 💅
  • -o FILE — output file [stdout]. yes, stdout is the default, she's generous
  • -f FILE — load an indexed fasta file into the collection of references. can be used multiple times. adds an extra column with the path to the reference file. stack 'em up 🧚
  • -F FILE — read a file containing the paths to indexed fasta files. one path per line. the lazy-girl way to do -f a million times 🍓
  • -X — use a custom index file. for when your index files aren't where the tool expects, and you're like "no bestie, these ones" 🔥

⭐ EXAMPLES ⭐

o print the samples from a set of BAM/SAM files, with a header

there is no sample defined in the header of 'example.sam', so a dot is used for the sample name. not a bug, that's just her being honest 💀

$ samtools  samples -h S*.bam *.sam
#SM  PATH
S1   S1.bam
S2   S2.bam
S3   S3.bam
S4   S4.bam
S5   S5.bam
.    example.sam

o print the samples from a set of BAM/SAM files, with a header, print whether the file is indexed

same thing but now we're also asking "are you indexed?" and getting answers 🫶

$  samtools  samples -i -h S*.bam *.sam
#SM  PATH INDEX
S1   S1.bam    Y
S2   S2.bam    Y
S3   S3.bam    Y
S4   S4.bam    Y
S5   S5.bam    Y
.    example.sam    N

o print whether the files are indexed using custom bai files

look at that example.sam sitting there with an N — iconic honestly.

$ samtools samples -i -h -X S1.bam S2.bam S1.bam.bai S2.bam.bai
#SM  PATH INDEX
S1   S1.bam    Y
S2   S2.bam    Y

o read a tab delimited input <file>(tab)<bai> and print whether the files are indexed using custom bai files

the paste - - trick is such a serve, this is the pipeline of all time 🌸

$ find . -type f \( -name "S*.bam" -o -name "S*.bai" \) | sort | paste - - | samtools samples -i -h -X
#SM  PATH INDEX
S1   ./S1.bam  Y
S2   ./S2.bam  Y
S3   ./S3.bam  Y
S4   ./S4.bam  Y
S5   ./S5.bam  Y

o print the samples from a set of BAM/CRAM files, with a header, use '@RG/LB' instead of '@RG/SM'

note that S5.bam shows up twice here because it's got two libraries — multiple samples, multiple lines, we been knew 💜

$ samtools  samples -h -T LB S*.bam
#LB  PATH
S1   S1.bam
S2   S2.bam
S3   S3.bam
S4   S4.bam
S5Lib1    S5.bam
S5Lib2    S5.bam

o pipe a list of BAM/CRAM files , pipe it into samtools samples

yes the original really does have that space before the comma. i'm not fixing it, it's canon now 🎀

$ find . -type f \( -name "S*.bam" -o -name "*.cram" \) | samtools  samples -h
#SM  PATH
S5   ./S5.bam
S2   ./S2.bam
S4   ./S4.bam
S3   ./S3.bam
S1   ./example.cram
S1   ./S1.bam

o provide two reference sequences with option '-f', print the associated reference for each BAM files

two -f flags, two references, and she matches each file to the right one. the way that works >>> 😭

$ samtools  samples  -h -f reference.fa -f example.fa S*.bam *.sam *.cram
#SM  PATH REFERENCE
S1   S1.bam    reference.fa
S2   S2.bam    reference.fa
S3   S3.bam    reference.fa
S4   S4.bam    reference.fa
S5   S5.bam    reference.fa
.    example.sam    example.fa
S1   example.cram   example.fa

o provide a list of reference sequences with option '-F', print the associated reference for each BAM files

same result as above, but the references live in a file. one path per line, no notes ✨

$ cat references.list
reference.fa
example.fa
$ samtools  samples  -h -F references.list S*.bam *.sam *.cram
#SM  PATH REFERENCE
S1   S1.bam    reference.fa
S2   S2.bam    reference.fa
S3   S3.bam    reference.fa
S4   S4.bam    reference.fa
S5   S5.bam    reference.fa
.    example.sam    example.fa
S1   example.cram   example.fa
ok real talk for one sec: notice how -f/-F add that fourth REFERENCE column and -i adds that INDEX column — those extra columns are optional columns, so don't be thrown when your output is shorter than someone else's. 💖

👑 AUTHOR 👑

Written by Pierre Lindenbaum from Institut du Thorax U1087, Nantes, France. legend behavior, honestly 🫶

Samtools website: http://www.htslib.org/

and that's the page!! this whole thing is from samtools-1.24, dated 9 July 2026 — so if you're reading this from some other version of samtools-samples(1), check your date bestie 🌈💅✨

📦 where this page comes from