Module estimate 

Model Estimation via Penalized Likelihood and REML

This module orchestrates the core model fitting procedure for Generalized Additive Models (GAMs). It determines optimal smoothing parameters directly from the data, moving beyond simple hyperparameter-driven models. This is achieved through a nested optimization scheme, a standard approach for this class of models:

1. Outer Loop (planner-selected optimizer): Optimizes the log-smoothing parameters (rho) by maximizing a marginal likelihood criterion. For non-Gaussian models (e.g., Logit), this is the Laplace Approximate Marginal Likelihood (LAML). The concrete solver is chosen centrally by rho_optimizer from the derivative capability of the model path: ARC with analytic Hessian when available, BFGS for gradient-only problems, and EFS / hybrid EFS when the hyperparameter geometry admits those fixed-point updates.

2. Inner Loop (P-IRLS): For each set of trial smoothing parameters from the outer loop, this routine finds the corresponding model coefficients (beta) by running a Penalized Iteratively Reweighted Least Squares (P-IRLS) algorithm to convergence.

This two-tiered structure allows the model to learn the appropriate complexity for each smooth term directly from the data.

Re-exports

pub use crate::model_types::AdaptiveRegularizationOptions;

pub use crate::model_types::FitArtifacts;

pub use crate::model_types::FitGeometry;

pub use crate::model_types::FitInference;

pub use crate::model_types::FitOptions;

pub use crate::model_types::FittedBlock;

pub use crate::model_types::FittedLinkState;

pub use crate::model_types::UnifiedFitResult;

pub use crate::model_types::UnifiedFitResultParts;

pub use crate::model_types::saved_latent_cloglog_state_from_fit;

pub use crate::model_types::saved_mixture_state_from_fit;

pub use crate::model_types::saved_sas_state_from_fit;

pub use crate::model_types::validate_dense_hessian_export;

pub use crate::model_types::validate_explicit_dense_hessian_for_whitening;

Modules

reml

Structs

ContinuousSmoothnessOrder

ExternalJointHyperEvaluator

ExternalOptimOptions

ExternalOptimResult

ModelSummary

ParametricTermSummary

SmoothTermSummary

Enums

BlockRole

Role of a coefficient block within a multi-parameter model.

CoefficientPriorMean

Programmatic prior mean for a coefficient penalty block.

ContinuousSmoothnessOrderStatus

Dispersion

Dispersion contract used by inferential covariance and reference distributions.

EstimationError

A comprehensive error type for the model estimation process.

PenaltyCoordinate

A rho-coordinate always contributes

PenaltySpec

A penalty specification for the public estimate API.

Constants

RHO_BOUND

Functions

compute_continuous_smoothness_order

dispersion_from_likelihood

ensure_finite_scalar

Public wrapper returning String errors for use outside the estimation module.

evaluate_external_ift_residual_at_perturbed_rho

Evaluate IFT and flat warm-start inner residuals at rho + delta_rho.

evaluate_externalcost_andridge

Evaluate the external cost and report the stabilization ridge used. This is a diagnostic helper for tests that need to detect ridge jitter.

evaluate_externalgradient

Evaluate the analytic gradient of the external REML objective.

fit_gam

External-design GAM entrypoint for GLM-style families supported by optimize_external_design. Survival families such as RoystonParmar use survival-specific training APIs.

fit_gam_with_penalty_specs

fit_gamwith_heuristic_lambdas

optimize_external_design

Optimize smoothing parameters for an external design using the same REML/LAML machinery.

optimize_external_designwith_heuristic_lambdas

Same as optimize_external_design, but allows heuristic λ warm-start seeds for the outer smoothing search.

validate_all_finite

Public wrapper returning String errors for use outside the estimation module.