pyglmGamPoi
===========

**A native Python replacement for R glmGamPoi in SCTransform v2**

pyglmGamPoi reimplements ``sctransform::fit_glmGamPoi_offset`` — the per-gene
negative-binomial offset model at the heart of Seurat SCTransform v2 — in
pure Python/C++, with **no R runtime required**.

It is designed as a drop-in backend for
`trackcell <https://github.com/seqyuan/trackcell>`_ single-cell pipelines,
replacing ``Rscript`` subprocess calls to glmGamPoi while preserving numerical
parity with R.

Why pyglmGamPoi?
----------------

.. list-table::
   :header-rows: 1
   :widths: 30 35 35

   * -
     - R glmGamPoi (before)
     - pyglmGamPoi (after)
   * - Runtime
     - ``BiocManager::install("glmGamPoi")``
     - ``pip install pyglmGamPoi``
   * - Integration
     - ``Rscript`` subprocess per fit
     - Native Python call
   * - ``theta`` parity (real data)
     - reference
     - med |Δ| ≈ 10\ :sup:`-7`
   * - Inf ``theta`` (Poisson genes)
     - reference
     - exact match
   * - Speed (2000×2000 step1, 8 threads)
     - ~15 s
     - **~2.2 s** (~7× vs R)
   * - Memory (10x CSR)
     - dense ``toarray()``
     - native CSR (no densify)

Quick start
-----------

.. code-block:: python

   import numpy as np
   from pyglmGamPoi import fit_glmGamPoi_offset

   umi = np.random.poisson(3, size=(100, 50)).astype(float)
   log10_umi = np.log10(umi.sum(axis=0) + 1e-9)
   model_pars = fit_glmGamPoi_offset(umi, log10_umi)
   # columns: theta, Intercept, log_umi

Architecture
------------

.. code-block:: text

   pyglmGamPoi/offset.py          Python API (AnnData-friendly)
           │
   pyglmGamPoi/_core.so           pybind11 binding
           │
   src/glm_gp_offset.cpp          per-gene glm_gp loop
   src/offset_fit.cpp             Newton-Raphson + Brent fallback
   src/overdispersion.cpp         Cox-Reid overdispersion MLE

Algorithms follow `glmGamPoi <https://github.com/const-ae/glmGamPoi>`_ but are
**rewritten** without R/Rcpp dependencies.

Links
-----

* `GitHub <https://github.com/seqyuan/pyglmGamPoi>`_
* `Read the Docs <https://pyglmgampoi.readthedocs.io/>`_ (latest | `stable <https://pyglmgampoi.readthedocs.io/en/stable/>`_)
* `Changelog <https://pyglmgampoi.readthedocs.io/en/latest/changelog.html>`_
* `trackcell <https://github.com/seqyuan/trackcell>`_

.. toctree::
   :maxdepth: 2
   :caption: Contents

   evaluation
   installation
   api
   integration
   benchmark
   changelog

Indices
=======

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`