| blob | fcc96119f20aad00d090bb69d2a6496d85ffde4a |
1 # MACS: Model-based Analysis for ChIP-Seq
3  [](https://github.com/taoliu/MACS/blob/master/LICENSE)   [](https://travis-ci.com/taoliu/MACS)
5 [](https://pypistats.org/packages/macs2) [](https://anaconda.org/bioconda/macs2)
7 Latest Release:
8 * Github: [](https://github.com/taoliu/MACS/releases)
9 * PyPI: [  ](https://pypi.org/project/macs2/)
10 * Bioconda: [ ](https://anaconda.org/bioconda/macs2)
11 * Debian Med: [](https://packages.debian.org/stable/macs) [](https://packages.debian.org/sid/macs)
13 ## Introduction
15 With the improvement of sequencing techniques, chromatin
16 immunoprecipitation followed by high throughput sequencing (ChIP-Seq)
17 is getting popular to study genome-wide protein-DNA interactions. To
18 address the lack of powerful ChIP-Seq analysis method, we presented
19 the **M**odel-based **A**nalysis of **C**hIP-**S**eq (MACS), for
20 identifying transcript factor binding sites. MACS captures the
21 influence of genome complexity to evaluate the significance of
22 enriched ChIP regions and MACS improves the spatial resolution of
23 binding sites through combining the information of both sequencing tag
24 position and orientation. MACS can be easily used for ChIP-Seq data
25 alone, or with a control sample with the increase of
26 specificity. Moreover, as a general peak-caller, MACS can also be
27 applied to any "DNA enrichment assays" if the question to be asked is
28 simply: *where we can find significant reads coverage than the random
29 background*.
31 ## Recent Changes for MACS (2.2.6)
33 ### 2.2.6
34 * New Features
36 1) Speed up MACS2. Some programming tricks and code cleanup. The
37 filter_dup function replaces separate_dups. The later one was
38 implemented for potentially putting back duplicate reads in
39 certain downstream analysis. However such analysis hasn't been
40 implemented. Optimize speed of writing bedGraph files. Optimize
41 BAM and BAMPE parsing with pointer casting instead of python
42 unpack.
44 2) The comment lines in the headers of BED or SAM files will be
45 correctly skipped. However, MACS2 won't check comment lines in the
46 middle of the file.
48 * Bugs fixed
50 1) Cutoff-analysis in callpeak command. #341
52 2) Issues related to SAMParser and three ELAND Parsers are
53 fixed. #347
55 * Other
57 1) cmdlinetest script in test/ folder has been updated to: 1. test
58 cutoff-analysis with callpeak cmd; 2. output the 2 lines before
59 and after the error or warning message during tests; 3. output
60 only the first 10 lines if the difference between test result and
61 standard result can be found; 4. prockreport monitor CPU time and
62 memory usage in 1 sec interval -- a bit more accurate.
64 2) Python3.5 support is removed. Now MACS2 requires Python>=3.6.
66 ### 2.2.5
67 * Features added
69 1) *Github code only and Not included in MACS2 release* New
70 testing data for performance test. An subsampled ENCODE2 CTCF
71 ChIP-seq dataset, including 5million ChIP reads and 5 million
72 control reads, has been included in the test folder for testing
73 CPU and memory usage (i.e. 5M test). Several related scripts ,
74 including `prockreport` for output cpu memory usage, `pyprofile`
75 and `pyprofile_stat` for debuging and profiling MACS2 codes, have
76 been included.
78 2) Speed up pvalue-qvalue checkup (pqtable checkup) #335 #338.
79 The old hashtable.pyx implementation copied from Pandas (very old
80 version) doesn't work well in Python3+Cython. It slows down the
81 pqtable checkup using the identical Cython codes as in
82 v2.1.4. While running 5M test, the `__getitem__` function in the
83 hashtable.pyx took 3.5s with 37,382,037 calls in MACS2 v2.1.4, but
84 148.6s with the same number of calls in MACS2 v2.2.4. As a
85 consequence, the standard python dictionary implementation has
86 replaced hashtable.pyx for pqtable checkup. Now MACS2 runs a bit
87 faster than py2 version, but uses a bit more memory. In general,
88 v2.2.5 can finish 5M reads test in 20% less time than MACS2
89 v2.1.4, but use 15% more memory.
91 * Bug fixed
93 1) More Python3 related fixes, e.g. the return value of keys from
94 py3 dict. #333 #337
96 ## Install
98 Please check the file 'INSTALL.md' in the distribution.
100 ## Usage
102 ```
103 macs2 [-h] [--version]
104 {callpeak,bdgpeakcall,bdgbroadcall,bdgcmp,bdgopt,cmbreps,bdgdiff,filterdup,predictd,pileup,randsample,refinepeak}
105 ```
107 Example for regular peak calling: `macs2 callpeak -t ChIP.bam -c
108 Control.bam -f BAM -g hs -n test -B -q 0.01`
110 Example for broad peak calling: `macs2 callpeak -t ChIP.bam -c
111 Control.bam --broad -g hs --broad-cutoff 0.1`
113 There are twelve functions available in MAC2S serving as sub-commands.
115 Subcommand | Description
116 -----------|----------
117 `callpeak` | Main MACS2 Function to call peaks from alignment results.
118 `bdgpeakcall` | Call peaks from bedGraph output.
119 `bdgbroadcall` | Call broad peaks from bedGraph output.
120 `bdgcmp` | Comparing two signal tracks in bedGraph format.
121 `bdgopt` | Operate the score column of bedGraph file.
122 `cmbreps` | Combine BEDGraphs of scores from replicates.
123 `bdgdiff` | Differential peak detection based on paired four bedGraph files.
124 `filterdup` | Remove duplicate reads, then save in BED/BEDPE format.
125 `predictd` | Predict d or fragment size from alignment results.
126 `pileup` | Pileup aligned reads (single-end) or fragments (paired-end)
127 `randsample` | Randomly choose a number/percentage of total reads.
128 `refinepeak` | Take raw reads alignment, refine peak summits.
130 We only cover `callpeak` module in this document. Please use `macs2
131 COMMAND -h` to see the detail description for each option of each
132 module.
134 ### Call peaks
136 This is the main function in MACS2. It can be invoked by 'macs2
137 callpeak' command. If you type this command without parameters, you
138 will see a full description of command-line options. Here we only list
139 the essential options.
141 #### Essential Options
143 ##### `-t/--treatment FILENAME`
145 This is the only REQUIRED parameter for MACS. The file can be in any
146 supported format specified by `--format` option. Check `--format` for
147 detail. If you have more than one alignment file, you can specify them
148 as `-t A B C`. MACS will pool up all these files together.
150 ##### `-c/--control`
152 The control or mock data file. Please follow the same direction as for
153 `-t`/`--treatment`.
155 ##### `-n/--name`
157 The name string of the experiment. MACS will use this string NAME to
158 create output files like `NAME_peaks.xls`, `NAME_negative_peaks.xls`,
159 `NAME_peaks.bed` , `NAME_summits.bed`, `NAME_model.r` and so on. So
160 please avoid any confliction between these filenames and your existing
161 files.
163 ##### `--outdir`
165 MACS2 will save all output files into the specified folder for this
166 option.
168 ##### `-f/--format FORMAT`
170 Format of tag file can be `ELAND`, `BED`, `ELANDMULTI`, `ELANDEXPORT`,
171 `ELANDMULTIPET` (for pair-end tags), `SAM`, `BAM`, `BOWTIE`, `BAMPE`
172 or `BEDPE`. Default is `AUTO` which will allow MACS to decide the
173 format automatically. `AUTO` is also useful when you combine different
174 formats of files. Note that MACS can't detect `BAMPE` or `BEDPE`
175 format with `AUTO`, and you have to implicitly specify the format for
176 `BAMPE` and `BEDPE`.
178 Nowadays, the most common formats are BED or BAM/SAM.
180 ###### BED
181 The BED format can be found at [UCSC genome browser
182 website](http://genome.ucsc.edu/FAQ/FAQformat#format1).
184 The essential columns in BED format input are the 1st column
185 `chromosome name`, the 2nd `start position`, the 3rd `end position`,
186 and the 6th, `strand`.
188 Note that, for BED format, the 6th column of strand information is
189 required by MACS. And please pay attention that the coordinates in BED
190 format are zero-based and half-open
191 (http://genome.ucsc.edu/FAQ/FAQtracks#tracks1).
193 ###### BAM/SAM
195 If the format is BAM/SAM, please check the definition in
196 (http://samtools.sourceforge.net/samtools.shtml). If the BAM file is
197 generated for paired-end data, MACS will only keep the left mate(5'
198 end) tag. However, when format BAMPE is specified, MACS will use the
199 real fragments inferred from alignment results for reads pileup.
201 ###### BEDPE or BAMPE
203 A special mode will be triggered while the format is specified as
204 'BAMPE' or 'BEDPE'. In this way, MACS2 will process the BAM or BED
205 files as paired-end data. Instead of building a bimodal distribution
206 of plus and minus strand reads to predict fragment size, MACS2 will
207 use actual insert sizes of pairs of reads to build fragment pileup.
209 The BAMPE format is just a BAM format containing paired-end alignment
210 information, such as those from BWA or BOWTIE.
212 The BEDPE format is a simplified and more flexible BED format, which
213 only contains the first three columns defining the chromosome name,
214 left and right position of the fragment from Paired-end
215 sequencing. Please note, this is NOT the same format used by BEDTOOLS,
216 and the BEDTOOLS version of BEDPE is actually not in a standard BED
217 format. You can use MACS2 subcommand `randsample` to convert a BAM
218 file containing paired-end information to a BEDPE format file:
220 ```
221 macs2 randsample -i the_BAMPE_file.bam -f BAMPE -p 100 -o the_BEDPE_file.bed
222 ```
224 ##### `-g/--gsize`
226 PLEASE assign this parameter to fit your needs!
228 It's the mappable genome size or effective genome size which is
229 defined as the genome size which can be sequenced. Because of the
230 repetitive features on the chromosomes, the actual mappable genome
231 size will be smaller than the original size, about 90% or 70% of the
232 genome size. The default *hs* -- 2.7e9 is recommended for human
233 genome. Here are all precompiled parameters for effective genome size:
235 * hs: 2.7e9
236 * mm: 1.87e9
237 * ce: 9e7
238 * dm: 1.2e8
240 Users may want to use k-mer tools to simulate mapping of Xbps long
241 reads to target genome, and to find the ideal effective genome
242 size. However, usually by taking away the simple repeats and Ns from
243 the total genome, one can get an approximate number of effective
244 genome size. A slight difference in the number won't cause a big
245 difference of peak calls, because this number is used to estimate a
246 genome-wide noise level which is usually the least significant one
247 compared with the *local biases* modeled by MACS.
249 ##### `-s/--tsize`
251 The size of sequencing tags. If you don't specify it, MACS will try to
252 use the first 10 sequences from your input treatment file to determine
253 the tag size. Specifying it will override the automatically determined
254 tag size.
256 ##### `-q/--qvalue`
258 The q-value (minimum FDR) cutoff to call significant regions. Default
259 is 0.05. For broad marks, you can try 0.05 as the cutoff. Q-values are
260 calculated from p-values using the Benjamini-Hochberg procedure.
262 ##### `-p/--pvalue`
264 The p-value cutoff. If `-p` is specified, MACS2 will use p-value instead
265 of q-value.
267 ##### `--min-length`, `--max-gap`
269 These two options can be used to fine-tune the peak calling behavior
270 by specifying the minimum length of a called peak and the maximum
271 allowed a gap between two nearby regions to be merged. In another
272 word, a called peak has to be longer than *min-length*, and if the
273 distance between two nearby peaks is smaller than *max-gap* then they
274 will be merged as one. If they are not set, MACS2 will set the DEFAULT
275 value for *min-length* as the predicted fragment size *d*, and the
276 DEFAULT value for *max-gap* as the detected read length. Note, if you
277 set a *min-length* value smaller than the fragment size, it may have
278 NO effect on the result. For BROAD peak calling, try to set a large
279 value such as 500bps. You can also use '--cutoff-analysis' option with
280 the default setting, and check the column 'avelpeak' under different
281 cutoff values to decide a reasonable *min-length* value.
283 ##### `--nolambda`
285 With this flag on, MACS will use the background lambda as local
286 lambda. This means MACS will not consider the local bias at peak
287 candidate regions.
289 ##### `--slocal`, `--llocal`
291 These two parameters control which two levels of regions will be
292 checked around the peak regions to calculate the maximum lambda as
293 local lambda. By default, MACS considers 1000bp for small local
294 region(`--slocal`), and 10000bps for large local region(`--llocal`)
295 which captures the bias from a long-range effect like an open
296 chromatin domain. You can tweak these according to your
297 project. Remember that if the region is set too small, a sharp spike
298 in the input data may kill a significant peak.
300 ##### `--nomodel`
302 While on, MACS will bypass building the shifting model.
304 ##### `--extsize`
306 While `--nomodel` is set, MACS uses this parameter to extend reads in
307 5'->3' direction to fix-sized fragments. For example, if the size of
308 the binding region for your transcription factor is 200 bp, and you
309 want to bypass the model building by MACS, this parameter can be set
310 as 200. This option is only valid when `--nomodel` is set or when MACS
311 fails to build model and `--fix-bimodal` is on.
313 ##### `--shift`
315 Note, this is NOT the legacy `--shiftsize` option which is replaced by
316 `--extsize`! You can set an arbitrary shift in bp here. Please Use
317 discretion while setting it other than the default value (0). When
318 `--nomodel` is set, MACS will use this value to move cutting ends (5')
319 then apply `--extsize` from 5' to 3' direction to extend them to
320 fragments. When this value is negative, ends will be moved toward
321 3'->5' direction, otherwise 5'->3' direction. Recommended to keep it
322 as default 0 for ChIP-Seq datasets, or -1 * half of *EXTSIZE* together
323 with `--extsize` option for detecting enriched cutting loci such as
324 certain DNAseI-Seq datasets. Note, you can't set values other than 0
325 if the format is BAMPE or BEDPE for paired-end data. The default is 0.
327 Here are some examples for combining `--shift` and `--extsize`:
329 1. To find enriched cutting sites such as some DNAse-Seq datasets. In
330 this case, all 5' ends of sequenced reads should be extended in both
331 directions to smooth the pileup signals. If the wanted smoothing
332 window is 200bps, then use `--nomodel --shift -100 --extsize 200`.
334 2. For certain nucleosome-seq data, we need to pile up the centers of
335 nucleosomes using a half-nucleosome size for wavelet analysis
336 (e.g. NPS algorithm). Since the DNA wrapped on nucleosome is about
337 147bps, this option can be used: `--nomodel --shift 37 --extsize 73`.
339 ##### `--keep-dup`
341 It controls the MACS behavior towards duplicate tags at the exact same
342 location -- the same coordination and the same strand. The default
343 'auto' option makes MACS calculate the maximum tags at the exact same
344 location based on binomial distribution using 1e-5 as p-value cutoff;
345 and the 'all' option keeps every tags. If an integer is given, at
346 most this number of tags will be kept at the same location. The
347 default is to keep one tag at the same location. Default: 1
349 ##### `--broad`
351 When this flag is on, MACS will try to composite broad regions in
352 BED12 ( a gene-model-like format ) by putting nearby highly enriched
353 regions into a broad region with loose cutoff. The broad region is
354 controlled by another cutoff through `--broad-cutoff`. The maximum
355 length of broad region length is 4 times of d from MACS. DEFAULT:
356 False
358 ##### `--broad-cutoff`
360 Cutoff for the broad region. This option is not available unless
361 `--broad` is set. If `-p` is set, this is a p-value cutoff, otherwise,
362 it's a q-value cutoff. DEFAULT: 0.1
364 ##### `--scale-to <large|small>`
366 When set to "large", linearly scale the smaller dataset to the same
367 depth as larger dataset. By default or being set as "small", the
368 larger dataset will be scaled towards the smaller dataset. Beware, to
369 scale up small data would cause more false positives.
371 ##### `-B/--bdg`
373 If this flag is on, MACS will store the fragment pileup, control
374 lambda in bedGraph files. The bedGraph files will be stored in the
375 current directory named `NAME_treat_pileup.bdg` for treatment data,
376 `NAME_control_lambda.bdg` for local lambda values from control.
378 ##### `--call-summits`
380 MACS will now reanalyze the shape of signal profile (p or q-score
381 depending on the cutoff setting) to deconvolve subpeaks within each
382 peak called from the general procedure. It's highly recommended to
383 detect adjacent binding events. While used, the output subpeaks of a
384 big peak region will have the same peak boundaries, and different
385 scores and peak summit positions.
387 ##### `--buffer-size`
389 MACS uses a buffer size for incrementally increasing internal array
390 size to store reads alignment information for each chromosome or
391 contig. To increase the buffer size, MACS can run faster but will
392 waste more memory if certain chromosome/contig only has very few
393 reads. In most cases, the default value 100000 works fine. However, if
394 there are a large number of chromosomes/contigs in your alignment and
395 reads per chromosome/contigs are few, it's recommended to specify a
396 smaller buffer size in order to decrease memory usage (but it will
397 take longer time to read alignment files). Minimum memory requested
398 for reading an alignment file is about # of CHROMOSOME * BUFFER_SIZE *
399 8 Bytes. DEFAULT: 100000
401 #### Output files
403 1. `NAME_peaks.xls` is a tabular file which contains information about
404 called peaks. You can open it in excel and sort/filter using excel
405 functions. Information include:
407 - chromosome name
408 - start position of peak
409 - end position of peak
410 - length of peak region
411 - absolute peak summit position
412 - pileup height at peak summit
413 - -log10(pvalue) for the peak summit (e.g. pvalue =1e-10, then
414 this value should be 10)
415 - fold enrichment for this peak summit against random Poisson
416 distribution with local lambda,
417 - -log10(qvalue) at peak summit
419 Coordinates in XLS is 1-based which is different from BED
420 format. When `--broad` is enabled for broad peak calling, the
421 pileup, p-value, q-value, and fold change in the XLS file will be
422 the mean value across the entire peak region, since peak summit
423 won't be called in broad peak calling mode.
425 2. `NAME_peaks.narrowPeak` is BED6+4 format file which contains the
426 peak locations together with peak summit, p-value, and q-value. You
427 can load it to the UCSC genome browser. Definition of some specific
428 columns are:
430 - 5th: integer score for display. It's calculated as
431 `int(-10*log10pvalue)` or `int(-10*log10qvalue)` depending on
432 whether `-p` (pvalue) or `-q` (qvalue) is used as score
433 cutoff. Please note that currently this value might be out of the
434 [0-1000] range defined in [UCSC ENCODE narrowPeak
435 format](https://genome.ucsc.edu/FAQ/FAQformat.html#format12). You
436 can let the value saturated at 1000 (i.e. p/q-value = 10^-100) by
437 using the following 1-liner awk: `awk -v OFS="\t"
438 '{$5=$5>1000?1000:$5} {print}' NAME_peaks.narrowPeak`
439 - 7th: fold-change at peak summit
440 - 8th: -log10pvalue at peak summit
441 - 9th: -log10qvalue at peak summit
442 - 10th: relative summit position to peak start
444 The file can be loaded directly to the UCSC genome browser. Remove
445 the beginning track line if you want to analyze it by other tools.
447 3. `NAME_summits.bed` is in BED format, which contains the peak
448 summits locations for every peak. The 5th column in this file is
449 the same as what is in the `narrowPeak` file. If you want to find
450 the motifs at the binding sites, this file is recommended. The file
451 can be loaded directly to the UCSC genome browser. Remove the
452 beginning track line if you want to analyze it by other tools.
454 4. `NAME_peaks.broadPeak` is in BED6+3 format which is similar to
455 `narrowPeak` file, except for missing the 10th column for
456 annotating peak summits. This file and the `gappedPeak` file will
457 only be available when `--broad` is enabled. Since in the broad
458 peak calling mode, the peak summit won't be called, the values in
459 the 5th, and 7-9th columns are the mean value across all positions
460 in the peak region. Refer to `narrowPeak` if you want to fix the
461 value issue in the 5th column.
463 5. `NAME_peaks.gappedPeak` is in BED12+3 format which contains both
464 the broad region and narrow peaks. The 5th column is the score for
465 showing grey levels on the UCSC browser as in `narrowPeak`. The 7th
466 is the start of the first narrow peak in the region, and the 8th
467 column is the end. The 9th column should be RGB color key, however,
468 we keep 0 here to use the default color, so change it if you
469 want. The 10th column tells how many blocks including the starting
470 1bp and ending 1bp of broad regions. The 11th column shows the
471 length of each block and 12th for the start of each block. 13th:
472 fold-change, 14th: *-log10pvalue*, 15th: *-log10qvalue*. The file can
473 be loaded directly to the UCSC genome browser. Refer to
474 `narrowPeak` if you want to fix the value issue in the 5th column.
476 6. `NAME_model.r` is an R script which you can use to produce a PDF
477 image of the model based on your data. Load it to R by:
479 `$ Rscript NAME_model.r`
481 Then a pdf file `NAME_model.pdf` will be generated in your current
482 directory. Note, R is required to draw this figure.
484 7. The `NAME_treat_pileup.bdg` and `NAME_control_lambda.bdg` files are
485 in bedGraph format which can be imported to the UCSC genome browser
486 or be converted into even smaller bigWig files. The
487 `NAME_treat_pielup.bdg` contains the pileup signals (normalized
488 according to `--scale-to` option) from ChIP/treatment sample. The
489 `NAME_control_lambda.bdg` contains local biases estimated for each
490 genomic location from the control sample, or from treatment sample
491 when the control sample is absent. The subcommand `bdgcmp` can be
492 used to compare these two files and make a bedGraph file of scores
493 such as p-value, q-value, log-likelihood, and log fold changes.
495 ## Other useful links
497 * [Cistrome](http://cistrome.org/ap/)
498 * [bedTools](http://code.google.com/p/bedtools/)
499 * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/)
501 ## Tips of fine-tuning peak calling
503 There are several subcommands within MACSv2 package to fine-tune or
504 customize your analysis:
506 1. `bdgcmp` can be used on `*_treat_pileup.bdg` and
507 `*_control_lambda.bdg` or bedGraph files from other resources to
508 calculate the score track.
510 2. `bdgpeakcall` can be used on `*_treat_pvalue.bdg` or the file
511 generated from bdgcmp or bedGraph file from other resources to call
512 peaks with given cutoff, maximum-gap between nearby mergeable peaks
513 and a minimum length of peak. bdgbroadcall works similarly to
514 bdgpeakcall, however, it will output `_broad_peaks.bed` in BED12
515 format.
517 3. Differential calling tool -- `bdgdiff`, can be used on 4 bedGraph
518 files which are scores between treatment 1 and control 1, treatment
519 2 and control 2, treatment 1 and treatment 2, treatment 2 and
520 treatment 1. It will output consistent and unique sites according
521 to parameter settings for minimum length, the maximum gap and
522 cutoff.
524 4. You can combine subcommands to do a step-by-step peak calling. Read
525 detail at [MACS2
526 wikipage](https://github.com/taoliu/MACS/wiki/Advanced%3A-Call-peaks-using-MACS2-subcommands)