docs/source/docs/filterdup.md

   1 # filterdup
   2
   3 ## Overview
   4 The `filterdup` command is part of the MACS3 suite of tools and is
   5 used on alignment files to remove duplicate reads.
   6
   7 ## Detailed Description
   8
   9 The `filterdup` command takes an input alignment file and produces an
  10 output file in BED format with duplicate reads removed according to
  11 the setting. When the input is in BAMPE format (BAM file from aligning
  12 paired-end data), it will produce a BEDPE format file where each row
  13 represent a read-pair.
  14
  15 The `filteredup` command can also be used to convert any acceptable
  16 format of MACS3 to BED or BEDPE (in case of `-f BAMPE`) format, if you
  17 use `--keep-dup all` option.
  18
  19 Please note that, when writing BED format output for single-end
  20 dataset, MACS3 assume all the reads having the same length either from
  21 `-s` setting or from auto-detection.
  22
  23 ## Command Line Options
  24
  25 Here is a brief overview of the command line options:
  26
  27 - `-i` or `--ifile`: The input alignment file. If multiple files are
  28   given as '-t A B C', then they will all be read and pooled. REQUIRED.
  29 - `-f`or `--format`: The format of the alignment file. Options
  30   include: "AUTO", "BED" or "ELAND" or "ELANDMULTI" or "ELANDEXPORT"
  31   or "SAM" or "BAM" or "BOWTIE" or "BAMPE" or "BEDPE". The default
  32   AUTO option will let `filterdup` decide which format the file
  33   is. Please check the [`callpeak`](./callpeak.md) for detail. Choices
  34   can be `ELAND/ELANDMULTI/ELANDEXPORT/SAM/BAM/BOWTIE` or
  35   `BAMPE/BEDPE`. DEFAULT: `AUTO`
  36 - `-g` or `--gsize`: Please check [`callpeak`](./callpeak.md) for
  37   detail. DEFAULT:hs
  38 - `-s` or `--tsize`: The tag size. This will override the auto
  39   detected tag size. DEFAULT: Not set
  40 - `-p` or `--pvalue`: The pvalue cutoff for binomial distribution
  41   test. DEFAULT:1e-5
  42 - `--keep-dup`: The number of duplicates to keep. It controls the
  43   'macs3 filterdup' behavior towards duplicate tags/pairs at the exact
  44   same location -- the same coordination and the same strand. If the
  45   value is `auto`, `filterdup` will calculate the maximum tags at the
  46   exact same location based on a binomal distribution using given `-p`
  47   as pvalue cutoff; and the `all` value will keep every tags (useful
  48   if you only want to convert formats). If an integer is given, at
  49   most this number of tags will be kept at the same location. Note,
  50   MACS3 `callpeak` function uses `--keep-dup=1` as default. Note, if
  51   you've used `samtools` or `picard` to flag reads as 'PCR/Optical
  52   duplicate' in bit 1024, MACS3 will still read them although the
  53   reads may be decided by MACS3 as duplicate later. Default: `auto`
  54 - `--buffer-size`: The buffer size for incrementally increasing
  55   internal array size to store reads alignment information. In most
  56   cases, you don't have to change this parameter. However, if there
  57   are large number of chromosomes/contigs/scaffolds in your alignment,
  58   it's recommended to specify a smaller buffer size in order to
  59   decrease memory usage (but it will take longer time to read
  60   alignment files). Minimum memory requested for reading an alignment
  61   file is about `# of CHROMOSOME * BUFFER_SIZE * 8` Bytes. DEFAULT:
  62   100000
  63 - `--verbose`: The verbose level. 0: only show critical message, 1:
  64   show additional warning message, 2: show process information, 3:
  65   show debug messages. If you want to know where are the duplicate
  66   reads, use 3. DEFAULT:2
  67 - `--outdir`: If specified all output files will be written to that
  68   directory. Default: the current working directory
  69 - `-o` or `--ofile`: The output BED file name. If not specified, will
  70   write to standard output. Note, if the input format is BAMPE or
  71   BEDPE, the output will be in BEDPE format. DEFAULT: stdout
  72 - `-d` or `--dry-run`: When set, filterdup will only output numbers
  73   instead of writing output files, including maximum allowable
  74   duplicates, total number of reads before filtering, total number of
  75   reads after filtering, and redundant rate. Default: not set
  76
  77 ## Example Usage
  78
  79 Here is an example of how to use the `filterdup` command:
  80
  81 ```bash
  82 macs3 filterdup -i input.bam -o output.bed --gsize hs --format AUTO --keep-dup 1 --buffer-size 100000
  83 ```
  84
  85 In this example, the program will remove duplicate reads from the
  86 `input.bam` file and write the result to `output.bed`. The mappable
  87 genome size is set to `hs` (Homo Sapiens), the format of the input
  88 file is determined automatically, and the program keeps only one
  89 duplicate.
  90
  91 Here is an example to convert BAMPE file into BEDPE. Please note that
  92 `-f BAMPE` and `--keep-dup all` are both necessary for format
  93 conversion:
  94
  95 ```bash
  96 macs3 filterdup -i input.bam -o output.bedpe -f BAMPE --keep-dup all
  97 ```