Introduction
RNA velocity (La Manno et al, 2018) scRNA-seq analysis method is used to infer cell state by measuring the ratio of unspliced to spliced messenger RNA (mRNA) transcripts. This ratio provides information about the transcriptional activity of a gene and its direction. By comparing the ratio of unspliced to spliced transcripts between two time points or two developmental stages, RNA velocity can predict the direction and speed of cell fate decisions, such as cell differentiation and proliferation.
Since its inception, there have been a number of models developed toward optimizing the accuracy of RNA velocity. In this tutorial, we'll go over the basic steps of one such model, scVelo (Bergen et al, 2020) on an example data set generated with a Parse Evercode WT kit (v4 chemistry) on PBMCs taken from two human donors. Please see the Scvelo user guide for a full list of plots and functions
Install Python modules
We recommend running this tutorial in a new conda environment, separate from your current split-pipe installation. You can start a fresh environment by running conda create -n scvelo python=3.12 and run the following pip commands to install the necessary Python modules.
# standard installation
# pin pandas <3: scvelo (0.3.4, the latest release) has open compatibility issues with pandas 3, see https://github.com/theislab/scvelo/issues/1344
pip install "pandas<3"
pip install dask pyarrow
pip install scvelo
pip install scanpy
pip install python-igraph
pip install seaborn
pip install leidenalg
pip install "pynndescent<0.7"The Parse Biosciences pipeline (run in Trailmaker or via local installation) generates a table containing every unique transcript identified for a given sublibrary. This table, also called the "transcript assignment file" (tscp_assignment.csv.gz), is located in the "process" directory within each sublibrary output directory and contains the splicing information for each transcript identified in a Parse assay. This splicing information can be used to generate the splice matrices required to run scVelo.
Build the combined AnnData object
Importing modules, generating splice matrices for each sublibrary, concatenating them, and joining in the sample metadata have all been consolidated into a single script, generate_scvelo_adata.py (attached at the bottom of this article). The script doesn't assume any particular sublibrary folder naming convention (e.g. S1-out). Instead, for each sublibrary listed in the combine-mode output's process/run_proc_def.json, it:
- Unzips that sublibrary's transcript assignment file if that hasn't already been done;
- Looks up that sublibrary's transcript count cutoff from the cell_tscp_cutoff column of the all-sample row in its agg_sample_summary.csv;
- Determines the sublibrary's __sN identifier from its position in the all-sample entry's sublib_list in run_proc_def.json;
- Builds an AnnData object with spliced and unspliced layers from the transcript assignment file, filtered down to barcodes meeting the cutoff.
It then concatenates all of the sublibraries and joins in the combined cell metadata (sample ids and other per-cell info) from the DGE_filtered folder in the all-sample sample folder of your split-pipe --mode comb output.
Below, we'll show two examples for running the generate_scvelo_adata.py script. The first example pertains to split-pipe runs executed locally, and the second example is for split-pipe runs executed on Trailmaker.
If you ran split-pipe locally
Run the script from the command line, pointing it at the working directory that contains your sublibrary output folders. --comb-dir is the name of your split-pipe combine-mode output folder (comb-out by default), and --out is where the final combined Anndata object gets written. This can point anywhere, including outside working_dir.
python /gnrl/scripts/python/generate_scvelo_adata.py \
/gnrl/analysis/test-sets/pbmc-v4/ \
--comb-dir combined \
--out /gnrl/analysis/tutorial-data/scvelo/scvelo_adata_raw.h5ad
If you ran split-pipe on Trailmaker
In Trailmaker's pipeline module, start by downloading the combined and sublibrary output directories by navigating to the "Download Output" option in your pipeline results page (pictured below). Next, select "All files" and click on "Copy resumable download command(s)". Then paste and run the download commands in a Linux or Mac terminal (Windows is not supported). Please note, the "All files" download option will only be available on Trailmaker for 30 days after the pipeline has run to completion.
Once the directories are downloaded, they'll need to be unzipped. You can unzip all the files in a given directory using the shell command below.
for file in *.zip; do
[ -f "$file" ] || continue
unzip "$file"
done
After unzipping the files, you should see a directory structure that looks like following:
├── output_combined ├── output_S10 ├── output_S11 ├── output_S12 ├── output_S13 ├── output_S14 ├── output_S15 ├── output_S16 └── output_S9
Next, we'll need to use the "gunzip" command to extract the cell metadata file from the "all-sample" sample in the "output_combined" directory.
gunzip output_combined/all-sample/DGE_filtered/cell_metadata.csv.gz
And lastly, we'll run the generate_scvelo_adata.py script on the "output_combined" directory.
python /gnrl/scripts/python/generate_scvelo_adata.py \
/gnrl/analysis/ \
--comb-dir output_combined \
--out /gnrl/analysis/scvelo_adata_raw.h5ad
This saves each sublibrary's raw AnnData object (sub_adata.h5ad) along with the final combined object (scvelo_adata_raw.h5ad).
Run through cell preprocessing and clustering.
Now we're ready to load our combined AnnData object (scvelo_adata_raw.h5ad ) into Scanpy. For brevity, the following steps are run through a minimal Scanpy preprocessing and clustering workflow, except for the Scvelo functions scv.pp.moments, scv.tl.velocity, and scv.tl.velocity_graph. The specific details of these functions are explained on the scvelo documentation page. Please see the Scanpy documentation page for a full list of preprocessing functions.
import scanpy as sc
import anndata as ad
import scvelo as scv
working_dir = "/gnrl/analysis/tutorial-data/scvelo/"
ad_splice = ad.read_h5ad(f"{working_dir}scvelo_adata_raw.h5ad")
scv.settings.verbosity = 3 # show errors(0), warnings(1), info(2), hints(3)
scv.pp.filter_genes(ad_splice, min_shared_counts=10)
scv.pp.normalize_per_cell(ad_splice)
sc.pp.log1p(ad_splice)
sc.pp.highly_variable_genes(ad_splice, n_top_genes=3000, subset=True)
scv.pp.remove_duplicate_cells(ad_splice)
sc.pp.neighbors(ad_splice, n_pcs=50, n_neighbors=30)
scv.pp.moments(ad_splice)
sc.tl.umap(ad_splice)
sc.tl.leiden(ad_splice, resolution=1.0)
scv.tl.velocity(ad_splice, mode="deterministic")
scv.tl.velocity_graph(ad_splice)Then, save the finalized anndata object so that you can revisit the results later without having to re-run the previous steps.
# Save anndata object to h5ad file
ad_splice.write(f"{working_dir}scvelo_adata.h5ad")
# Read object in
ad_splice = ad.read_h5ad(f"{working_dir}scvelo_adata.h5ad")Plot the results
import seaborn as sns
# Set figure parameters
scv.settings.presenter_view = True # set max width size for presenter view
scv.set_figure_params("scvelo") # for beautified visualization
scv.set_figure_params(
figsize=(6,6),
dpi=150,
format="png",
dpi_save=300,
transparent=False,
facecolor="white",
fontsize=8)
cluster_colors=sns.color_palette("hls", ad_splice.obs["leiden"].nunique())
scv.pl.velocity_embedding_stream(
ad_splice,
basis="umap",
color="leiden",
palette=cluster_colors,
size=5,
alpha=0.4,
fontsize=10,
title="Leiden clusters",
arrow_size=0.5,
save=f"{working_dir}stream_embedding")For details on all of the available plots and functions please see the scvelo documentation page.