mtopic.pl.scatter_pie

Contents

mtopic.pl.scatter_pie#

mtopic.pl.scatter_pie(mdata, topics='topics', x='coords', radius=0.005, xrange=[0, 1], yrange=[0, 1], figsize=(10, 10), palette=None, annotation=None, title=None, legend=True, legend_ncol=1, legend_markersize=10, fontsize=10, transparent=False, save=None)#

Create a scatter plot with pie charts representing topic distributions at each cell/spot coordinate.

This function visualizes topic distributions for each sample in a dataset using pie charts positioned at their corresponding spatial or embedding coordinates. Each pie chart represents the distribution of topics for a single cell/spot, and a legend provides the color mapping for each topic.

Parameters:

  • mdata (muon.MuData) – A MuData object containing multimodal single-cell data, including topic distributions and coordinates.

  • topics (str, optional) – Key in mdata.obsm for the topic distribution matrix. Default is 'topics'.

  • x (str, optional) – Key in mdata.obsm for a pandas DataFrame of spatial or embedding coordinates. Default is 'coords'.

  • radius (float, optional) – Radius of each pie chart in data coordinates. Default is 0.005.

  • xrange (list, optional) – Range [min, max] of x-coordinates to display. Default is [0, 1].

  • yrange (list, optional) – Range [min, max] of y-coordinates to display. Default is [0, 1].

  • figsize (tuple, optional) – Figure size (width, height) in inches. Default is (10, 10).

  • palette (dict, optional) – Dictionary mapping topic names to hex color strings (e.g. {'topic_1': '#ffbcdd', ...}). If None, colors are generated automatically from matplotlib colormaps. 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.

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

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

  • legend_markersize (int, optional) – Size of the circle markers in the legend. Default is 10.

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

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

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

Returns:

None

Example:
import mtopic

mdata = mtopic.read.h5mu("path/to/file.h5mu")

mtopic.pl.scatter_pie(
    mdata,
    topics='topics',
    x='coords',
    radius=0.01,
    palette=P22ATAC_TOPIC_COLOR,
    annotation=P22ATAC_TOPIC_CELLTYPE,
    save='scatter_pie.png'
)
Notes:

  • Coordinates are normalised to [0, 1] before plotting.

  • Range filters: use xrange and yrange to zoom into a specific region.

  • Performance: pie charts are rendered as PatchCollection objects (one per topic) rather than individual ax.pie() calls, making the function efficient for large datasets.

Contents