README.md

   1 # MACS: Model-based Analysis for ChIP-Seq
   2
   3 ![Status](https://img.shields.io/pypi/status/macs3.svg) ![License](https://img.shields.io/github/license/macs3-project/MACS) ![Programming languages](https://img.shields.io/github/languages/top/macs3-project/MACS) ![CI x64](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20x64/badge.svg?branch=master) ![CI non x64](https://github.com/macs3-project/MACS/workflows/MACS3%20CI%20non%20x64/badge.svg?branch=master) ![CI Mac OS](https://github.com/macs3-project/MACS/actions/workflows/build-and-test-MACS3-macos.yml/badge.svg?branch=master)
   4
   5 [![PyPI
   6 download](https://img.shields.io/pypi/dm/macs3?label=pypi%20downloads)](https://pypistats.org/packages/macs3)
   7
   8 Latest Release:
   9
  10 * Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases)
  11 * PyPI: [![PyPI Release](https://img.shields.io/pypi/v/macs3.svg)![PyPI Python Version](https://img.shields.io/pypi/pyversions/MACS3)![PyPI Format](https://img.shields.io/pypi/format/macs3)](https://pypi.org/project/macs3/)
  12 * Anaconda: [![Anaconda-Server Badge](https://anaconda.org/macs3/macs3/badges/version.svg)](https://anaconda.org/macs3/macs3)
  13 * Debian Med: [![Debian Stable](https://img.shields.io/debian/v/macs/stable?label=debian%20stable)](https://packages.debian.org/stable/macs)[![Debian Unstable](https://img.shields.io/debian/v/macs/sid?label=debian%20sid)](https://packages.debian.org/sid/macs)
  14
  15 ## Introduction
  16
  17 With the improvement of sequencing techniques, chromatin
  18 immunoprecipitation followed by high throughput sequencing (ChIP-Seq)
  19 is getting popular to study genome-wide protein-DNA interactions. To
  20 address the lack of powerful ChIP-Seq analysis method, we presented
  21 the **M**odel-based **A**nalysis of **C**hIP-**S**eq (MACS), for
  22 identifying transcript factor binding sites. MACS captures the
  23 influence of genome complexity to evaluate the significance of
  24 enriched ChIP regions and MACS improves the spatial resolution of
  25 binding sites through combining the information of both sequencing tag
  26 position and orientation. MACS can be easily used for ChIP-Seq data
  27 alone, or with a control sample with the increase of
  28 specificity. Moreover, as a general peak-caller, MACS can also be
  29 applied to any "DNA enrichment assays" if the question to be asked is
  30 simply: *where we can find significant reads coverage than the random
  31 background*.
  32
  33 ## Changes for MACS (3.0.1)
  34
  35 *Bugs fixed*
  36
  37 1) Fixed a bug that the `hmmatac` can't correctly save the digested
  38         signal
  39         files. [#605](https://github.com/macs3-project/MACS/issues/605)
  40         [#611](https://github.com/macs3-project/MACS/pull/611)
  41
  42 2) Applied a patch to remove cython requirement from the installed
  43         system. (it's needed for building the
  44         package). [#606](https://github.com/macs3-project/MACS/issues/606)
  45         [#612](https://github.com/macs3-project/MACS/pull/612)
  46
  47 3) Relax the testing script while comparing the peaks called from
  48         current codes and the standard peaks. To implement this, we added
  49         'intersection' function to 'Regions' class to find the
  50         intersecting regions of two Regions object (similar to PeakIO but
  51         only recording chromosome, start and end positions). And we
  52         updated the unit test 'test_Region.py' then implemented a script
  53         'jaccard.py' to compute the Jaccard Index of two peak files. If
  54         the JI > 0.99 we would think the peaks called and the standard
  55         peaks are similar. This is to avoid the problem caused by
  56         different Numpy/SciPy/sci-kit learn libraries, when certain peak
  57         coordinates may have 10bps
  58         difference. [#615](https://github.com/macs3-project/MACS/issues/615)
  59         [#619](https://github.com/macs3-project/MACS/pull/619)
  60
  61 4) Due to [the changes in scikit-learn
  62         1.3.0](https://scikit-learn.org/1.3/whats_new/v1.3.html), the way
  63         hmmlearn 0.3 uses Kmeans will end up with inconsistent results
  64         between sklearn <1.3 and sklearn >=1.3. Therefore, we patched the
  65         class hmm.GaussianHMM and adjusted the standard output from
  66         `hmmratac` subcommand. The change is based on [hmmlearn
  67         PR#545](https://github.com/hmmlearn/hmmlearn/pull/545). The idea
  68         is to do the random seeding of KMeans 10 times. Now the `hmmratac`
  69         results should be more consistent (at least
  70         JI>0.99). [#615](https://github.com/macs3-project/MACS/issues/615)
  71         [#620](https://github.com/macs3-project/MACS/pull/620)
  72
  73 *Other*
  74
  75 1) We added some dependencies to MACS3. `hmmratc` subcommand needs
  76         `hmmlearn` library, `hmmlearn` needs `scikit-learn` and
  77         `scikit-learn` needs `scipy`. Since major releases have happened
  78         for both`scipy` and `scikit-learn`, we have to set specific
  79         version requirements for them in order to make sure the output
  80         results from `hmmratac` are consistent.
  81
  82 2) We updated our documentation website using
  83     Sphinx. https://macs3-project.github.io/MACS/
  84
  85 ## Changes for MACS (3.0.0)
  86
  87 1) Call variants in peak regions directly from BAM files. The
  88         function was originally developed under code name SAPPER. Now
  89         SAPPER has been merged into MACS as the `callvar` command. It can
  90         be used to call SNVs and small INDELs directly from alignment
  91         files for ChIP-seq or ATAC-seq. We call `fermi-lite` to assemble
  92         the DNA sequence at the enriched genomic regions (binding sites or
  93         accessible DNA) and to refine the alignment when necessary. We
  94         added `simde` as        a submodule in order to support fermi-lite
  95         library under non-x64 architectures.
  96
  97 2) HMMRATAC module is added as subcommand `hmmratac`. HMMRATAC is a
  98         dedicated software to analyze ATAC-seq data. The basic idea behind
  99         HMMRATAC is to digest ATAC-seq data according to the fragment
 100         length of read pairs into four signal tracks: short fragments,
 101         mono-nucleosomal fragments, di-nucleosomal fragments and
 102         tri-nucleosomal fragments. Then integrate the four tracks again
 103         using Hidden Markov Model to consider three hidden states: open
 104         region, nucleosomal region, and background region. The orginal
 105         paper was published in 2019 written in JAVA, by Evan Tarbell. We
 106         implemented it in Python/Cython and optimize the whole process
 107         using existing MACS functions and hmmlearn. Now it can run much
 108         faster than the original JAVA version. Note: evaluation of the
 109         peak calling results is still underway.
 110
 111 3) Speed/memory optimization.  Use the cykhash to replace python
 112         dictionary. Use buffer (10MB) to read and parse input file (not
 113         available for BAM file parser). And many optimization tweaks. We
 114         added memory monitoring to the runtime messages.
 115
 116 4) R wrappers for MACS -- MACSr for bioconductor.
 117
 118 5) Code cleanup. Reorganize source codes.
 119
 120 6) Unit testing.
 121
 122 7) Switch to Github Action for CI, support multi-arch testing
 123         including x64, armv7, aarch64, s390x and ppc64le. We also test on
 124         Mac OS 12.
 125
 126 8) MACS tag-shifting model has been refined. Now it will use a naive
 127         peak calling approach to find ALL possible paired peaks at + and -
 128         strand, then use all of them to calculate the
 129         cross-correlation. (a related bug has been fix
 130         [#442](https://github.com/macs3-project/MACS/issues/442))
 131
 132 9) BAI index and random access to BAM file now is
 133         supported. [#449](https://github.com/macs3-project/MACS/issues/449).
 134
 135 10) Support of Python > 3.10 [#498](https://github.com/macs3-project/MACS/issues/498)
 136
 137 11) The effective genome size parameters have been updated
 138         according to deeptools. [#508](https://github.com/macs3-project/MACS/issues/508)
 139
 140 12) Multiple updates regarding dependencies, anaconda built, CI/CD
 141         process.
 142
 143 13) Cython 3 is supported.
 144
 145 14) Documentations for each subcommand can be found under /docs
 146
 147 *Other*
 148
 149 1) Missing header line while no peaks can be called
 150 [#501](https://github.com/macs3-project/MACS/issues/501)
 151 [#502](https://github.com/macs3-project/MACS/issues/502)
 152
 153 2) Note: different numpy, scipy, sklearn may give slightly
 154         different results for hmmratac results. The current standard
 155         results for automated testing in `/test` directory are from Numpy
 156         1.25.1, Scipy 1.11.1, and sklearn 1.3.0.
 157
 158 ## Install
 159
 160 The common way to install MACS is through
 161 [PYPI](https://pypi.org/project/macs3/)). Please check the
 162 [INSTALL](docs/INSTALL.md) document for detail.
 163
 164 MACS3 has been tested using GitHub Actions for every push and PR in
 165 the following architectures:
 166
 167  * x86_64 (Ubuntu 22, Python 3.9, 3.10, 3.11, 3.12)
 168  * aarch64 (Ubuntu 22, Python 3.10)
 169  * armv7 (Ubuntu 22, Python 3.10)
 170  * ppc64le (Ubuntu 22, Python 3.10)
 171  * s390x (Ubuntu 22, Python 3.10)
 172  * Apple chips (Mac OS 13, Python 3.9, 3.10, 3.11, 3.12)
 173
 174 In general, you can install through PyPI as `pip install macs3`.  To
 175 use virtual environment is highly recommended. Or you can install
 176 after unzipping the released package downloaded from Github, then use
 177 `pip install .` command. Please note that, we haven't tested
 178 installation on any Windows OS, so currently only Linux and Mac OS
 179 systems are supported. Also, for aarch64, armv7, ppc64le and s390x,
 180 due to some unknown reason potentially related to the scientific
 181 calculation libraries MACS3 depends on, such as Numpy, Scipy,
 182 hmm-learn, scikit-learn, the results from `hmmratac` subcommand may
 183 not be consistent with the results from x86 or Apple chips. Please be
 184 aware.
 185
 186 ## Usage
 187
 188 Example for regular peak calling on TF ChIP-seq:
 189
 190 `macs3 callpeak -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01`
 191
 192 Example for broad peak calling on Histone Mark ChIP-seq:
 193
 194 `macs3 callpeak -t ChIP.bam -c Control.bam --broad -g hs --broad-cutoff 0.1`
 195
 196 Example for peak calling on ATAC-seq (paired-end mode):
 197
 198 `macs3 callpeak -f BAMPE -t ATAC.bam -g hs -n test -B -q 0.01`
 199
 200 There are currently 14 functions available in MACS3 serving as
 201 sub-commands. Please click on the link to see the detail description
 202 of the subcommands.
 203
 204 Subcommand | Description
 205 -----------|----------
 206 [`callpeak`](docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results.
 207 [`bdgpeakcall`](docs/bdgpeakcall.md) | Call peaks from bedGraph file.
 208 [`bdgbroadcall`](docs/bdgbroadcall.md) | Call nested broad peaks from bedGraph file.
 209 [`bdgcmp`](docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format.
 210 [`bdgopt`](docs/bdgopt.md) | Operate the score column of bedGraph file.
 211 [`cmbreps`](docs/cmbreps.md) | Combine bedGraph files of scores from replicates.
 212 [`bdgdiff`](docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files.
 213 [`filterdup`](docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format file.
 214 [`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.
 215 [`pileup`](docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end)
 216 [`randsample`](docs/randsample.md) | Randomly choose a number/percentage of total reads, then save in BED/BEDPE format file.
 217 [`refinepeak`](docs/refinepeak.md) | Take raw reads alignment, refine peak summits.
 218 [`callvar`](docs/callvar.md) | Call variants in given peak regions from the alignment BAM files.
 219 [`hmmratac`](docs/hmmratac.md) | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data.
 220
 221 For advanced usage, for example, to run `macs3` in a modular way,
 222 please read the [advanced usage](docs/Advanced_Step-by-step_Peak_Calling.md). There is a
 223 [Q&A](docs/qa.md) document where we collected some common questions
 224 from users.
 225
 226 ## Contribute
 227
 228 Please read our [CODE OF CONDUCT](CODE_OF_CONDUCT.md) and [How to
 229 contribute](CONTRIBUTING.md) documents. If you have any questions,
 230 suggestion/ideas, or just want to have conversions with developers and
 231 other users in the community, we recommend using the [MACS
 232 Discussions](https://github.com/macs3-project/MACS/discussions)
 233 instead of posting to our
 234 [Issues](https://github.com/macs3-project/MACS/issues) page.
 235
 236 ## Ackowledgement
 237
 238 MACS3 project is sponsored by
 239 [CZI EOSS](https://chanzuckerberg.com/eoss/). And we particularly want
 240 to thank the user community for their supports, feedbacks and
 241 contributions over the years.
 242
 243 ## Citation
 244
 245 2008: [Model-based Analysis of ChIP-Seq
 246 (MACS)](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2008-9-9-r137)
 247
 248 ## Other useful links
 249
 250  * [Cistrome](http://cistrome.org/)
 251  * [bedTools](http://code.google.com/p/bedtools/)
 252  * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/)
 253  * [deepTools](https://github.com/deeptools/deepTools/)