Probabilistic Coupling of Cell States and Microenvironments

Defining a microenvironment through continuous cell states

A cell has a molecular profile and a physical boundary. A microenvironment is observed through the cells that occur together and their spatial arrangement. Mievformer therefore defines a microenvironment through its probabilistic relationship with continuous cell states: which molecular states are enriched in a particular local tissue context, relative to their frequency across the tissue?

Let \(z\) denote a continuous molecular-state representation and \(e\) an embedding of the surrounding local tissue context. Mievformer learns an approximate conditional density ratio:

\[ g_\theta(e, z) \approx \frac{p(z \mid e)}{p(z)}. \]

This ratio describes how strongly state \(z\) is enriched in context \(e\) compared with the tissue-wide cell-state distribution. It retains molecular variation within cell types, so discrete cell-type annotations are not required for learning the relationship or identifying niches.

The same relationship supports analysis in both directions: from a tissue context to the populations expected there, and from a cell state to its niche preferences.

Learning the context-state relationship

Mievformer takes gene-expression-derived cell-state representations, typically PCA coordinates in adata.obsm['X_pca'], and spatial coordinates in adata.obsm['spatial']. For each central cell, it constructs a spatial neighborhood and masks the central cell’s molecular state. A Transformer encodes the neighboring molecular states and their positions relative to the center, producing the context embedding \(e\).

A learned score function evaluates the compatibility of this context with candidate central-cell states. An InfoNCE objective favors the observed context-state pair over other candidate states in the mini-batch. With candidates sampled from the marginal cell-state distribution, exponentiating and normalizing the scores with respect to that distribution yields the density-ratio estimate \(g_\theta(e, z)\).

mievformer.optimize_nicheformer() performs training and computes the score-function weights, a niche representation, a neighbor graph, UMAP, and Leiden niche labels in one call. Evaluating the learned relationship on a shared reference set of continuous cell states produces a frequency profile for each context. These profiles provide the basis for comparing contexts and identifying niches.

Biological analyses from the same probabilistic coupling

Cell state to niche: preferences within a cell population

Bayesian inversion relates a cell’s molecular state to the microenvironments in which that state is expected:

\[ p_\theta(e \mid z) = \frac{g_\theta(e, z)\,p(e)} {\int g_\theta(e', z)\,p(e')\,de'}. \]

Integrating this conditional distribution over niche cluster \(c\) gives its cell-state-conditioned membership probability:

\[ q_c(z) = \int_{e \in c} p_\theta(e \mid z)\,de. \]

This describes a cell state’s preference across niches, including whether that preference is concentrated in one niche or spread across several. It complements the discrete niche label assigned from the cell’s observed neighborhood. Within one cell population, membership profiles can reveal heterogeneity associated with different local contexts.

The package exposes this direction through mievformer.calculate_niche_density_ratio() and mievformer.calculate_niche_cluster_membership(). mievformer.analyze_niche_membership() groups cells by those profiles and visualizes the result. The current membership API returns relative soft membership profiles; see the API reference for how its reference sampling and aggregation relate to the probability above.

Tissue context to population: conditional population probabilities

The density ratio defines a conditional cell-state distribution, \(p_\theta(z \mid e) = p(z)g_\theta(e, z)\). Integrating over the molecular states belonging to a target population \(C\) gives:

\[ \rho_C(e) = \int_{z \in C} p_\theta(z \mid e)\,dz. \]

This is the probability that a central cell belongs to population \(C\), given its surrounding tissue context. Evaluating it at each cell location creates a continuous map of contexts enriched for that population. mievformer.estimate_population_density() estimates this quantity from sampled cell states and stores it in adata.obs['<group>_density']. Despite the historical API name, the quantity is a conditional population probability, not a count per unit area.

Linking molecular variation to local tissue organization

The two directions address complementary biological questions:

Niche-associated cell states: Which cells within a population prefer a given niche, and which expression programs vary with that preference?
Colocalization-associated expression: Which genes vary within a cell population as its local contexts become more enriched for another population?

For the second question, first estimate the target population probability across the full tissue, then use mievformer.analyze_density_correlation() on the cell population whose expression you want to study. This connects expression variation to the learned context-state relationship. These associations describe colocalization; they do not by themselves establish a causal interaction.

Multiple spatial slices

When batch_key identifies multiple samples, Mievformer constructs spatial neighborhoods independently within each slice and conditions the cell-state model on sample identity. The learned relationship measures enrichment relative to each sample’s own cell-state distribution. Balanced reference profiles then provide a shared representation for comparing niches across slices.

The multi-batch tutorial demonstrates the workflow. Sample conditioning and reference metadata are retained in the result to make the analysis reproducible.