mechanochat.plotting.signal_direction_plot#

mechanochat.plotting.signal_direction_plot(sem: SEM2 | None = None, adata: AnnData | None = None, spatial_key: str | None = 'spatial', sig_mat: csr_matrix | ndarray[Any, dtype[_ScalarType_co]] | None = None, signal: str | None = None, th: float = 0., quiver_length: float = 0.45, min_quiver_length: float = -1., quiver2d_param: dict = {}, width_bin_n=3, width_scale=[0.5, 2], cid_list: ndarray[Any, dtype[int64]] | ndarray[Any, dtype[bool_]] | Sequence[int] | None = None, scaling: bool = True, ax: Axes | None = None, rotation: Dict | None = None)[source]#

Plot spatial directions of cell-cell communication using quiver arrows.

For each sender-receiver pair with signal strength above th, draws an arrow centered at the midpoint of the sender-receiver segment with length (end - start) * quiver_length. When communication is bidirectional (both sig_mat[i, j] > th and sig_mat[j, i] > th), two opposite quiver arrows are overlaid at the midpoint to form a visual double-headed arrow. Arrow width is stratified by signal strength percentiles.

Parameters:

  • sem (SEM2, optional) – Subcellular element method object. If provided, cell coordinates and signal matrix are retrieved from sem. Takes precedence over adata.

  • adata (AnnData, optional) – AnnData object used when sem is None. Must contain spatial coordinates in adata.obsm[spatial_key] and the signal matrix in adata.obsp[signal].

  • spatial_key (str, default 'spatial') – Key in adata.obsm for spatial coordinates. Only used when sem is None.

  • sig_mat (csr_matrix or ndarray, optional) – Signal matrix of shape (nc, nc). sig_mat[i, j] is the signal strength from sender j to receiver i. Required if signal is not provided.

  • signal (str, optional) – Key in sem.adata.obsp or adata.obsp to retrieve the signal matrix. Takes precedence over sig_mat.

  • th (float or callable, default 0.) – Signal strength threshold. Sender-receiver pairs with signal <= th are not plotted. If callable, it is applied to all signal data values to compute th.

  • quiver_length (float, default 0.45) – Fraction of the sender-to-receiver vector used as arrow length. 1.0 means the arrow tip reaches the receiver centroid.

  • min_quiver_length (float, default -1.) – Minimum arrow length for bidirectional pairs; shorter arrows are stretched to this length so that they stay visible between two adjacent cells

  • quiver2d_param (dict, default {}) – Additional keyword arguments passed to ax.quiver()

  • width_bin_n (int, default 3) – Number of bins the signal strengths are split into; each bin is drawn with its own arrow width

  • width_scale (list of float, default [0.5, 2]) – Minimum and maximum multipliers applied to the base arrow width across the percentile strata defined by

  • cid_list (ndarray, optional) – Array of cell indices to include. Only sender-receiver pairs where both cells are in cid_list are plotted. Default: all cells.

  • scaling (bool, default True) – If True and sem is provided, transforms internal simulation coordinates to original spatial coordinates via xc * scale + deltax.

  • ax (Axes, optional) – Target matplotlib axes object. Creates new figure if None.

  • rotation (dict, optional) – Rotate the coordinates before plotting. Keys: ‘center’ (2,) and ‘theta’ (radians)

Returns:

ax (Axes)