Spatial niche detection

easydecon includes simple spatial niche utilities that cluster local composition profiles derived from posterior-like matrices.

Public functions:

detect_spatial_niches_from_posteriors
detect_niches_from_easydecon_result
summarize_niche_compositions
plot_niche_compositions

Inputs

detect_spatial_niches_from_posteriors accepts either a pandas DataFrame or an EasyDeconResult-like object. If a result object has posterior_df=None, pass use_assignment_if_no_posterior=True to use assignment_df instead.

Rows are aligned to table.obs.index. Spatial coordinates are read from table.obsm["spatial"], with a fallback to table.obs[["x", "y"]] when those columns exist.

Smoothing and clustering

n_neighbors: Number of spatial nearest neighbors for optional local averaging.
smooth: If True, cluster neighborhood-smoothed profiles.
n_niches: Fixed number of niche clusters when auto_n_niches=False.
auto_n_niches, n_niches_min, n_niches_max, selection_metric: Optional k selection using silhouette or inertia.
random_state: Seed passed to k-means.
add_to_obs: If True, writes labels to table.obs[niches_column].

Example

niches, smoothed, diagnostics = ed.detect_niches_from_easydecon_result(
    sdata,
    result,
    n_neighbors=6,
    auto_n_niches=True,
    n_niches_min=2,
    n_niches_max=8,
    return_diagnostics=True,
)

composition = ed.summarize_niche_compositions(smoothed, niches)
fig, ax = ed.plot_niche_compositions(smoothed, niches)

niches is a DataFrame with one categorical label column. smoothed is the matrix used for clustering. Niche IDs are categorical labels and do not imply an ordering.

Spatial niche clustering is exploratory. It depends on posterior quality, coordinate quality, neighborhood size, and the chosen number of clusters.