multigedi.tools.differential

multigedi.tools.differential(adata, contrast, *, mode='full', include_offset=True, key='gedi', modality=None, 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[float]) – Contrast vector of length num_covariates (the number of original H covariates — i.e. H.shape[1] as passed to gd.tl.gedi). The contrast lives in the user-facing covariate space, not in the compressed L-space; H_rotation projects it into L-space internally. 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 original covariate effects (length num_covariates = H.shape[1]), not of the compressed L-space metagene-style covariates. The two spaces differ when H is rank-deficient (e.g. collinear categorical covariates), in which case L < num_covariates; the internal H_rotation matrix (shape (num_covariates, L) in Python, transposed vs the R convention of (L, num_covariates)) projects the user-supplied contrast into the L-space via H_rotation.T @ contrast.

For example, with covariates [treatment, sex], a contrast of [1, 0] computes the treatment effect, while [1, -1] computes the interaction.

Examples

>>> import multigedi 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)