Note: As of v.0.2.0, computation of persistent homology has switched to using to gudhi package from dionysus. There may thus be small numerical differences between results obtained using versions 0.1.0 and 0.2.0. If you wish to re-create the exact results from [1] please use version 0.1.0.

PersiST

PersiST is an exploratory method for analysing spatial transcriptomics (and other spatial 'omics) datsets. Given a spatial transcriptomics data set containing expression data on multiple genes, resolved to a shared set of co-ordinates (for example, Visium type spatial transcriptomics data), PersiST computes a single score for each gene that measures the amount of spatial structure that gene shows in its expression pattern, called the Coefficient of Spatial Structure (CoSS). This score can be used for multiple analytical tasks, as we show below.

Installation

PersiST can be installed using pip:

python3 -m pip install persist_spatial

Documentation

PersiST's documentation can be found here. The methodology is given in more detail in [1].

Tutorial

Spatially Variable Gene Identification

For this tutorial, we shall be looking at a Visium type spatial transcriptomics data on a sample from the Kidney Precision Medicine Project[2].

import pandas as pd
df = pd.read_csv('data/kpmp_30-10125_spatial_expression.csv')
df.head()

This is a pandas DataFrame where the first two columns correspond to the well co-ordinates, and the remaining columns contain the expression of each gene in each well (in this case measured in counts per million). This is the format PersiST expects spatial transcriptomics data to come in.

We can compute CoSS values for all the genes in this sample using the function run_persistence(), which takes as input a data frame like the above. This should take about 10 - 20 minutes, depending on the system you are running this on.

import persist_spatial
metrics = persist_spatial.run_persistence(df)

The CoSS is a measure of the amount of spatial structure in a gene's expression pattern. Let's take a look at those genes with the highest CoSS scores:

metrics = metrics.sort_values('CoSS', ascending=False)
metrics.iloc[:10,:]

PersiST outputs a number of quantities for each gene:

• CoSS: The Coefficient of Spatial Structure, a continuous quantity that can serve as a proxy for the amount of spatial structure in a gene's expression.
• Ratio: Roughly, this measures how much of a gene's CoSS is down to a single spatial features. Genes with a high ratio may be techinical artefacts.
• gene_rank: The rank of each gene, where gene's are ranked from highest to lowest CoSS (so a rank of 1 is give to the gene with the highest CoSS).
• possible_artefact: Based on the ratio, PersiST automatically flags genes as possible artefacts. We emphasise that this is only a suggestion, manual inspection should be performed before dismissing any genes.
• svg: Based on the CoSS scores, PersiST automatically calls genes as spatially variable or not.

We can plot the expression of those genes for which the CoSS is highest using the function plot_many_genes(), to which we need to provide a dataframe containing spatial expression data, and a list of genes to plot.

persist_spatial.plot_many_genes(df, list(metrics.gene)[:20])

We can see that PersiST effectively surfaces those genes with notable spatial structure.

From the CoSS scores PersiST automatically calles genes as spatially variable or not (this is the 'svg' column in the results). This provides a triaged list of genes that can be selected for further analysis.

For example, one can search for genes with spatially similar expression patterns. Reduction to the comparatively small number of genes PersiST typically calls as SV makes this task much easier; in our experience simple clustering methods, such as hierarchical clustering, were effective to pick out groups of SVGs with co-localised expression.

For example, we plot group of genes all expressed in the glomeruli of this particular sample. This group was obtained by running simple hierarchichal clustering on the list of SVGs identified by PersiST and manually inspecting the results.

persist_spatial.plot_many_genes(df, ['PODXL', 'PTGDS', 'IGFBP5', 'TGFBR2', 'IFI27', 'HTRA1'], numcols=3)

Differential Spatial Expression Testing

If you are working with multiple spatial transcriptomics samples, and there are defined subgroups present within these samples, the CoSS scores can be used to look for genes that display difference in their spatial pattern of expression between the subgroups.

In the KPMP dataset, there are Acute Kidney Infection (AKI) and Chronic Kidney Disease (CKD) samples. For each gene, we computed the average CoSS score within the AKI and CKD samples. The gene with the highest different between the two was UMOD. Below we plot the expression of UMOD in all the kpmp samples.

In the AKI samples, UMOD displays well-defined regions of higher expression, whereas in the CKD samples the expression of UMOD is much more diffuse.

UMOD is a marker gene for tubles, a key structural component of the kidney. It is plausible that this difference in expression between the AKI and CKD samples reflects the structural breakdown that is chracteristic of progressed kidney disease. Using PersiST, we are able to automatically detect and quantify this structural breakdown.

References

[1] Boyle J et al, "Topological Data Analysis for Unsupervised Feature Selection in Large Scale Spatial Omics Data Sets", Bulletin of Mathematical Biology (2026).

[2] Blue B Lake et al, “An atlas of healthy and injured cell states and niches in the human kidney”, Nature (2023).