Getting started on Ubuntu

Use the following directions to quickly get started and run on Ubuntu the ExpressionMatrix2 software on a toy dataset distributed as part of the repository.

• Use a Linux machine running Ubuntu 16.04 (the current long term support release of Ubuntu). Other distributions using similar versions of the Linux kernel, such as Linux Mint 18, will also work.
• Make sure the following package, available from the standard Ubuntu repositories, is installed:
  • Graphviz (package graphviz).
  If this package is not installed, you can install it using command sudo apt-get install graphviz. This requires root access.
• Select one of the releases available on GitHub and download the tar file for the release you selected. The information in this page applies to release 0.4.0 or later, and the commands below assume that you selected release 0.4.0. In that case the tar file will be named ExpressionMatrix2-0.4.0.tar.
• Create an empty directory. In the rest of these directions we assume that the directory you created is ~/ExpressionMatrix2. If you use a different name, make sure to use the correct name instead of the one used in the rest of these directions.
• Move the tar file you downloaded from the directory where your browser stores downloads (usually ~/Downloads) to the ~/ExpressionMatrix2 directory your just created, then cd to ~/ExpressionMatrix2.
• Extract the files contained in the tar file you downloaded using command tar -xvf ExpressionMatrix2-0.4.0.tar. This will create a new directory ~/ExpressionMatrix2/ExpressionMatrix2-0.4.0 containing a doc directory, a test directory, and a build directory containing ExpressionMatrix2 shared libraries for various platforms.
• To get started on Ubuntu in the simplest mode of operation, you will use shared library ~/ExpressionMatrix2/ExpressionMatrix2-0.4.0/build/Release-ubuntu16-nohdf5-python2/ExpressionMatrix2.so. To make this shared library visible as a Python package, set environment variable PYTHONPATH to ~/ExpressionMatrix2/ExpressionMatrix2-0.4.0/build/Release-ubuntu16-nohdf5-python2. In the bash shell, you can do this using command export PYTHONPATH=~/ExpressionMatrix2/ExpressionMatrix2-0.4.0/build/Release-ubuntu16-nohdf5-python2.
• Now cd to test directory ~/ExpressionMatrix2/ExpressionMatrix2-0.4.0/tests/ToyTest1. It contains input files with a sample expression matrix and cell meta data for a small toy test with just 3 cells and 3 genes. It also contains two small python scripts.
• Run command python run.py.
• Run command python runServer.py. This starts the ExpressionMatrix2 code in a mode where if behaves as an http server that can be used for interactive visualization and analysis. This command continues running until you interrupt it.
• While the server is running, start a web browser on the same machine, and point it to the following URL: http://localhost:17100.
• Interactively explore the functionality offered by the server. You will need a more real test case to perform any interesting visualization or analysis, but if you made it here you are ready to run the ExpressionMatrix2 software on real data. See here for more information.

For convenience, the list below summarizes the commands to run. This assumes that you start in directory ~/ExpressionMatrix2 containing the tar file ExpressionMatrix2-0.4.0.tar:

tar -xvf ExpressionMatrix2-0.4.0.tar
cd ExpressionMatrix2-0.4.0/tests/ToyTest1
export PYTHONPATH=~/ExpressionMatrix2/ExpressionMatrix2-0.4.0/build/Release-ubuntu16-nohdf5-python2
python run.py
python runServer.py

Python 3

If you prefer to use Python 3, the same procedure will work with the following minor changes, assuming of course that Python 3 is installed on your machine.

• Set PYTHONPATH to point to ~/ExpressionMatrix2/ExpressionMatrix2-0.4.0/build/Release-ubuntu16-nohdf5-python3.
• When invoking run.py and runServer.py, prefix them with python3 instead of python. Alternatively, you can invoke these scripts as ./run.py and ./runServer.py because their first line specifies python3 as the interpreter to be used by the shell.