SPRING_py3

This is an update of AllonKleinLab/SPRING_dev to use Python 3.

Conda Environment and Installing Python libraries

To run SPRING Viewer locally, you'll need to set up a conda environment for it and install its dependencies:

numpy scipy matplotlib h5py flask networkx scikit-learn (imported as sklearn) python-louvain (imported as community) fa2

We recommend Anaconda (specifically Miniconda) to manage your Python libraries. You can download it here: https://conda.io/miniconda.html.

Create a Python 3 conda environment for SPRING viewer to run in. For example, to create a conda environment called spring_viewer with Python 3.9, you can open Terminal (Mac) or Anaconda Prompt (Windows) and enter:

conda create -n spring_viewer python=3.9

Activate your new conda environment by running:

conda activate spring_viewer

Most of the libraries SPRING needs can then be installed by running:

conda install numpy scipy matplotlib h5py flask networkx scikit-learn

Also run:

pip install annoy python-louvain

The ForceAtlas2 Library

The forceatles fa2 library is used for allowing dynamic interaction and layout of graphs in SPRING. In this Python3 upgrade, the fa2 library should be installed as per the package documentation using the following line:

pip install fa2

However at the time of this update, this line threw an error. SPRING_py3 can still be used for all other functions for interactive data exploration, using data xy coordinate layouts prepared in advance, e.g. using scanpy.

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

These files are generated in scanpy using scanpy.external.exporting.spring_project.

Running SPRING Viewer

Open Terminal (Mac) or Anaconda Prompt (Windows) and change directories (cd) to the directory containing this README file (SPRING_dev/).
Activate your conda environment for running SPRING; you can list all your conda environments by running conda env list if you need a reminder of what it's called. As an example, if your environment is called spring_viewer, you can activate it by entering the following: conda activate spring_viewer
Start a local server by entering the following: ./start_server.sh
Open web browser (preferably Chrome; best to use incognito mode to ensure no cached data is used).
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).

Summary of major changes from SPRING_dev to SPRING_py3

Updated syntax to python3
Uses flask for http server, instead of cgi
Removed old unused script directories
Added .gitignore file
In-progress (incomplete) update of code to allow running SPRING from any working directory

AllonKleinLab / SPRING_py3