Provided by: samtools_1.17-1_amd64 bug

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/>