spac.visualization._prepare_spatial_distance_data(adata, annotation, stratify_by=None, spatial_distance='spatial_distance', distance_from=None, distance_to=None, log=False)[source]

Prepares a tidy DataFrame for nearest-neighbor (spatial distance) plotting.

This function:

  1. Validates required parameters (annotation, distance_from).

  2. Retrieves the spatial distance matrix from adata.obsm[spatial_distance].

  3. Merges annotation (and optional stratify column).

  4. Filters rows to the reference phenotype (distance_from).

  5. Subsets columns if distance_to is given; otherwise keeps all distances.

  6. Reshapes (melts) into long-form data: columns -> [cellid, group, distance].

  7. Applies optional log1p transform.

The resulting DataFrame is suitable for plotting with tool like Seaborn.

Parameters:

  • adata (anndata.AnnData) – Annotated data matrix, containing distances in adata.obsm[spatial_distance].

  • annotation (str) – Column in adata.obs indicating cell phenotype or annotation.

  • stratify_by (str, optional) – Column in adata.obs used to group/stratify data (e.g., image or sample).

  • spatial_distance (str, optional) – Key in adata.obsm storing the distance DataFrame. Default ‘spatial_distance’.

  • distance_from (str) – Reference phenotype from which distances are measured. Required.

  • distance_to (str or list of str, optional) – Target phenotype(s). If None, use all available phenotype distances.

  • log (bool, optional) – If True, applies np.log1p transform to the ‘distance’ column, which is renamed to ‘log_distance’.

Returns:

Tidy DataFrame with columns:

  • ’cellid’: index of the cell from ‘adata.obs’.

  • ’group’: the target phenotype (column names of ‘distance_map’.

  • ’distance’: the numeric distance value.

  • ’phenotype’: the reference phenotype (‘distance_from’).

  • ’stratify_by’: optional grouping column, if provided.

Return type:

pd.DataFrame

Raises:

ValueError – If required parameters are missing, if phenotypes are not found in adata.obs, or if the spatial distance matrix is not available in adata.obsm.

Examples

>>> df_long = _prepare_spatial_distance_data(
...     adata=my_adata,
...     annotation='cell_type',
...     stratify_by='sample_id',
...     spatial_distance='spatial_distance',
...     distance_from='Tumor',
...     distance_to=['Stroma', 'Immune'],
...     log=True
... )
>>> df_long.head()