NAME

       samtools-markdup - mark duplicate alignments in a coordinate sorted file

SYNOPSIS

       samtools  markdup  [-l  length] [-r] [-s] [-T] [-S] [-f file] [-d distance] [-c] [-t] [-m]
       [--mode] [--include-fails]  [--no-PG]  [-u]  [--no-multi-dup]  [--read-coords]  [--coords-
       order] [--barcode-tag] [--barcode-name] [--barcode-rgx] in.algsort.bam out.bam

DESCRIPTION

       Mark duplicate alignments from a coordinate sorted file that has been run through samtools
       fixmate with the -m option.  This program relies on  the  MC  and  ms  tags  that  fixmate
       provides.

OPTIONS

       -l INT     Expected maximum read length of INT bases.  [300]

       -r         Remove duplicate reads.

       -s         Print some basic stats. See STATISTICS.

       -T PREFIX  Write temporary files to PREFIX.samtools.nnnn.mmmm.tmp

       -S         Mark supplementary reads of duplicates as duplicates.

       -f file    Write stats to named file.

       -d distance
                  The  optical  duplicate  distance.   Suggested  settings of 100 for HiSeq style
                  platforms or about 2500 for NovaSeq ones.  Default is 0 to not look for optical
                  duplicates.   When  set,  duplicate  reads  are tagged with dt:Z:SQ for optical
                  duplicates  and  dt:Z:LB  otherwise.   Calculation  of  distance   depends   on
                  coordinate  data embedded in the read names produced by the Illumina sequencing
                  machines.  Optical duplicate detection will not  work  on  non  standard  names
                  without the use of --read-coords.

       -c         Clear previous duplicate settings and tags.

       -t         Mark duplicates with the name of the original in a do tag.

       -m, --mode TYPE
                  Duplicate  decision  method  for  paired  reads.   Values  are  t or s.  Mode t
                  measures positions based on template  start/end  (default).   Mode  s  measures
                  positions  based  on sequence start.  While the two methods identify mostly the
                  same reads as duplicates, mode s tends to return more results.  Unpaired  reads
                  are treated identically by both modes.

       -u         Output uncompressed SAM, BAM or CRAM.

       --include-fails
                  Include quality checked failed reads.

       --no-multi-dup
                  Stop  checking  duplicates  of duplicates for correctness.  While still marking
                  reads as duplicates further checks to make  sure  all  optical  duplicates  are
                  found  are not carried out.  Also operates on -t tagging where reads may tagged
                  with a better quality read but not necessarily the best one.  Using this option
                  can  speed up duplicate marking when there are a great many duplicates for each
                  original read.

       --read-coords REGEX
                  This takes a POSIX regular expression for at least  x  and  y  to  be  used  in
                  optical  duplicate marking It can also include another part of the read name to
                  test for equality, eg lane:tile elements. Elements  wanted  are  captured  with
                  parentheses.  Examples below.

       --coords-order ORDER
                  The  order  of  the elements captured in the regular expression. Default is txy
                  where t is a part of the read name selected for string comparison and  x/y  the
                  coordinates  used for optical duplicate detection.  Valid orders are: txy, tyx,
                  xyt, yxt, xty, ytx, xy and yx.

       --barcode-tag TAG
                  Duplicates must now also match the barcode tag.

       --barcode-name
                  Use the UMI/barcode embedded in the read name (eigth colon delimited part).

       --barcode-rgx REGEX
                  Regex for barcode in the readname (alternative to --barcode-name).

       --no-PG    Do not add a PG line to the output file.

       -@, --threads INT
                  Number of input/output compression threads to use in addition  to  main  thread
                  [0].

STATISTICS

       Entries are:
       COMMAND: the command line.
       READ: number of reads read in.
       WRITTEN: reads written out.
       EXCLUDED: reads ignored.  See below.
       EXAMINED: reads examined for duplication.
       PAIRED: reads that are part of a pair.
       SINGLE: reads that are not part of a pair.
       DUPLICATE PAIR: reads in a duplicate pair.
       DUPLICATE SINGLE: single read duplicates.
       DUPLICATE PAIR OPTICAL: optical duplicate paired reads.
       DUPLICATE SINGLE OPTICAL: optical duplicate single reads.
       DUPLICATE NON PRIMARY: supplementary/secondary duplicate reads.
       DUPLICATE NON PRIMARY OPTICAL: supplementary/secondary optical duplicate reads.
       DUPLICATE PRIMARY TOTAL: number of primary duplicate reads.
       DUPLICATE TOTAL: total number of duplicate reads.
       ESTIMATED  LIBRARY  SIZE:  estimate  of  the  number of unique fragments in the sequencing
       library.

       Estimated library size makes various assumptions  e.g.  the  library  consists  of  unique
       fragments  that  are randomly selected (with replacement) with equal probability.  This is
       unlikely to be true in practice.  However it can provide a  useful  guide  into  how  many
       unique  read  pairs are likely to be available.  In particular it can be used to determine
       how much more data might be obtained by further sequencing of the library.

       Excluded reads are those marked as secondary, supplementary or unmapped.   By  default  QC
       failed  reads  are also excluded but can be included as an option.  Excluded reads are not
       used for calculating duplicates.  They can optionally be marked as duplicates if they have
       a primary that is also a duplicate.

EXAMPLES

       This first collate command can be omitted if the file is already name ordered or collated:

           samtools collate -o namecollate.bam example.bam

       Add ms and MC tags for markdup to use later:

           samtools fixmate -m namecollate.bam fixmate.bam

       Markdup needs position order:

           samtools sort -o positionsort.bam fixmate.bam

       Finally mark duplicates:

           samtools markdup positionsort.bam markdup.bam

       Typically  the  fixmate step would be applied immediately after sequence alignment and the
       markdup step after sorting by chromosome and position.  Thus no additional sort steps  are
       normally needed.

       To  use  the  regex  to  obtain  coordinates  from  reads,  two or three values have to be
       captured.   To  mimic  the  normal  behaviour  and  match  a  read  name  of  the   format
       machine:run:flowcell:lane:tile:x:y use:

           --read-coords '([!-9;-?A-~]+:[0-9]+:[0-9]+:[0-9]+:[0-9]+):([0-9]+):([0-9]+)'
           --coords-order txy

       To match only the coordinates of x:y:randomstuff use:

           --read-coords '^([[:digit:]]+):([[:digit:]]+)'
           --coords-order xy

       It  is  possible that complex regular expressions may slow the running of the program.  It
       would be best to keep them simple.

AUTHOR

       Written by Andrew Whitwham from the Sanger Institute.

SEE ALSO

       samtools(1), samtools-sort(1), samtools-collate(1), samtools-fixmate(1)

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