docs/bdgbroadcall.md

   1 # bdgbroadcall
   2
   3 ## Overview
   4 The `bdgbroadcall` subcommand of the MACS3 suite identifies 'nested'
   5 broad peaks from a single bedGraph track for scores, a function
   6 essential in certain ChIP-Seq analyses.
   7
   8 ## Detailed Description
   9
  10 The `bdgbroadcall` command takes an input bedGraph file and produces
  11 an output file with broad peaks called. It is important to note: only
  12 bedGraph files from MACS3 are acceptable to use in the `bdgbroadcall`
  13 command, as All regions on the same chromosome in the bedGraph file
  14 should be continuous.
  15
  16 Unlike narrow peak calling performed using `bdgpeakcall` or `callpeak`
  17 without the `--broad` option, this command, along with the `--broad`
  18 option in `callpeak`, facilitates broad peak calling, producing
  19 results in the UCSC gappedPeak format which encapsulates a nested
  20 structure of peaks. To conceptualize 'nested' peaks, picture a gene
  21 structure housing regions analogous to exons (strong peaks) and
  22 introns coupled with UTRs (weak peaks). The broad peak calling process
  23 utilizes two distinct cutoffs to discern broader, weaker peaks and
  24 narrower, stronger peaks, which are subsequently nested to provide a
  25 detailed peak landscape.
  26
  27 Please note that, if you only want to call 'broader' peak and not
  28 interested in the nested peak structure, please simply use
  29 `bdgpeakcall` with weaker cutoff.
  30
  31 ## Command Line Options
  32
  33 The command line options for `bdgbroadcall` are defined in `macs3
  34 bdgbroadcall --help` command. Here is a brief overview of these
  35 options:
  36
  37 - `-i` or `--ifile`: Genome-wide score for each possible location in
  38   bedGraph format. This is REQUIRED.
  39 - `-c` or `--cutoff-peak`: Cutoff for stronger and narrower peaks
  40   depending on which method you used for the score track. If the file
  41   contains qvalue scores from MACS3, score 2 means qvalue 0.01.
  42   DEFAULT: 2
  43 - `-C` or `--cutoff-link`: Cutoff for weaker and broader regions
  44   depending on which method you used for the score track. If the file
  45   contains qvalue scores from MACS3, score 1 means qvalue 0.1, and
  46   score 0.3 means qvalue 0.5. DEFAULT: 1
  47 - `-l` or `--min-length`: Minimum length of stronger peak, better to
  48   set it as d value. DEFAULT: 200
  49 - `-g` or `--lvl1-max-gap`: Maximum gap between stronger peaks, better
  50   to set it as the tag size. DEFAULT: 30
  51 - `-G` or `--lvl2-max-gap`: Maximum gap between weaker peaks, better
  52   to set it as 4 times the d value. DEFAULT: 800
  53 - `--no-trackline`: Tells MACS not to include a trackline with
  54   bedGraph files. The trackline is used by UCSC for display.
  55 - `--verbose`: Set verbose level of runtime messages. 0: only show
  56   critical messages, 1: show additional warning messages, 2: show
  57   process information, 3: show debug messages. DEFAULT: 2
  58 - `--outdir`: If specified, all output files will be written to that
  59   directory. Default: the current working directory
  60 - `-o` or `--ofile`: Output file name. Mutually exclusive with
  61   `--o-prefix`.
  62 - `--o-prefix`: Output file prefix. Mutually exclusive with
  63   `-o/--ofile`.
  64
  65 ## Example Usage
  66
  67 Here is an example of how to use the `bdgbroadcall` command:
  68
  69 ```
  70 macs3 bdgbroadcall -i input.bedGraph -o output.gappedPeak -c 2 -C 1.5 -l 500 -g 500 -G 1000
  71 ```
  72
  73 In this example, the program will call broad peaks from the
  74 `input.bedGraph` file and write the result to `output.gappedPeak`. The
  75 cutoff value for calling stronger peaks is set to 2.0, the minimum
  76 length of stronger peaks is set to 500, the maximum gap between
  77 stronger peaks is set to 500, the cutoff value for weaker peaks is set
  78 to 1.5, and the maximum gap for weaker peaks is set to 1000.
  79