fit_reml

SuperLSS.fit_reml(

X: object | EagerFrame,

y: NDArray,

sample_weight: NDArray | None = None,

offsets: Mapping[str, NDArray] | None = None,

*,

method: str = 'efs',

max_reml_iter: int = 100,

reml_tol: float = 1e-06,

max_log_step: float = 5.0,

max_lambda: float = 10000000000.0,

initial_lambda: float | None = None,

max_inner_iter: int = 100,

inner_tol: float = 1e-07,

lambdas: Mapping[str, float] | None = None,

retain_rows: bool = True,

acceleration: Literal['none', 'multisecant'] = 'none',

acceleration_history: int = 5,

acceleration_max_amplification: float = 8.0,

practical_reml: bool = True,

retain_history_rows: bool = False,

practical_reml_parameter_tol: float = 0.001,

reml_plateau_tol: float = 1e-07,

outer: Literal['efs', 'efs+newton'] = 'efs',

phase_recorder: FitPhaseRecorder | None = None,

) → SuperLSS

Fit coefficients and estimate smoothing parameters jointly.

X supplies the declared columns and y supplies the response in the same row order. sample_weight follows the model’s weight_semantics. offsets maps family parameter names to known additions on the link scale. This method updates the model and returns it.

outer selects the smoothing optimiser. The default "efs" runs generalised Fellner-Schall updates. "efs+newton" adds Newton refinement using the LAML gradient and Hessian in log lambda.

practical_reml stops the Fellner–Schall loop after sustained negligible objective and fitted-parameter movement. Set it to False when strict Fellner–Schall stationarity is required.

Historical coefficient fits retain compact evidence by default, with row arrays kept only for the terminal fit and recent plateau checks. Set retain_history_rows=True to keep every fit’s eta and theta for debugging. retain_rows separately controls final row diagnostics and keeps its existing default.

By default, choose a data-scaled starting penalty for each term. initial_lambda=None adjusts the starting strength of smoothing to the term’s units and the information in the data. Terms with several penalties get a separate start for each. These starts are clipped to the smoothing bounds. Families without expected information and terms with unresolved numerical rank use 0.1, also clipped to those bounds.

A numeric initial_lambda supplies a common start. Entries in lambdas override it, and fixed penalty policies take precedence over both. The smoothing result retains the numeric starts for replay. Stops can depend on the starting values, so vary them when comparing fits.