cellina.make_perturbed_expression

cellina.make_perturbed_expression(adata, perturbations=None, groupby=None, layer_key='counts_cf', base=2.718281828459045, add_shift=False, renormalize=True, inplace=True)

Apply Node perturbations to counts and store the result as a layer.

Counts-space analog of make_neighbor_perturbation(). Cellina scales counts; the GCN aggregates over the spatial graph at inference time when this layer is supplied via cf_layer.

Parameters:

• adata (AnnData) – AnnData with raw counts in adata.X.

• perturbations (Optional[dict] (default: None)) – Dict[str, float] mapping gene → perturbation value (\(\delta_g\), global) when groupby=None. Dict[str, pd.Series] mapping cell-type label → gene-indexed perturbation value (\(\delta_g\)) Series when groupby is set. 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}\)). None copies adata.X unchanged.

• groupby (Optional[str] (default: None)) – Column in adata.obs for cell-type-specific perturbations.

• layer_key (str (default: 'counts_cf')) – Key to write in adata.layers.

• base (float (default: 2.718281828459045)) – Base for logFC → fold-change conversion. Default np.e.

• add_shift (bool (default: False)) – If True, add the logFC directly to counts instead of multiplying.

• renormalize (bool (default: True)) – If True, rescale rows after perturbation to preserve library sizes.

• inplace (bool (default: True)) – If True, write to adata.layers[layer_key] and return None. If False, return the perturbed matrix without modifying adata.

Raises:

ValueError – If groupby is set and perturbations contains unknown cell types.