docs/bdgopt.md

   1 # bdgopt
   2
   3 ## Overview
   4 The `bdgopt` command is part of the MACS3 suite of tools and is used
   5 to modify a single bedGraph file. It provides various operations to
   6 modify the value in the fourth column of the bedGraph file -- the
   7 score column.
   8
   9 ## Detailed Description
  10
  11 The `bdgopt` command takes an input bedGraph file and produces an
  12 output file with modified scores. It uses various methods to modify
  13 the scores in the bedGraph files, greatly improving the flexibility of
  14 your data for further analysis. Operations on score column of bedGraph
  15 file include multiplication, addition, maximization with a given
  16 value, minimization with a given value, and pvalue-to-qvalue
  17 conversion (-log10 form).  Note: All regions on the same chromosome in
  18 the bedGraph file should be continuous. We recommend to use the
  19 bedGraph files from MACS3.
  20
  21 ## Command Line Options
  22
  23 Here is a brief overview of the commandline options:
  24
  25 - `-i` or `--ifile`: A bedGraph file containing scores. Note: this
  26   must be a bedGraph file covering the ENTIRE genome. REQUIRED
  27 - `-m` or `--method`: Method to modify the score column of the
  28   bedGraph file. Available choices are: multiply, add, max, min, or
  29   p2q.
  30     - `multiply`: The EXTRAPARAM is required and will be multiplied to
  31       the score column. If you intend to divide the score column by X,
  32       use the value of 1/X as EXTRAPARAM.
  33     - `add`: The EXTRAPARAM is required and will be added to the score
  34       column. If you intend to subtract the score column by X, use the
  35       value of -X as EXTRAPARAM.
  36     - `max`: The EXTRAPARAM is required and will take the maximum
  37       value between the score and the EXTRAPARAM.
  38     - `min`: The EXTRAPARAM is required and will take the minimum
  39       value between the score and the EXTRAPARAM.
  40     - `p2q`: This will convert p-value scores to q-value scores using
  41       the Benjamini-Hochberg process. The EXTRAPARAM is not
  42       required. This method assumes the scores are -log10 p-value from
  43       MACS3. Any other types of scores will cause unexpected errors.
  44 - `-p` or `--extra-param`: The extra parameter for METHOD. Check the
  45   detail of the -m option.
  46 - `--outdir`: If specified, all output files will be written to that
  47   directory. Default: the current working directory
  48 - `-o` or `--ofile`: Output BEDGraph filename.
  49 - `--verbose`: Set the verbose level of runtime messages. 0: only show
  50   critical messages, 1: show additional warning messages, 2: show
  51   process information, 3: show debug messages. DEFAULT: 2
  52
  53
  54 ## Example Usage
  55
  56 Here is an example of how to use the `bdgopt` command:
  57
  58 ```bash
  59 macs3 bdgopt -i input.bedGraph -o output.bedGraph --method multiply --extraparam 2.0
  60 ```
  61
  62 In this example, the program will modify the scores in the
  63 `input.bedGraph` file and write the result to `output.bedGraph`. The
  64 method used for modification is `multiply`, and the extra parameter is
  65 set to 2.0, meaning that all scores will be multiplied by 2.0.
  66
  67 Some use cases for `bdgopt`:
  68
  69 1. If you plan to scale up or down the scores in the bedGraph file,
  70    you can use `-m multiply` with a larger than 1 (>1) EXTRAPARAM in
  71    `-p` to scale up, or a positive value smaller than 1 (>0 and <1)
  72    EXTRAPARAM in `-p` to scale up; or `-m add` with a positive value
  73    in `-p` to increase the scores by a fixed amount or a negative
  74    value to decrease the scores.
  75 2. If you want to cap the score in the bedGraph, you can use `-m max`
  76    with the upper limit score you want to use in `-p`. If you want to
  77    set the minimum score in the bedGraph, for example to set the whole
  78    genome background signal in the MACS control lambda track, you can
  79    use `-m min` with the value in `-p`.
  80