mechanochat.tools.signal_direction#

mechanochat.tools.signal_direction(xc: ndarray[Any, dtype[_ScalarType_co]], sig_mat: csr_matrix, xc2grid_map: dict | None = None, Nc_grid_min: int = 3, W_grid_min: float = 0.)[source]#

Direction of the signal received by each cell, optionally averaged over a grid.

For cell i the direction is the signal-weighted mean of the vectors pointing from its partners to itself,

\[V_i = \frac{\sum_j s_{ij} (x_i - x_j)}{\sum_j s_{ij}}\]

so with a receiver-major matrix (row = receiver, e.g. .obsp[‘mechano_*’]) the vector points along the incoming signal, from the senders towards the receiver.

Parameters:

xc (numpy.ndarray) – (nc, dim) cell coordinates.
sig_mat (csr_matrix) – (nc, nc) signal matrix.
xc2grid_map (dict, optional) – Cell-to-grid mapping from cell2grid. If None, only the per-cell directions are returned.
Nc_grid_min (int) – Minimum number of cells for a grid cell to be kept.
W_grid_min (float) – Minimum total signal for a grid cell to be kept.

Returns:

Vc (numpy.ndarray) – (nc, dim) per-cell direction. Returned alone when xc2grid_map is None.
Xgrid, Vgrid, Wgrid, Vc (tuple) – When xc2grid_map is given: the signal-weighted mean position, the signal-weighted mean direction and the total signal of each retained grid cell, plus the per-cell directions.