(howto) Set up a Virtual Environment and install all dependencies for Oncotator
Using the script we provide is the easiest way to set up your Python environment to run Oncotator. It will install all the other software that is required by Oncotator. Note however that the script does not install Oncotator itself; you will still have to do that manually once you have successfully run the script. See this tutorial for instructions on how to install Oncotator and run it for the first time.
1. Install the
virtualenv library for Python
First you need to install the
virtualenv library for Python, which you can get here. You can either use your favorite Python package management tool, or install it manually.
$ pip install virtualenv
In this tutorial we use
pip, which is a very convenient way to manage Python packages (for more details and instructions on installing pip, see the documentation here).
2. Make sure that you have a C compiler and a FORTRAN compiler installed on your system
The script will install some software that needs to be compiled, so you need to have some compilers installed on your system. See the article on Oncotator's dependencies for details and links to software downloads. If you are on MacOSX, make sure you have the XCode developer tools installed.
3. Run the setup script
Once you have
virtualenv installed, you just run the script we provide using the following command:
$ bash scripts/create_oncotator_venv.sh -e <venv_location>
<venv_location> is the location (filepath) where you want your virtual environment to live. This creates several directories containing all the necessary files for your shiny new virtual environment. If that works right away (which it should in most cases), skip on ahead to the next step. If you run into any issues, see the Troubleshooting section at the end of this document.
4. Activate the virtual environment
Whenever you want to use your virtual environment, use this command to activate it:
$ source <venv_location>/bin/activate
Once the environment is activated, anything you do involving Python (installing packages or running programs) will be executed within that environment. It's like having a bubble universe on your machine. When you're done, just deactivate it using this command:
If you plan to always do all your Python work inside the virtual environment, you can leave it activated, and it will be ready for you at any time as long as your shell session stays open.
See this document for more details on how to use your new virtual environment.
If you wish to add the oncotator executable to your path:
$ export PATH=<venv_location>/bin/oncotator:$PATH
5. Troubleshooting the setup script
There are a few known issues that can cause the script to fail, depending on your system. See the article on Oncotator's dependencies for details of known issues and solutions. If you are on MacOSX and you run into the XCode 5.1.1 compilation bug (described in the article referenced above), you can apply the workaround to the script by adding the
-c flag to your command like this:
$ bash scripts/create_oncotator_venv.sh -e <venv_location> -c
If that still doesn't work, you'll have to skip those packages and install them manually afterward. To skip packages that require compilation, add the
-k flag to your command like this:
$ bash scripts/create_oncotator_venv.sh -e <venv_location> -k
Finally, there is one package (pyvcf) that currently can't be installed through
pip. The script is set up to retrieve the source (using
wget) and install it from another repository, but in some cases (e.g. if you don't have
wget installed) it may fail. If so, you'll need to skip that package and install it manually afterward. To skip that package, add the
-s flag to your command like this:
$ bash scripts/create_oncotator_venv.sh -e <venv_location> -s