docs/pileup.md

   1 # pileup
   2
   3 ## Overview
   4 The `pileup` command is part of the MACS3 suite of tools and is used
   5 to pile up alignment files. It is a fast algorithm to generate
   6 coverage track from alignment file -- either single-end or paired-end
   7 data.
   8
   9 ## Detailed Description
  10
  11 The `pileup` command takes in one or multiple input files and produces
  12 an output file with the piled-up genomic coverage. It uses an
  13 efficient algorithm to pile up the alignments.
  14
  15 ![Pileup Algorithm](pileup.png)
  16
  17 Pileup aligned reads with a given extension size (fragment size or d
  18 in MACS language). Note there will be no step for duplicate reads
  19 filtering or sequencing depth scaling, so you may need to do certain
  20 pre/post-processing, such as using `filterdup` or `randsample`
  21 command.
  22
  23 ## Command Line Options
  24
  25 Here is a brief overview of the command line options for `pileup`:
  26
  27 - `-i` or `--ifile`: Alignment file. If multiple files are given as
  28   '-t A B C', then they will all be read and combined. REQUIRED.
  29 - `-o` or `--ofile`: Output bedGraph file name. If not specified, will
  30   write to standard output. REQUIRED.
  31 - `--outdir`: If specified, all output files will be written to that
  32   directory. Default: the current working directory
  33 - `-f ` or `--format`: Format of the tag file.
  34   - `AUTO`: MACS3 will pick a format from "AUTO", "BED", "ELAND",
  35     "ELANDMULTI", "ELANDEXPORT", "SAM", "BAM", and "BOWTIE". If the
  36     format is BAMPE or BEDPE, please specify it explicitly.
  37   - `BAMPE` or `BEDPE`: When the format is BAMPE or BEDPE, the -B and
  38     --extsize options would be ignored.
  39   - Other options correspond to specific formats.
  40 - `-B` or `--both-direction`: By default, any read will be extended
  41   towards the downstream direction by the extension size. If this
  42   option is set, aligned reads will be extended in both upstream and
  43   downstream directions by the extension size. This option will be
  44   ignored when the format is set as BAMPE or BEDPE. DEFAULT: False
  45 - `--extsize`: The extension size in bps. Each alignment read will
  46   become an EXTSIZE of the fragment, then be piled up. Check
  47   description for -B for details. This option will be ignored when the
  48   format is set as BAMPE or BEDPE. DEFAULT: 200
  49 - `--buffer-size`: Buffer size for incrementally increasing the
  50   internal array size to store read alignment information. In most
  51   cases, you don't have to change this parameter. However, if there
  52   are a large number of chromosomes/contigs/scaffolds in your
  53   alignment, it's recommended to specify a smaller buffer size in
  54   order to decrease memory usage (but it will take longer time to read
  55   alignment files). Minimum memory requested for reading an alignment
  56   file is about # of CHROMOSOME * BUFFER_SIZE * 8 Bytes. DEFAULT:
  57   100000
  58 - `--verbose`: Set verbose level. 0: only show critical messages, 1:
  59   show additional warning messages, 2: show process information, 3:
  60   show debug messages. If you want to know where are the duplicate
  61   reads, use 3. DEFAULT: 2
  62
  63 ## Example Usage
  64
  65 Here is an example of how to use the `pileup` command:
  66
  67 ```bash
  68 macs3 pileup -i treatment.bam -o piledup.bedGraph -f BAM --extsize 147
  69 ```
  70
  71 In this example, the program will pile up the alignments in the
  72 `treatment.bam` file and write the result to `piledup.bedGraph`. The
  73 input file is in BAM format, and we extend each sequencing tag into a
  74 147bps fragment for pileup.