NAME

       samtools-reference - extracts an embedded reference from a CRAM file

SYNOPSIS

       samtools reference [-q] [-r region] [-o out.fa] in.cram

DESCRIPTION

       Creates  the  reference  from  aligned  data  using  either  the MD:Z auxiliary tags or an
       embedded reference in a CRAM file.  The output is a FASTA file.

       For the embedded reference mode (-e) this operation is  fast,  but  only  works  on  CRAMs
       produced  using  --output-fmt-option  embed_ref=1.   Note  this  may  not  be the complete
       reference used.  Each CRAM slice will hold the  entire  reference  that  spans  the  slice
       coordinates, but gaps in coverage can lead to gaps between slices.  However this reference
       should be suitable for passing into a CRAM decode (samtools view -T ref.fa).

       For SAM/BAM files or CRAMs without reference, using the  MD:Z  tag  may  also  produce  an
       incomplete reference.  Unlike embedded reference, this reference may not be sufficient for
       decoding a CRAM file as the CRAM  slice  headers  store  the  MD5sum  of  the  portion  of
       reference than spans that slice, but the slice may not have 100% coverage leading to Ns in
       the computed reference.  However it should still be  possible  to  decode  such  CRAMs  by
       ignoring the md5 mismatches using e.g. samtools view --input-fmt-option ignore_md5=1.

OPTIONS

       -e      Enable CRAM embedded reference mode.

       -q      Enables quiet mode and will produce no output.  By default a line per reference is
               reporting describing the percentage with non-N bases.

       -r region
               Specifies a single region to produce the reference from.  If specified,  an  index
               file must be present.

       -o FILE Write the FASTA records to FILE.  By default this is sent to stdout.

       -@ INT  The number of BAM/CRAM decompression threads to use in addition to the main thread
               [0].

               Note this does not multi-thread the main reference generation  steps,  so  scaling
               may  be  capped by 2 or 3 threads, depending on the data.  It will also not affect
               the -e option for CRAM embedded reference, although this is  already  the  fastest
               method.

AUTHOR

       Written by James Bonfield from the Sanger Institute.

SEE ALSO

       samtools(1)

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