Merge pull request #502 from macs3-project/macs3/fix/501headerline
[MACS.git] / README.md
blobfc95c62bd9bb0af429dad0fb0fe5b1e96ee1e0b0
1 # MACS: Model-based Analysis for ChIP-Seq
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,%20python%203.7/badge.svg)
5 [![PyPI download](https://img.shields.io/pypi/dm/macs3?label=pypi%20downloads)](https://pypistats.org/packages/macs3) [![Bioconda download](https://img.shields.io/conda/dn/bioconda/macs3?label=bioconda%20downloads)](https://anaconda.org/bioconda/macs3)
7 Latest Release:
8 * Github: [![Github Release](https://img.shields.io/github/v/release/macs3-project/MACS)](https://github.com/macs3-project/MACS/releases)
9 * 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/)
10 * Bioconda: [![Bioconda Release](https://img.shields.io/conda/v/bioconda/macs3) ![Bioconda Platform](https://img.shields.io/conda/pn/bioconda/macs3)](https://anaconda.org/bioconda/macs3)
11 * 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)
13 ## Introduction
15 With the improvement of sequencing techniques, chromatin
16 immunoprecipitation followed by high throughput sequencing (ChIP-Seq)
17 is getting popular to study genome-wide protein-DNA interactions. To
18 address the lack of powerful ChIP-Seq analysis method, we presented
19 the **M**odel-based **A**nalysis of **C**hIP-**S**eq (MACS), for
20 identifying transcript factor binding sites. MACS captures the
21 influence of genome complexity to evaluate the significance of
22 enriched ChIP regions and MACS improves the spatial resolution of
23 binding sites through combining the information of both sequencing tag
24 position and orientation. MACS can be easily used for ChIP-Seq data
25 alone, or with a control sample with the increase of
26 specificity. Moreover, as a general peak-caller, MACS can also be
27 applied to any "DNA enrichment assays" if the question to be asked is
28 simply: *where we can find significant reads coverage than the random
29 background*.
31 **Please note that current MACS3 is still in alpha stage. However, we
32 utilize Github Action to implement the CI (Continous Integration) to
33 make sure that the main branch passes unit testing on certain
34 functions and subcommands to reproduce the correct outputs. We will
35 add more new features in the future.**
37 ## Recent Changes for MACS (3.0.0a6)
39 ### 3.0.0a6
40         * New features
41         
42         1) Speed/memory optimization.  Use the cykhash to replace python
43     dictionary. Use buffer (10MB) to read and parse input file (not
44     available for BAM file parser). And many optimization tweaks.
46         2) Code cleanup. Reorganize source codes.
48         3) Unit testing.
50         4) R wrappers for MACS -- MACSr matching the current version of
51     MACS
53     5) Switch to Github Action for CI, support multi-arch testing
54     including x64, armv7, aarch64, s390x and ppc64le.
56     6) MACS tag-shifting model has been refined. Now it will use a
57     naive peak calling approach to find ALL possible paired peaks at +
58     and - strand, then use all of them to calculate the
59     cross-correlation. (a related bug has been fix #442)
61     7) Call variants in peak regions directly from BAM files. The
62         function was originally developed under code name SAPPER. Now
63         SAPPER has been merged into MACS. Also, `simde` has been added as
64         a submodule in order to support fermi-lite library under non-x64
65         architectures.
67 ## Install
69 The common way to install MACS is through
70 [PYPI](https://pypi.org/project/macs3/)) or
71 [conda](https://anaconda.org/bioconda/macs3). Please check the
72 [INSTALL](./docs/INSTALL.md) document for detail.
74 MACS3 has been tested in CI for every push and PR in the following
75 architectures:
77  * x86_64
78  * aarch64
79  * armv7
80  * ppc64le
81  * s390x 
83 ## Usage
85 Example for regular peak calling on TF ChIP-seq:
87 `macs3 callpeak -t ChIP.bam -c Control.bam -f BAM -g hs -n test -B -q 0.01`
89 Example for broad peak calling on Histone Mark ChIP-seq:
91 `macs3 callpeak -t ChIP.bam -c Control.bam --broad -g hs --broad-cutoff 0.1`
93 Example for peak calling on ATAC-seq (paired-end mode):
95 `macs3 callpeak -f BAMPE -t ATAC.bam -g hs -n test -B -q 0.01`
97 There are currently twelve functions available in MAC3 serving as
98 sub-commands. Please click on the link to see the detail description
99 of the subcommands.
101 Subcommand | Description
102 -----------|----------
103 [`callpeak`](./docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results.
104 [`bdgpeakcall`](./docs/bdgpeakcall.md) | Call peaks from bedGraph output.
105 [`bdgbroadcall`](./docs/bdgbroadcall.md) | Call broad peaks from bedGraph output.
106 [`bdgcmp`](./docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format.
107 [`bdgopt`](./docs/bdgopt.md) | Operate the score column of bedGraph file.
108 [`cmbreps`](./docs/cmbreps.md) | Combine BEDGraphs of scores from replicates.
109 [`bdgdiff`](./docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files.
110 [`filterdup`](./docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format.
111 [`predictd`](./docs/predictd.md) | Predict d or fragment size from alignment results.
112 [`pileup`](./docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end)
113 [`randsample`](./docs/randsample.md) | Randomly choose a number/percentage of total reads.
114 [`refinepeak`](./docs/refinepeak.md) | Take raw reads alignment, refine peak summits.
115 [`callvar`](./docs/callvar.md) | Call variants in given peak regions from the alignment BAM files.
118 For advanced usage, for example, to run `macs3` in a modular way,
119 please read the [advanced usage](./docs/advanced_usage.md). There is a
120 [Q&A](./docs/qa.md) document where we collected some common questions
121 from users.
123 ## Contribute
125 Please read our [CODE OF CONDUCT](./CODE_OF_CONDUCT.md) and
126 [How to contribute](./CONTRIBUTING.md) documents. If you have any
127 questions, suggestion/ideas, or just want to have conversions with
128 developers and other users in the community, we recommand you use the
129 [MACS Discussions](https://github.com/macs3-project/MACS/discussions)
130 instead of posting to our
131 [Issues](https://github.com/macs3-project/MACS/issues) page.
133 ## Ackowledgement
135 MACS3 project is sponsored by
136 [CZI EOSS](https://chanzuckerberg.com/eoss/). And we particularly want
137 to thank the user community for their supports, feedbacks and
138 contributions over the years.
140 ## Other useful links
142  * [Cistrome](http://cistrome.org/)
143  * [bedTools](http://code.google.com/p/bedtools/)
144  * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/)
145  * [deepTools](https://github.com/deeptools/deepTools/)