delnx.tl.build_design

delnx.tl.build_design(obs, formula=None, condition_key=None, reference=None, covariate_keys=None)[source]

Build a design matrix from a formula or condition_key.

Parameters:

  • obs (DataFrame) – Observation metadata (typically adata.obs).

  • formula (str | None (default: None)) – R-style formula (e.g., "~ treatment + batch"). Mutually exclusive with condition_key.

  • condition_key (str | None (default: None)) – Column in obs for condition labels. Builds a formula internally. Mutually exclusive with formula.

  • reference (str | None (default: None)) – Reference level for the condition. Used to reorder categorical levels so the reference becomes the intercept. Only used with condition_key or when formula contains a simple term matching a categorical column.

  • covariate_keys (list[str] | None (default: None)) – Additional columns to include as covariates. Only used with condition_key (ignored when formula is provided, since covariates should be part of the formula).

Return type:

tuple[ndarray, list[str]]

Returns:

tuple[np.ndarray, list[str]] Design matrix of shape (n_obs, n_coef) and list of column names.

Raises:

ValueError – If both formula and condition_key are specified, or neither is.