docs/bdgcmp.md

   1 # bdgcmp
   2
   3 ## Overview
   4 The `bdgcmp` command is part of the MACS3 suite of tools and is used
   5 to compare two bedGraph files in each basepair that are commonly
   6 covered by the two files. The typical use case is to calculate pvalue
   7 or qvalue using Poisson model for each basepair given a treatment
   8 pileup signal file in bedGraph format and a control lambda bedGraph
   9 file. But we provides more functions rather than pvalue and qvalue,
  10 including subtract, division (FE) and more.
  11
  12 ## Detailed Description
  13
  14 The `bdgcmp` command takes two input bedGraph files (e.g. a control
  15 and a treatment bedgraph) and produces an output bedGraph of
  16 comparison scores for each genomic position involved in the bedGraph
  17 files. The `bdgcmp` command normally is used to deduct noise from a
  18 signal track in bedGraph (e.g. ChIP treatment) over another signal
  19 track in bedGraph (e.g. control). Note: All regions on the same
  20 chromosome in the bedGraph file should be continuous so we recommand
  21 you use the bedGraph files from MACS3. We provide the following
  22 function to 'compare two tracks':
  23
  24 - `ppois` Poisson p-value (-log10(pvalue) form) using the second file
  25   (-c) as lambda and treatment (-t) as observation
  26 - `qpoi`s The q-value through a BH process for poisson pvalues
  27 - `subtract` Subtraction from treatment
  28 - `FE` linear scale fold enrichment, or the score from file A divided
  29   by the score from file B
  30 - `logFE` log10 fold enrichment(need to set pseudocount)
  31 - `logLR` log10 likelihood between ChIP-enriched model and open
  32   chromatin model (need to set pseudocount)
  33 - `slogLR` symmetric log10 likelihood between two ChIP-enrichment
  34   models using Poison distribution, and this can be used to compare
  35   ChIP signals from two differen conditions (differential binding)
  36 - `max` Maximum value between the two tracks.
  37
  38 ## Command Line Options
  39
  40 Here is a brief description of the command line options for `bdgcmp` :
  41
  42 - `-t` or `--tfile`: Treatment bedGraph file, e.g. *_treat_pileup.bdg
  43   from MACS. REQUIRED
  44 - `-c` or `--cfile`: Control bedGraph file, e.g. *_control_lambda.bdg
  45   from MACS. REQUIRED
  46 - `-S` or `--scaling-factor`: Scaling factor for treatment and control
  47   track. Keep it as 1.0 or default in most cases. Set it ONLY while
  48   you have SPMR output from MACS3 callpeak, and plan to calculate
  49   scores as MACS3 callpeak module. If you want to simulate 'callpeak'
  50   w/o '--to-large', calculate effective smaller sample size after
  51   filtering redundant reads in million (e.g., put 31.415926 if
  52   effective reads are 31,415,926) and input it for '-S'; for 'callpeak
  53   --to-large', calculate effective reads in a larger sample. DEFAULT:
  54   1.0
  55 - `-p` or `--pseudocount`: The pseudocount used for calculating logLR,
  56   logFE or FE. The count will be applied after normalization of
  57   sequencing depth. DEFAULT: 0.0, no pseudocount is applied.
  58 - `-m` or `--method`: Method to use while calculating a score in any
  59   bin by comparing the treatment value and control value. Available
  60   choices are: `ppois`, `qpois`, `subtract`, `logFE`,` logLR`,
  61   `slogLR`, and `max`. They represent Poisson P-value (-log10(pvalue)
  62   form) using control as lambda and treatment as observation, q-value
  63   through a BH process for Poisson p-values, subtraction from
  64   treatment, linear scale fold enrichment, log10 fold enrichment (need
  65   to set pseudocount), log10 likelihood between ChIP-enriched model
  66   and open chromatin model (need to set pseudocount), symmetric log10
  67   likelihood between two ChIP-enrichment models, or the maximum value
  68   between the two tracks. The default option is ppois.
  69 - `--verbose`: Set the verbose level of runtime messages. 0: only show
  70   critical messages, 1: show additional warning messages, 2: show
  71   process information, 3: show debug messages. DEFAULT: 2
  72 - `--outdir`: If specified, all output files will be written to that
  73   directory. Default: the current working directory
  74 - `--o-prefix`: The PREFIX of the output bedGraph file to write
  75   scores. If it is given as A, and the method is 'ppois', the output
  76   file will be A_ppois.bdg. Mutually exclusive with -o/--ofile.
  77 - `-o` or `--ofile`: Output filename. Mutually exclusive with
  78   --o-prefix. The number and the order of arguments for --ofile must
  79   be the same as for -m.
  80
  81 ## Example Usage
  82
  83 Here is an example of how to use the `bdgcmp` command:
  84
  85 ```bash
  86 macs3 bdgcmp -t treatment.bedGraph -c control.bedGraph -m ppois -p 1.0 -S 1.0 -o output.bedGraph
  87 ```
  88
  89 In this example, the program will compare the `treatment.bedGraph`
  90 file and the `control.bedGraph` file and write the result to
  91 `output.bedGraph`. The method used for comparison is `ppois`, the
  92 pseudo-count is set to 1.0, and the scaling factor is set to 1.0.