A Hitchhiker's Guide to Installing candis on Mac OS X

From Zero to Hero - Achilles Rasquinha

To the best of my knowledge, this will be the only page you'd ever require to install candis right from scratch. This script also believes to be a foolproof setup to have candis onto your system. In case if you run into some problems, feel free to raise an issue here.

NOTE: To see if your Mac OS X version has been tested for the following script, check here. You're free to revise this page in order to add your Mac OS X version if you're successful with this script too (psst, helps others).

Installation

First, open your Terminal (Finder > Go (Menu Bar) > Utilities > Terminal)

TL;DR

$ curl -sL git.io/install-candis | python

• Install Xcode command-line tools

$ xcode-select --install

When you execute the above command, a pop-up window will appear. Click on Install and then accept the terms and conditions (by clicking on Agree). Once downloaded and installed, click on Done.

Brewing

• Install Homebrew - Mac OS X's package manager
  (Requires Ruby installed. To our luck, Ruby comes packaged with most Mac OS X systems)

On OS X El Capitan, Yosemite, Mavericks, and macOS Sierra, Ruby 2.0 is included. OS X Mountain Lion, Lion, and Snow Leopard ship with Ruby 1.8.7 - Ruby Lang Documentation

(Type ruby --version to check whether Ruby is available on your system)

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

• Check whether Homebrew has been installed correctly

$ brew doctor

You should then see - Your system is ready to brew! on your terminal screen

• Update Homebrew and its formulae

$ brew update

Git

• Install git (Using Homebrew)

$ brew install git

• ...and check if git has been correctly installed.

$ git --version

You should then see the version information only.

Fetching candis via git

• Clone candis (Optional - Add the --recursive flag to clone candis-res, a repository with sample genomic data) using git.

$ git clone --recursive https://github.com/HelikarLab/candis.git

This just goes ahead and pulls the source files from the remote git repository.

• Ensure you're pointing to candis's root directory

$ cd candis

Adding candis to your Environment Variable

Add candis to your $PYTHONPATH Environment Variable as follows:

$ # Add Environment Variable to ~/.bash_profile
$ echo "export PYTHONPATH=path/to/candis/candis:$PYTHONPATH" >> ~/.bash_profile
$ # Refresh ~/.bash_profile
$ source ~/.bash_profile                                                 

where path/to/candis is the absolute path to your candis source directory. Note that $PYTHONPATH points to candis's Python source directory (path/to/candis/candis) and not its root source directory (path/to/candis).

Dependency Requirements for both, Development and Production

candis's API (CLI as well as the RIA server) is built using Python (3.6+); while from Data Manipulation to Model Deployment uses Python wrappers for R and WEKA (which requires Java). In addition, candis requires graphviz installed (to generate Graph Visualisations for models like Decision Trees, etc.).

• Install Python 3 (Using Homebrew)
  (Comes with pip - Python's Package Manager installed)

$ brew install python3

• Install R (Using Homebrew)

$ brew tap homebrew/science # Everything Science
$ brew tap caskroom/cask    # Homebrew's "drag-and-drop" alternative
$ brew cask install xquartz # X Window System (Using Homebrew Cask)
$ brew install r            # Install R

• Check if R is correctly installed

$ R --version

• Install WEKA (Using Homebrew Cask)

$ brew cask install weka

Homebrew Cask automatically handles the required dependencies for you.

• Install Graphviz (Using Homebrew)

$ brew install graphviz

Installing R dependencies

• Run the R/setup.R script within the candis source directory as follows:

$ cd R && Rscript setup.R && cd ..

Installing Python dependencies

Creating a Python Virtual Environment

We recommend you to install candis's Python Dependencies within a virtualenv (A virtualenv goes ahead and creates an isolated Python environment for you).

• Install and Create a virtualenv named venv

$ pip3 install virtualenv    # Installs a Python Virtual Environment
$ virtualenv venv -p python3 # Creates  a Python Virtual Environment named `venv`
$ source venv/bin/activate   # Goes ahead and activates the Virtual Environment for you.

ISSUE: candis uses python-weka-wrapper (which then uses the python-javabridge library for running and accessing the Java Virtual Machine) to utilize everything (almost) WEKA has to offer. A quick warning is that candis uses a bleeding-edge version of python-javabridge (Check out python-javabridge's Issue #111).

• First, install numpy (a dependency of python-javabridge)

(venv) $ pip install numpy

• Now, simply install candis's Python Dependencies

For Production only

(venv) $ pip install -r requirements.txt

For Development only

(venv) $ pip install -r requirements-dev.txt

• Finally, candis uses matplotlib to render neat graphs. Hence, change matplotlib's backend to TkAgg

$ echo "backend: TkAgg" >> ~/.matplotlib/matplotlibrc

Dependency Requirements for Development

candis comes with out-of-the-box precompiled JavaScript and CSS files. However if you're interested in building one yourself, you'd then require Node.js and SASS as additional dependencies.

• Install Node.js (Using Homebrew)
  (Comes with npm - Node's Package Manager installed).

$ brew install node

• Install SASS (as a Ruby Gem)

$ gem install sass

Using Sample Data provided

candis comes with a candis-res directory that provides you some sample genomic data to start with. Simply:

$ mkdir CRES && cp candis-res/CRES/* CRES

Running the candis Rich Internet Application (RIA)

Run candis as a module

(venv) $ python -m candis

Open your favourite browser, type localhost:5000 on the address bar and press Enter (Return). You should then see something like this.

Tried and Tested

NOTE: If you're attempting to revise this page after successfully installing and running candis, kindly add the required details in the following format only.

Name	Version	By
Mac Sierra	10.12.5	Achilles Rasquinha @achillesrasquinha, [email protected]