gedi2py.tools.differential

gedi2py.tools.differential(adata, contrast, *, mode='full', include_offset=True, key='gedi', key_added=None, copy=False)[source]

Compute differential expression effects from GEDI model.

Uses the sample-level covariate matrix H and learned regression coefficients (Rk, Ro) to compute differential expression effects for a given contrast.

Parameters:

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

  • contrast (ndarray | list) – Contrast vector of length L (number of covariates). Specifies the linear combination of covariate effects to compute.

  • mode (Literal['full', 'offset', 'metagene'], default: 'full') – Type of differential effect to compute: - "full": Full cell-specific effect (diffQ, J × N matrix) - "offset": Global gene offset effect (diffO, J vector) - "metagene": Effect on metagene loadings

  • include_offset (bool, default: True) – If True and mode is "full", add the offset effect (diffO) to the cell-specific effect.

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

  • key_added (str | None, default: None) – Key to store results. Defaults depend on mode: - "full": adata.layers['{key}_diff'] - "offset": adata.var['{key}_diff_offset']

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

Return type:

AnnData | ndarray | None

Returns:

  • Depending on mode and copy

  • - ``mode=”full”``, ``copy=True`` ((n_cells, n_genes) array)

  • - ``mode=”offset”``, ``copy=True`` ((n_genes,) array)

  • - Otherwise (None (stores in adata))

Notes

Differential effects require that a covariate matrix H was provided during model training via gd.tl.gedi(..., H=covariate_matrix).

The contrast vector defines a linear combination of covariate effects. For example, with covariates [treatment, sex], a contrast of [1, 0] computes the treatment effect, while [1, -1] computes the interaction.

Examples

>>> import gedi2py as gd
>>> import numpy as np
>>> # Assuming H is (n_samples, 2) with [treatment, control]
>>> gd.tl.gedi(adata, batch_key="sample", H=H_matrix)
>>> contrast = np.array([1, -1])  # treatment - control
>>> gd.tl.differential(adata, contrast)
>>> adata.layers["gedi_diff"]  # (n_cells, n_genes)