FactorSmooth#

class superglm.FactorSmooth( variable: str, *, group: str, basis: Literal['fs', 'sz'] = 'fs', kind: str = 'ps', k: int = 6, m: int = 2, levels=None, unseen: Literal['population', 'error'] = 'population', missing: Literal['error'] = 'error', lambda_policy: LambdaPolicy | dict[str, LambdaPolicy] | None = None, name: str | None = None, )#

Bases: object

A factor-by-P-spline interaction.

basis="fs" is fully penalized and retains independent level curves. basis="sz" represents centered sum-to-zero deviations; its specialized geometry is populated by the design-matrix builder.

levels= binds the grouping column’s level universe (spec 2026-08-11, §3.1). Under basis="fs" a declared level with no training rows keeps its own curve block and shrinks to zero through the penalty. basis="sz" rejects one: its sum-to-zero contrast is what identifies the deviations, and an empty level makes that constraint vacuous.

property parent_names: tuple[str, str]#: The numeric marginal and grouping columns read by this interaction.

adopt_dtype_categories(categories: list) → None#

Adopt a dtype-declared universe unless one is already declared.

Not reached by the main-loop hooks this release: FactorSmooth lives in the interaction specs, and dm_builder/binding_ops bind main-loop features only. Declare levels= explicitly; this hook exists so the wiring lands in one place when interaction binding is added.

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 group binding without mutating the spec.

build( x: NDArray, group: NDArray, specs: dict[str, Any], sample_weight: NDArray[floating] | None = None, ) → GroupInfo#: Build one exact compact factor-by-spline block.

build_discrete( x: NDArray, group: NDArray, specs: dict[str, Any], n_bins: int, sample_weight: NDArray[floating] | None = None, ) → GroupInfo#: Build compact support-space geometry with a fixed natural basis.

validate_population_prediction_values( x: NDArray, group: NDArray, ) → None#: Validate rows for a population prediction that skips this deviation.

validate_prediction_values( x: NDArray, group: NDArray, ) → tuple[NDArray[float64], NDArray[int64]]#: Validate new rows and return the numeric marginal and fitted-level codes.

marginal_basis( x: NDArray, ) → NDArray[float64]#: Evaluate the fitted natural marginal basis on requested numeric values.

score( x: NDArray, group: NDArray, beta: NDArray, ) → NDArray[float64]#: Score fitted level-specific deviations without expanding factor geometry.

transform( x: NDArray, group: NDArray, ) → NDArray[float64]#: Materialize a small prediction matrix for compatibility and references.

reconstruct( beta: NDArray, ) → dict[str, Any]#: Return fitted natural-basis coefficients by level.