metachat.pl.plot_group_communication_compare_hierarchy_diagram

metachat.pl.plot_group_communication_compare_hierarchy_diagram(adata_A, adata_B, condition_name_A=None, condition_name_B=None, 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, node_sizes_limit=(50, 300), edge_sizes_limit=(0.5, 10), group_cmap=None, alpha=0.5, figsize=(10, 3), ax=None, plot_savepath=None)

Plot a hierarchy-style diagram comparing group-level MCC between two conditions.

This visualization contrasts the direction and strength of group-level metabolic cell communication (MCC) between two conditions (e.g., Control vs Disease). Sender–receiver relationships are represented as directed edges between nodes on two parallel panels, showing both conditions side by side.

Parameters

adata_Aanndata.AnnData

Annotated data matrix for condition A. Must contain group-level MCC results.

adata_Banndata.AnnData

Annotated data matrix for condition B. Must contain the same structure as adata_A.

condition_name_Astr, optional

Label for condition A, shown on the left panel (e.g., “Control”).

condition_name_Bstr, optional

Label for condition B, shown on the right panel (e.g., “Disease”).

database_namestr

Name of the metabolite–sensor interaction database used for MCC computation.

group_namestr

Column name in adata.obs containing group/cell-type annotations.

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

Direction of communication summary to visualize.

metabolite_namestr, optional

Specific metabolite to visualize.

metapathway_namestr, optional

Specific metabolic pathway to visualize.

customerlist_namestr, optional

Custom metabolite list name to visualize.

ms_pair_namestr, optional

Name of a specific metabolite–sensor pair to visualize.

permutation_spatialbool, default=False

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

p_value_cutofffloat, default=0.05

Threshold for significance in group-level communication.

node_sizes_limittuple of float, default=(50, 300)

Minimum and maximum node size for scaling group strength.

edge_sizes_limittuple of float, default=(0.5, 10)

Minimum and maximum edge width for scaling communication intensity.

group_cmapdict, optional

Mapping from group names to colors. If None, retrieved from adata.obs[group_name].cat.categories and corresponding color table in adata.uns[group_name + "_colors"].

alphafloat, default=0.5

Transparency for non-significant edges.

figsizetuple of float, default=(10, 3)

Figure size (width, height).

axmatplotlib.axes.Axes, optional

Existing Matplotlib axis to draw the hierarchy diagram on. If None, a new figure and axis are created.

plot_savepathstr, optional

File path to save the figure (e.g., "results/group_compare_hierarchy.pdf"). The format is inferred from the file extension. If None, the plot is displayed interactively without saving.

Returns

axmatplotlib.axes.Axes

Matplotlib axis containing the hierarchy comparison diagram.

Notes

• This function visualizes the output from mc.tl.communication_group() or mc.tl.communication_group_spatial() for two different conditions.

• Node size reflects total communication strength per group.

• Edge width and color indicate direction and magnitude of communication.

• Non-significant edges (p ≥ cutoff) are rendered transparent with reduced opacity.