peach.pl.archetypal_space_multi

peach.pl.archetypal_space_multi#

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()