'\" t
.TH samtools-samples 1 "12 September 2024" "samtools-1.21" "Bioinformatics tools"
.SH NAME
samtools samples \- prints the samples from an alignment file
.\"
.\" Copyright (C) 2021 Genome Research Ltd.
.\"
.\" Author: Pierre Lindenbaum <pierre.lindenbaum@univ-nantes.fr>
.\" Author: Valeriu Ohan <vo2@sanger.ac.uk>
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
.\" to deal in the Software without restriction, including without limitation
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
.\" and/or sell copies of the Software, and to permit persons to whom the
.\" Software is furnished to do so, subject to the following conditions:
.\"
.\" The above copyright notice and this permission notice shall be included in
.\" all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
.\" DEALINGS IN THE SOFTWARE.
.
.\" For code blocks and examples (cf groff's Ultrix-specific man macros)
.de EX

.  in +\\$1
.  nf
.  ft CR
..
.de EE
.  ft
.  fi
.  in

..
.
.SH SYNOPSIS
.PP
.B samtools samples
.RI [ options ]
.I (<input>|stdin)
.PP
.B samtools samples
.RI [ options ]
.B -X
.IR f1.bam " " f2.bam " ... " f1.bam.bai " " f2.bam.bai " ... "

.SH DESCRIPTION
.PP
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.

.SH OPTIONS
.TP 8
.B -?
print help and exit
.TP
.B -h
print a header
.TP
.B -i
test if the file is indexed. Add an extra column to the output with a single
character value (Y/N).
.TP
.BI "-T " TAG
provide the sample tag name from the @RG line [SM].
.TP
.BI "-o " FILE
output file [stdout].
.TP
.BI "-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.
.TP
.BI "-F " FILE
read a file containing the paths to indexed fasta files. One path per line.
.TP
.B -X
use a custom index file.

.SH EXAMPLES
.IP o 2
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.
.EX 2
$ 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
.EE
.IP o 2
print the samples from a set of BAM/SAM files, with a header, print whether the
file is indexed.
.EX 2
$  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
.EE
.IP o 2
print whether the files are indexed using custom bai files.
.EX 2
$ 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
.EE
.IP o 2
read a tab delimited input <file>(tab)<bai> and print whether the files are
indexed using custom bai files.
.EX 2
$ find . -type f \[rs]( -name "S*.bam" -o -name "S*.bai" \[rs]) | 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
.EE
.IP o 2
print the samples from a set of BAM/CRAM files, with a header, use '@RG/LB'
instead of '@RG/SM'.
.EX 2
$ 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
.EE
.IP o 2
pipe a list of BAM/CRAM files , pipe it into  samtools samples.
.EX 2
$ find . -type f \[rs]( -name "S*.bam" -o -name "*.cram" \[rs]) | samtools  samples -h
#SM	PATH
S5	./S5.bam
S2	./S2.bam
S4	./S4.bam
S3	./S3.bam
S1	./example.cram
S1	./S1.bam
.EE
.IP o 2
provide two reference sequences with option '-f', print the associated reference
for each BAM files.
.EX 2
$ 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
.EE
.IP o 2
provide a list of reference sequences with option '-F', print the associated
reference for each BAM files.
.EX 2
$ 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
.EE

.SH AUTHOR
.PP
Written by Pierre Lindenbaum from Institut du Thorax U1087, Nantes, France.

.PP
Samtools website: <http://www.htslib.org/>