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