INSTALL.md

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