API#

Trackcell entry point#

pyglmGamPoi.fit_offset_model(umi, regressor_data, gene_index, *, method='glmGamPoi_offset', allow_inf_theta=True, apply_shrinkage=True)[source]#

Fit glmGamPoi offset models (sctransform fit_glmGamPoi_offset).

Parameters:

  • umi (ndarray | spmatrix) – UMI count matrix, genes × cells (CSR sparse or dense).

  • regressor_data (DataFrame) – Cell-level covariates, one row per cell. Must contain log_umi in log10 scale, indexed by cell barcodes in the same order as umi columns.

  • gene_index (Index) – Gene identifiers, length umi.shape[0].

  • method (str) – Must be "glmGamPoi_offset".

  • allow_inf_theta (bool) – When False, cap theta at mean(mu)/1e-4 (Seurat default).

  • apply_shrinkage (bool) – When True (default), apply loc_median_fit dispersion trend and refit intercepts (R glm_gp(overdispersion_shrinkage=TRUE)).

Return type:

DataFrame with columns theta, Intercept, log_umi.

pyglmGamPoi.is_available()[source]#

Return True when the native C++ extension is importable.

Return type:

bool

Low-level fitting#

pyglmGamPoi.fit_glmGamPoi_offset(umi, log10_umi, *, gene_names=None, allow_inf_theta=True, apply_shrinkage=True)[source]#

Fit glmGamPoi offset models (low-level API).

For trackcell integration, prefer pyglmGamPoi.fit_offset_model() which accepts regressor_data in the same format as trackcell cell_attr.

Parameters:

  • umi (ndarray | spmatrix) – UMI count matrix, genes × cells.

  • log10_umi (ndarray) – Per-cell log10 UMI values (length = n_cells).

  • gene_names (list[str] | ndarray | None) – Optional gene index labels.

  • allow_inf_theta (bool) – When False, cap theta at mean(mu)/1e-4.

  • apply_shrinkage (bool) – When True (default, R glm_gp default), apply cross-gene dispersion trend via loc_median_fit and refit intercepts.

Return type:

DataFrame with columns theta, Intercept, log_umi.

Shrinkage utilities#

pyglmGamPoi.loc_median_fit(x, y, *, fraction=0.1, npoints=None, weighted=True, ignore_zeros=False)[source]#

Local median fit (glmGamPoi::loc_median_fit).

Used to estimate dispersion trend across gene means.

Parameters:

  • x (ndarray)

  • y (ndarray)

  • fraction (float)

  • npoints (int | None)

  • weighted (bool)

  • ignore_zeros (bool)

Return type:

ndarray

pyglmGamPoi.overdispersion_shrinkage(disp_est, gene_means, df, *, disp_trend=True, ql_disp_trend=None, npoints=None)[source]#

Shrink overdispersion estimates (glmGamPoi::overdispersion_shrinkage).

glm_gp uses dispersion_trend (local median of raw MLE) for the second beta fit pass; ql_disp_shrunken is returned for downstream DE workflows.

Parameters:

  • disp_est (ndarray)

  • gene_means (ndarray)

  • df (float | ndarray)

  • disp_trend (bool | ndarray | None)

  • ql_disp_trend (bool | None)

  • npoints (int | None)

Return type:

OverdispersionShrinkageResult

Validation helpers#

pyglmGamPoi.normalize_model_pars_columns(model_pars)[source]#

Normalize coefficient column names to trackcell conventions.

trackcell applies the same rename in _sctransform_v2._normalize_model_pars_columns.

Parameters:

model_pars (DataFrame)

Return type:

DataFrame