delnx.tl.nb_fit

delnx.tl.nb_fit(adata, condition_key=None, formula=None, design=None, design_column_names=None, reference=None, covariate_keys=None, size_factors='normed_sum', layer=None, overdispersion=True, batch_size=512, maxiter=100, verbose=True, overdispersion_shrinkage=True, do_cox_reid_adjustment=True)

Fit Gamma-Poisson (negative binomial) GLMs to count data.

This implements the glmGamPoi approach for fast and accurate differential expression analysis using GPU-accelerated Newton-Raphson with quasi-likelihood dispersion shrinkage.

Parameters:

• adata (AnnData) – AnnData object containing count data.

• condition_key (str | None (default: None)) – Column in adata.obs for condition labels. Creates a design matrix with intercept + condition indicators. Mutually exclusive with formula.

• formula (str | None (default: None)) – R-style formula for the design matrix (e.g., "~ treatment + batch" or "~ treatment * batch"). Parsed by patsy. Mutually exclusive with condition_key.

• design (ndarray | None (default: None)) – Custom design matrix. If provided, overrides condition_key, formula, reference, and covariate_keys. Shape should be (n_samples, n_coefficients).

• design_column_names (list[str] | None (default: None)) – Column names for a custom design matrix. Enables string-based contrast in nb_test(). If None with custom design, generic names coef_0, coef_1, … are used.

• reference (str | None (default: None)) – Reference level for the condition. This level becomes the intercept. If None, the alphabetically first level is used.

• covariate_keys (list[str] | None (default: None)) – Columns in adata.obs to include as covariates in the design matrix. Only used with condition_key (include covariates in formula directly).

• size_factors (str | ndarray | None (default: 'normed_sum')) –

  Size factors for normalization. Can be:

  • "normed_sum": Compute using normalized sum method

  • "poscounts": DESeq2-style positive counts method

  • np.ndarray: Pre-computed size factors

  • None: No size factor normalization (all 1s)

• layer (str | None (default: None)) – Layer in adata.layers containing counts. If None, uses adata.X.

• overdispersion (bool (default: True)) – Whether to estimate overdispersion. If False, uses Poisson (disp=0).

• batch_size (int (default: 512)) – Number of genes to process in each batch.

• maxiter (int (default: 100)) – Maximum iterations for Newton-Raphson.

• verbose (bool (default: True)) – Whether to show progress.

• overdispersion_shrinkage (bool (default: True)) – Whether to apply quasi-likelihood shrinkage to dispersions.

• do_cox_reid_adjustment (bool (default: True)) – Whether to apply Cox-Reid adjustment to dispersion MLE.

Return type:

NBFitResult

Returns:

NBFitResult Fitted model results containing coefficients, dispersions, and fitted values.

Examples

Basic usage with condition comparison:

>>> import delnx as dx
>>> fit = dx.tl.nb_fit(adata, condition_key="treatment")
>>> results = dx.tl.nb_test(adata, fit, contrast="treatment[T.drugA]")

With reference level and covariates:

>>> fit = dx.tl.nb_fit(adata, condition_key="treatment", reference="control",
...                    covariate_keys=["batch", "sex"])

Formula-based design with interactions:

>>> fit = dx.tl.nb_fit(adata, formula="~ treatment * batch")
>>> results = dx.tl.nb_test(adata, fit, contrast="treatment[T.drugA]:batch[T.batch2]")

Continuous covariate:

>>> fit = dx.tl.nb_fit(adata, formula="~ age + sex")
>>> results = dx.tl.nb_test(adata, fit, contrast="age")