nstat.fit_poisson_glm

nstat.fit_poisson_glm(x, y, *, offset=None, include_intercept=True, l2=1e-06, max_iter=120, tol=1e-08, eta_bound=20.0)[source]

Fit a Poisson GLM (log link) by Newton-Raphson with an L2 ridge penalty.

Maximises the L2-penalised Poisson log-likelihood sum(y * eta - exp(eta)) with eta = X @ beta + offset. The linear predictor is clipped to [-eta_bound, eta_bound] before exponentiation for numerical stability.

Parameters:

  • x (array_like, shape (n_samples,) or (n_samples, n_features)) – Design matrix, or a single covariate vector (treated as one column).

  • y (array_like, shape (n_samples,)) – Observed non-negative counts (for example spikes per bin).

  • offset (array_like, shape (n_samples,), optional) – Per-sample additive offset to the linear predictor, for example log(bin_width) to model a rate. Defaults to zero.

  • include_intercept (bool, default True) – Prepend a constant column to x. The intercept is not penalised.

  • l2 (float, default 1e-6) – Ridge penalty applied to all non-intercept coefficients.

  • max_iter (int, default 120) – Maximum number of Newton iterations.

  • tol (float, default 1e-8) – Convergence tolerance on the L2 norm of the coefficient update.

  • eta_bound (float, default 20.0) – Clip bound for the linear predictor during the Newton iterations (a Python-only stability guard with no MATLAB counterpart at this default). Analysis.GLMFit’s poisson ('GLM') path passes MATLAB’s own glmfit log-link bound here instead (-log(realmin**0.25), from stattestlink.m); every other caller keeps the default. This matches the BOUND glmfit’s own iterations use, not its full numerical path: MATLAB’s glmfit initializes from startingVals(y) (a function of the data), while this Newton-IRLS starts from beta = 0 unconditionally, so on a design whose MLE is far from 0 the two can still walk different paths (and, on a sufficiently extreme design, Python can diverge where MATLAB’s better-initialized walk converges) even with the bound matched.

Returns:

Frozen dataclass with intercept, coefficients, n_iter, converged and log_likelihood (the unpenalised Poisson log-likelihood, up to the log(y!) constant) fields.

Return type:

PoissonGLMResult

Raises:

ValueError – If x and y have different numbers of rows, or offset has a different length than y.