docs/source/docs/cmbreps.md

   1 # cmbreps
   2
   3 ## Overview
   4 The `cmbreps` command is part of the MACS3 suite of tools and is used
   5 to combine bedGraph files from replicates. It is particularly useful
   6 in ChIP-Seq analysis where multiple replicates of the same experiment
   7 are performed.
   8
   9 ## Detailed Description
  10
  11 The `cmbreps` command takes a list of input bedGraph files
  12 (replicates) and produces an output file with combined scores. Note:
  13 All regions on the same chromosome in the bedGraph file should be
  14 continuous so bedGraph files from MACS3 are recommended.
  15
  16 The `cmbreps` command provides different way to combine replicates,
  17 compared with the `callpeak` command where all replicates will be
  18 simply pooled. A possible usage is that: for each replicate, we can
  19 first follow the instructions in the [Advanced Step-by-step Peak
  20 Calling](./Advanced_Step-by-step_Peak_Calling.md) to generate the
  21 p-value scores through `bdgcmp -m ppois`, use `cmbreps -m fisher` to
  22 use Fisher's combined probability test to combine all the p-value
  23 score tracks and generate a single BedGraph, then call peaks using
  24 `bdgpeakcall`.
  25
  26 ## Command Line Options
  27
  28 Here is a brief overview of command line options:
  29
  30 - `-i IFILE1 IFILE2 [IFILE3 ...]`: MACS score in bedGraph for each
  31   replicate. Require at least 2 files. REQUIRED
  32 - `-m` or `--method`: Method to use while combining scores from
  33   replicates.
  34   - `fisher`: Fisher's combined probability test. It requires scores
  35     in ppois form (-log10 pvalues) from `bdgcmp`. Other types of
  36     scores for this method may cause cmbreps unexpected errors.
  37   - `max`: Take the maximum value from replicates for each genomic
  38     position.
  39   - `mean`: Take the average value. Note, except for Fisher's method,
  40     max or mean will take scores AS IS which means they won't convert
  41     scores from log scale to linear scale or vice versa.
  42 - `--outdir`: If specified, all output files will be written to that
  43   directory. Default: the current working directory
  44 - `-o` or `--ofile`: Output BEDGraph filename for combined scores.
  45 - `--verbose`: Set the verbose level of runtime messages. 0: only show
  46   critical messages, 1: show additional warning messages, 2: show
  47   process information, 3: show debug messages. DEFAULT: 2
  48
  49
  50 ## Example Usage
  51
  52 Here is an example of how to use the `cmbreps` command:
  53
  54 ```bash
  55 macs3 cmbreps -i replicate1.bedGraph replicate2.bedGraph replicate3.bedGraph -o combined.bedGraph --method mean
  56 ```
  57
  58 In this example, the program will combine the scores in the
  59 `replicate1.bedGraph`, `replicate2.bedGraph`, and
  60 `replicate3.bedGraph` files and write the result to
  61 `combined.bedGraph`. The method used for combining scores is `mean` so
  62 it will take the average score from the three replicates at each
  63 genomic location.
  64