gedi2py.tools.gradient

gedi2py.tools.gradient(adata, pathway_idx=None, *, key='gedi', copy=False)[source]

Compute gradient of pathway activity across cells.

Uses the pathway coefficient matrix A and cell loadings B to compute the gradient of pathway activity in the latent space.

Parameters:

  • adata (AnnData) – Annotated data matrix with GEDI results.

  • pathway_idx (int | None, default: None) – Index of the pathway to compute gradient for. If None, computes gradients for all pathways.

  • key (str, default: 'gedi') – Key in adata.uns where GEDI results are stored.

  • copy (bool, default: False) – If True, return the gradient array instead of storing in adata.

Return type:

AnnData | ndarray | None

Returns:

  • If ``copy=True`` –

    • If pathway_idx is specified: (n_cells, K) gradient array

    • If pathway_idx is None: (n_cells, K, n_pathways) gradient array

  • Otherwise, stores in ``adata.obsm[``’{key}_gradient’:py:class:`]` and returns ``None`.`

Notes

The gradient represents the direction in latent space that maximally increases pathway activity. This can be used for trajectory analysis or identifying cells transitioning along a pathway.

This requires that a pathway prior matrix C was provided during model training.

Examples

>>> import gedi2py as gd
>>> gd.tl.gedi(adata, batch_key="sample", C=pathway_matrix)
>>> gd.tl.gradient(adata, pathway_idx=0)
>>> adata.obsm["gedi_gradient"]  # direction to increase pathway 0