metachat.pl.plot_direction_similarity

metachat.pl.plot_direction_similarity(df_direction, cluster_labels, cmap='mako', figsize=(9, 7), title='Flow pattern similarity (Euclidean-based)', savepath=None)

Plot a block-ordered similarity heatmap for direction-based flow clusters.

This function visualizes the pairwise similarity of MCC flow direction histograms across all metabolite–sensor pairs, ordered by K-means cluster labels. The resulting heatmap highlights within-cluster consistency and between-cluster differences in flow directionality patterns.

The similarity between two pairs is defined as:

S = 1 - D / D.max(),

where D is the pairwise Euclidean distance between direction histograms. Thus, S ranges from 0 (completely dissimilar) to 1 (identical).

Parameters

df_directionpandas.DataFrame

Matrix of direction histogram features (rows = metabolite–sensor pairs, columns = direction bins, typically 18 bins).

cluster_labelsnumpy.ndarray or array-like

Cluster assignments for each M–S pair, usually obtained from K-means or hierarchical clustering.

cmapstr or matplotlib Colormap, default=”mako”

Colormap for the similarity heatmap. Can be any seaborn or matplotlib colormap.

figsizetuple of (float, float), default=(9, 7)

Figure size in inches.

titlestr, default=”Flow pattern similarity (Euclidean-based)”

Title displayed at the top of the plot.

savepathstr or None, optional

If provided, saves the figure to the specified file path.

Returns

None

Displays a block-ordered heatmap showing inter-pair similarity and cluster boundaries.

Notes

• The similarity matrix is computed as 1 - D / D.max(), where D is the Euclidean distance matrix among all histograms.

• The function automatically sorts rows and columns by cluster label to create block-like patterns for visual cluster inspection.

• Colored sidebars indicate cluster membership along both axes.

• A legend summarizes each flow pattern cluster with its sample size.