| blob | 1a2b86fcaaa6e14bf5be4cc7ccc0b4abfe6bdd20 |
1 # MACS: Model-based Analysis for ChIP-Seq
3      
5 [](https://pypistats.org/packages/macs3)
8 Latest Release:
9 * Github: [](https://github.com/macs3-project/MACS/releases)
10 * PyPI: [](https://pypi.org/project/MACS3/)
11 * Bioconda:[](https://anaconda.org/bioconda/macs3)
12 * Debian Med: [](https://packages.debian.org/stable/macs)[](https://packages.debian.org/sid/macs)
14 ## Introduction
16 With the improvement of sequencing techniques, chromatin
17 immunoprecipitation followed by high throughput sequencing (ChIP-Seq)
18 is getting popular to study genome-wide protein-DNA interactions. To
19 address the lack of powerful ChIP-Seq analysis method, we presented
20 the **M**odel-based **A**nalysis of **C**hIP-**S**eq (MACS), for
21 identifying transcript factor binding sites. MACS captures the
22 influence of genome complexity to evaluate the significance of
23 enriched ChIP regions and MACS improves the spatial resolution of
24 binding sites through combining the information of both sequencing tag
25 position and orientation. MACS can be easily used for ChIP-Seq data
26 alone, or with a control sample with the increase of
27 specificity. Moreover, as a general peak-caller, MACS can also be
28 applied to any "DNA enrichment assays" if the question to be asked is
29 simply: *where we can find significant reads coverage than the random
30 background*.
32 ## Changes for MACS (3.0.2)
34 ### Features added
36 1) Introduce a new emission model for the `hmmratac` function. Now
37 users can choose the simpler Poisson emission `--hmm-type poisson`
38 instead of the default Gaussian emission. As a consequence, the
39 saved HMM model file in json will include the hmm-type information
40 as well. Note that in order to be compatible with the HMM model
41 file from previous version, if there is no hmm-type information in
42 the model file, the hmm-type will be assigned as gaussian. #635
44 2) `hmmratac` now output narrowPeak format output. The summit
45 position and the peak score columns reported in the narrowPeak
46 output represents the position with highest foldchange value
47 (pileup vs average background).
49 3) Add `--cutoff-analysis-steps` and `--cutoff-analysis-max` for
50 `callpeak`, `bdgpeakcall`, and `hmmratac` so that we can
51 have finer resolution of the cutoff analysis report. #636 #642
53 4) Reduce memory usage of `hmmratac` during decoding step, by
54 writing decoding results to a temporary file on disk (file
55 location depends on the environmental TEMP setting), then loading
56 it back while identifying state pathes. This change will decrease
57 the memory usage dramatically. #628 #640
59 5) Fix instructions for preparing narrowPeak files for uploading
60 to UCSC browser, with the `--trackline` option in `callpeak`. #653
62 6) For gappedPeak output, set thickStart and thickEnd columns as
63 0, according to UCSC definition.
65 ### Bugs fixed
67 1) Use `-O3` instead of `-Ofast` for compatibility. #637
69 ### Documentation
71 1) Update instruction to install macs3 through conda/bioconda
73 2) Reorganize MACS3 docs and publish through
74 https://macs3-project.github.io/MACS
76 3) Description on various file formats used in MACS3.
78 ## Install
80 The common way to install MACS is through
81 [PYPI](https://pypi.org/project/macs3/)) or
82 [conda](https://anaconda.org/macs3/macs3). Please check the
83 [INSTALL](docs/INSTALL.md) document for detail.
85 MACS3 has been tested using GitHub Actions for every push and PR in
86 the following architectures:
88 * x86_64 (Ubuntu 22, Python 3.9, 3.10, 3.11)
89 * aarch64 (Ubuntu 22, Python 3.10)
90 * armv7 (Ubuntu 22, Python 3.10)
91 * ppc64le (Ubuntu 22, Python 3.10)
92 * s390x (Ubuntu 22, Python 3.10)
93 * Apple chips (Mac OS 13, Python 3.11)
95 In general, you can install through PyPI as `pip install macs3`. To
96 use virtual environment is highly recommended. Or you can install
97 after unzipping the released package downloaded from Github, then use
98 `pip install .` command. Please note that, we haven't tested
99 installation on any Windows OS, so currently only Linux and Mac OS
100 systems are supported. Also, for aarch64, armv7, ppc64le and s390x,
101 due to some unknown reason potentially related to the scientific
102 calculation libraries MACS3 depends on, such as Numpy, Scipy,
103 hmm-learn, scikit-learn, the results from `hmmratac` subcommand may
104 not be consistent with the results from x86 or Apple chips. Please be
105 aware.
107 ## Usage
109 Example for regular peak calling on TF ChIP-seq:
111 `macs3 callpeak -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01`
113 Example for broad peak calling on Histone Mark ChIP-seq:
115 `macs3 callpeak -t ChIP.bam -c Control.bam --broad -g hs --broad-cutoff 0.1`
117 Example for peak calling on ATAC-seq (paired-end mode):
119 `macs3 callpeak -f BAMPE -t ATAC.bam -g hs -n test -B -q 0.01`
121 There are currently 14 functions available in MACS3 serving as
122 sub-commands. Please click on the link to see the detail description
123 of the subcommands.
125 Subcommand | Description
126 -----------|----------
127 [`callpeak`](docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results.
128 [`bdgpeakcall`](docs/bdgpeakcall.md) | Call peaks from bedGraph file.
129 [`bdgbroadcall`](docs/bdgbroadcall.md) | Call nested broad peaks from bedGraph file.
130 [`bdgcmp`](docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format.
131 [`bdgopt`](docs/bdgopt.md) | Operate the score column of bedGraph file.
132 [`cmbreps`](docs/cmbreps.md) | Combine bedGraph files of scores from replicates.
133 [`bdgdiff`](docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files.
134 [`filterdup`](docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format file.
135 [`predictd`](docs/predictd.md) | Predict d or fragment size from alignment results. In case of PE data, report the average insertion/fragment size from all pairs.
136 [`pileup`](docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end)
137 [`randsample`](docs/randsample.md) | Randomly choose a number/percentage of total reads, then save in BED/BEDPE format file.
138 [`refinepeak`](docs/refinepeak.md) | Take raw reads alignment, refine peak summits.
139 [`callvar`](docs/callvar.md) | Call variants in given peak regions from the alignment BAM files.
140 [`hmmratac`](docs/hmmratac.md) | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data.
142 For advanced usage, for example, to run `macs3` in a modular way,
143 please read the [advanced usage](docs/Advanced_Step-by-step_Peak_Calling.md). There is a
144 [Q&A](docs/qa.md) document where we collected some common questions
145 from users.
147 ## Contribute
149 Please read our [CODE OF CONDUCT](CODE_OF_CONDUCT.md) and [How to
150 contribute](CONTRIBUTING.md) documents. If you have any questions,
151 suggestion/ideas, or just want to have conversions with developers and
152 other users in the community, we recommend using the [MACS
153 Discussions](https://github.com/macs3-project/MACS/discussions)
154 instead of posting to our
155 [Issues](https://github.com/macs3-project/MACS/issues) page.
157 ## Ackowledgement
159 MACS3 project is sponsored by [](https://czi.co/EOSS). And we particularly want to thank the user community for their supports, feedbacks and contributions over the years.
161 ## Citation
163 2008: [Model-based Analysis of ChIP-Seq
164 (MACS)](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2008-9-9-r137)
166 ## Other useful links
168 * [Cistrome](http://cistrome.org/)
169 * [bedTools](http://code.google.com/p/bedtools/)
170 * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/)
171 * [deepTools](https://github.com/deeptools/deepTools/)
174 ```{toctree}
175 :maxdepth: 2
176 :hidden:
178 index.md
179 docs/INSTALL.md
180 docs/subcommands_index.md
181 docs/fileformats_index.md
182 docs/tutorial.md
183 docs/qa.md
184 CODE_OF_CONDUCT.md
185 CONTRIBUTING.md