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.0)
  31
  32 1) Call variants in peak regions directly from BAM files. The
  33         function was originally developed under code name SAPPER. Now
  34         SAPPER has been merged into MACS as the `callvar` command. It can
  35         be used to call SNVs and small INDELs directly from alignment
  36         files for ChIP-seq or ATAC-seq. We call `fermi-lite` to assemble
  37         the DNA sequence at the enriched genomic regions (binding sites or
  38         accessible DNA) and to refine the alignment when necessary. We
  39         added `simde` as        a submodule in order to support fermi-lite
  40         library under non-x64 architectures.
  41
  42 2) HMMRATAC module is added as subcommand `hmmratac`. HMMRATAC is a
  43         dedicated software to analyze ATAC-seq data. The basic idea behind
  44         HMMRATAC is to digest ATAC-seq data according to the fragment
  45         length of read pairs into four signal tracks: short fragments,
  46         mono-nucleosomal fragments, di-nucleosomal fragments and
  47         tri-nucleosomal fragments. Then integrate the four tracks again
  48         using Hidden Markov Model to consider three hidden states: open
  49         region, nucleosomal region, and background region. The orginal
  50         paper was published in 2019 written in JAVA, by Evan Tarbell. We
  51         implemented it in Python/Cython and optimize the whole process
  52         using existing MACS functions and hmmlearn. Now it can run much
  53         faster than the original JAVA version. Note: evaluation of the
  54         peak calling results is still underway.
  55
  56 3) Speed/memory optimization.  Use the cykhash to replace python
  57         dictionary. Use buffer (10MB) to read and parse input file (not
  58         available for BAM file parser). And many optimization tweaks. We
  59         added memory monitoring to the runtime messages.
  60
  61 4) R wrappers for MACS -- MACSr for bioconductor.
  62
  63 5) Code cleanup. Reorganize source codes.
  64
  65 6) Unit testing.
  66
  67 7) Switch to Github Action for CI, support multi-arch testing
  68         including x64, armv7, aarch64, s390x and ppc64le. We also test on
  69         Mac OS 12.
  70
  71 8) MACS tag-shifting model has been refined. Now it will use a naive
  72         peak calling approach to find ALL possible paired peaks at + and -
  73         strand, then use all of them to calculate the
  74         cross-correlation. (a related bug has been fix
  75         [#442](https://github.com/macs3-project/MACS/issues/442))
  76
  77 9) BAI index and random access to BAM file now is
  78         supported. [#449](https://github.com/macs3-project/MACS/issues/449).
  79
  80 10) Support of Python > 3.10 [#498](https://github.com/macs3-project/MACS/issues/498)
  81
  82 11) The effective genome size parameters have been updated
  83         according to deeptools. [#508](https://github.com/macs3-project/MACS/issues/508)
  84
  85 12) Multiple updates regarding dependencies, anaconda built, CI/CD
  86         process.
  87
  88 13) Cython 3 is supported.
  89
  90 14) Documentations for each subcommand can be found under /docs
  91
  92 *Other*
  93
  94 1) Missing header line while no peaks can be called
  95 [#501](https://github.com/macs3-project/MACS/issues/501)
  96 [#502](https://github.com/macs3-project/MACS/issues/502)
  97
  98 2) Note: different numpy, scipy, sklearn may give slightly
  99         different results for hmmratac results. The current standard
 100         results for automated testing in `/test` directory are from Numpy
 101         1.25.1, Scipy 1.11.1, and sklearn 1.3.0.
 102
 103 ## Install
 104
 105 The common way to install MACS is through
 106 [PYPI](https://pypi.org/project/macs3/)) or
 107 [conda](https://anaconda.org/macs3/macs3). Please check the
 108 [INSTALL](./docs/INSTALL.md) document for detail.
 109
 110 MACS3 has been tested using GitHub Actions for every push and PR in
 111 the following architectures:
 112
 113  * x86_64 (Python 3.9, 3.10, 3.11, 3.12)
 114  * aarch64 (Python 3.9)
 115  * armv7 (Python 3.9)
 116  * ppc64le (Python 3.9)
 117  * s390x (Python 3.9)
 118  * Apple chips (Python 3.11)
 119
 120 In general, you can install through PyPI as `pip install macs3`.
 121 To use virtual environment is highly recommended. Or you can install
 122 after unzipping the released package downloaded from Github, then
 123 use `pip install .` command. Please note that, we haven't tested
 124 installation on any Windows OS, so currently only Linux and Mac OS
 125 systems are supported.
 126
 127 ## Usage
 128
 129 Example for regular peak calling on TF ChIP-seq:
 130
 131 `macs3 callpeak -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01`
 132
 133 Example for broad peak calling on Histone Mark ChIP-seq:
 134
 135 `macs3 callpeak -t ChIP.bam -c Control.bam --broad -g hs --broad-cutoff 0.1`
 136
 137 Example for peak calling on ATAC-seq (paired-end mode):
 138
 139 `macs3 callpeak -f BAMPE -t ATAC.bam -g hs -n test -B -q 0.01`
 140
 141 There are currently 14 functions available in MACS3 serving as
 142 sub-commands. Please click on the link to see the detail description
 143 of the subcommands.
 144
 145 Subcommand | Description
 146 -----------|----------
 147 [`callpeak`](./docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results.
 148 [`bdgpeakcall`](./docs/bdgpeakcall.md) | Call peaks from bedGraph file.
 149 [`bdgbroadcall`](./docs/bdgbroadcall.md) | Call nested broad peaks from bedGraph file.
 150 [`bdgcmp`](./docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format.
 151 [`bdgopt`](./docs/bdgopt.md) | Operate the score column of bedGraph file.
 152 [`cmbreps`](./docs/cmbreps.md) | Combine bedGraph files of scores from replicates.
 153 [`bdgdiff`](./docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files.
 154 [`filterdup`](./docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format file.
 155 [`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.
 156 [`pileup`](./docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end)
 157 [`randsample`](./docs/randsample.md) | Randomly choose a number/percentage of total reads, then save in BED/BEDPE format file.
 158 [`refinepeak`](./docs/refinepeak.md) | Take raw reads alignment, refine peak summits.
 159 [`callvar`](./docs/callvar.md) | Call variants in given peak regions from the alignment BAM files.
 160 [`hmmratac`](./docs/hmmratac.md) | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data.
 161
 162 For advanced usage, for example, to run `macs3` in a modular way,
 163 please read the [advanced usage](./docs/Advanced_Step-by-step_Peak_Calling.md). There is a
 164 [Q&A](./docs/qa.md) document where we collected some common questions
 165 from users.
 166
 167 ## Contribute
 168
 169 Please read our [CODE OF CONDUCT](./CODE_OF_CONDUCT.md) and [How to
 170 contribute](./CONTRIBUTING.md) documents. If you have any questions,
 171 suggestion/ideas, or just want to have conversions with developers and
 172 other users in the community, we recommend using the [MACS
 173 Discussions](https://github.com/macs3-project/MACS/discussions)
 174 instead of posting to our
 175 [Issues](https://github.com/macs3-project/MACS/issues) page.
 176
 177 ## Ackowledgement
 178
 179 MACS3 project is sponsored by
 180 [CZI EOSS](https://chanzuckerberg.com/eoss/). And we particularly want
 181 to thank the user community for their supports, feedbacks and
 182 contributions over the years.
 183
 184 ## Citation
 185
 186 2008: [Model-based Analysis of ChIP-Seq
 187 (MACS)](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2008-9-9-r137)
 188
 189 ## Other useful links
 190
 191  * [Cistrome](http://cistrome.org/)
 192  * [bedTools](http://code.google.com/p/bedtools/)
 193  * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/)
 194  * [deepTools](https://github.com/deeptools/deepTools/)
 195