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 outer_strategy 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::inference::predict::CoefficientUncertaintyResult;

pub use crate::inference::predict::InferenceCovarianceMode;

pub use crate::inference::predict::MeanIntervalMethod;

pub use crate::inference::predict::PredictInput;

pub use crate::inference::predict::PredictPosteriorMeanResult;

pub use crate::inference::predict::PredictResult;

pub use crate::inference::predict::PredictUncertaintyOptions;

pub use crate::inference::predict::PredictUncertaintyResult;

pub use crate::inference::predict::PredictableModel;

pub use crate::inference::predict::coefficient_uncertainty;

pub use crate::inference::predict::coefficient_uncertaintywith_mode;

pub use crate::inference::predict::enrich_posterior_mean_bounds;

pub use crate::inference::predict::predict_gam;

pub use crate::inference::predict::predict_gam_posterior_mean;

pub use crate::inference::predict::predict_gam_posterior_meanwith_backend;

pub use crate::inference::predict::predict_gam_posterior_meanwith_fit;

pub use crate::inference::predict::predict_gamwith_uncertainty;

Structs

AdaptiveRegularizationOptions

ContinuousSmoothnessOrder

ExternalOptimOptions

ExternalOptimResult

FitArtifacts

Post-fit artifacts needed by downstream diagnostics/inference without re-running PIRLS.

FitGeometry

Working-set geometry at convergence needed by ALO and other post-fit diagnostics. Only populated when the inner solver provides the data.

FitInference

FitOptions

FittedBlock

Inference quantities for one coefficient block.

ModelSummary

ParametricTermSummary

SmoothTermSummary

UnifiedFitResult

Unified fit result for all model types (standard GAM, GAMLSS, survival).

UnifiedFitResultParts

Enums

BlockRole

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

ContinuousSmoothnessOrderStatus

EstimationError

A comprehensive error type for the model estimation process.

FittedLinkState

PenaltySpec

A penalty specification for the public estimate API.

Functions

compute_continuous_smoothness_order

ensure_finite_scalar

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

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_gamwith_heuristic_lambdas

Canonical engine entrypoint for external designs on supported GLM-style families. Likelihood dispatch is determined by family together with external-link options in opts; survival families use survival-specific training APIs.

optimize_external_design

Optimize smoothing parameters for an external design using the same REML/LAML machinery. Contract: likelihood dispatch is determined by opts.family.

optimize_external_designwith_heuristic_lambdas

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

saved_latent_cloglog_state_from_fit

saved_mixture_state_from_fit

saved_sas_state_from_fit

validate_all_finite

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

validate_dense_hessian_export

Validate the structural integrity of an exported penalized Hessian.

validate_explicit_dense_hessian_for_whitening

Validate that a saved penalized Hessian is an explicit dense precision matrix suitable for HMC/NUTS whitening.