Provided by: samtools_1.20-3_amd64 
NAME
samtools-samples - prints the samples from an alignment file
SYNOPSIS
samtools samples [options] (<input>|stdin)
samtools samples [options] -X f1.bam f2.bam ... f1.bam.bai f2.bam.bai ...
DESCRIPTION
Print the sample names found in the read-groups and the path to the reference genome from
alignment files. The output of this tool can be used to create an input for any popular
workflow manager. The input is a list of SAM/BAM/CRAM files, or the path to those files
can be provided via stdin. The output is tab-delimited containing the sample name as the
first column, the path to the alignment file as the second column, the path to the
reference genome as a third optional column and a single character flag (Y/N) indicating
whether the alignment file is indexed or not as a fourth optional column. If no reference
is found for an alignment, a dot (.) will be used in the reference path column. If no
sample is available in any read-group header, a dot (.) will be used as the sample name.
If a BAM file contains more than one sample, one line will be printed for each sample.
OPTIONS
-? print help and exit
-h print a header
-i test if the file is indexed. Add 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].
-o FILE output file [stdout].
-f FILE load an indexed fasta file in the collection of references. Can be used multiple
times. Add an extra column with the path to the reference file.
-F FILE read a file containing the paths to indexed fasta files. One path per line.
-X use a custom index file.
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.
$ 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.
$ 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.
$ 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.
$ 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'.
$ 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.
$ 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.
$ 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.
$ 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
AUTHOR
Written by Pierre Lindenbaum from Institut du Thorax U1087, Nantes, France.
Samtools website: <http://www.htslib.org/>