scHopfield.tools.energy_embedding

scHopfield.tools.energy_embedding(adata: AnnData, basis: str = 'umap', resolution: int = 50, cluster_key: str = 'cell_type', degradation_key: str = 'gamma', copy: bool = False) → AnnData | None[source]

Compute energy landscape on 2D embedding space.

For each cluster, creates a grid in the embedding space and computes the Hopfield energy at each grid point. The grid is transformed to the original high-dimensional gene expression space using the inverse UMAP transform, and energies are computed using the cluster-specific interaction matrices.

Stores grid coordinates and energy values in adata.uns[‘scHopfield’] with keys: ‘grid_X_{cluster}’, ‘grid_Y_{cluster}’, ‘grid_energy_{cluster}’, ‘grid_energy_interaction_{cluster}’, ‘grid_energy_degradation_{cluster}’, ‘grid_energy_bias_{cluster}’.

Parameters:

  • adata (AnnData) – Annotated data object with computed UMAP embedding

  • basis (str, optional (default: 'umap')) – Name of the embedding basis to use (from obsm[‘X_{basis}’])

  • resolution (int, optional (default: 50)) – Number of grid points per dimension (creates resolution x resolution grid)

  • cluster_key (str, optional (default: 'cell_type')) – Key in adata.obs for cluster labels

  • degradation_key (str, optional (default: 'gamma')) – Key in adata.var for degradation rates (fallback if cluster-specific not found)

  • copy (bool, optional (default: False)) – Whether to return a copy or modify in place

Returns:

Returns AnnData if copy=True, otherwise modifies in place and returns None

Return type:

Optional[AnnData]