NAME

       samtools fasta / fastq - converts a SAM/BAM/CRAM file to FASTA or FASTQ

SYNOPSIS

       samtools fastq [options] in.bam
       samtools fasta [options] in.bam

DESCRIPTION

       Converts a BAM or CRAM into either FASTQ or FASTA format depending on the command invoked.
       The files will be automatically  compressed  if  the  file  names  have  a  .gz  or  .bgzf
       extension.

       If  the input contains read-pairs which are to be interleaved or written to separate files
       in the same order, then the input should be first collated by name.  Use samtools  collate
       or samtools sort -n to ensure this.

       For  each different QNAME, the input records are categorised according to the state of the
       READ1 and READ2 flag bits.  The three categories used are:

       1 : Only READ1 is set.

       2 : Only READ2 is set.

       0 : Either both READ1 and READ2 are set; or neither is set.

       The exact meaning of these categories depends on the sequencing technology  used.   It  is
       expected  that ordinary single and paired-end sequencing reads will be in categories 1 and
       2 (in the case of paired-end reads, one read of the pair will be in category 1, the  other
       in  category 2).  Category 0 is essentially a “catch-all” for reads that do not fit into a
       simple paired-end sequencing model.

       For each category only one sequence will be written for a given QNAME.  If more  than  one
       record is available for a given QNAME and category, the first in input file order that has
       quality values will be used.  If none of the candidate records has  quality  values,  then
       the first in input file order will be used instead.

       Sequences  will  be written to standard output unless one of the -1, -2, -o, or -0 options
       is used, in which case sequences for that category will be written to the specified  file.
       The  same filename may be specified with multiple options, in which ase the sequences will
       be multiplexed in order of occurrence.

       If a singleton file is specified using the -s option then only paired  sequences  will  be
       output  for  categories 1 and 2; paired meaning that for a given QNAME there are sequences
       for both category 1 and 2.  If there is a sequence for only one of categories 1 or 2  then
       it will be diverted into the specified singletons file.  This can be used to prepare fastq
       files for programs that cannot handle a mixture of paired and singleton reads.

       The -s option only affects category 1 and 2 records.  The output for category  0  will  be
       the same irrespective of the use of this option.

OPTIONS

       -n      By  default,  either  '/1'  or  '/2'  is  added to the end of read names where the
               corresponding READ1 or READ2 FLAG bit is set.  Using -n causes read  names  to  be
               left as they are.

       -N      Always  add  either  '/1'  or  '/2'  to  the  end of read names even when put into
               different files.

       -O      Use quality values from OQ tags  in  preference  to  standard  quality  string  if
               available.

       -s FILE Write singleton reads to FILE.

       -t      Copy RG, BC and QT tags to the FASTQ header line, if they exist.

       -T TAGLIST
               Specify  a  comma-separated list of tags to copy to the FASTQ header line, if they
               exist.

       -1 FILE Write reads with the READ1 FLAG set  (and  READ2  not  set)  to  FILE  instead  of
               outputting  them.   If the -s option is used, only paired reads will be written to
               this file.

       -2 FILE Write reads with the READ2 FLAG set  (and  READ1  not  set)  to  FILE  instead  of
               outputting  them.   If the -s option is used, only paired reads will be written to
               this file.

       -o FILE Write reads with either READ1 FLAG or READ2 flag set to FILE instead of outputting
               them to stdout.  This is equivalent to -1 FILE -2 FILE.

       -0 FILE Write  reads  where  the READ1 and READ2 FLAG bits set are either both set or both
               unset to FILE instead of outputting them.

       -f INT  Only output alignments with all bits set in INT present in the  FLAG  field.   INT
               can  be  specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal
               by beginning with `0' (i.e. /^0[0-7]+/) [0].

       -F INT  Do not output alignments with any bits set in INT present in the FLAG field.   INT
               can  be  specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal
               by  beginning  with  `0'  (i.e.  /^0[0-7]+/)  [0x900].   This  defaults  to  0x900
               representing filtering of secondary and supplementary alignments.

       -G INT  Only EXCLUDE reads with all of the bits set in INT present in the FLAG field.  INT
               can be specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or  in  octal
               by beginning with `0' (i.e. /^0[0-7]+/) [0].

       -i      add Illumina Casava 1.8 format entry to header (eg 1:N:0:ATCACG)

       -c [0..9]
               set compression level when writing gz or bgzf fastq files.

       --i1 FILE
               write first index reads to FILE

       --i2 FILE
               write second index reads to FILE

       --barcode-tag TAG
               aux tag to find index reads in [default: BC]

       --quality-tag TAG
               aux tag to find index quality in [default: QT]

       --index-format STR
               string to describe how to parse the barcode and quality tags. For example:

               i14i8   the first 14 characters are index 1, the next 8 characters are index 2

               n8i14   ignore the first 8 characters, and use the next 14 characters for index 1

                       If  the  tag  contains  a separator, then the numeric part can be replaced
                       with '*' to mean 'read until the separator or end of tag', for example:

               n*i*    ignore the left part of the tag until the separator, then use  the  second
                       part

EXAMPLES

       Output  paired reads to separate files, discarding singletons, supplementary and secondary
       reads.  The resulting files can be used with, for example, the bwa aligner.

           samtools fastq -1 paired1.fq -2 paired2.fq -0 /dev/null -s /dev/null -n in.bam

       Output paired and singleton reads in a single file, discarding supplementary and secondary
       reads.   To  get all of the reads in a single file, it is necessary to redirect the output
       of samtools fastq.  The output file is suitable for use with bwa mem -p which  understands
       interleaved files containing a mixture of paired and singleton reads.

           samtools fastq -0 /dev/null in.bam > all_reads.fq

       Output  paired reads in a single file, discarding supplementary and secondary reads.  Save
       any singletons in a separate file.  Append /1 and  /2  to  read  names.   This  format  is
       suitable  for  use  by  NextGenMap  when  using its -p and -q options.  With this aligner,
       paired reads must be mapped separately to the singletons.

           samtools fastq -0 /dev/null -s single.fq -N in.bam > paired.fq

BUGS

       o The way of specifying output files is far to complicated and easy to get wrong.

AUTHOR

       Written by Heng Li, with modifications by Martin Pollard and Jennifer Liddle, all from the
       Sanger Institute.

SEE ALSO

       samtools(1), samtools-faidx(1), samtools-fqidx(1)

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