Mievformer - Microenvironment Inference via Transformer
Mievformer defines tissue microenvironments through their probabilistic relationships with continuous cell states. It learns which molecular states are enriched in a local tissue context relative to their frequency across the tissue, using neighboring cells’ molecular states and relative spatial positions.
This probabilistic coupling provides a common basis for identifying niches, characterizing cell-state-dependent niche preferences, and estimating the probability of a target population in each local context. These quantities link molecular variation within cell populations to tissue organization.
Key Features
Continuous cell states: Learn from molecular representations without requiring discrete cell-type labels for training or niche identification.
Probabilistic microenvironments: A masked self-supervised Transformer estimates cell-state enrichment from the surrounding tissue context.
Niche preferences: Compare soft niche membership profiles to identify cellular subpopulations with distinct relationships to their microenvironments.
Population probabilities and colocalization: Map contexts enriched for a target population and identify associated gene-expression signatures.
Multiple spatial slices: Jointly analyze samples with sample-conditioned modeling and spatial neighborhoods constructed within each slice.
AnnData integration: Store results alongside expression and spatial data for analysis with the Scanpy ecosystem.
Getting Started
Install Mievformer via pip:
pip install mievformer
Basic usage example:
import mievformer as mf
import scanpy as sc
# Load your spatial transcriptomics data
adata = sc.read_h5ad("your_data.h5ad")
# Learn the context-state relationship and identify tissue niches
adata = mf.optimize_nicheformer(adata, model_path="model.pth")
# Describe cell-state-dependent niche preferences
adata = mf.calculate_niche_density_ratio(adata)
adata = mf.calculate_niche_cluster_membership(adata)
# Group cells by their niche membership profiles and visualize
adata = mf.analyze_niche_membership(adata, file_path="niche_composition.png")
The input AnnData object should contain cell-state representations in
obsm['X_pca'] and coordinates in obsm['spatial']. Cell-type labels are
needed only when selecting populations for downstream analysis. For example,
given a population labeled TypeA in obs['cell_type']:
# Estimate the probability of TypeA in each local tissue context
adata = mf.estimate_population_density(
adata,
group="TypeA",
cluster_key="cell_type",
max_cell_num=min(1000, adata.n_obs),
)
# Find expression signatures of TypeA-enriched contexts within TypeB cells
query = adata[adata.obs["cell_type"] == "TypeB"].copy()
corrs = mf.analyze_density_correlation(query, density_col="TypeA_density")
Read the Probabilistic Coupling of Cell States and Microenvironments for the probabilistic definition and the single-slice tutorial for a complete example.
Contents
Getting Started
About