peach.pl

peach.pl#

Plotting functions for archetypal analysis.

peach.pl.archetypal_space(adata, *, archetype_coords_key='archetype_coordinates', pca_key='X_pca', color_by=None, use_layer='logcounts', cell_size=2.0, cell_opacity=0.6, archetype_size=8.0, archetype_color='red', show_archetype_labels=True, show_connections=True, color_scale='viridis', categorical_colors=None, title='Archetypal Space Visualization', auto_scale=True, save_path=None, fixed_ranges=None, legend_marker_scale=1.0, legend_font_size=12, show_centroids=False, centroid_condition=None, centroid_order=None, centroid_groupby=None, centroid_size=20.0, centroid_start_symbol='circle', centroid_end_symbol='diamond', centroid_line_width=6.0, centroid_colors=None, **kwargs)[source]#

Visualize cells in 3D archetypal coordinate space.

Creates an interactive 3D scatter plot showing cells positioned in PCA space with archetype positions and optional coloring by gene expression or metadata.

Parameters:

adata (AnnData) – Annotated data object with archetypal coordinates.
archetype_coords_key (str, default: "archetype_coordinates") – Key in adata.uns containing archetype coordinates [n_archetypes, n_pcs].
pca_key (str, default: "X_pca") – Key in adata.obsm containing PCA coordinates [n_cells, n_pcs].
color_by (str | None, default: None) – Column in adata.obs (categorical/continuous) or gene name in adata.var.index for expression coloring.
use_layer (str, default: "logcounts") – Layer for gene expression. Falls back to adata.X if not found.
cell_size (float, default: 2.0) – Size of cell points.
cell_opacity (float, default: 0.6) – Opacity of cell points (0-1).
archetype_size (float, default: 8.0) – Size of archetype diamond markers.
archetype_color (str, default: "red") – Color for archetype markers.
show_archetype_labels (bool, default: True) – Whether to show ‘Arch1’, ‘Arch2’, etc. labels.
show_connections (bool, default: True) – Whether to draw lines connecting all archetype pairs.
color_scale (str, default: "viridis") – Plotly color scale for continuous variables.
categorical_colors (dict | None, default: None) – Custom colors for categorical variables {category: color}.
title (str, default: "Archetypal Space Visualization") – Plot title.
auto_scale (bool, default: True) – Whether to auto-scale axes using 1st-99th percentiles.
save_path (str | None, default: None) – Path to save HTML file.
fixed_ranges (dict | None, default: None) – Fixed axis ranges {‘x’: (min, max), ‘y’: (min, max), ‘z’: (min, max)}.
legend_marker_scale (float, default: 1.0) – Scale factor for legend marker sizes.
legend_font_size (int, default: 12) – Font size for legend text.
show_centroids (bool, default: False) – Whether to display condition centroids on the plot. Requires centroids computed via pc.tl.compute_conditional_centroids().
centroid_condition (str | None, default: None) – Column name in adata.obs for condition centroids. Must have centroids pre-computed via pc.tl.compute_conditional_centroids().
centroid_order (list | None, default: None) – Order of condition levels for trajectory line. If provided, draws a line connecting centroids in this order. Example: [‘chemo-naive’, ‘IDS’] for treatment timeline.
centroid_groupby (str | None, default: None) – Column name for multi-group trajectories. If provided, draws separate trajectory per group with different colors.
centroid_size (float, default: 20.0) – Size of centroid markers.
centroid_start_symbol (str, default: "circle") – Plotly symbol for first centroid in trajectory.
centroid_end_symbol (str, default: "diamond") – Plotly symbol for last centroid in trajectory.
centroid_line_width (float, default: 6.0) – Width of trajectory line connecting centroids.
centroid_colors (dict | None, default: None) – Custom colors for centroid markers/lines. If centroid_groupby used: {group: color} (e.g., {‘long’: ‘magenta’, ‘short’: ‘cyan’}). Otherwise: {‘default’: color}.
**kwargs – Additional arguments passed to underlying visualization.

Returns:

Interactive 3D scatter plot containing: - Cell points colored by color_by (with colorbar if continuous) - Archetype positions as diamond markers - Archetype labels (if show_archetype_labels=True) - Hull edges connecting archetypes (if show_connections=True) - Condition centroids with trajectory lines (if show_centroids=True)

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If adata.obsm[‘archetype_distances’] not found (run pc.tl.archetypal_coordinates() first).

Examples

>>> # Color by cell type metadata
>>> fig = pc.pl.archetypal_space(adata, color_by="cell_type")
>>> fig.show()

>>> # Color by gene expression
>>> fig = pc.pl.archetypal_space(adata, color_by="CD3D")
>>> fig.show()

>>> # Custom styling
>>> fig = pc.pl.archetypal_space(
...     adata, color_by="pseudotime", color_scale="plasma", cell_opacity=0.4, archetype_size=12.0
... )

>>> # With condition trajectory centroids
>>> pc.tl.compute_conditional_centroids(adata, "treatment_phase")
>>> fig = pc.pl.archetypal_space(
...     adata,
...     show_centroids=True,
...     centroid_condition="treatment_phase",
...     centroid_order=["chemo-naive", "IDS"],
...     centroid_colors={"default": "magenta"},
... )

>>> # Multi-group trajectories (treatment × response)
>>> pc.tl.compute_conditional_centroids(adata, "treatment_phase", groupby="response")
>>> fig = pc.pl.archetypal_space(
...     adata,
...     show_centroids=True,
...     centroid_condition="treatment_phase",
...     centroid_groupby="response",
...     centroid_order=["chemo-naive", "IDS"],
...     centroid_colors={"long": "magenta", "short": "cyan"},
... )

peach.pl.archetypal_space_multi(adata_list, *, archetype_coords_key='archetype_coordinates', pca_key='X_pca', labels_list=None, color_by=None, color_values=None, cell_size=2.0, cell_opacity=0.6, archetype_size=8.0, archetype_colors=None, show_labels=True, auto_scale=True, range_reference=None, fixed_ranges=None, color_scale='viridis', categorical_colors=None, title='Multi-Archetypal Space Comparison', save_path=None)[source]#

Compare multiple archetypal analysis fits in 3D PCA space.

Creates an interactive 3D scatter plot comparing multiple archetypal fits, useful for comparing different conditions, treatments, or parameter settings.

Parameters:

adata_list (list of AnnData) – List of AnnData objects with PCA coordinates and archetype results
archetype_coords_key (str, default: "archetype_coordinates") – Key in adata.uns containing archetype coordinates
pca_key (str, default: "X_pca") – Key in adata.obsm containing PCA coordinates
labels_list (list of str | None, default: None) – Labels for each dataset (defaults to ‘Set 1’, ‘Set 2’, etc.)
color_by (str | list of str | None, default: None) – Column(s) to color cells by - single string or list per dataset
color_values (array | list of arrays | None, default: None) – Direct color values - single array or list per dataset
cell_size (float, default: 2.0) – Size of cell points
cell_opacity (float, default: 0.6) – Opacity of cell points (0-1)
archetype_size (float, default: 8.0) – Size of archetype markers
archetype_colors (list of str | None, default: None) – Colors for archetype markers per dataset
show_labels (bool | list of int, default: True) – Which datasets to show archetype labels for (bool, list of indices)
auto_scale (bool, default: True) – Whether to auto-scale axes based on all data
range_reference (int | AnnData | None, default: None) – Reference dataset index or AnnData for axis scaling
fixed_ranges (dict | None, default: None) – Fixed axis ranges {‘x’: (min, max), ‘y’: (min, max), ‘z’: (min, max)}
color_scale (str, default: 'viridis') – Plotly color scale for continuous variables
categorical_colors (dict | None, default: None) – Custom colors for categorical variables
title (str, default: 'Multi-Archetypal Space Comparison') – Plot title
save_path (str | Path | None, default: None) – Optional path to save HTML file

Returns:

Interactive 3D comparison plot

Return type:

plotly.graph_objects.Figure

Examples

>>> # Compare treatment conditions
>>> fig = pc.pl.archetypal_space_multi(
...     adata_list=[adata_control, adata_treated],
...     labels_list=["Control", "Treated"],
...     color_by=["cell_type", "cell_type"],
...     title="Treatment Effect on Archetypal Space",
... )
>>> fig.show()

>>> # Compare different archetype numbers
>>> fig = pc.pl.archetypal_space_multi(
...     adata_list=[adata_k3, adata_k5, adata_k7],
...     labels_list=["K=3", "K=5", "K=7"],
...     show_labels=[2],  # Only show labels for K=7
...     title="Archetype Number Comparison",
... )
>>> fig.show()

peach.pl.training_metrics(history, *, height=400, width=800, display=True, **kwargs)[source]#

Visualize training metrics over epochs.

Creates interactive Plotly visualization with loss components, stability metrics, and convergence analysis.

Parameters:

history (dict) – Training history dictionary from pc.tl.train_archetypal(). Expected keys: ‘loss’, ‘archetypal_loss’, ‘KLD’, ‘rmse’, ‘vertex_stability_latent’, ‘vertex_stability_pca’, ‘loss_delta’.
height (int, default: 400) – Base plot height in pixels (actual height is 2x for 3 rows).
width (int, default: 800) – Plot width in pixels.
display (bool, default: True) – Whether to display the plot immediately via fig.show().
**kwargs – Additional arguments passed to plot_training_metrics.

Returns:

Interactive training metrics plot with 3-row layout: - Row 1 (40%): Loss metrics (loss, archetypal_loss, KLD, rmse) - Row 2 (30%): Stability metrics (vertex_stability_latent/pca) - Row 3 (30%): Convergence (loss_delta with rolling mean)

Returns None only if history is empty.

Return type:

plotly.graph_objects.Figure or None

Examples

>>> results = pc.tl.train_archetypal(adata, n_archetypes=5)
>>> fig = pc.pl.training_metrics(results["history"], display=False)
>>> fig.write_html("training.html")

peach.pl.elbow_curve(cv_summary, *, metrics=['archetype_r2', 'rmse'], **kwargs)[source]#

Plot elbow curves for hyperparameter selection.

Parameters:

cv_summary (CVSummary) – Cross-validation results from pc.tl.hyperparameter_search()
metrics (list[str], default: ["archetype_r2", "rmse"]) – Metrics to plot
**kwargs – Additional arguments passed to plot_elbow_curve

Returns:

Interactive elbow curve plot

Return type:

plotly.graph_objects.Figure

peach.pl.dotplot(results_df, *, x_col='archetype', y_col='gene', size_col='mean_archetype', color_col='pvalue', top_n_per_group=10, filter_zero_p=True, log_transform_p=True, max_log_p=300.0, title='Gene-Archetype Associations', figsize=(12, 8), color_palette='plasma', save_path=None, **kwargs)[source]#

Create dotplot visualization for statistical results.

Creates publication-ready dotplot showing statistical test results with effect sizes encoded as dot size and significance as color.

Parameters:

results_df (pd.DataFrame) – Statistical test results from pc.tl.gene_associations(), pc.tl.pathway_associations(), or pc.tl.pattern_analysis().
x_col (str, default: "archetype") – Column for x-axis (groups).
y_col (str, default: "gene") – Column for y-axis (features).
size_col (str, default: "mean_archetype") – Column for dot size (effect magnitude).
color_col (str, default: "pvalue") – Column for dot color (significance).
top_n_per_group (int, default: 10) – Number of top results per group.
filter_zero_p (bool, default: True) – Whether to filter out p-values of exactly 0.
log_transform_p (bool, default: True) – Whether to apply -log10 transformation to p-values.
max_log_p (float, default: 300.0) – Maximum -log10(p-value) cap.
title (str, default: "Gene-Archetype Associations") – Plot title.
figsize (tuple[float, float], default: (12, 8)) – Figure size as (width, height).
color_palette (str, default: "plasma") – Matplotlib colormap name.
save_path (str | None, default: None) – Path to save the figure.
**kwargs – Additional arguments passed to create_dotplot_visualization.

Returns:

Dotplot figure with: - X-axis: Groups (archetypes/patterns) - Y-axis: Features (genes/pathways), sorted by effect size - Dot size: Effect magnitude (with legend) - Dot color: -log10(p-value) (with colorbar) - Background panels grouping features by archetype

Return type:

matplotlib.figure.Figure

Notes

Auto-detects result type and adjusts columns: - Gene results: Uses defaults - Pathway results: Switches y_col to ‘pathway’ - Pattern results: Uses pattern_name, effect_range - Exclusivity results: Uses tradeoff_score, effect_range

Examples

>>> gene_results = pc.tl.gene_associations(adata)
>>> fig = pc.pl.dotplot(gene_results)
>>> plt.show()

>>> # Pathway results (auto-detected)
>>> pathway_results = pc.tl.pathway_associations(adata)
>>> fig = pc.pl.dotplot(pathway_results, title="Pathway Associations")

peach.pl.archetype_positions(adata, *, coords_key='archetype_coordinates', title='Archetype Positions in PCA Space', figsize=(15, 6), cmap='tab10', show_distances=True, save_path=None, **kwargs)[source]#

Visualize archetype positions in PCA space with distance matrix.

Creates a two-panel visualization showing archetype positions in the first two principal components and a pairwise distance matrix heatmap.

Parameters:

adata (AnnData) – Annotated data object with archetype coordinates
coords_key (str, default: "archetype_coordinates") – Key in adata.uns containing archetype coordinates
title (str, default: "Archetype Positions in PCA Space") – Main figure title
figsize (tuple, default: (15, 6)) – Figure size as (width, height)
cmap (str, default: 'tab10') – Colormap for archetype points
show_distances (bool, default: True) – Whether to show distance matrix panel
save_path (str | None, default: None) – Path to save the figure
**kwargs – Additional arguments passed to plot_archetype_positions

Returns:

Figure with archetype position visualizations

Return type:

matplotlib.figure.Figure

Examples

>>> fig = pc.pl.archetype_positions(adata)
>>> plt.show()

>>> # Save high-resolution figure
>>> fig = pc.pl.archetype_positions(adata, title="Helsinki EOC Archetype Positions", save_path="archetypes.png")

Notes

The visualization includes: - Left panel: Archetype positions in PC1-PC2 space with convex hull - Right panel: Pairwise distance matrix with values

Requires at least 2 dimensions in archetype coordinates. For 3D visualization, use archetype_positions_3d().

peach.pl.archetype_positions_3d(adata, *, coords_key='archetype_coordinates', title='Archetype Positions in 3D PCA Space', figsize=(12, 10), cmap='tab10', save_path=None, **kwargs)[source]#

Visualize archetype positions in 3D PCA space.

Creates an interactive 3D visualization of archetype positions with convex hull edges connecting the archetypes.

Parameters:

adata (AnnData) – Annotated data object with archetype coordinates
coords_key (str, default: "archetype_coordinates") – Key in adata.uns containing archetype coordinates
title (str, default: "Archetype Positions in 3D PCA Space") – Figure title
figsize (tuple, default: (12, 10)) – Figure size as (width, height)
cmap (str, default: 'tab10') – Colormap for archetype points
save_path (str | None, default: None) – Path to save the figure
**kwargs – Additional arguments passed to plot_archetype_distances_3d

Returns:

3D visualization of archetypes

Return type:

matplotlib.figure.Figure

Examples

>>> # Basic 3D visualization
>>> fig = pc.pl.archetype_positions_3d(adata)
>>> plt.show()

>>> # Custom visualization
>>> fig = pc.pl.archetype_positions_3d(adata, cmap="Set1", title="3D Archetype Hull")

Notes

Requires at least 3 dimensions in archetype coordinates. The visualization includes convex hull edges connecting archetypes.

peach.pl.archetype_statistics(adata, *, coords_key='archetype_coordinates', verbose=True)[source]#

Compute and display statistics about archetype positions.

Calculates pairwise distances, identifies nearest/farthest archetype pairs, and computes convex hull metrics when possible.

Parameters:

adata (AnnData) – Annotated data object with archetype coordinates.
coords_key (str, default: "archetype_coordinates") – Key in adata.uns containing archetype coordinates.
verbose (bool, default: True) – Whether to print statistics to console.

Returns:

Statistics dictionary with keys: - n_archetypes : int - Number of archetypes - n_dimensions : int - Embedding dimensions - mean_distance : float - Mean pairwise Euclidean distance - std_distance : float - Std of pairwise distances - min_distance : float - Minimum pairwise distance - max_distance : float - Maximum pairwise distance - distance_range : float - max - min distance - nearest_pair : tuple[int, int] - Indices of nearest pair (0-based) - farthest_pair : tuple[int, int] - Indices of farthest pair (0-based) - distance_matrix : np.ndarray - Full pairwise distance matrix - hull_volume : float | None - Convex hull volume (3D+ only) - hull_area : float | None - Convex hull surface area (3D+ only)

Return type:

dict

Raises:

ValueError – If adata.uns[coords_key] not found.

Examples

>>> stats = pc.pl.archetype_statistics(adata)
[STATS] Archetype Statistics
==================================================
Number of archetypes: 5
...

>>> # Quiet mode
>>> stats = pc.pl.archetype_statistics(adata, verbose=False)
>>> print(f"Nearest pair: A{stats['nearest_pair'][0] + 1}-A{stats['nearest_pair'][1] + 1}")

peach.pl.pattern_dotplot(pattern_df, pattern_type=None, top_n=20, min_effect_size=0.5, max_pvalue=0.05, figsize=(12, 8), title=None, save_path=None, **kwargs)[source]#

Create dotplot for pattern analysis results.

Visualizes the top features (pathways/genes) for each pattern, showing effect sizes and significance levels.

Parameters:

pattern_df (pd.DataFrame) – Results from archetype_exclusive_patterns, specialization_patterns, or tradeoff_patterns functions.
pattern_type (str, optional) – Type of pattern for title generation (“exclusive”, “specialization”, “tradeoff”). If None, inferred from data.
top_n (int, default: 20) – Number of top features to show.
min_effect_size (float, default: 0.5) – Minimum absolute effect size to include.
max_pvalue (float, default: 0.05) – Maximum p-value to include.
figsize (tuple, default: (12, 8)) – Figure size.
title (str, optional) – Custom title. If None, auto-generated based on pattern_type.
save_path (str, optional) – Path to save the figure.
**kwargs – Additional arguments passed to create_dotplot_visualization.

Returns:

Dotplot figure with: - X-axis: Pattern codes or archetype names - Y-axis: Feature names (genes/pathways) - Dot size: Effect size magnitude - Dot color: -log10(p-value) (significance)

Returns placeholder figure with message if input is empty or no features pass filters.

Return type:

matplotlib.figure.Figure

Examples

>>> exclusive = pc.tl.archetype_exclusive_patterns(adata)
>>> fig = pc.pl.pattern_dotplot(exclusive, pattern_type="exclusive")

>>> tradeoffs = pc.tl.tradeoff_patterns(adata, tradeoffs="pairs")
>>> fig = pc.pl.pattern_dotplot(tradeoffs, min_effect_size=1.0, top_n=30, title="Strong Tradeoff Patterns")

peach.pl.pattern_summary_barplot(pattern_results, figsize=(14, 6), save_path=None)[source]#

Create summary barplot showing pattern counts across different analyses.

Parameters:

pattern_results (dict) – Dictionary with pattern DataFrames from different analyses e.g., {‘exclusive’: exclusive_df, ‘specialization’: spec_df, ‘tradeoff’: trade_df}
figsize (tuple, default: (14, 6)) – Figure size
save_path (str, optional) – Path to save the figure

Returns:

The summary barplot figure

Return type:

plt.Figure

Examples

>>> results = {
...     "exclusive": pc.tl.archetype_exclusive_patterns(adata),
...     "specialization": pc.tl.specialization_patterns(adata),
...     "tradeoff_pairs": pc.tl.tradeoff_patterns(adata, tradeoffs="pairs"),
... }
>>> fig = pc.pl.pattern_summary_barplot(results)

peach.pl.pattern_heatmap(pattern_df, adata, top_n=30, cluster_patterns=True, cluster_features=True, figsize=(10, 12), cmap='RdBu_r', save_path=None, **kwargs)[source]#

Create heatmap showing pattern expression across archetypes.

Parameters:

pattern_df (pd.DataFrame) – Pattern analysis results
adata (AnnData) – Annotated data object with archetype assignments and scores
top_n (int, default: 30) – Number of top features to show
cluster_patterns (bool, default: True) – Whether to cluster patterns (rows)
cluster_features (bool, default: True) – Whether to cluster features (columns)
figsize (tuple, default: (10, 12)) – Figure size
cmap (str, default: 'RdBu_r') – Colormap for the heatmap
save_path (str, optional) – Path to save the figure
**kwargs – Additional arguments passed to sns.heatmap

Returns:

The heatmap figure

Return type:

plt.Figure

peach.pl.fate_probabilities(adata, lineages=None, basis='X_umap', same_plot=False, ncols=3, figsize=None, **kwargs)[source]#

Plot fate probabilities on embedding.

Visualizes the probability of cells committing to each lineage/archetype using CellRank’s plotting functionality.

Parameters:

adata (AnnData) – Annotated data matrix with fate probabilities computed.
lineages (list of str, optional) – Specific lineages to plot. If None, plots all lineages.
basis (str, default: 'X_umap') – Embedding to use (‘X_umap’, ‘X_pca’, etc.).
same_plot (bool, default: False) – If True, plots all lineages on same axes (pie chart style). If False, creates separate panel per lineage.
ncols (int, default: 3) – Number of columns for multi-panel plot (if same_plot=False).
figsize (tuple, optional) – Figure size. If None, automatically determined.
**kwargs – Additional arguments passed to CellRank’s plot function.

Returns:

Displays matplotlib figure. CellRank’s plotting functions display directly rather than returning figure objects.

Return type:

None

Raises:

ImportError – If CellRank is not installed.
NotImplementedError – If GPCCA object not stored in adata.uns[‘cellrank_gpcca’].

Examples

>>> pc.pl.fate_probabilities(adata, same_plot=False, ncols=3)

>>> pc.pl.fate_probabilities(adata, lineages=["archetype_3", "archetype_5"], same_plot=True)

peach.pl.lineage_drivers(adata, lineage, n_genes=20, driver_key=None, figsize=(10, 8), **kwargs)[source]#

Plot heatmap of top driver genes for a lineage.

Visualizes expression of genes most correlated with commitment to a specific lineage/archetype.

Parameters:

adata (AnnData) – Annotated data matrix
lineage (str) – Target lineage name (e.g., ‘archetype_5’)
n_genes (int, optional (default: 20)) – Number of top genes to plot
driver_key (str, optional) – Key in adata.varm containing driver gene scores. If None, computes drivers on-the-fly using correlation method
figsize (tuple, optional (default: (10, 8))) – Figure size
**kwargs – Additional arguments passed to seaborn.heatmap

Returns:

fig – Figure object

Return type:

matplotlib.figure.Figure

Examples

Plot top 20 driver genes:

>>> import peach as pc
>>> pc.pl.lineage_drivers(adata, lineage="archetype_5", n_genes=20)

Custom number of genes:

>>> pc.pl.lineage_drivers(adata, lineage="archetype_3", n_genes=30, figsize=(12, 10))

Using pre-computed drivers:

>>> drivers = pc.tl.compute_lineage_drivers(adata, lineage="archetype_5")
>>> adata.var["driver_scores"] = drivers[f"archetype_5_corr"]
>>> pc.pl.lineage_drivers(adata, lineage="archetype_5", driver_key="driver_scores")

Notes

If driver_key is None, uses simple correlation method
Heatmap rows are cells ordered by fate probability
Heatmap columns are top driver genes

See also

gene_trends: Plot expression trends along pseudotime
fate_probabilities: Visualize fate probability distributions

peach.pl.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.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_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.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_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.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

Modules

`peach.pl.archetypal`	Archetypal visualization functions.
`peach.pl.cellrank_viz`	Visualization functions for CellRank archetypal trajectories.
`peach.pl.debug_dotplot`	Debug wrapper for dotplot to diagnose rendering issues
`peach.pl.pattern_visualization`	Visualization functions for pattern analysis results.
`peach.pl.results`	Results visualization functions.
`peach.pl.spatial`	Spatial archetype visualization functions.

peach.pl

Contents

peach.pl#