cellina.make_neighbor_perturbation

cellina.make_neighbor_perturbation#

cellina.make_neighbor_perturbation(adata, perturbations, connectivity_key='spatial_connectivities', groupby=None, neighbor_genes=None, obsm_key_out='spatial_x_cf', layer_key='counts_cf', base=2.718281828459045, add_shift=False, renormalize=True)#

Apply Node perturbations to neighbour expression and re-aggregate.

Perturbed expression is written to adata.layers[layer_key] and the resulting spatial features to adata.obsm[obsm_key_out]. The original count matrix adata.X is not modified.

Parameters:

  • adata (AnnData) – AnnData object.

  • connectivity_key (str (default: 'spatial_connectivities')) – Key in adata.obsp for the spatial connectivity matrix.

  • perturbations (dict) – When groupby=None: Dict[str, float] mapping gene → perturbation value (\(\delta_g\)) applied globally to all cells. When groupby is set: Dict[str, pd.Series] mapping cell-type label → gene-indexed perturbation value (\(\delta_g\)) Series. Values are interpreted as additive shifts when add_shift=True (\(T_g(x) = x + \delta_g\)) or as logFCs when add_shift=False (\(T_g(x) = x \cdot e^{\delta_g}\)).

  • groupby (Optional[str] (default: None)) – Column in adata.obs used to apply cell-type-specific perturbations. When None, perturbations are applied globally to all cells.

  • neighbor_genes (Optional[List[str]] (default: None)) – Subset of genes to aggregate. None means all genes.

  • obsm_key_out (str (default: 'spatial_x_cf')) – Key in adata.obsm for the counterfactual spatial features.

  • layer_key (str (default: 'counts_cf')) – Key in adata.layers where the perturbed counts are stored.

Raises:

ValueError – If perturbations contains cell-type keys that are not present in adata.obs[groupby]. Partial dictionaries (covering only a subset of cell types) are allowed — unspecified cell types are left unmodified.

Return type:

None