Installing Python libraries

To run SPRING Viewer locally, make sure Python 2.7 is installed (and that it's your active version). You will also need the following Python libraries:

scikit-learn
numpy
scipy
matplotlib
h5py
networkx
fa2
python-louvain

We recommend Anaconda to manage your Python libraries. You can download it here (be sure to get the Python 2.7 version): https://conda.io/miniconda.html. Libraries can then be installed using the command conda. To do so, open Terminal (Mac) or Anaconda Prompt (Windows) and enter:

conda install scikit-learn numpy scipy matplotlib h5py

The remaining libraries can be installed using pip. Note that if you're a Windows user, you'll first need to install Microsoft Visual C++ compiler for Python (available from http://aka.ms/vcpython27). Enter the following into Terminal or Anaconda Prompt:

pip install networkx fa2 python-louvain

Setting up a SPRING data directory

See the example notebooks:
Hematopoietic progenitor FACS subpopulations
Mature blood cells (10X Genomics 4k PBMCs)
CITE-seq data from 10X Genomics
PBMCs from 10X Genomics

A SPRING data set consist of a main directory and any number of subdirectories, with each subdirectory corresponding to one SPRING plot (i.e. subplot) that draws on a data matrix stored in the main directory. The main directory should have the following files, as well as one subdirectory for each SPRING plot.

matrix.mtx
counts_norm_sparse_cells.hdf5
counts_norm_sparse_genes.hdf5
genes.txt

Each subdirectory should contain:

categorical_coloring_data.json
cell_filter.npy
cell_filter.txt
color_data_gene_sets.csv
color_stats.json
coordinates.txt
edges.csv
graph_data.json
run_info.json

Running SPRING Viewer

1. Open Terminal (Mac) or Anaconda Prompt (Windows) and change directories (cd) to the directory containing this README file (SPRING_dev/).
2. Start a local server by entering the following: python -m CGIHTTPServer 8000
3. Open web browser (preferably Chrome; best to use incognito mode to ensure no cached data is used).
4. View data set by navigating to corresponding URL: http://localhost:8000/springViewer_1_6_dev.html?path_to/main/subplot. In the example above, if you wanted to view a SPRING plot called FullDataset_v1 in the main directory 10X_PBMCs_Signac_GitHub, then you would navigate to http://localhost:8000/springViewer_1_6_dev.html?datasets/10X_PBMCs_Signac_GitHub/FullDataset_v1

Signac

To classify cellular phenotypes in single cell data, SignacX was integrated with the files output by SPRING (specifically, the matrix.mtx, genes.txt, edges.csv and categorical_coloring_data.json files), such that SPRING data can be classified by Signac in R with only a few lines of code. First, install SignacX in R:

# load the Signac library
install.packages('SignacX')
library(SignacX)

Now classify the cellular phenotypes in R, which allows them to be visualized in SPRING Viewer:

# dir is the subdirectory generated by the Jupyter notebook; it is the directory that contains the 'categorical_coloring_data.json' file.
dir = "./FullDataset_v1" 

# load the expression data
E = CID.LoadData(dir)

# generate cellular phenotype labels
labels = Signac(E, spring.dir = dir, num.cores = 4)
# alternatively, if you're in a hurry, use:
# labels = SignacFast(E, spring.dir = dir, num.cores = 4)
celltypes = GenerateLabels(labels, E = E, spring.dir = dir)

# write cell types and Louvain clusters to SPRING
dat <- CID.writeJSON(celltypes, spring.dir = dir)

Subsequently, the single cell data together with the cellular phenotypes (and Louvain clusters) can be visualized in SPRING Viewer (Signac writes the cell type and clustering information to the categorical_coloring_data.json file).