INSTALL Guide For MACS3
Please check the following instructions to complete your installation.
Here we list some prerequisites for installing and running MACS3. But if you are using conda or pip to install, the installer will check the dependencies and install them if necessary. Therefore, this section is for reference purpose, and if you are looking for steps to build and install MACS3, please go to the next section. Please note that, we haven’t tested installation on any Windows OS, so currently only Linux and Mac OS systems are supported.
MACS v3 requires Python3. We have tested MACS in Python3.9 to 3.12.
NumPy, hmmlearn, Scipy, scikit-learn
MACS calls functions from NumPy and hmmlearn. Since hmmlearn further requires scikit-learn which requires SciPy, and these libraries are crucial for reproducing your results, we also add them into the requirement list with specific version numbers. So here is the list of the required python libraries that will impact the numerical calculation in MACS3:
Cython is required to translate .pyx codes to .c code. The version of Cython has to be >=3.0.
cykhash is a fast and efficient hash implementation in Cython. It can be seen as the cython implementation of khash. It is used to replace python dictionary in MACS3 codes. We require cykhash version 2.
fermi-lite and simde
A newly added
callvar subcommand in MACS3 uses
fermi-lite to assemble the DNA
sequence in a peak region while necessary. A modified fermi-lite has
been included in MACS3 package. Since fermi-lite was implemented using
intel SSE2 intrinsics for x86 CPUs, we added
simde as submodule to
solve the compatibility issues on non-x86 architectures. Note that, we
may remove this submodule and add simde in dependencies of MACS3
GCC, Python-dev, meson …
GCC is required to compile
.c codes in MACS v3 package, and python
header files are needed. If you are using Mac OSX, we recommend you
install Xcode; if you are using Linux, you need to make sure
python-dev package is installed – the actual package name depends
on the Linux OS distribution, you are using. Also, since the most
recent Numpy/Scipy use meson to build the
libraries, make sure they have been installed.
Prepare a virtual Python environment
We strongly recommend installing your MACS program in a virtual environment, so that you have full control of your installation and won’t mess up with your system libraries. To learn about virtual environment, read this article. A simple way to create a virtual environment of Python3 is
$ python3 -m venv MACS3env/
Then activate it by
$ source MACS3env/bin/activate
There is another solution, pipx, to make a clean isolated python environment to run python tools such as MACS3. We won’t explore it here but if you are insterested in it, please click the link above and read the tutorial.
Install through PyPI
The easiest way to install MACS is through PyPI system. Get
it’s not available in your system. If you create a virtual environment
as described before, your
pip command will install everything under
the folder you specified previously through
python3 -m env command,
or to your active conda environment.
Then under the command line, type
pip install macs3. PyPI will
install dependencies automatically if it is absent. By default,
will install the newest version of dependencies that satisfy the
requirements of MACS3. When you run the command without virtual
environment, you may need to be the root user or system administrator
so as to complete the installation. Please contact the system
administrator if you want their help.
To upgrade MACS3, type
pip install --upgrade macs3. It will check
currently installed MACS3, compare the version with the one on PyPI
repository, download and install a newer version while necessary.
Install from source through pip
pip for source code installations. To install a source
distribution of MACS, unpack the distribution tarball, or clone Git
git clone --recurse-submodules firstname.lastname@example.org:macs3-project/MACS.git. Go to the directory where you
cloned MACS from github or unpacked from tarball, and simply run the
$ pip install .
The command will treat the current working directory as the ‘package’
to be installed. The behavior will be the same as
pip install macs3
as described in the previous section “Install through PyPI”.
You can also install MACS3 from source code in a “modern” two-steps
way. First, use the build system to make a wheel (in this case, you
need to install
build first by
pip install build):
$ python -m build --wheel
This will make a ‘.whl’ file under ‘dist’ directory. Then you can
install the wheel through
$ pip install dist/MACS3-3.x.x-x-x-x.whl
Please use the real filename in the ‘dist’ directory.