peach.pl.archetype_statistics

peach.pl.archetype_statistics(adata, *, coords_key='archetype_coordinates', verbose=True)

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