Trajectorama

Trajectorama is an algorithm that implements coexpression-based integration of multi-study single-cell trajectories. Trajectorama is described in the paper "Coexpression enables multi-study cellular trajectories of development and disease" by Brian Hie, Hyunghoon Cho, Bryan Bryson, and Bonnie Berger.

Installation

The most import dependency is on a custom implementation of Louvain clustering, which can be installed with the below commands: ```

Binary dependency (for Ubuntu/Debian).

sudo apt-get install bison flex

git clone https://github.com/brianhie/louvain-igraph cd louvain-igraph python setup.py install ```

Troubleshooting: To avoid conflicts with the main version of louvain-igraph, install the custom Louvain package first in a new conda environment prior to installation of any downstream dependencies (like scanpy and trajectorama).

Installing Trajectorama can then be done by: python -m pip install trajectorama

API and example usage

We provide a basic API around the core algorithm that takes an expression matrix augmented with study information and returns a list of coexpression matrices, with corresponding indices into the original data: ```python import trajectorama

X = [ ... ] # Sample-by-gene expression matrix. studies = [ ... ] # Study identifiers, one for each row of X.

Xscoexpr, sampleidxs = trajectorama.transform( X, studies, corrcutoff=0.7, corrmethod='spearman', clustermethod='louvain', mincluster_samples=500, ) ```

The coexpression matrix Xs_coexpr[i] is defined over the subset of cells X[sample_idxs[i], :]. See the documentation string under the transform() function at the top of trajectorama/trajectorama.py for the full list of parameters and default values.

This list of coexpression matrices can then be used in further analysis, e.g., you can flatten the matrices and use Scanpy to visualize the matrices as a KNN graph based on distance in coexpression space: ```python from anndata import AnnData import numpy as np import scanpy as sc from scipy.sparse import csr_matrix

Save upper triangle and flatten.

nfeatures = X.shape[1] triuidx = np.triuindices(nfeatures) # Indices of upper triangle. Xcoexpr = np.concatenate([ Xcoexpri[triuidx].flatten() for Xcoexpri in Xcoexprs ]) Xcoexpr = csrmatrix(Xcoexpr)

Plot KNN graph in coexpression space.

adata = AnnData(Xcoexpr) sc.pp.neighbors(adata) sc.tl.drawgraph(adata) sc.pl.draw_graph(adata)

```

The example scripts below show more detailed usage of Trajectorama, which was used to generate the paper results.

Examples

Trajectorama for mouse neuronal development

Trajectorama analyzes five large-scale studies of mouse neurons over multiple points in development.

Data can be found at http://trajectorama.csail.mit.edu/data.tar.gz and can be downloaded as: wget http://trajectorama.csail.mit.edu/data.tar.gz tar xvf data.tar.gz

To preprocess the data, run the command: python bin/process.py conf/mouse_develop.txt This preprocessing step only needs to be done once. Then, we perform panclustering and coexpression matrix computation using the command: bash python bin/mouse_develop.py > mouse_develop.log This will save each coexpression matrix as a .npz file to a directory under target/sparse_correlations/. Computing all coexpression matrices should complete in around an hour when running on a single core.

The downstream analysis can then be performed on these cached matrices using the commands: bash python bin/mouse_develop_cached.py >> mouse_develop.log python bin/mouse_develop_dictionary.py >> mouse_develop.log This will log some relevant statistics and save visualizations under the figures/ directory.

Trajectorama for human hematopoiesis

We can perform a similar workflow for human hematopoiesis by running the commands: ```bash

Download (if not done so for mouse data).

wget http://trajectorama.csail.mit.edu/data.tar.gz tar xvf data.tar.gz

Preprocess.

python bin/process.py conf/hematopoiesis.txt

Analyze.

python bin/hematopoiesis.py > hematopoiesis.log python bin/hematopoiesiscached.py >> hematopoiesis.log python bin/hematopoiesisdictionary.py >> hematopoiesis.log ```

Trajectorama for microglia

We can perform a similar workflow for mouse and human microglia in various conditions by running the commands: ```bash

Download (if not done so for mouse data).

wget http://trajectorama.csail.mit.edu/data.tar.gz tar xvf data.tar.gz

Preprocess.

python bin/process.py conf/microglia.txt

Analyze.

python bin/microglia.py > microglia.log python bin/microglia_cached.py >> microglia.log ```

Questions

Create an issue in the repository or contact brianhie@mit.edu for any pertinent questions or concerns. We will do our best to answer promptly and feel free to create a pull request and contribute!