1samtools-samples(1)          Bioinformatics tools          samtools-samples(1)
2
3
4

NAME

6       samtools samples - prints the samples from an alignment file
7

SYNOPSIS

9       samtools samples [options] (<input>|stdin)
10
11       samtools  samples  [options] -X f1.bam f2.bam ... f1.bam.bai f2.bam.bai
12       ...
13
14

DESCRIPTION

16       Print the sample names found in the read-groups and  the  path  to  the
17       reference  genome  from alignment files. The output of this tool can be
18       used to create an input for any popular workflow manager. The input  is
19       a  list  of  SAM/BAM/CRAM files, or the path to those files can be pro‐
20       vided via stdin. The output is tab-delimited containing the sample name
21       as  the first column, the path to the alignment file as the second col‐
22       umn, the path to the reference genome as a third optional column and  a
23       single  character  flag  (Y/N) indicating whether the alignment file is
24       indexed or not as a fourth optional column.  If no reference  is  found
25       for  an alignment, a dot (.) will be used in the reference path column.
26       If no sample is available in any read-group header, a dot (.)  will  be
27       used  as  the sample name. If a BAM file contains more than one sample,
28       one line will be printed for each sample.
29
30

OPTIONS

32       -?      print help and exit
33
34       -h      print a header
35
36       -i      test if the file is indexed. Add an extra column to the  output
37               with a single character value (Y/N).
38
39       -T TAG  provide the sample tag name from the @RG line [SM].
40
41       -o FILE output file [stdout].
42
43       -f FILE load an indexed fasta file in the collection of references. Can
44               be used multiple times. Add an extra column with  the  path  to
45               the reference file.
46
47       -F FILE read  a  file  containing the paths to indexed fasta files. One
48               path per line.
49
50       -X      use a custom index file.
51
52

EXAMPLES

54       o print the samples from a set of BAM/SAM files, with a  header.  There
55         is no sample defined in the header of 'example.sam', so a dot is used
56         for the sample name.
57
58           $ samtools  samples -h S*.bam *.sam
59           #SM  PATH
60           S1   S1.bam
61           S2   S2.bam
62           S3   S3.bam
63           S4   S4.bam
64           S5   S5.bam
65           .    example.sam
66
67
68       o print the samples from a set of BAM/SAM files, with a  header,  print
69         whether the file is indexed.
70
71           $  samtools  samples -i -h S*.bam *.sam
72           #SM  PATH INDEX
73           S1   S1.bam    Y
74           S2   S2.bam    Y
75           S3   S3.bam    Y
76           S4   S4.bam    Y
77           S5   S5.bam    Y
78           .    example.sam    N
79
80
81       o print wether the files are indexed using custom bai files.
82
83           $ samtools samples -i -h -X S1.bam S2.bam S1.bam.bai S2.bam.bai
84           #SM  PATH INDEX
85           S1   S1.bam    Y
86           S2   S2.bam    Y
87
88
89       o read  a  tab  delimited  input <file>(tab)<bai> and print whether the
90         files are indexed using custom bai files.
91
92           $ find . -type f \( -name "S*.bam" -o -name "S*.bai" \) | sort | paste - - | samtools samples -i -h -X
93           #SM  PATH INDEX
94           S1   ./S1.bam  Y
95           S2   ./S2.bam  Y
96           S3   ./S3.bam  Y
97           S4   ./S4.bam  Y
98           S5   ./S5.bam  Y
99
100
101       o print the samples from a set of BAM/CRAM files, with  a  header,  use
102         '@RG/LB' instead of '@RG/SM'.
103
104           $ samtools  samples -h -T LB S*.bam
105           #LB  PATH
106           S1   S1.bam
107           S2   S2.bam
108           S3   S3.bam
109           S4   S4.bam
110           S5Lib1    S5.bam
111           S5Lib2    S5.bam
112
113
114       o pipe a list of BAM/CRAM files , pipe it into  samtools samples.
115
116           $ find . -type f \( -name "S*.bam" -o -name "*.cram" \) | samtools  samples -h
117           #SM  PATH
118           S5   ./S5.bam
119           S2   ./S2.bam
120           S4   ./S4.bam
121           S3   ./S3.bam
122           S1   ./example.cram
123           S1   ./S1.bam
124
125
126       o provide  two  reference sequences with option '-f', print the associ‐
127         ated reference for each BAM files.
128
129           $ samtools  samples  -h -f reference.fa -f example.fa S*.bam *.sam *.cram
130           #SM  PATH REFERENCE
131           S1   S1.bam    reference.fa
132           S2   S2.bam    reference.fa
133           S3   S3.bam    reference.fa
134           S4   S4.bam    reference.fa
135           S5   S5.bam    reference.fa
136           .    example.sam    example.fa
137           S1   example.cram   example.fa
138
139
140       o provide a list of reference sequences with option '-F', print the as‐
141         sociated reference for each BAM files.
142
143           $ cat references.list
144           reference.fa
145           example.fa
146           $ samtools  samples  -h -F references.list S*.bam *.sam *.cram
147           #SM  PATH REFERENCE
148           S1   S1.bam    reference.fa
149           S2   S2.bam    reference.fa
150           S3   S3.bam    reference.fa
151           S4   S4.bam    reference.fa
152           S5   S5.bam    reference.fa
153           .    example.sam    example.fa
154           S1   example.cram   example.fa
155
156
157

AUTHOR

159       Written  by  Pierre  Lindenbaum  from Institut du Thorax U1087, Nantes,
160       France.
161
162
163       Samtools website: <http://www.htslib.org/>
164
165
166
167samtools-1.15.1                  7 April 2022              samtools-samples(1)