hrchy_cytocommunity.visualization.visualization.vis_scatter_label

hrchy_cytocommunity.visualization.visualization.vis_scatter_label(target_graph_map: DataFrame, label_name, dict_color, title=None, output_dir=None, label_order=None, level='fine', output_screen=False)

Visualize spatial scatter plots colored by cluster or cell-type labels.

This function generates a 2D scatter plot of spatial coordinates from single-cell or spot-level spatial omics data, where points are colored by the specified label (e.g., fine-grained cluster, coarse-grained cluster, or cell type). The function supports custom color palettes, legend ordering, and output saving.

Parameters:

  • target_graph_map (pandas.DataFrame) – DataFrame containing at least the following columns: - x_coordinate : float — x-axis coordinate of each cell or spot - y_coordinate : float — y-axis coordinate of each cell or spot - plus one or more label columns (e.g., fine_GT, coarse_GT, CellType) that will be used for coloring.

  • label_name (str) – Column name in target_graph_map to be visualized as color categories.

  • dict_color (dict or list or None) – Color mapping for each label. If None, automatically selects a default palette: - Set2 for coarse level - hsv for fine level

  • title (str, optional) – Title of the figure. If None, no title is shown.

  • output_dir (str or Path, optional) – Directory to save the output PNG figure. If None, the figure is not saved.

  • label_order (list of str, optional) – Specific order of labels for the legend. If None, the legend follows the default seaborn order.

  • level ({'fine', 'coarse'}, default='fine') – Determines which default color palette to use when dict_color is None.

  • output_screen (bool, default=False) – Whether to display the figure on screen (plt.show()).

Returns:

The function creates and optionally saves a scatter plot but does not return any object.

Return type:

None

Notes

  • The function automatically removes axis ticks and borders for clean visualization.

  • The y-axis is inverted (ax.invert_yaxis()) to match typical spatial transcriptomics coordinate orientation.

  • Legends are dynamically generated and can be reordered by providing label_order.

  • When both output_dir and title are given, the saved file name will be <output_dir>/<title>.png.

Examples

>>> vis_scatter_label(
...     target_graph_map=df,
...     label_name='fine_GT',
...     dict_color=None,
...     title='Fine-level Clusters',
...     output_dir='results/figures',
...     level='fine',
...     output_screen=True
... )