metachat.pl.plot_group_communication_heatmap

metachat.pl.plot_group_communication_heatmap(adata, database_name=None, group_name=None, metabolite_name=None, metapathway_name=None, customerlist_name=None, ms_pair_name=None, summary='sender', permutation_spatial=False, p_value_plot=True, p_value_cutoff=0.05, size_scale=300, cmap='green', palette=None, marker='s', x_order=None, y_order=None, figsize=(10, 10), ax=None, plot_savepath=None)

Plot a heatmap diagram for group-level metabolic cell communication (MCC).

This function visualizes group-level MCC intensity between sender and receiver cell groups, using aheatmap representation. Each point corresponds to a sender–receiver pair, colored by communication strength and optionally marked with significance (*).

The group-level communication results must be computed beforehand by mc.tl.communication_group() or mc.tl.communication_group_spatial().

Parameters

adataanndata.AnnData

Annotated data matrix containing group-level MCC results in adata.uns.

database_namestr

Name of the metabolite–sensor interaction database.

group_namestr

Column name in adata.obs specifying the cell group annotation.

metabolite_namestr, optional

Name of a specific metabolite to visualize (e.g., 'HMDB0000148').

metapathway_namestr, optional

Name of a specific metabolic pathway to visualize.

customerlist_namestr, optional

Name of a custom metabolite list to visualize.

ms_pair_namestr, optional

Name of a specific metabolite–sensor pair to visualize.

summary{“sender”, “receiver”}, default=”sender”

Direction of communication summary to visualize.

permutation_spatialbool, default=False

Whether to use results from mc.tl.communication_group_spatial.

p_value_plotbool, default=True

Whether to mark significant interactions with an asterisk *.

p_value_cutofffloat, default=0.05

Significance threshold for group-level MCC visualization.

size_scalefloat, default=300

Scaling factor controlling marker size proportional to MCC score.

cmap{“green”, “red”, “blue”}, default=”green”

Predefined color theme for communication strength.

palettelist, optional

Custom color palette list. If specified, overrides cmap.

markerstr, default=”s”

Matplotlib marker style used in the scatter plot.

x_orderlist of str, optional

Order of sender groups along the x-axis.

y_orderlist of str, optional

Order of receiver groups along the y-axis.

figsizetuple of float, default=(10, 10)

Size of the output figure (width, height).

plot_savepathstr, optional

File path to save the figure. The format is inferred from the extension.

axmatplotlib.axes.Axes, optional

Existing axis to draw on. If None, a new figure and axis are created.

Returns

axmatplotlib.axes.Axes

Matplotlib axis containing the heatmap plot.

Notes

• The function expects communication matrices and p-values stored in:

  • adata.uns["MetaChat_group-<group_name>-<database_name>-<summary>-<target>"] or

  • adata.uns["MetaChat_group_spatial-..."] for spatial permutation results.

• Significance marks (*) are added when p_value_plot=True and p < p_value_cutoff.

• Marker size and color are scaled by communication intensity.

• Use x_order and y_order to enforce custom group display order.