spac.visualization module

spac.visualization.boxplot(adata, annotation=None, second_annotation=None, layer=None, ax=None, features=None, log_scale=False, **kwargs)[source]

Create a boxplot visualization of the features in the passed adata object. This function offers flexibility in how the boxplots are displayed, based on the arguments provided.

Parameters:

  • adata (anndata.AnnData) – The AnnData object.

  • annotation (str, optional) – Annotation to determine if separate plots are needed for every label.

  • second_annotation (str, optional) – Second annotation to further divide the data.

  • layer (str, optional) – The name of the matrix layer to use. If not provided, uses the main data matrix adata.X.

  • ax (matplotlib.axes.Axes, optional) – An existing Axes object to draw the plot onto, optional.

  • features (list, optional) – List of feature names to be plotted. If not provided, all features will be plotted.

  • log_scale (bool, optional) – If True, the Y-axis will be in log scale. Default is False.

  • **kwargs –

    Additional arguments to pass to seaborn.boxplot. Key arguments include: - orient: Determines the orientation of the plot. * “v”: Vertical orientation (default). In this case, categorical data

    will be plotted on the x-axis, and the boxplots will be vertical.

    • ”h”: Horizontal orientation. Categorical data will be plotted on the

      y-axis, and the boxplots will be horizontal.

Returns:

fig, ax – The created figure and axes for the plot.

Return type:

matplotlib.figure.Figure, matplotlib.axes.Axes

Examples

  • Multiple features boxplot: boxplot(adata, features=[‘GeneA’,’GeneB’])

  • Boxplot grouped by a single annotation: boxplot(adata, features=[‘GeneA’], annotation=’cell_type’)

  • Boxplot for multiple features grouped by a single annotation: boxplot(adata, features=[‘GeneA’, ‘GeneB’], annotation=’cell_type’)

  • Nested grouping by two annotations: boxplot(adata, features=[‘GeneA’], annotation=’cell_type’, second_annotation=’treatment’)

spac.visualization.boxplot_interactive(adata, annotation=None, layer=None, ax=None, features=None, showfliers=None, log_scale=False, orient='v', figure_width=3.2, figure_height=2, figure_dpi=200, defined_color_map=None, annotation_colorscale='viridis', feature_colorscale='seismic', figure_type='interactive', return_metrics=False, **kwargs)[source]

Generate a boxplot for given features from an AnnData object.

This function visualizes the distribution of gene expression (or other features) across different annotations in the provided data. It can handle various options such as log-transformation, feature selection, and handling of outliers.

Parameters:

  • adata (AnnData) – An AnnData object containing the data to plot. The expression matrix is accessed via adata.X or adata.layers[layer], and annotations are taken from adata.obs.

  • annotation (str, optional) – The name of the annotation column (e.g., cell type or sample condition) from adata.obs used to group the features. If None, no grouping is applied.

  • layer (str, optional) – The name of the layer from adata.layers to use. If None, adata.X is used.

  • ax (matplotlib.axes.Axes, optional) – The figure to plot the boxplot onto. If None, a new figure is created.

  • features (list of str, optional) – The list of features (genes) to plot. If None, all features are included.

  • showfliers ({None, "downsample", "all"}, default = None) – If ‘all’, all outliers are displayed in the boxplot. If ‘downsample’, when num outliers is >10k, they are downsampled to 10% of the original count. If None, outliers are hidden.

  • log_scale (bool, default=False) – If True, the log1p transformation is applied to the features before plotting. This option is disabled if negative values are found in the features.

  • orient ({"v", "h"}, default="v") – The orientation of the boxplots: “v” for vertical, “h” for horizontal.

  • figure_width (int, optional) – Width of the figure in inches. Default is 3.2.

  • figure_height (int, optional) – Height of the figure in inches. Default is 2.

  • figure_dpi (int, optional) – DPI (dots per inch) for the figure. Default is 200.

  • defined_color_map (str, optional) – Key in ‘adata.uns’ holding a pre-computed color dictionary. Falls back to automatic generation from ‘annotation’ values.

  • ax – A Matplotlib Axes object. Currently, this parameter is not used by the underlying plotting functions (Seaborn’s catplot/displot), which will always generate a new figure and axes. The ax key in the returned dictionary will contain the Axes from these new plots. This parameter is maintained for API consistency and potential future enhancements. Default is None.

  • **kwargs (dict) – Additional arguments for seaborn figure-level functions.

Returns:

figplotly.graph_objects.Figure or str
The generated boxplot figure, which can be either:

  • If figure_type is “static”: A base64-encoded PNG

image string - If figure_type is “interactive”: A Plotly figure object

dfpd.DataFrame

A DataFrame containing the features and their corresponding values.

metricspd.DataFrame

A DataFrame containing the computed boxplot metrics (if return_metrics is True).

Return type:

A dictionary containing the following keys

spac.visualization.dimensionality_reduction_plot(adata, method=None, annotation=None, feature=None, layer=None, ax=None, associated_table=None, **kwargs)[source]

Visualize scatter plot in PCA, t-SNE, UMAP, or associated table.

Parameters:

  • adata (anndata.AnnData) – The AnnData object with coordinates precomputed by the ‘tsne’ or ‘UMAP’ function and stored in ‘adata.obsm[“X_tsne”]’ or ‘adata.obsm[“X_umap”]’

  • method (str, optional (default: None)) – Dimensionality reduction method to visualize. Choose from {‘tsne’, ‘umap’, ‘pca’}.

  • annotation (str, optional) – The name of the column in adata.obs to use for coloring the scatter plot points based on cell annotations. Takes precedence over feature.

  • feature (str, optional) – The name of the gene or feature in adata.var_names to use for coloring the scatter plot points based on feature expression.

  • layer (str, optional) – The name of the data layer in adata.layers to use for visualization. If None, the main data matrix adata.X is used.

  • ax (matplotlib.axes.Axes, optional (default: None)) – A matplotlib axes object to plot on. If not provided, a new figure and axes will be created.

  • associated_table (str, optional (default: None)) – Name of the key in obsm that contains the numpy array. Takes precedence over method

  • **kwargs – Parameters passed to visualize_2D_scatter function, including point_size.

Returns:

  • fig (matplotlib.figure.Figure) – The created figure for the plot.

  • ax (matplotlib.axes.Axes) – The axes of the plot.

spac.visualization.heatmap(adata, column, layer=None, **kwargs)[source]

Plot the heatmap of the mean feature of cells that belong to a column.

Parameters:

  • adata (anndata.AnnData) – The AnnData object.

  • column (str) – Name of member of adata.obs to plot the histogram.

  • layer (str, default None) – The name of the adata layer to use to calculate the mean feature.

  • **kwargs – Parameters passed to seaborn heatmap function.

Returns:

  • pandas.DataFrame – A dataframe tha has the labels as indexes the mean feature for every marker.

  • matplotlib.figure.Figure – The figure of the heatmap.

  • matplotlib.axes._subplots.AxesSubplot – The AsxesSubplot of the heatmap.

spac.visualization.hierarchical_heatmap(adata, annotation, features=None, layer=None, cluster_feature=False, cluster_annotations=False, standard_scale=None, z_score='annotation', swap_axes=False, rotate_label=False, **kwargs)[source]

Generates a hierarchical clustering heatmap and dendrogram. By default, the dataset is assumed to have features as columns and annotations as rows. Cells are grouped by annotation (e.g., phenotype), and for each group, the average expression intensity of each feature (e.g., protein or marker) is computed. The heatmap is plotted using seaborn’s clustermap.

Parameters:

  • adata (anndata.AnnData) – The AnnData object.

  • annotation (str) – Name of the annotation in adata.obs to group by and calculate mean intensity.

  • features (list or None, optional) – List of feature names (e.g., markers) to be included in the visualization. If None, all features are used. Default is None.

  • layer (str, optional) – The name of the adata layer to use to calculate the mean intensity. If not provided, uses the main matrix. Default is None.

  • cluster_feature (bool, optional) – If True, perform hierarchical clustering on the feature axis. Default is False.

  • cluster_annotations (bool, optional) – If True, perform hierarchical clustering on the annotations axis. Default is False.

  • standard_scale (int or None, optional) – Whether to standard scale data (0: row-wise or 1: column-wise). Default is None.

  • z_score (str, optional) – Specifies the axis for z-score normalization. Can be “feature” or “annotation”. Default is “annotation”.

  • swap_axes (bool, optional) – If True, switches the axes of the heatmap, effectively transposing the dataset. By default (when False), annotations are on the vertical axis (rows) and features are on the horizontal axis (columns). When set to True, features will be on the vertical axis and annotations on the horizontal axis. Default is False.

  • rotate_label (bool, optional) – If True, rotate x-axis labels by 45 degrees. Default is False.

  • **kwargs –

    Additional parameters passed to sns.clustermap function or its underlying functions. Some essential parameters include: - cmap : colormap

    Colormap to use for the heatmap. It’s an argument for the underlying sns.heatmap() used within sns.clustermap(). Examples include “viridis”, “plasma”, “coolwarm”, etc.

    • {row,col}_colors : Lists or DataFrames Colors to use for annotating the rows/columns. Useful for visualizing additional categorical information alongside the main heatmap.

    • {dendrogram,colors}_ratio : tuple(float) Control the size proportions of the dendrogram and the color labels relative to the main heatmap.

    • cbar_pos : tuple(float) or None Specify the position and size of the colorbar in the figure. If set to None, no colorbar will be added.

    • tree_kws : dict Customize the appearance of the dendrogram tree. Passes additional keyword arguments to the underlying matplotlib.collections.LineCollection.

    • method : str The linkage algorithm to use for the hierarchical clustering. Defaults to ‘centroid’ in the function, but can be changed.

    • metric : str The distance metric to use for the hierarchy. Defaults to ‘euclidean’ in the function.

Returns:

  • mean_intensity (pandas.DataFrame) – A DataFrame containing the mean intensity of cells for each annotation.

  • clustergrid (seaborn.matrix.ClusterGrid) – The seaborn ClusterGrid object representing the heatmap and dendrograms.

  • dendrogram_data (dict) – A dictionary containing hierarchical clustering linkage data for both rows and columns. These linkage matrices can be used to generate dendrograms with tools like scipy’s dendrogram function. This offers flexibility in customizing and plotting dendrograms as needed.

Examples

import matplotlib.pyplot as plt import pandas as pd import anndata from spac.visualization import hierarchical_heatmap X = pd.DataFrame([[1, 2], [3, 4]], columns=[‘gene1’, ‘gene2’]) annotation = pd.DataFrame([‘type1’, ‘type2’], columns=[‘cell_type’]) all_data = anndata.AnnData(X=X, obs=annotation)

mean_intensity, clustergrid, dendrogram_data = hierarchical_heatmap(

all_data, “cell_type”, layer=None, z_score=”annotation”, swap_axes=True, cluster_feature=False, cluster_annotations=True

)

# To display a standalone dendrogram using the returned linkage matrix: import scipy.cluster.hierarchy as sch import numpy as np import matplotlib.pyplot as plt

# Convert the linkage data to type double dendro_col_data = np.array(dendrogram_data[‘col_linkage’], dtype=np.double)

# Ensure the linkage matrix has at least two dimensions and more than one linkage if dendro_col_data.ndim == 2 and dendro_col_data.shape[0] > 1:

fig, ax = plt.subplots(figsize=(10, 7)) sch.dendrogram(dendro_col_data, ax=ax) plt.title(‘Standalone Col Dendrogram’) plt.show()

else:

print(“Insufficient data to plot a dendrogram.”)

spac.visualization.histogram(adata, feature=None, annotation=None, layer=None, group_by=None, together=False, ax=None, x_log_scale=False, y_log_scale=False, **kwargs)[source]

Plot the histogram of cells based on a specific feature from adata.X or annotation from adata.obs.

Parameters:

  • adata (anndata.AnnData) – The AnnData object.

  • feature (str, optional) – Name of continuous feature from adata.X to plot its histogram.

  • annotation (str, optional) – Name of the annotation from adata.obs to plot its histogram.

  • layer (str, optional) – Name of the layer in adata.layers to plot its histogram.

  • group_by (str, default None) – Choose either to group the histogram by another column.

  • together (bool, default False) – If True, and if group_by != None, create one plot combining all groups. If False, create separate histograms for each group. The appearance of combined histograms can be controlled using the multiple and element parameters in **kwargs. To control how the histograms are normalized (e.g., to divide the histogram by the number of elements in every group), use the stat parameter in **kwargs. For example, set stat=”probability” to show the relative frequencies of each group.

  • ax (matplotlib.axes.Axes, optional) – An existing Axes object to draw the plot onto, optional.

  • x_log_scale (bool, default False) – If True, the data will be transformed using np.log1p before plotting, and the x-axis label will be adjusted accordingly.

  • y_log_scale (bool, default False) – If True, the y-axis will be set to log scale.

  • **kwargs –

    Additional keyword arguments passed to seaborn histplot function. Key arguments include: - multiple: Determines how the subsets of data are displayed

    on the same axes. Options include:
    • ”layer”: Draws each subset on top of the other

      without adjustments.

    • ”dodge”: Dodges bars for each subset side by side.

    • ”stack”: Stacks bars for each subset on top of each other.

    • ”fill”: Adjusts bar heights to fill the axes.

    • element: Determines the visual representation of the bins.
      Options include:

      • ”bars”: Displays the typical bar-style histogram (default).

      • ”step”: Creates a step line plot without bars.

      • ”poly”: Creates a polygon where the bottom edge represents

        the x-axis and the top edge the histogram’s bins.

    • log_scale: Determines if the data should be plotted on

      a logarithmic scale.

    • stat: Determines the statistical transformation to use on the data
      for the histogram. Options include:

      • ”count”: Show the counts of observations in each bin.

      • ”frequency”: Show the number of observations divided by the bin width.

      • ”density”: Normalize such that the total area of the histogram

        equals 1.

      • ”probability”: Normalize such that each bar’s height reflects

        the probability of observing that bin.

    • bins: Specification of hist bins.

      Can be a number (indicating the number of bins) or a list (indicating bin edges). For example, bins=10 will create 10 bins, while bins=[0, 1, 2, 3] will create bins [0,1), [1,2), [2,3]. If not provided, the binning will be determined automatically. Note, don’t pass a numpy array, only python lists or strs/numbers.

Returns:

figmatplotlib.figure.Figure

The created figure for the plot.

axsmatplotlib.axes.Axes or list of Axes

The Axes object(s) of the histogram plot(s). Returns a single Axes if only one plot is created, otherwise returns a list of Axes.

dfpandas.DataFrame

DataFrame containing the data used for plotting the histogram.

Return type:

A dictionary containing the following

spac.visualization.interactive_spatial_plot(adata, annotations=None, feature=None, layer=None, dot_size=1.5, dot_transparency=0.75, annotation_colorscale='rainbow', feature_colorscale='balance', figure_width=6, figure_height=4, figure_dpi=200, font_size=12, stratify_by=None, defined_color_map=None, reverse_y_axis=False, cmin=None, cmax=None, **kwargs)[source]

Create an interactive scatter plot for spatial data using provided annotations.

Parameters:

  • adata (AnnData) – Annotated data matrix object, must have a .obsm attribute with ‘spatial’ key.

  • annotations (list of str or str, optional) – Column(s) in adata.obs that contain the annotations to plot. If a single string is provided, it will be converted to a list. The interactive plot will show all the labels in the annotation columns passed.

  • feature (str, optional) – If annotation is None, the name of the gene or feature in adata.var_names to use for coloring the scatter plot points based on feature expression.

  • layer (str, optional) – If feature is not None, the name of the data layer in adata.layers to use for visualization. If None, the main data matrix adata.X is used.

  • dot_size (float, optional) – Size of the scatter dots in the plot. Default is 1.5.

  • dot_transparency (float, optional) – Transparancy level of the scatter dots. Default is 0.75.

  • annotation_colorscale (str, optional) – Name of the color scale to use for the dots when annotation is used. Default is ‘Viridis’.

  • feature_colorscale (srt, optional) – Name of the color scale to use for the dots when feature is used. Default is ‘seismic’.

  • figure_width (int, optional) – Width of the figure in inches. Default is 12.

  • figure_height (int, optional) – Height of the figure in inches. Default is 8.

  • figure_dpi (int, optional) – DPI (dots per inch) for the figure. Default is 200.

  • font_size (int, optional) – Font size for text in the plot. Default is 12.

  • stratify_by (str, optional) – Column in adata.obs to stratify the plot. Default is None.

  • defined_color_map (str, optional) – Predefined color mapping stored in adata.uns for specific labels. Default is None, which will generate the color mapping automatically.

  • reverse_y_axis (bool, optional) – If True, reverse the Y-axis of the plot. Default is False.

  • cmin (float, optional) – Minimum value for the color scale when using features. Default is None.

  • cmax (float, optional) – Maximum value for the color scale when using features. Default is None.

  • **kwargs – Additional keyword arguments for customization.

Returns:

A list of dictionaries, each containing the following keys: - “image_name”: str, the name of the generated image. - “image_object”: Plotly Figure object.

Return type:

list of dict

Notes

This function is tailored for spatial single-cell data and expects the AnnData object to have spatial coordinates in its .obsm attribute under the ‘spatial’ key.

spac.visualization.plot_ripley_l(adata, phenotypes, regions=None, sims=False, return_df=False, **kwargs)[source]

Plot Ripley’s L statistic for multiple bins and different regions for a given pair of phenotypes.

Parameters:

  • adata (AnnData) – AnnData object containing Ripley’s L results in adata.uns[‘ripley_l’].

  • phenotypes (tuple of str) – A tuple of two phenotypes: (center_phenotype, neighbor_phenotype).

  • regions (list of str, optional) – A list of region labels to plot. If None, plot all available regions. Default is None.

  • sims (bool, optional) – Whether to plot the simulation results. Default is False.

  • return_df (bool, optional) – Whether to return the DataFrame containing the Ripley’s L results.

  • kwargs (dict, optional) – Additional keyword arguments to pass to seaborn.lineplot.

Raises:

ValueError – If the Ripley L results are not found in adata.uns[‘ripley_l’].

Returns:

  • ax (matplotlib.axes.Axes) – The Axes object containing the plot, which can be further modified.

  • df (pandas.DataFrame, optional) – The DataFrame containing the Ripley’s L results, if return_df is True.

Example

>>> ax = plot_ripley_l(
...     adata,
...     phenotypes=('Phenotype1', 'Phenotype2'),
...     regions=['region1', 'region2'])
>>> plt.show()

This returns the Axes object for further customization and displays the plot.

spac.visualization.present_summary_as_figure(summary_dict: dict) → Figure[source]

Build a static Plotly figure (using a table) to depict the summary dictionary.

The figure includes columns:

  • Column name

  • Data type

  • Count of missing values

  • Missing indices (as a string)

  • Summary details (formatted as JSON for readability)

Parameters:

summary_dict (dict) – The summary dictionary returned from summarize_dataframe.

Returns:

A static Plotly table figure representing the summary.

Return type:

plotly.graph_objects.Figure

spac.visualization.present_summary_as_html(summary_dict: dict) → str[source]

Build an HTML string that presents the summary information intuitively.

For each specified column, the HTML includes:

  • Column name and data type

  • Count and list of missing indices

  • Summary details presented in a table (for numeric: stats; categorical: unique values and counts)

Parameters:

summary_dict (dict) – The summary dictionary returned by summarize_dataframe.

Returns:

HTML string representing the summary.

Return type:

str

spac.visualization.relational_heatmap(adata: AnnData, source_annotation: str, target_annotation: str, color_map: str = 'mint', **kwargs)[source]

Generates a relational heatmap from the given AnnData object. The color map refers to matplotlib color maps, default is mint. For more information on colormaps, see: https://matplotlib.org/stable/users/explain/colors/colormaps.html

Parameters:

  • adata (anndata.AnnData) – The annotated data matrix.

  • source_annotation (str) – The source annotation to use for the relational heatmap.

  • target_annotation (str) – The target annotation to use for the relational heatmap.

  • color_map (str) – The color map to use for the relational heatmap. Default is mint.

  • **kwargs (dict, optional) – Additional keyword arguments. For example, you can pass font_size=12.0.

Returns:

A dictionary containing: - “figure” (plotly.graph_objs._figure.Figure):

The generated relational heatmap as a Plotly figure.

  • ”file_name” (str):

    The name of the file where the relational matrix can be saved.

  • ”data” (pandas.DataFrame):

    A relational matrix DataFrame with percentage values. Rows represent source annotations, columns represent target annotations, and an additional “total” column sums the percentages for each source.

Return type:

dict

spac.visualization.sankey_plot(adata: AnnData, source_annotation: str, target_annotation: str, source_color_map: str = 'tab20', target_color_map: str = 'tab20c', sankey_font: float = 12.0, prefix: bool = True)[source]

Generates a Sankey plot from the given AnnData object. The color map refers to matplotlib color maps, default is tab20 for source annotation, and tab20c for target annotation. For more information on colormaps, see: https://matplotlib.org/stable/users/explain/colors/colormaps.html

Parameters:

  • adata (anndata.AnnData) – The annotated data matrix.

  • source_annotation (str) – The source annotation to use for the Sankey plot.

  • target_annotation (str) – The target annotation to use for the Sankey plot.

  • source_color_map (str) – The color map to use for the source nodes. Default is tab20.

  • target_color_map (str) – The color map to use for the target nodes. Default is tab20c.

  • sankey_font (float, optional) – The font size to use for the Sankey plot. Defaults to 12.0.

  • prefix (bool, optional) – Whether to prefix the target labels with the source labels. Defaults to True.

Returns:

The generated Sankey plot.

Return type:

plotly.graph_objs._figure.Figure

spac.visualization.spatial_plot(adata, spot_size, alpha, vmin=-999, vmax=-999, annotation=None, feature=None, layer=None, ax=None, **kwargs)[source]

Generate the spatial plot of selected features :param adata: The AnnData object containing target feature and spatial coordinates. :type adata: anndata.AnnData :param spot_size: The size of spot on the spatial plot. :type spot_size: int :param alpha: The transparency of spots, range from 0 (invisible) to 1 (solid) :type alpha: float :param vmin: The lower limit of the feature value for visualization :type vmin: float or int :param vmax: The upper limit of the feature value for visualization :type vmax: float or int :param feature: The feature to visualize on the spatial plot.

Default None.

Parameters:

  • annotation (str) – The annotation to visualize in the spatial plot. Can’t be set with feature, default None.

  • layer (str) – Name of the AnnData object layer that wants to be plotted. By default adata.raw.X is plotted.

  • ax (matplotlib.axes.Axes) – The matplotlib Axes containing the analysis plots. The returned ax is the passed ax or new ax created. Only works if plotting a single component.

  • **kwargs – Arguments to pass to matplotlib.pyplot.scatter()

Returns:

Single or a list of class

Return type:

~matplotlib.axes.Axes.

spac.visualization.threshold_heatmap(adata, feature_cutoffs, annotation, layer=None, swap_axes=False, **kwargs)[source]

Creates a heatmap for each feature, categorizing intensities into low, medium, and high based on provided cutoffs.

Parameters:

  • adata (anndata.AnnData) – AnnData object containing the feature intensities in .X attribute or specified layer.

  • feature_cutoffs (dict) – Dictionary with feature names as keys and tuples with two intensity cutoffs as values.

  • annotation (str) – Column name in .obs DataFrame that contains the annotation used for grouping.

  • layer (str, optional) – Layer name in adata.layers to use for intensities. If None, uses .X attribute.

  • swap_axes (bool, optional) – If True, swaps the axes of the heatmap.

  • **kwargs (keyword arguments) – Additional keyword arguments to pass to scanpy’s heatmap function.

Returns:

A dictionary contains the axes of figures generated in the scanpy heatmap function. Consistent Key: ‘heatmap_ax’ Potential Keys includes: ‘groupby_ax’, ‘dendrogram_ax’, and ‘gene_groups_ax’.

Return type:

Dictionary of Axes

spac.visualization.tsne_plot(adata, color_column=None, ax=None, **kwargs)[source]

Visualize scatter plot in tSNE basis.

Parameters:

  • adata (anndata.AnnData) – The AnnData object with t-SNE coordinates precomputed by the ‘tsne’ function and stored in ‘adata.obsm[“X_tsne”]’.

  • color_column (str, optional) – The name of the column to use for coloring the scatter plot points.

  • ax (matplotlib.axes.Axes, optional (default: None)) – A matplotlib axes object to plot on. If not provided, a new figure and axes will be created.

  • **kwargs – Parameters passed to scanpy.pl.tsne function.

Returns:

  • fig (matplotlib.figure.Figure) – The created figure for the plot.

  • ax (matplotlib.axes.Axes) – The axes of the tsne plot.

spac.visualization.visualize_2D_scatter(x, y, labels=None, point_size=None, theme=None, ax=None, annotate_centers=False, x_axis_title='Component 1', y_axis_title='Component 2', plot_title=None, color_representation=None, **kwargs)[source]

Visualize 2D data using plt.scatter.

Parameters:

  • x (array-like) – Coordinates of the data.

  • y (array-like) – Coordinates of the data.

  • labels (array-like, optional) – Array of labels for the data points. Can be numerical or categorical.

  • point_size (float, optional) – Size of the points. If None, it will be automatically determined.

  • theme (str, optional) – Color theme for the plot. Defaults to ‘viridis’ if theme not recognized. For a list of supported themes, refer to Matplotlib’s colormap documentation: https://matplotlib.org/stable/tutorials/colors/colormaps.html

  • ax (matplotlib.axes.Axes, optional (default: None)) – Matplotlib axis object. If None, a new one is created.

  • annotate_centers (bool, optional (default: False)) – Annotate the centers of clusters if labels are categorical.

  • x_axis_title (str, optional) – Title for the x-axis.

  • y_axis_title (str, optional) – Title for the y-axis.

  • plot_title (str, optional) – Title for the plot.

  • color_representation (str, optional) – Description of what the colors represent.

  • **kwargs – Additional keyword arguments passed to plt.scatter.

Returns:

  • fig (matplotlib.figure.Figure) – The figure of the plot.

  • ax (matplotlib.axes.Axes) – The axes of the plot.

spac.visualization.visualize_nearest_neighbor(adata, annotation, distance_from, distance_to=None, stratify_by=None, spatial_distance='spatial_distance', facet_plot=False, method=None, plot_type=None, log=False, annotation_colorscale='rainbow', defined_color_map=None, ax=None, **kwargs)[source]

Visualize nearest-neighbor (spatial distance) data between groups of cells with optional pin-color map via numeric or distribution plots.

This landing function first constructs a tidy long-form DataFrame via function _prepare_spatial_distance_data, then dispatches plotting to function _plot_spatial_distance_dispatch. A pin-color feature guarantees consistent mapping from annotation labels to colors across figures, drawing the mapping from adata.uns (if present) or generating one automatically through spac.utils.color_mapping.

Plot arrangement logic:

  1. If stratify_by is not None and facet_plot=True => single figure with subplots (faceted).

  2. If stratify_by is not None and facet_plot=False => multiple separate figures, one per group.

  3. If stratify_by is None => a single figure with one plot.

Parameters:

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

  • annotation (str) – Column in adata.obs containing cell phenotypes or annotations.

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

  • distance_to (str or list of str, optional) – Target phenotype(s) to measure distance to. If None, uses all available phenotypes.

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

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

  • facet_plot (bool, optional) – If True (and stratify_by is not None), subplots in a single figure. Otherwise, multiple or single figure(s).

  • method ({'numeric', 'distribution'}) – Determines the plotting style (catplot vs displot).

  • plot_type (str or None, optional) – Specific seaborn plot kind. If None, sensible defaults are selected (‘boxen’ for numeric, ‘violin’ for distribution). For method=’numeric’: ‘box’, ‘violin’, ‘boxen’, ‘strip’, ‘swarm’. For method=’distribution’: ‘hist’, ‘kde’, ‘ecdf’.

  • log (bool, optional) – If True, applies np.log1p transform to the distance values.

  • annotation_colorscale (str, optional) – Matplotlib colormap name used when auto-enerating a new mapping. Ignored if ‘defined_color_map’ is provided.

  • defined_color_map (str, optional) – Key in ‘adata.uns’ holding a pre-computed color dictionary. Falls back to automatic generation from ‘annotation’ values.

  • ax (matplotlib.axes.Axes, optional) – The matplotlib Axes containing the analysis plots. The returned ax is the passed ax or new ax created. Only works if plotting a single component. Default is None.

  • **kwargs (dict) – Additional arguments for seaborn figure-level functions.

Returns:

{

‘data’: pd.DataFrame, # long-form table for plotting ‘fig’ : matplotlib.figure.Figure | list[Figure] | None, ‘ax’: matplotlib.axes.Axes | list[matplotlib.axes.Axes], ‘palette’: dict # {label: ‘#rrggbb’}

}

Return type:

dict

Raises:

ValueError – If required parameters are invalid.

Examples

>>> res = visualize_nearest_neighbor(
...     adata=my_adata,
...     annotation='cell_type',
...     distance_from='Tumour',
...     distance_to=['Stroma', 'B cell'],
...     method='numeric',
...     plot_type='box',
...     facet_plot=True,
...     stratify_by='image_id',
...     defined_color_map='pin_color_map'
... )
>>> fig = res['fig']      # matplotlib.figure.Figure
>>> ax_list = res['ax']   # list[matplotlib.axes.Axes] (faceted plot)
>>> df  = res['data']     # long-form DataFrame
>>> ax_list[0].set_title('Tumour → Stroma distances')

Functions