docs/INSTALL.md

   1 # INSTALL Guide For MACS3
   2 Time-stamp: <2023-11-14 16:43:54 Tao Liu>
   3
   4 Please check the following instructions to complete your installation.
   5
   6 ## Prerequisites
   7
   8 Here we list some prerequisites for installing and running MACS3. But
   9 if you are using conda or pip to install, the installer will check the
  10 dependencies and install them if necessary. Please note that, we
  11 haven't tested installation on any Windows OS, so currently only Linux
  12 and Mac OS systems are supported.
  13
  14 ### Python3
  15
  16 MACS v3.x.x requires Python3. We have tested MACS in Python3.9 to 3.12.
  17
  18 ### NumPy, hmmlearn
  19
  20 MACS requires NumPy>=1.19 (>=1.24 recommended) and hmmlearn>=0.3
  21 during installation. Note that hmmlearn further requires SciPy and
  22 sklearn (aka scikit-learn).
  23
  24 ### Cython
  25
  26 [Cython](http://cython.org/) is required to translate .pyx codes to .c
  27 code. The version of Cython has to be >=0.29.
  28
  29 ### cykhash
  30
  31 [cykhash](https://github.com/realead/cykhash) is a fast and efficient
  32 hash implementation in Cython. It is used to replace python dictionary
  33 in MACS3 codes. Since it requires Cython, make sure you install Cython
  34 first, then install cykhash.
  35
  36 ### fermi-lite and simde
  37
  38 A newly added `callvar` subcommand in MACS3 uses
  39 [fermi-lite](https://github.com/lh3/fermi-lite) to assemble the DNA
  40 sequence in a peak region while necessary. A modified fermi-lite has
  41 been included in MACS3 package. Since fermi-lite was implemented using
  42 intel SSE2 intrinsics for x86 CPUs, we added
  43 [simde](https://github.com/simd-everywhere/simde) as submodule to
  44 solve the compatibility issues on non-x86 architectures. Note that, we
  45 may remove this submodule and add simde in *dependencies* of MACS3
  46 later.
  47
  48 ### GCC and Python-dev
  49
  50 GCC is required to compile `.c` codes in MACS v3 package, and python
  51 header files are needed. If you are using Mac OSX, I recommend you
  52 install Xcode; if you are using Linux, you need to make sure
  53 `python-dev` package is installed -- the actual package name depends
  54 on the Linux OS distribution, you are using.
  55
  56 ## Prepare a virtual Python environment
  57
  58 We strongly recommend installing your MACS program in a virtual
  59 environment, so that you have full control of your installation and
  60 won't mess up with your system libraries. To learn about virtual
  61 environment, read [this
  62 article](https://docs.python.org/3/library/venv.html). A simple way to
  63 create a virtual environment of Python3 is
  64
  65 `$ python3 -m venv MyPythonEnv/`
  66
  67 Then activate it by
  68
  69 `$ source MyPythonEnv/bin/activate`
  70
  71 If you use 'conda', it will also provide virtual environment. Please
  72 read:
  73 [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html)
  74 or [miniconda](https://docs.conda.io/en/latest/miniconda.html)
  75
  76 ## Install through PyPI
  77
  78 The easiest way to install MACS is through PyPI system. Get `pip` if
  79 it's not available in your system. If you create a virtual environment
  80 as described before, your `pip` command will install everything under
  81 the folder you specified previously through `python3 -m env` command,
  82 or to your active conda environment.
  83
  84 Then under the command line, type `pip install macs3`. PyPI will
  85 install dependencies automatically if it is absent.
  86
  87 To upgrade MACS3, type `pip install --upgrade macs3`. It will check
  88 currently installed MACS3, compare the version with the one on PyPI
  89 repository, download and install a newer version while necessary.
  90
  91 ## Install from source
  92
  93 MACS uses `pip` for source code installations. To install a source
  94 distribution of MACS, unpack the distribution tarball, or clone Git
  95 repository with `git clone --recurse-submodules git@github.com:taoliu/MACS.git`.
  96 Go to the directory where you cloned MACS from github, and simply
  97 run the install command:
  98
  99  `$ pip install .`
 100
 101 By default, the script will install python library and executable
 102 codes according to the environment. When you run the command under
 103 virtualenv or conda environment, the script will install to the virtual
 104 environment instead. When you run the command without virtual environment,
 105 you may need to be root or administrator of the machine so as to
 106 complete the installation. Please contact the system administrator
 107 if you want their help.
 108
 109 ## Configure environment variables
 110
 111 *Note*, if you are using a virtual environment, you should skip this
 112 section since all the corresponding environment variables have been
 113 correctly set while you `activate` the environment.
 114
 115 After running the setup script, you might need to add the install
 116 location to your `PYTHONPATH` and `PATH` environment variables. The
 117 process for doing this varies on each platform, but the general
 118 concept is the same across platforms.
 119
 120 ### PYTHONPATH
 121
 122 To set up your `PYTHONPATH` environment variable, you'll need to add
 123 the value `PREFIX/lib/pythonX.Y/site-packages` to your existing
 124 `PYTHONPATH`. In this value, X.Y stands for the major–minor version of
 125 Python you are using (such as 3.7; you can find this with
 126 `sys.version[:3]` from a Python command line). `PREFIX` is the install
 127 prefix where you installed MACS. If you did not specify a prefix on
 128 the command line, MACS will be installed using Python's sys.prefix
 129 value.
 130
 131 On Linux, using bash, I include the new value in my `PYTHONPATH` by
 132 adding this line to my `~/.bashrc`::
 133
 134  `$ export
 135  PYTHONPATH=/home/taoliu/lib/python3.7/site-packages:$PYTHONPATH`
 136
 137 Using Windows, you need to open up the system properties dialog and
 138 locate the tab labeled Environment. Add your value to the `PYTHONPATH`
 139 variable, or create a new `PYTHONPATH` variable if there isn't one
 140 already.
 141
 142 ### PATH
 143
 144 Just like your `PYTHONPATH`, you'll also need to add a new value to
 145 your PATH environment variable so that you can use the MACS command
 146 line directly. Unlike the `PYTHONPATH` value, however, this time
 147 you'll need to add `PREFIX/bin` to your PATH environment variable. The
 148 process for updating this is the same as described above for the
 149 `PYTHONPATH` variable::
 150
 151  `$ export PATH=/home/myaccount/bin:$PATH`
 152