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