Ouroboros

Ouroboros is a variational autoencoder that infers cell cycle phase, cell cycle pseudotime and dormancy pseudotime from scRNA-seq datasets. New cells are mapped onto a common pre-trained embedding, enabling comparative quantitative analyses along dormancy pseudotime between samples and experimental conditions.

For more information see the Wiki: wiki

Installation

Ouroboros supports Python 3.9–3.10. Cartopy is an optional dependency required for some plotting functions. It is recommended to install via conda before installing Ouroboros.

Installation:

conda create -n ouroboros_env -c conda-forge python=3.9 pip=24.3.1
conda activate ouroboros_env 
conda install -c conda-forge cartopy -y
pip install ouroboros

Alternatively, you can install directly from conda:

conda install steiflab::ouroboros

Install directly from GitHub (not recommended):

pip install git+https://github.com/steiflab/Ouroboros.git

ScPhere is included as part of Ouroboros and has been updated for compatibility with TensorFlow 2. ScPhere was originally developed by Jiarui Ding and colleagues at the Klarman Cell Observatory.

Running Ouroboros within a scanpy workflow isn't strictly necessary, but if you want to work within a scanpy workflow as outlined in the tutorial, install scanpy into the environment like so:

conda activate ouroboros_env
mamba install -c conda-forge "scanpy>=1.9.3,<1.11"

Running Ouroboros

For a full tutorial see the Wiki: wiki

There are seperate tutorials for python (scanpy) and R (seurat) users, and an additonal tutorial to embed RNA velocity vectors into the sphere.

To run Ouroboros on an h5ad/ Scanpy object

Ouroboros requires raw count data. Before running Ouroboros, make sure your raw counts are stored in adata.layers["raw_counts"], and save your Scanpy object as an .h5ad file.

Gene names must be in HUGO gene symbol format rather than Ensembl IDs.

anndata.write_h5ad('adata.h5ad')

For .csv input, gene names should be provided as column names (in HUGO gene symbol format), and cell IDs should be provided as row names.

Then you can run Ouroboros on the command line like so:

ouroboros \
    --data /path/to/h5ad  \
    --data_type h5ad \
    --species human \
    --outdir /path/to/output/directory \
    --seed 0 \
    --repeat 5 

Arguments:

* If any gene is missing from training feature set from the input data, the model must be retrained. To ensure robust performance, Ouroboros will retrain the VAE {repeat} times and select the model that correlates with the consensus. However, increasing the repeat parameter will significantly extend runtime.

Ouroboros Output

The main output from Ouroboros is ouroboros_embedding_pseudotime.csv, where each row represents a cell embedded in the spherical latent space. The columns are described below:

If the input matrix is missing one or more genes required by the training dataset, Ouroboros will retrain the model using the available training genes. Retraining may reduce model accuracy. When retraining occurs, retrained_reference_embedding.csv is generated, containing the three-dimensional latent-space coordinates of the retrained reference cells and their ground-truth phase labels. A qc.csv file is also generated containing quality-control metrics for the retrained model, including the number of missing training genes, KL divergence, log-likelihood, and SHAP score loss attributable to missing genes.

Ouroboros also generates three interactive spherical plots: ouroboros_cell_cycle_pseudotime.html, which displays cells coloured by cell-cycle pseudotime, ouroboros_dormancy_pseudotime.html, which displays cells coloured by dormancy pseudotime and ouroboros_KNN_phase.html, which displays cells coloured by discrete KNN_phase. The distribution of pseudotime values is additionally provided as pseudotime_histogram.png.

Plotting Ouroboros output

We have included several python functions to help you explore the Ouroboros output sphere.

See Wiki tutorials for more information

Acknowledgements

This project makes use of scPhere, developed by the Broad Institute and distributed under the BSD 3-Clause License.

We have included a lightly modified version of scPhere (updated for TensorFlow 2.x support) within this repository.

If you use functionality derived from scPhere, please also cite: Ding, J., Regev, A. Deep generative model embedding of single-cell RNA-Seq profiles on hyperspheres and hyperbolic spaces. Nat Commun 12, 2554 (2021). https://doi.org/10.1038/s41467-021-22851-4

License

Ouroboros is distributed under the MIT License (see LICENSE). scPhere is distributed under the BSD 3-Clause License (see scphere/LICENSE).