docs/INSTALL.md

   1 # INSTALL Guide For MACS3
   2
   3 Please check the following instructions to complete your installation.
   4
   5 ## Prerequisites
   6
   7 Here we list some prerequisites for installing and running MACS3. But
   8 if you are using conda or pip to install, the installer will check the
   9 dependencies and install them if necessary. Therefore, this section is
  10 for reference purpose, and if you are just looking for steps to
  11 install MACS3, please go to the next section. Please note that, we
  12 haven't tested installation on any Windows OS, so currently only Linux
  13 and Mac OS systems are supported.
  14
  15 ### Python3
  16
  17 MACS v3 requires Python3. We have tested MACS in Python3.9 to 3.12.
  18
  19 ### NumPy, hmmlearn, Scipy, scikit-learn
  20
  21 MACS calls functions from [NumPy](https://numpy.org/) and
  22 [hmmlearn](https://hmmlearn.readthedocs.io/). Since hmmlearn further
  23 requires [scikit-learn](https://scikit-learn.org/) which requires
  24 [SciPy](https://scipy.org/), and these libraries are crucial for
  25 reproducing your results, we also add them into the requirement list
  26 with specific version numbers. So here is the list of the required
  27 python libraries that will impact the numerical calculation in MACS3:
  28
  29  - numpy>=1.25
  30  - hmmlearn>=0.3.2
  31  - scikit-learn>=1.3
  32  - scipy>=1.12
  33
  34 ### Cython
  35
  36 [Cython](http://cython.org/) is required to translate .pyx codes to .c
  37 code. The version of Cython has to be >=3.0.
  38
  39 ### cykhash
  40
  41 [cykhash](https://github.com/realead/cykhash) is a fast and efficient
  42 hash implementation in Cython. It can be seen as the cython
  43 implementation of
  44 [khash](https://github.com/attractivechaos/klib/blob/master/khash.h). It
  45 is used to replace python dictionary in MACS3 codes. We require
  46 cykhash version 2.
  47
  48 ### fermi-lite and simde
  49
  50 A newly added `callvar` subcommand in MACS3 uses
  51 [fermi-lite](https://github.com/lh3/fermi-lite) to assemble the DNA
  52 sequence in a peak region while necessary. A modified fermi-lite has
  53 been included in MACS3 package. Since fermi-lite was implemented using
  54 intel SSE2 intrinsics for x86 CPUs, we added
  55 [simde](https://github.com/simd-everywhere/simde) as submodule to
  56 solve the compatibility issues on non-x86 architectures. Note that, we
  57 may remove this submodule and add simde in *dependencies* of MACS3
  58 later.
  59
  60 ### GCC, Python-dev, meson ...
  61
  62 GCC is required to compile `.c` codes in MACS v3 package, and python
  63 header files are needed. If you are using Mac OSX, we recommend you
  64 install Xcode; if you are using Linux, you need to make sure
  65 `python-dev` package is installed -- the actual package name depends
  66 on the Linux OS distribution, you are using. Also, since the most
  67 recent Numpy/Scipy use [meson](https://mesonbuild.com/) to build the
  68 libraries, make sure they have been installed.
  69
  70 ## Prepare a virtual Python environment
  71
  72 We strongly recommend installing your MACS program in a virtual
  73 environment, so that you have full control of your installation and
  74 won't mess up with your system libraries. To learn about virtual
  75 environment, read [this
  76 article](https://docs.python.org/3/library/venv.html). A simple way to
  77 create a virtual environment of Python3 is
  78
  79 `$ python3 -m venv MACS3env/`
  80
  81 Then activate it by
  82
  83 `$ source MACS3env/bin/activate`
  84
  85 If you use 'conda', it will also provide virtual environment. Please
  86 read:
  87 [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html)
  88 or [miniconda](https://docs.conda.io/en/latest/miniconda.html) For
  89 example, after installing 'conda', you can use `conda create -n MACS3`
  90 to create a new environment called 'MACS3' then switch to this
  91 environment with `conda activate MACS3`.
  92
  93 There is another solution, [pipx](https://pipx.pypa.io/), to make a
  94 clean isolated python environment to run python tools such as
  95 MACS3. We won't explore it here but if you are insterested in it,
  96 please click the link above and read the tutorial.
  97
  98 ## Install through PyPI
  99
 100 The easiest way to install MACS is through PyPI system. Get `pip` if
 101 it's not available in your system. If you create a virtual environment
 102 as described before, your `pip` command will install everything under
 103 the folder you specified previously through `python3 -m env` command,
 104 or to your active conda environment.
 105
 106 Then under the command line, type `pip install macs3`. PyPI will
 107 install dependencies automatically if it is absent. By default, `pip`
 108 will install the newest version of dependencies that satisfy the
 109 requirements of MACS3. When you run the command without virtual
 110 environment, you may need to be the root user or system administrator
 111 so as to complete the installation. Please contact the system
 112 administrator if you want their help.
 113
 114 To upgrade MACS3, type `pip install --upgrade macs3`. It will check
 115 currently installed MACS3, compare the version with the one on PyPI
 116 repository, download and install a newer version while necessary.
 117
 118 ## Install through conda
 119
 120 To install MACS3 using 'conda', simply execute `conda install -c
 121 bioconda macs3` in your conda environment. This command installs MACS3
 122 along with its dependencies from the Bioconda channel. Please ensure
 123 conda is installed and a dedicated conda environment has been created
 124 and activated beforehand for a smooth installation process.
 125
 126 ## Install from source through pip
 127
 128 MACS uses `pip` for source code installations. To install a source
 129 distribution of MACS, unpack the distribution tarball, or clone Git
 130 repository with `git clone --recurse-submodules
 131 git@github.com:macs3-project/MACS.git`.  Go to the directory where you
 132 cloned MACS from github or unpacked from tarball, and simply run the
 133 install command:
 134
 135  `$ pip install .`
 136
 137 The command will treat the current working directory as the 'package'
 138 to be installed. The behavior will be the same as `pip install macs3`
 139 as described in the previous section "Install through PyPI".
 140
 141 You can also install MACS3 from source code in a "modern" two-steps
 142 way. First, use the build system to make a wheel (in this case, you
 143 need to install `build` first by `pip install build`):
 144
 145 `$ python -m build --wheel`
 146
 147 This will make a '.whl' file under 'dist' directory. Then you can
 148 install the wheel through `pip`:
 149
 150 `$ pip install dist/MACS3-3.x.x-x-x-x.whl`
 151
 152 Please use the real filename in the 'dist' directory.
 153