peach.pl.archetypal_space

peach.pl.archetypal_space#

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"},
... )