Installing RNAvigate

Choose one of the installation options below:

Docker installation

To install RNAvigate locally, this is the easiest option.

Step 1 - Install Docker Desktop

Docker Desktop

Step 2 - Run RNAvigate docker image

Open Docker Desktop. In the top search bar, type “psirving/rnavigate”, and click “run”. Expand the “Optional settings” drop-down menu, and enter the following options:

  • Container name: RNAvigate

  • Host port: 8888

  • Volumes:

    • Host path: use the (…) button to choose a directory.

    • Container path: /home/jovyan/work

The choice of “Host path” is important. RNAvigate will only have access to this directory. Choose a high level directory that includes data files you wish to work on, but not too high. For example, your home directory is perhaps not appropriate. A good choice for me would be my “weeks_lab” directory, where I do all of my lab related work.

Click “run” again. This will take you to a terminal, at the end of which you should see something like this:

YYYY-MM-DD HH:MM:SS     To access the notebook, open this file in a browser:
YYYY-MM-DD HH:MM:SS         file:///home/jovyan/.local/share/jupyter/runtime/nbserver-7-open.html
YYYY-MM-DD HH:MM:SS     Or copy and paste one of these URLs:
YYYY-MM-DD HH:MM:SS         http://12ab34de56fg:8888/?token=01234567890abcdefghijklmnopqrstuvwxyz01234567890
YYYY-MM-DD HH:MM:SS      or http://127.0.0.1:8888/?token=01234567890abcdefghijklmnopqrstuvwxyz01234567890

Step 3 - Open Jupyter server

Click on either the 2nd or 3rd link above, or copy/paste them into a browser. This will open a Jupyter server. Navigate to /home/jovyan/work/, this is linked to the host path that you set up in step 2. Your files are accessible here. You can now open a new Jupyter Notebook and start exploring your data!

Step 4 - Save and quit

Don’t forget to save! To stop the session, go back to Docker Desktop, and click the stop button in the upper-right.

Step 5 - Restarting RNAvigate

To restart this session, go the “Containers” menu, click “start” on the RNAvigate container. Next to that button, click (…) -> “view details” and go back to step 3.

Anaconda installation

If you are working on shared HPC resources, the Docker method may not work. Use conda instead.

Step 1 - Download RNAvigate

In a terminal, navigate to the directory in which you’ll save RNAvigate. Clone the github repository. Then, navigate into the new RNAvigate directory.

git clone https://github.com/Weeks-UNC/RNAvigate.git RNAvigate_v1.0.0
cd RNAvigate_v1.0.0

Step 2 - Create the conda environment

Create a conda enviroment using the included environment.yml file. This step can take a long time, be patient. Grab a coffee.

conda env create -f environment.yml

Step 3 - Install RNAvigate as a Jupyter kernel

Activate the new conda environment. Install the RNAvigate package in the new conda environment. Then, install the new environment for Jupyter.

conda activate RNAvigate_v1.0.0
conda develop .
python -m ipykernel install --user --name=RNAvigate_v1.0.0

Step 4 - Test the installation

Test the installation by opening an example Jupyter Notebook.

You may need to follow additional guidance for using Jupyter Notebooks on HPCs. This is dependent on the administration of your HPC, and outside the scope of this guide.

jupyter notebook ./docs/examples/

Open a notebook and click “Kernel”, “restart and run all”.

If RNAvigate fails to import, add this code to the very top of the notebook. Replace /path/to/RNAvigate/ with the location of your RNAvigate directory.

import sys
sys.path.append('/path/to/RNAvigate/')

This is an occassionally recurring issue with conda develop . used in step 3. If you know of a solution, please let me know on Github issues. I’m trying to avoid adding directly to system path, so that different versions of RNAvigate work in different notebooks.

Manual installation

To install manually, you will need the following dependencies in your python environment:

  • scipy >= 1.6.2

  • py3dmol >= 0.8.0

  • matplotlib >= 3.3.4

  • python >= 3.9.2

  • seaborn >= 0.11.1

  • biopython >= 1.78

  • numpy >= 1.20.1

  • pandas >= 1.2.4

  • scikit-learn >= 1.0.2

Download the package from Github. Add this directory your $PYTHONPATH, and you are good to go.

UNC Longleaf installation

Step 1 - Install RNAvigate

First, we need to make sure that you have an Anaconda environment that includes all dependencies and that that environment is available to Jupyter. This does not change your default modules. They will be restored next time you log in.

module rm python pymol pyrosetta
module load anaconda/2019.10
conda env create -f /proj/kweeks/bin/RNAvigate_v1.0.0/environment.yml
source activate RNAvigate_v1.0.0
conda develop /proj/kweeks/bin/RNAvigate_v1.0.0/
python -m ipykernel install --user --name=RNAvigate_v1.0.0

If this occured without errors, exit longleaf and go to UNC’s OpenOnDemand Service. OpenOnDemand is UNC’s platform for using interactive programs within Longleaf.

Step 2 - Open Jupyter on OnDemand

Log in using your ONYEN, and start a jupyter notebook.

  1. Click on interactive apps, under servers, click on Jupyter Notebook.

  2. Enter the number of hours you will be working, 1 CPU, other fields blank.

  3. Don’t forget to save before you run out of time!

Step 3 - Test the installation

Navigate to your data directory, and open a new notebook using the “RNAvigate_v1.0.0” option. Type import rnavigate as rnav into the first code cell and run it. If no errors occur, you’re ready to starting exploring your data!