estimate_theta

SuperGLM.estimate_theta(

X: object,

y: NDArray,

sample_weight: NDArray | None = None,

offset: NDArray | None = None,

*,

fit_mode: str = 'fit',

theta_bounds: tuple[float, float] = (1e-08, 100000000.0),

xatol: float = 0.01,

ci_alpha: float | None = None,

progress_callback: Callable[[...], None] | None = None,

)

Estimate NB2 theta via profile likelihood, refit, and return result.

The mean fit alternates with the root of the closed-form profile score in theta at that mean (Venables & Ripley 2002, ch. 7.4; Lawless 1987) until theta settles, and the published fit is refitted at the estimate.

Parameters:

Xpandas or eager Polars DataFrame

Feature matrix. Lazy frames must be collected before fitting.

yarray-like

Count response.

sample_weightarray-like, optional

Observation weights, read under the model’s weight_semantics.

offsetarray-like, optional

Offset added to the linear predictor.

fit_mode{“fit”, “reml”, “inherit”}

Fitting regime for the published final fit. The alternation itself uses ordinary fits.

theta_boundstuple of float

Search range for theta. An estimate on a bound warns with NBThetaBoundWarning and reports converged=False.

xatolfloat

The alternation stops once theta moves by at most this fraction of itself between successive mean fits.

ci_alphafloat, optional

Compute the 1 - ci_alpha likelihood-ratio interval at the published mean before returning. It is inverted from that mean’s own profile optimum; where theta_hat is not it (an alternation or joint refinement that stopped short, or theta_hat outside that interval), a caution is warned, recorded, and shown in the interval’s status.

progress_callbackcallable, optional

Called as progress_callback(phase, payload): "profiling" with {"profile_trace": [row]} for each alternation step, then "best_found" and "final_refit" with {"profile_estimate": ...}.