metachat.tl.compute_direction_histogram_per_pair

metachat.tl.compute_direction_histogram_per_pair(adata, database_name, all_ms_pairs, summary='receiver', grid_density=0.5, n_bins=18, eps=0.001)[source]

Compute per-pair directional histograms for MCC vector fields.

This function computes a 19-dimensional direction histogram for each metabolite–sensor (M–S) pair, based on the angular distribution of local communication flow vectors. Grid points that are zero vectors across all pairs are removed before histogramming.

The last bin (dir_bin_zero) represents the fraction of zero vectors, while the remaining n_bins bins capture the normalized angular distribution of nonzero vectors.

Steps

  1. For each M–S pair, retrieve the vector field using mc.pl.plot_communication_flow() (grid mode).

  2. Stack all vector fields and identify grid positions that are zero across all pairs.

  3. Remove all-zero grids and retain only informative ones.

  4. For each remaining M–S pair: - Normalize vector magnitudes by their maximum norm. - Set vectors below eps to zero. - Compute the histogram of angles using atan2(Vy, Vx) with n_bins bins. - Compute the zero fraction (ratio of zero vectors to total grid points). - Concatenate n_bins angular bins and one zero bin (total 19 features).

  5. Return a DataFrame summarizing per-pair histograms and the filtered grid coordinates.

Parameters

adataanndata.AnnData

Annotated data object containing spatial coordinates and MCC flow results.

database_namestr

Name of the metabolite–sensor database used in MCC inference.

all_ms_pairslist

List of metabolite–sensor pair names to process.

summarystr, default=”receiver”

Whether to summarize the flow field from the “sender” or “receiver” perspective.

grid_densityfloat, default=0.5

Density parameter controlling the grid resolution for vector field sampling.

n_binsint, default=18

Number of angular bins for histogramming directions.

epsfloat, default=1e-3

Threshold below which vectors are treated as zero.

Returns

df_histpandas.DataFrame

DataFrame of shape (n_pairs × (n_bins + 1)) containing the angular distribution (dir_bin_0–dir_bin_{n_bins-1}) and zero fraction (dir_bin_zero) for each metabolite–sensor pair.

coords_filterednumpy.ndarray

Array of filtered grid coordinates (G × 2) retained after removing all-zero grid points.

Notes

  • This function is designed to produce direction histograms that summarize flow orientation patterns across multiple metabolite–sensor pairs.

  • The output is suitable for downstream analyses such as clustering or comparing flow directionality patterns between pathways or tissue regions.

  • The function internally suppresses plotting figures for performance.