What are the platform requirements and software dependencies for running Oncotator?
Oncotator is written in Python. It can be run on all major Unix-based operating systems (Linux, MacOSX, etc.) that support Python. Unfortunately, running on Windows is not currently supported due to a dependency,
pysam, being unsupported on Windows.
Note that Oncotator requires Python 2.7.x; other versions of Python (including Python 3) are not supported.
Oncotator depends on several external Python libraries, which you'll need to install to your environment. The full list of dependencies is given below. There are two ways to install these dependencies: the easiest way is to run the automated setup script we provide, or you can install them manually one by one. The script will set up a Virtual Environment and install all necessary packages to that environment for you. It is especially convenient if you do not have administrative permissions on your machine (see the tutorial for details).
Python libraries required by Oncotator
- pysam* (version 0.7.5)
The libraries marked with a * require a compilation step, so you'll need some additional software installed. See below for other software dependencies and known issues.
Other software dependencies
The packages marked with a * in the list above need to be compiled from C source code, so you will need to have a C compiler installed before you can install them. If your system is MacOSX, you will need to download and install the XCode developer tools, which are available for free in Apple's App Store.
- VCF manipulation
Troubleshooting known installation issues
We have run into some issues while testing these installation instructions; see below for a list of issues and solutions. This list may not be complete; let us know in the comments if you encounter other problems and we'll try to help you. If you found the solutions yourself, even better, but be sure to post your solution so others can benefit from it.
Note that these issues can be handled through the virtual environment installation script we provide; see the script documentation for details.
- Compilation issues
If you don't have the appropriate compilers installed, some of the package installations will fail. See the section above for information about compiler requirements.
In addition, there is a known bug on MacOSX caused by XCode 5.1.1 that causes compilation failures in the packages that are marked with a * in the list above. This bug is documented here in Apple's Developer Tools knowledgebase. There is a reported solution on Stackoverflow that works in our hands. You just need to add this flag to your pip command line:
pip command line would be:
ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install <package-name>
<package-name> is e.g.
numpy. If you're installing the package manually from source instead of using a package manager, you can just use the flag in your command line in the same way, as in:
ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future python setup.py build
In any case you'll see a lot of warnings being emitted, but the installation will be successful.
- Pysam version
At time of writing, Oncotator specifically requires version 0.7.5 of Pysam. However, that version is not available as a verified package, so you need to add a flag to install command to allow an unverified package to be used. Otherwise
pip will claim that there is no version 0.7.5 available at all. The full command is then:
pip install -I --allow-unverified pysam pysam==0.7.5
To which you may need to prepend the
ARCHFLAGS bit if you run into the compilation issue described above.
- PyVCF version
At time of writing, the official version of PyVCF has a bug that causes Oncotator to fail when processing VCF files. We have a forked version that we fixed ourselves, which you can get here. This package is installed by the setup script that we provide, but in rare cases the installation does not work. If you run into this problem you'll need to download the source package and install it manually using the classic
python setup.py install command as described in this tutorial.
Important note on permissions:
If you do not have root access to your python interpreter, you will need to set up a python virtual environment in order to run Oncotator. The idea is that
virtualenv.py can be run as a standalone script, thereby bypassing superuser requirements. See the tutorial referenced above for details on how to do this. More information about virtual environments can be found here.