MACS3 calls ChIP-Seq peaks with a model, and 3.0.5 rewrote the pileup in NumPy

The question MACS3 answers: where are the reads enriched

ChIP-Seq asks where a protein binds DNA, and the raw answer is a pileup of sequencing tags across the genome. Turning that pileup into a list of binding sites is the peak calling step, and MACS3 is one of the tools built for it. The name expands to Model-based Analysis for ChIP-Seq, and the model matters: the approach takes genome complexity into account when it judges whether a region is enriched, and it combines the position and the orientation of the sequencing tags to improve the spatial resolution of the calls.

The project describes itself as a general peak caller rather than a ChIP-Seq only tool. Any DNA enrichment assay works, including ATAC-Seq and DNase-Seq, as long as the question you are asking is where read coverage exceeds the random background. You can also run it on ChIP-Seq data with no control sample at all, and adding one control raises specificity rather than being a precondition.

The intended users are genomic analysts who already have aligned reads and want a peak list, not a general genomics toolkit. MACS3 does not align reads, does not filter them, and does not assemble a genome. Its input is a treatment track and optionally a control track, and its output is peaks with scores and summits.

One thing the README does not do is document the statistical model itself. The repository topics list poisson-equation among the labels, which points at the statistical backbone, but the prose stops at describing the model-based idea in general terms and directs readers to the MACS3 website for the documentation.

Three commands, three different kinds of data

The release notes for 3.0.5 name several entry points, and they divide the project into three lines of work. hmmratac is the single-cell peak caller, and the changes to it include a new --jump option that controls fragment-length EM updates, a fix for an IndexError during peak refinement, and a change so that a successful --cutoff-analysis-only run exits with status 0 instead of a failure code.

bdgdiff is a separate command whose role in the release notes is a bug fix: decimal-score truncation was corrected in it. The name points at comparing signal tracks, and that is exactly the kind of step that sits after peak calling rather than inside it.

PETrackII handles fragment data from single-cell experiments, and 3.0.5 added PETrackII.return_anndata for building sparse barcode-by-peak AnnData matrices from that fragment data. That addition is the reason pandas and anndata became runtime dependencies in this release.

This gives you a genuine choice of approach inside the project. The bulk ChIP-Seq route asks where coverage exceeds background across the whole library. The single-cell route asks the same question per barcode and then hands you a sparse matrix whose rows are cells and whose columns are peaks, so downstream analysis can treat the result as a matrix rather than as a list of intervals. Both routes call peaks; only one of them gives you per-cell structure.

A Python 3.12 floor and a compiled extension stack

MACS3 3.0.5 raised its minimum Python version, and that is the first thing to check before anything else. The packaging metadata states the requirement plainly:

requires-python = ">=3.12"
license = "BSD-3-Clause"

The legacy setup script enforces the same floor and refuses to continue on older interpreters, printing a critical message that the Python version must be at least 3.12. The classifiers list Python 3.12, 3.13 and 3.14, and the project is tagged as Production/Stable for development status.

The runtime dependencies are a scientific Python stack:

dependencies = ["numpy>=1.25",
                "scipy>=1.12",
                "pandas>=2.0",
                "anndata>=0.10",
                "hmmlearn>=0.3.2",
                "scikit-learn>=1.3"]

There is a build step on top of that. The build system requires setuptools, NumPy and Cython, which tells you the package is not pure Python:

[build-system]
requires=['setuptools>=80.0', 'numpy>=1.25', 'Cython>=3.0']
build-backend = "setuptools.build_meta"

The setup script compiles the Cython extension modules with optimisation flags turned down for size and speed rather than for debuggability, and it links a bundled fermi-lite directory with SIMD defines, with special handling for clang, gcc and icc compilers. In practice this means a source install needs a working C toolchain, while a binary from PyPI, Bioconda or Debian Med spares you that.

Distribution is broad: releases appear on GitHub, on PyPI as macs3, on Bioconda and in Debian Med, and the documentation lives on the MACS3 website.

What 3.0.5 changed under the hood

The headline change in the 3.0.5 notes is a rewrite of the internal hot path. Peak calling, pileup output and peak-model construction moved to faster NumPy-backed routines called PileupV2, the fragment exclusion and score caches were optimised, and the release claims a 1.4x speedup over 3.0.4. The dependency on cykhash was removed in the same release, which is consistent with the move away from the previous hashing and pileup implementation.

The rest of the release is a list of corrections that matter if you have been trusting older results. In bdgdiff, decimal scores were being truncated. Summit scores were wrong for maxima sitting in below-cutoff gaps. hmmratac could raise an IndexError during peak refinement. Summit coordinates and peak boundaries were off around the temporary search padding, and shape filtering of summit candidates was wrong on both sides of a local maximum.

The last group is the kind of detail that separates a call you can trust from one you cannot. A wrong summit coordinate is not a cosmetic issue in a ChIP-Seq workflow, because the summit is often the position you use to design a validation primer or to inspect a motif.

For users, the practical reading is that 3.0.5 is a correctness release as much as a speed release, and 3.0.4, dated 2026-02-23, sits between the older v3.0.3 from 2025-02-20 and the current one dated 2026-09-25.

If your clone still points at master

The default branch of MACS3 was renamed to main, and the README spells out the repair for anyone whose clone is still on the old name:

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

Run those in the repository root of your existing clone. The first line renames your local branch, the second brings down the new remote references, the third points your local branch at origin/main, and the last resets the remote HEAD so that git commands resolve the correct default branch. Skipping this step is harmless for reading the code but it will make your working tree look permanently behind, since fetches against a renamed default branch leave your master pointing at a stale commit.

The repository layout supports the way this project is used. MACS3/ holds the package itself, docs/ holds the documentation sources that feed the website, notebooks/ holds analysis examples, scripts/ holds helper scripts, bin/ holds entry point scripts, test/ holds the test suite, and the presence of .github/ with separate CI workflows for x64 Linux, non-x64 Linux and macOS reflects the fact that the compiled extensions have to build on more than one platform.

Where MACS3 is the wrong choice

The clearest wrong-tool case is the Python floor. A locked production environment on 3.11 cannot run the current release, and setup.py exits before building anything, so the cost of adopting 3.0.5 is a Python upgrade for the whole environment rather than a single package install. Conda and Debian packages soften that, but the dependency floor still applies to whatever they resolve.

The second is scope of the assay. MACS3 calls enriched regions. If your question is which transcription factor is bound at a site, peaks are the input to that question rather than the answer to it, and the project is not a motif tool. If your data is not a DNA enrichment assay at all, there is no reading of this pipeline that applies.

The third is the single-cell route, which is newer and rougher. The 3.0.5 notes list an IndexError, a shape filtering bug and an incorrect exit status for hmmratac, all fixed in that release. That is not a criticism of the maintainers, who fixed them, but it means older installs behave differently on the same data.

A quieter limitation is that the README does not document the statistical model, the input format details, or the parameters you are expected to tune, and it does not cover how to interpret the returned scores. Anyone who needs the reasoning behind a call rather than the call has to go to the MACS3 website or the 2026 paper.

Licence, releases and a solo maintainer

MACS3 is released under BSD-3-Clause, a permissive licence that allows use and modification in commercial and academic settings and requires that the copyright notice and licence text be kept with redistributed copies. The metadata lists the licence files that must travel with the package, including the notices for the bundled libdeflate, NumPy and fermi-lite components, so anyone packaging MACS3 needs to carry those along.

Release history is steady rather than rapid. v3.0.5 came out on 2026-09-25, v3.0.4 on 2026-02-23 and v3.0.3 on 2025-02-20, and the repository is not archived, with the last push on 2026-10-20. The project is maintained by one person in spare time, with sponsorship from CZI's Essential Open Source Software for Science, and it asks for donations to keep that going.

Citation is versioned. For MACS version 2 and 3 the project asks for the 2026 paper MACS3: A Peak-calling Platform for Bulk and Single-cell Regulatory Genomics, while users of version 1 should cite the 2008 paper Model-based Analysis of ChIP-Seq. Two papers, two audiences, and the second one is a historical reference rather than a description of the code you are about to run.

Editorial conclusion

Adopt MACS3 when your data is ChIP-Seq, ATAC-Seq or another DNA enrichment assay and you want peaks called by a model rather than by a threshold, and reach for the single-cell path with hmmratac and PETrackII only when you have fragment data with barcodes. Do not adopt it if your environment is stuck on Python 3.11, since the package requires 3.12 or later and setup.py refuses to build on anything older, and do not expect the README to explain the statistical model, because it does not. Before you run it, check the version you install against the fixes in 3.0.5, since earlier releases carry the hmmratac IndexError and the bdgdiff decimal truncation, and decide where your peak files belong in the results directory of your pipeline, since MACS3 writes output files but the README does not describe a session or project layout for them.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. macs3-project/MACS on GitHub
3. Project website
4. README
5. Releases