docs/INSTALL.md

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