mtopic.pl.dominant_topics

mtopic.pl.dominant_topics#

mtopic.pl.dominant_topics(mdata, x, topics='topics', palette=None, annotation=None, title=None, marker='.', s=20, fontsize=10, markerscale=1, legend=True, legend_ncol=1, figsize=(7, 5), random_state=2291, transparent=False, save=None)#

Visualize the dominant topic for each cell/spot in a MuData object.

This function creates a scatter plot where each point represents a cell/spot, colored according to the dominant topic (i.e., the topic with the highest probability) for that sample. The plot provides an intuitive overview of how topics are distributed spatially or in a given embedding. A legend maps colors to topics for easy interpretation.

Parameters:

  • mdata (muon.MuData) – A MuData object containing multimodal single-cell data with topic distributions stored in obsm.

  • x (str) – The key in obsm of mdata representing the spatial coordinates or embeddings to use for plotting (e.g., ‘coords’, ‘umap’).

  • topics (str, optional) – The key in obsm of mdata representing the topic distribution. Default is ‘topics’.

  • palette (dict, optional) – A dictionary mapping topics to specific colors. If None, a default palette of unique hex colors is generated. Default is None.

  • annotation (dict, optional) – Dictionary mapping topic names to display labels shown in the legend (e.g. {'topic_1': 'Inhibitory neurons-3', ...}). If None or a topic is not found, the raw topic name is used. Default is None.

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

  • marker (str, optional) – Marker style for the scatter plot. Default is ‘.’.

  • s (int, optional) – Marker size in the scatter plot. Default is 20.

  • fontsize (int, optional) – Font size for legend labels. Default is 10.

  • markerscale (float, optional) – Scale of markers in the legend relative to their size in the scatter plot. Default is 1.

  • legend (bool, optional) – Whether to display the legend. Default is True.

  • legend_ncol (int, optional) – Number of columns in the legend. Default is 1.

  • figsize (tuple, optional) – Tuple specifying the figure size (width, height) in inches. Default is (7, 5).

  • random_state (int, optional) – Random seed for shuffling point plotting order, so no topic systematically occludes another. If None, a different random order is used each call. Default is 2291.

  • transparent (bool, optional) – Whether to save the figure with a transparent background. Useful for overlays or presentations. Default is False.

  • save (str, optional) – Path to save the figure. If None, the figure is displayed but not saved. Default is None.

Returns:

None

Example:
import mtopic

# Load MuData object
mdata = mtopic.read.h5mu("path/to/file.h5mu")

# Plot dominant topics for all samples
mtopic.pl.dominant_topics(
    mdata,
    x='umap',
    topics='topics',
    marker='o',
    s=30,
    fontsize=12,
    markerscale=3
)

# Save the figure to a file
mtopic.pl.dominant_topics(
    mdata,
    x='coords',
    save='dominant_topics.pdf'
)