mechanochat.plotting.signal_direction_plot3#

mechanochat.plotting.signal_direction_plot3(sem: SEM2 | SEM3 | 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, 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, plotter: Plotter | None = None) → Axes | Plotter[source]#

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

For each sender-receiver cell pair with signal strength above th, draws an arrow from the sender centroid toward the receiver centroid. Arrow width is stratified by signal strength percentiles to convey relative signal intensity.

Parameters:

  • sem (SEM2 or SEM3, 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.

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

  • 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 for 2D plots. Creates new figure if None.

  • plotter (pyvista.Plotter, optional) – PyVista plotter for 3D visualization. Creates new plotter if None.

Returns:

  • ax (Axes) – For 2D data (dim == 2).

  • plotter (pyvista.Plotter) – For 3D data (dim == 3).