PHD-MS: Persistent Homology for Domains at Multiple Scales

Multiscale domain identification for spatial transcriptomic data.

PHD-MS clusters a tissue at several resolutions, links overlapping clusters across resolutions into a cluster graph, and uses 0-dimensional persistent homology on that graph to find multiscale domains: groups of clusters that stay together over a wide range of overlap thresholds. Each domain comes with a persistence (how robust it is) and a per-spot coreness score.

Installation

pip install phd_ms

Or from source, in this directory:

pip install .

Quick start

We assume a spatially aware embedding (e.g. from GraphST) is stored in adata.obsm.

import numpy as np
import scanpy as sc
import phd_ms

adata = sc.read_h5ad('adata_151673.h5ad')

# 1. Leiden clusterings at several resolutions (returns keys, coarse to fine)
keys = phd_ms.pp.leiden(adata, resolutions=np.linspace(0.15, 0.95, 8), use_rep='X_gst')

# 2. Multiscale domains -> adata.obsm['multiscale'], adata.uns['multiscale']
domains = phd_ms.tl.multiscale(adata, keys, index='containment')

# 3. Plots
phd_ms.pl.persistence_diagram(domains)
phd_ms.pl.domains(adata, indices=range(10))   # the 10 most persistent domains
phd_ms.pl.heterogeneity(adata)

Other useful entry points:

Or run point_and_click.py (set DATA to your file first) for the clickable interface.

Notebook tutorials are in the examples folder: mouse_brain_v2.ipynb (finding multiscale domains) and visium_benchmark_v2.ipynb (benchmarking against annotated DLPFC layers). The 1.x notebooks, with their original outputs, are in examples/v1.

How coreness is defined

Every cluster r founds a domain that lives from its birth until it merges into an older domain (its death). A spot enters the domain at the first overlap threshold at which one of its clusters has joined r's component. Its coreness is the fraction of the domain's lifetime during which it belongs:

coreness = (death - entry) / (death - birth),   and 0 if the spot never enters.

Upgrading from 1.x

The 1.x functions (phd_ms.tl.preprocess_leiden, cluster_filtration, map_multiscale, ...) still work but emit a DeprecationWarning; see CHANGELOG.md for the new equivalents. Coreness values differ from 1.x (see the changelog).