RandomEffect#

class superglm.RandomEffect( *, levels=None, unseen: Literal['population', 'error'] = 'population', missing: Literal['error'] = 'error', lambda_policy: LambdaPolicy | None = None, )#

Bases: object

All-level categorical effect with a REML-estimated variance component.

levels= binds the level universe (spec 2026-08-11, §3.1) from an explicit sequence, a data column, or a categorical dtype. A declared level with no training rows is not pinned the way an unpenalized dummy is: it keeps its own coefficient and shrinks to the population value through the variance component, exactly as a thinly observed level does.

Notes

When a REML-estimated RandomEffect is fitted beside an unpenalised Categorical whose levels include some with exposure but no positive response (under a log link with a zero-mass family such as Tweedie or Poisson), those levels separate – their coefficients have no finite MLE – and the marginal likelihood becomes nearly flat in this term’s variance. The fitted variance component is then poorly determined, and for the estimated-scale Tweedie criterion it is additionally biased upward relative to exact-likelihood REML. fit_reml warns on that configuration; treat the published tau_squared with care there.

adopt_dtype_categories(categories: list) → None#: Adopt a dtype-declared universe unless one is already declared.

apply_level_binding(binding) → None#

Adopt a full-frame universe when nothing more specific declared one.

Only the levels are read: a penalized term has no base level, so its bindings carry base=None and there is nothing to pin.

resolve_binding( values: NDArray, sample_weight=None, )#: Compute this spec’s full-frame binding without mutating the spec.

build( x: NDArray, sample_weight: NDArray[floating] | None = None, ) → GroupInfo#: Factorize all fitted levels without dropping a reference category.

validate_prediction_values(x: NDArray) → None#: Reject missing values without applying the unseen-level policy.

score( x: NDArray, beta: NDArray[floating], ) → NDArray[floating]#: Select fitted level effects without materializing one-hot columns.

transform( x: NDArray, ) → NDArray[floating]#: Materialize a small all-level one-hot reference matrix.

reconstruct( beta: NDArray[floating], ) → dict[str, Any]#: Return one fitted effect for every represented level.