INSTALL.md

   1 # INSTALL Guide For MACS
   2 Time-stamp: <2019-12-12 13:26:11 taoliu>
   3
   4 Please check the following instructions to complete your installation.
   5
   6 ## Prerequisites
   7
   8 MACS v2.2.x requires Python3. We have tested MACS in Python3.6, 3.7
   9 and 3.8.
  10
  11 MACS also requires [Numpy](http://www.scipy.org/Download) (>=1.17).
  12
  13 GCC is required to compile `.c` codes in MACS v2 package, and python
  14 header files are needed. If you are using Mac OSX, I recommend you
  15 install Xcode; if you are using Linux, you need to make sure
  16 `python-dev` package is installed -- the actual package name depends
  17 on the Linux OS distribution, you are using.
  18
  19 [Cython](http://cython.org/) is **NOT** required although most of MACS
  20 codes are written in Cython. But if you plan to generate `.c` files
  21 from `.pyx` by yourself, you can install Cython (>=0.29), then use
  22 `setup.py` script.
  23
  24 ## Prepare a virtual Python environment
  25
  26 I strongly recommend installing your MACS program in a virtual
  27 environment, so that you have full control of your installation and
  28 won't mess up with your system libraries. To learn about virtual
  29 environment, read [this
  30 article](https://docs.python.org/3/library/venv.html). A simple way to
  31 create a virtual environment of Python3 is
  32
  33 `$ python3 -m venv MyPythonEnv/`
  34
  35 Then active it by
  36
  37 `$ source MyPythonEnv/bin/active`
  38
  39 ## Install through PyPI
  40
  41 The easiest way to install MACS is through PyPI system. Get `pip` if
  42 it's not available in your system. If you create a virtual environment
  43 as described before, your `pip` command will install everything under
  44 the folder you specified previously through `python3 -m env` command.
  45
  46 Then under the command line, type `pip install macs2`. PyPI will
  47 install Numpy automatically if it is absent.
  48
  49 To upgrade MACS2, type `pip install --upgrade macs2`. It will check
  50 currently installed MACS2, compare the version with the one on PyPI
  51 repository, download and install a newer version while necessary.
  52
  53 ## Install through Conda
  54
  55 Please check [MACS2 page on
  56 bioconda](https://anaconda.org/bioconda/macs2) for instructions.
  57
  58 ## Install through Debian APT
  59
  60 MACS is included in Debian Stretch/Buster/Unstable blessed by some
  61 kind of Supper Cow Powers.
  62
  63 ## Install from source
  64
  65 MACS uses Python's [setuptools](https://setuptools.readthedocs.io) for
  66 source code installations. To install a source distribution of MACS,
  67 unpack the distribution tarball, or clone Git repository with `git
  68 clone git@github.com:taoliu/MACS.git`. Go to the directory where you
  69 unpacked MACS, and simply run the install script:
  70
  71  `$ python setup.py install`
  72
  73 By default, the script will install python library and executable
  74 codes according to the environment. When you run the command under
  75 virtualenv, the script will install to the virtual environment
  76 instead. When you run it without virtual environment, you may need to
  77 be root or administrator of the machine so as to complete the
  78 installation. Please contact the system administrator if you want
  79 their help. If you need to provide a nonstandard install prefix, or
  80 any other nonstandard options, you can provide many command line
  81 options to the install script. Use the `--help` option to see a brief
  82 list of available options:
  83
  84  `$ python setup.py --help`
  85
  86 For example, if I want to install everything under my own HOME
  87 directory, use this command:
  88
  89  `$ python setup.py install --prefix /home/taoliu/`
  90
  91 As mentioned in *Prerequisites*, you don't need to install Cython in
  92 order to install MACS. When Cython is available, this setup script
  93 will regenerate C codes from Pyx codes when necessary. When Cython is
  94 not available, this setup script will just use the C codes included in
  95 the release package (or your Github clone) for installation.
  96
  97 ## Configure environment variables
  98
  99 *Note*, if you are using a virtual environment, you should skip this
 100 section since all the corresponding environment variables have been
 101 correctly set while you `activate` the environment.
 102
 103 After running the setup script, you might need to add the install
 104 location to your `PYTHONPATH` and `PATH` environment variables. The
 105 process for doing this varies on each platform, but the general
 106 concept is the same across platforms.
 107
 108 ### PYTHONPATH
 109
 110 To set up your `PYTHONPATH` environment variable, you'll need to add
 111 the value `PREFIX/lib/pythonX.Y/site-packages` to your existing
 112 `PYTHONPATH`. In this value, X.Y stands for the major–minor version of
 113 Python you are using (such as 3.7; you can find this with
 114 `sys.version[:3]` from a Python command line). `PREFIX` is the install
 115 prefix where you installed MACS. If you did not specify a prefix on
 116 the command line, MACS will be installed using Python's sys.prefix
 117 value.
 118
 119 On Linux, using bash, I include the new value in my `PYTHONPATH` by
 120 adding this line to my `~/.bashrc`::
 121
 122  `$ export
 123  PYTHONPATH=/home/taoliu/lib/python3.7/site-packages:$PYTHONPATH`
 124
 125 Using Windows, you need to open up the system properties dialog and
 126 locate the tab labeled Environment. Add your value to the `PYTHONPATH`
 127 variable, or create a new `PYTHONPATH` variable if there isn't one
 128 already.
 129
 130 ### PATH
 131
 132 Just like your `PYTHONPATH`, you'll also need to add a new value to
 133 your PATH environment variable so that you can use the MACS command
 134 line directly. Unlike the `PYTHONPATH` value, however, this time
 135 you'll need to add `PREFIX/bin` to your PATH environment variable. The
 136 process for updating this is the same as described above for the
 137 `PYTHONPATH` variable::
 138
 139  `$ export PATH=/home/taoliu/bin:$PATH`
 140
 141 -- Tao Liu <vladimir.liu@gmail.com>