peach.pl.spatial

peach.pl.spatial#

Spatial archetype visualization functions.

Interactive plotly visualizations for spatial archetype analysis results. Requires spatial analysis to have been run via pc.tl.spatial_neighbors().

Main Functions: - nhood_enrichment(): Heatmap of neighborhood enrichment z-scores - co_occurrence(): Line plot of distance-dependent co-occurrence ratios - spatial_archetypes(): Spatial scatter plot of cells colored by archetype - interaction_boundaries(): Spatial map of boundary scores between cell types - spatial_autocorr(): Dot plot of Moran’s I / Geary’s C per archetype - cross_correlations(): Diverging dot plot of per-archetype correlation between cell types

Functions

co_occurrence(adata, *[, uns_key, ...])

Line plot of distance-dependent archetype co-occurrence ratios.

cross_correlations(adata, *[, uns_key, ...])

Diverging dot plot of per-archetype cross-correlations between cell types.

interaction_boundaries(adata, *[, ...])

Spatial map of interaction boundary scores between cell types.

nhood_enrichment(adata, *[, uns_key, ...])

Heatmap of archetype neighborhood enrichment z-scores.

spatial_archetypes(adata, *[, spatial_key, ...])

Scatter plot of cells on spatial coordinates, colored by archetype.

spatial_autocorr(adata, *[, uns_key, title, ...])

Dot plot of spatial autocorrelation per archetype weight.
peach.pl.spatial.nhood_enrichment(adata, *, uns_key='archetype_nhood_enrichment', cluster_key='archetypes', title='Archetype Neighborhood Enrichment', colorscale='RdBu_r', save_path=None, **kwargs)[source]#

Heatmap of archetype neighborhood enrichment z-scores.

Positive values indicate spatial co-localization; negative values indicate spatial separation.

Parameters:

  • adata (AnnData) – Annotated data with neighborhood enrichment results.

  • uns_key (str, default: "archetype_nhood_enrichment") – Key in adata.uns containing enrichment results.

  • cluster_key (str, default: "archetypes") – Column in adata.obs with archetype labels (used for axis labels).

  • title (str, default: "Archetype Neighborhood Enrichment") – Plot title.

  • colorscale (str, default: "RdBu_r") – Plotly colorscale. RdBu_r: red=enriched, blue=depleted.

  • save_path (str | None, default: None) – Path to save the figure as HTML.

Return type:

plotly.graph_objects.Figure

peach.pl.spatial.co_occurrence(adata, *, uns_key='archetype_co_occurrence', cluster_key='archetypes', title='Archetype Spatial Co-occurrence', save_path=None, **kwargs)[source]#

Line plot of distance-dependent archetype co-occurrence ratios.

Shows how the co-occurrence ratio between archetype pairs changes with spatial distance. Values > 1 indicate co-occurrence above chance; values < 1 indicate avoidance.

Parameters:

  • adata (AnnData) – Annotated data with co-occurrence results.

  • uns_key (str, default: "archetype_co_occurrence") – Key in adata.uns containing co-occurrence results.

  • cluster_key (str, default: "archetypes") – Column in adata.obs with archetype labels.

  • title (str, default: "Archetype Spatial Co-occurrence") – Plot title.

  • save_path (str | None, default: None) – Path to save the figure as HTML.

Return type:

plotly.graph_objects.Figure

peach.pl.spatial.spatial_archetypes(adata, *, spatial_key='spatial', color_key='archetypes', point_size=2.0, opacity=0.7, title='Spatial Archetype Map', save_path=None, colors=None, legend_marker_size=12.0, **kwargs)[source]#

Scatter plot of cells on spatial coordinates, colored by archetype.

Parameters:

  • adata (AnnData) – Annotated data with spatial coordinates and archetype assignments.

  • spatial_key (str, default: "spatial") – Key in adata.obsm with 2D spatial coordinates.

  • color_key (str, default: "archetypes") – Column in adata.obs to color cells by.

  • point_size (float, default: 2.0) – Size of scatter points.

  • opacity (float, default: 0.7) – Point opacity.

  • title (str, default: "Spatial Archetype Map") – Plot title.

  • save_path (str | None, default: None) – Path to save the figure as HTML.

  • colors (list[str] | None, default: None) – Custom color list. If None, uses a perceptually distinct palette designed for archetype visualization.

  • legend_marker_size (float, default: 12.0) – Size of legend marker dots for readability.

Return type:

plotly.graph_objects.Figure

peach.pl.spatial.interaction_boundaries(adata, *, spatial_key='spatial', score_key='boundary_score', point_size=2.0, colorscale='Inferno', title=None, save_path=None, **kwargs)[source]#

Spatial map of interaction boundary scores between cell types.

Colors cells by their boundary score from pc.tl.archetype_interaction_boundaries(). High scores indicate cells at spatial fronts where archetype composition diverges between cell types.

Parameters:

  • adata (AnnData) – Annotated data with spatial coordinates and boundary scores.

  • spatial_key (str, default: "spatial") – Key in adata.obsm with 2D spatial coordinates.

  • score_key (str, default: "boundary_score") – Column in adata.obs with boundary scores.

  • point_size (float, default: 2.0) – Size of scatter points.

  • colorscale (str, default: "Inferno") – Plotly colorscale. Inferno: dark=low, bright=high boundaries.

  • title (str | None, default: None) – Plot title. Auto-generated from boundary result if None.

  • save_path (str | None, default: None) – Path to save the figure as HTML.

Return type:

plotly.graph_objects.Figure

peach.pl.spatial.spatial_autocorr(adata, *, uns_key='archetype_spatial_autocorr', title=None, save_path=None, **kwargs)[source]#

Dot plot of spatial autocorrelation per archetype weight.

Horizontal lollipop chart showing Moran’s I (or Geary’s C) for each archetype, ordered by value. Filled markers indicate significance (p < 0.05); open markers indicate non-significant.

Parameters:

  • adata (AnnData) – Annotated data with spatial autocorrelation results in adata.uns[uns_key].

  • uns_key (str, default: "archetype_spatial_autocorr") – Key in adata.uns with autocorrelation DataFrame.

  • title (str | None, default: None) – Plot title. Auto-detected from data if None.

  • save_path (str | None, default: None) – Path to save the figure as HTML.

Return type:

plotly.graph_objects.Figure

peach.pl.spatial.cross_correlations(adata, *, uns_key='archetype_interaction_boundaries', title=None, save_path=None, **kwargs)[source]#

Diverging dot plot of per-archetype cross-correlations between cell types.

Shows Spearman r for each archetype dimension: how the local weight of that archetype in cell type A’s neighbors correlates with its weight in cell type B’s neighbors across space.

Positive r (right): archetype co-localizes across cell types. Negative r (left): archetype anti-correlates — one type goes up while the other goes down in the same neighborhood.

Parameters:

  • adata (AnnData) – Annotated data with interaction boundary results in adata.uns[uns_key].

  • uns_key (str, default: "archetype_interaction_boundaries") – Key in adata.uns with boundary results dict.

  • title (str | None, default: None) – Plot title. Auto-generated from cell type names if None.

  • save_path (str | None, default: None) – Path to save the figure as HTML.

Return type:

plotly.graph_objects.Figure