metachat.pl.plot_group_communication_chord

metachat.pl.plot_group_communication_chord(adata, database_name=None, group_name=None, summary='sender', metabolite_name=None, metapathway_name=None, customerlist_name=None, ms_pair_name=None, permutation_spatial=False, p_value_cutoff=0.05, self_communication_off=False, highlight_group_sender=None, highlight_group_receiver=None, space=5, group_cmap=None, figsize=(5, 5), ax=None, plot_savepath=None)[source]

Plot a chord diagram representing group-level metabolic cell communication (MCC).

This function visualizes inter-group communication strength as a chord diagram, based on results computed by MetaChat group-level analysis. Each arc represents a cell group, and links represent the strength of metabolite-mediated communication between sender and receiver groups.

The communication matrix and associated p-values must be precomputed 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 used for MCC analysis.

group_namestr

Column name in adata.obs specifying cell group annotations.

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

Direction of communication summary to visualize.

metabolite_namestr, optional

Name of a specific metabolite to visualize.

metapathway_namestr, optional

Name of a specific metabolic pathway to visualize.

customerlist_namestr, optional

Name of a specific custom metabolite list to visualize.

ms_pair_name: str, optional

Name of a specific metabolite–sensor pair to visualize.

permutation_spatialbool, default=False

Whether to use results from spatially permuted communication tests (mc.tl.communication_group_spatial).

p_value_cutofffloat, default=0.05

P-value threshold for filtering significant group-level communications.

self_communication_offbool, default=False

Whether to remove self-communication.

highlight_group_senderstr or list of str, optional

Name(s) of sender group(s) to highlight. Other groups are rendered transparent.

highlight_group_receiverstr or list of str, optional

Name(s) of receiver group(s) to highlight. Other groups are rendered transparent.

spaceint, default=5

Angular spacing between group arcs in degrees.

group_cmapdict or str, optional

Mapping from group names to colors, or qualitative palette name (e.g., 'Plotly', 'Alphabet').

figsizetuple of float, default=(5, 5)

Figure size (width, height).

axmatplotlib.axes.Axes, optional

Existing axis to draw the chord diagram. If None, a new one is created.

plot_savepathstr, optional

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

Returns

axmatplotlib.axes.Axes

Matplotlib axis containing the chord diagram.

Notes

  • The function requires that group-level communication results are already computed and stored in:

    • adata.uns["MetaChat_group-<group_name>-<database_name>-<summary>-<target>"] (for mc.tl.communication_group()), or

    • adata.uns["MetaChat_group_spatial-..."] (for mc.tl.communication_group_spatial()).

  • Links are filtered by p_value_cutoff and optionally exclude self-communications.

  • Highlight options can be used to emphasize communication from or to selected cell groups.

  • This visualization helps identify dominant sender–receiver relationships across cell types or regions.