lgspline.fit: Low-Level Fitting for Lagrangian Smoothing Splines

In lgspline: Lagrangian Multiplier Smoothing Splines for Smooth Function Estimation

Low-Level Fitting for Lagrangian Smoothing Splines

Description

The core function for fitting Lagrangian smoothing splines with less user-friendliness. Called internally by lgspline after formula parsing, factor encoding, and correlation-structure setup.

Usage

lgspline.fit(
  predictors,
  y = NULL,
  standardize_response = TRUE,
  standardize_predictors_for_knots = TRUE,
  standardize_expansions_for_fitting = TRUE,
  family = gaussian(),
  glm_weight_function = default_glm_weight_function,
  schur_correction_function = function(X, y, B, dispersion, order_list, K, family,
    observation_weights, ...) {
     lapply(1:(K + 1), function(k) 0)
 },
  need_dispersion_for_estimation = FALSE,
  dispersion_function = function(mu, y, order_indices, family, observation_weights,
    VhalfInv, ...) {
     if (!is.null(VhalfInv)) {
         VhalfInv <-
    VhalfInv[order_indices, order_indices]
         c(mean((tcrossprod(VhalfInv, t(y -
    mu)))^2/family$variance(mu)))
     }
     else {
         c(mean((y -
    mu)^2/family$variance(mu)))
     }
 },
  K = NULL,
  custom_knots = NULL,
  cluster_on_indicators = FALSE,
  make_partition_list = NULL,
  previously_tuned_penalties = NULL,
  smoothing_spline_penalty = NULL,
  opt = TRUE,
  use_custom_bfgs = TRUE,
  delta = NULL,
  tol = 10 * sqrt(.Machine$double.eps),
  tuning_criterion = "loo",
  gcv_gamma = 1.4,
  initial_wiggle = c(2e-12, 2e-07, 2e-04, 0.2),
  initial_flat = c(0.5, 5),
  wiggle_penalty = 2e-07,
  flat_ridge_penalty = 0.5,
  unique_penalty_per_partition = TRUE,
  unique_penalty_per_predictor = TRUE,
  meta_penalty = 1e-08,
  predictor_penalties = NULL,
  partition_penalties = NULL,
  include_quadratic_terms = TRUE,
  include_cubic_terms = TRUE,
  include_quartic_terms = FALSE,
  include_2way_interactions = TRUE,
  include_3way_interactions = TRUE,
  include_quadratic_interactions = FALSE,
  offset = c(),
  just_linear_with_interactions = NULL,
  just_linear_without_interactions = NULL,
  exclude_interactions_for = NULL,
  exclude_these_expansions = NULL,
  custom_basis_fxn = NULL,
  include_constrain_fitted = TRUE,
  include_constrain_first_deriv = TRUE,
  include_constrain_second_deriv = TRUE,
  include_constrain_interactions = TRUE,
  add_first_and_second_derivative_constraints = NULL,
  qr_pivot_smoothing_constraints = TRUE,
  cl = NULL,
  chunk_size = NULL,
  parallel_eigen = TRUE,
  parallel_trace = FALSE,
  parallel_aga = FALSE,
  parallel_matmult = FALSE,
  parallel_qr = FALSE,
  parallel_bfgs = FALSE,
  parallel_grideval = TRUE,
  parallel_qr_qp = FALSE,
  parallel_unconstrained = FALSE,
  parallel_find_neighbors = TRUE,
  parallel_penalty = FALSE,
  parallel_make_constraint = TRUE,
  unconstrained_fit_fxn = unconstrained_fit_default,
  keep_weighted_Lambda = FALSE,
  iterate_tune = TRUE,
  iterate_final_fit = TRUE,
  blockfit = TRUE,
  qp_score_function = function(X, y, mu, order_list, dispersion, VhalfInv,
    observation_weights, ...) {
     default_qp_score_function(X, y, mu, order_list,
    dispersion, VhalfInv, observation_weights, family, ...)
 },
  qp_observations = NULL,
  qp_Amat = NULL,
  qp_bvec = NULL,
  qp_meq = 0,
  qp_positive_derivative = FALSE,
  qp_negative_derivative = FALSE,
  qp_positive_2ndderivative = FALSE,
  qp_negative_2ndderivative = FALSE,
  qp_monotonic_increase = FALSE,
  qp_monotonic_decrease = FALSE,
  qp_range_upper = NULL,
  qp_range_lower = NULL,
  qr_pivot_inequality_constraints = FALSE,
  qp_Amat_fxn = NULL,
  qp_bvec_fxn = NULL,
  qp_meq_fxn = NULL,
  constraint_values = cbind(),
  constraint_vectors = cbind(),
  return_G = TRUE,
  return_Ghalf = TRUE,
  return_U = TRUE,
  estimate_dispersion = TRUE,
  unbias_dispersion = TRUE,
  return_varcovmat = TRUE,
  exact_varcovmat = FALSE,
  return_lagrange_multipliers = FALSE,
  custom_penalty_mat = NULL,
  cluster_args = c(custom_centers = NA, nstart = 10),
  dummy_dividor = 1.2345672152894e-22,
  dummy_adder = 2.234567210529e-18,
  verbose = FALSE,
  verbose_tune = FALSE,
  dummy_fit = FALSE,
  auto_encode_factors = TRUE,
  observation_weights = NULL,
  do_not_cluster_on_these = c(),
  neighbor_tolerance = 1 + 1e-16,
  no_intercept = FALSE,
  VhalfInv = NULL,
  Vhalf = NULL,
  include_warnings = TRUE,
  og_cols = NULL,
  factor_groups = NULL,
  spline_groups = NULL,
  additive_spline_interaction_pairs = NULL,
  ...
)

Arguments

predictors	Numeric matrix or data frame of predictor variables on the low-level input scale expected by lgspline.fit. Unlike lgspline, this interface does not parse formulas or a separate data argument.
y	Default: NULL. Numeric response variable vector.
standardize_response	Default: TRUE. Logical indicator controlling whether the response variable should be centered and scaled before model fitting. Only offered for identity link functions.
standardize_predictors_for_knots	Default: TRUE. Logical flag controlling whether predictors are internally standardized for partitioning / knot placement. The exact transformation is handled inside make_partitions and depends on the effective clustering dimension.
standardize_expansions_for_fitting	Default: TRUE. Logical switch to standardize polynomial basis expansions during model fitting. Design matrices, variance-covariance matrices, and coefficients are backtransformed after fitting. \mathbf{U} and \mathbf{G} remain on the transformed scale; B_raw corresponds to coefficients on the expansion-standardized scale.
family	Default: gaussian(). GLM family specifying the error distribution and link function. Minimally requires: family name, link name, linkfun, linkinv, variance.
glm_weight_function	Default: GLM working weight family$mu.eta(eta)^2 / family$variance(mu), optionally multiplied by observation_weights.
schur_correction_function	Default: function returning list of zeros. Computes Schur complements \mathbf{S} added to \mathbf{G}: \mathbf{G}^{*} = (\mathbf{G}^{-1} + \mathbf{S})^{-1}.
need_dispersion_for_estimation	Default: FALSE. Logical indicator specifying whether a dispersion parameter is required for coefficient estimation (e.g. Weibull AFT).
dispersion_function	Default: function returning mean squared residuals. Custom function for estimating the exponential dispersion parameter.
K	Default: NULL. Integer specifying the number of knot locations. Intuitively, total partitions minus 1.
custom_knots	Default: NULL. Optional matrix providing user-specified knot locations in 1-D.
cluster_on_indicators	Default: FALSE. Logical flag for whether indicator variables should be used for clustering knot locations.
make_partition_list	Default: NULL. Optional list allowing direct specification of custom partition assignments. The make_partition_list returned by one model can be supplied here to reuse knot locations.
previously_tuned_penalties	Default: NULL. Optional list of pre-computed penalty components from a previous model fit.
smoothing_spline_penalty	Default: NULL. Optional custom smoothing spline penalty matrix.
opt	Default: TRUE. Logical switch controlling automatic penalty optimization.
use_custom_bfgs	Default: TRUE. Selects between a native damped-BFGS implementation with closed-form gradients or base R's BFGS with finite-difference gradients. The native path is usually faster, while the finite-difference fallback can be preferable when tuning under exact LOO and the leverage derivative is numerically noisy.
delta	Default: NULL. Numeric pseudocount for stabilizing optimization in non-identity link function scenarios.
tol	Default: 10*sqrt(.Machine$double.eps). Numeric convergence tolerance.
tuning_criterion	Default: "loo". Character scalar selecting the tuning criterion. Use "loo" for exact leave-one-out on the transformed tuning problem, or "gcv" for the generalized cross-validation criterion. The LOO path computes the needed hat-matrix diagonal exactly from blockwise constrained-\mathbf{G} quantities, without explicitly forming the full projection matrix or full hat matrix. In empirical diagnostics, the observation-wise derivative of the LOO leverage term can be numerically delicate even when the overall tuning criterion and fitted penalties remain well behaved; users who prefer a more conservative optimization path can set use_custom_bfgs = FALSE. Penalty gradients reuse the partition penalty-matrix derivatives \partial\ell/\partial\boldsymbol{\Lambda}_k, so additional tuned penalty directions require only trace products. For very large samples, generalized cross-validation is often the more practical choice; as a rough guideline, "gcv" is recommended once the sample size is above about 250,000.
gcv_gamma	Default: 1.4. Numeric scalar, at least 1, used only when tuning_criterion = "gcv". Multiplies the effective degrees of freedom in the GCV denominator during automatic penalty tuning. It is accepted but ignored when tuning_criterion = "loo".
initial_wiggle	Default: c(2e-12, 2e-7, 2e-4, 0.2). Numeric vector of initial grid points for wiggle penalty optimization, on the raw (non-negative) scale.
initial_flat	Default: c(0.5, 5). Numeric vector of initial grid points for ridge penalty optimization, on the raw scale (ratio of ridge to wiggle).
wiggle_penalty	Default: 2e-7. Numeric penalty on the integrated squared second derivative, governing function smoothness.
flat_ridge_penalty	Default: 0.5. Numeric flat ridge penalty for intercepts and linear terms only. Multiplied by wiggle_penalty to obtain total ridge penalty.
unique_penalty_per_partition	Default: TRUE. Logical flag allowing penalty magnitude to differ across partitions.
unique_penalty_per_predictor	Default: TRUE. Logical flag allowing penalty magnitude to differ between predictors.
meta_penalty	Default: 1e-8. Numeric regularization coefficient for predictor- and partition-specific penalties during tuning. On the raw scale, the implemented meta-penalty shrinks these penalty multipliers toward 1; the wiggle penalty receives only a tiny stabilizing penalty by default.
predictor_penalties	Default: NULL. Optional vector of custom penalties per predictor, on the raw (positive) scale.
partition_penalties	Default: NULL. Optional vector of custom penalties per partition, on the raw (positive) scale.
include_quadratic_terms	Default: TRUE. Logical switch to include squared predictor terms.
include_cubic_terms	Default: TRUE. Logical switch to include cubic predictor terms.
include_quartic_terms	Default: FALSE. Logical switch to include quartic predictor terms at this low-level interface.
include_2way_interactions	Default: TRUE. Logical switch for linear two-way interactions.
include_3way_interactions	Default: TRUE. Logical switch for three-way interactions.
include_quadratic_interactions	Default: FALSE. Logical switch for linear-quadratic interaction terms.
offset	Default: Empty vector. Column indices/names to include as offsets. Coefficients for offset terms are automatically constrained to 1.
just_linear_with_interactions	Default: NULL. Integer or character vector specifying predictors to retain as linear terms while still allowing interactions.
just_linear_without_interactions	Default: NULL. Integer or character vector specifying predictors to retain only as linear terms without interactions. Eligible for blockfitting.
exclude_interactions_for	Default: NULL. Integer or character vector of predictors to exclude from all interaction terms.
exclude_these_expansions	Default: NULL. Character vector of basis expansions to exclude. Named columns of data, or in the form "_1_", "_2_", "_1_x_2_", "_2_^2" etc. With formula or additive fits, exclusions target the generated expansion names after parsing; use dummy_fit = TRUE or a neighboring fit to inspect retained names.
custom_basis_fxn	Default: NULL. Optional user-defined function for custom basis expansions. See get_polynomial_expansions.
include_constrain_fitted	Default: TRUE. Logical switch to constrain fitted values at knot points.
include_constrain_first_deriv	Default: TRUE. Logical switch to constrain first derivatives at knot points.
include_constrain_second_deriv	Default: TRUE. Logical switch to constrain second derivatives at knot points.
include_constrain_interactions	Default: TRUE. Logical switch to constrain interaction terms at knot points.
add_first_and_second_derivative_constraints	Default: NULL. Logical switch controlling how first- and second-derivative smoothness constraints are assembled. If TRUE, the corresponding first- and second-derivative rows are added before entering the equality constraint matrix. If FALSE, they are kept as separate equality constraints. If NULL, they are combined only when more than one predictor is spline-expanded, so a model with one spline effect and any remaining non-spline effects keeps the derivative constraints separate.
qr_pivot_smoothing_constraints	Default: TRUE. Logical switch to reduce the smoothness/equality constraint matrix to a linearly independent set before fitting. Disabling this keeps the original equality columns.
cl	Default: NULL. Parallel processing cluster object (use parallel::makeCluster()).
chunk_size	Default: NULL. Integer specifying custom chunk size for parallel processing.
parallel_eigen	Default: TRUE. Logical flag for parallel eigenvalue decomposition. Ignored inside tuning fits when parallel_grideval or parallel_bfgs is using the cluster.
parallel_trace	Default: FALSE. Logical flag for parallel trace computation.
parallel_aga	Default: FALSE. Logical flag for parallel \mathbf{G} and \mathbf{A} matrix operations.
parallel_matmult	Default: FALSE. Logical flag for parallel block-diagonal matrix multiplication.
parallel_qr	Default: FALSE. Logical flag for the tall-skinny least-squares and rank-reduction steps that arise in transformed constraint solves. When active and a cluster is supplied, these steps use row-chunked cross-products with small dense fallback solves instead of relying entirely on base QR; unstable cases fall back automatically to .lm.fit() or qr().
parallel_bfgs	Default: False. Logical flag for parallel evaluation of damped BFGS step candidates during penalty tuning. When active and a cluster is supplied, multiple damping factors are evaluated across workers and inner parallel flags are ignored for those fits.
parallel_grideval	Default: TRUE. Logical flag for parallel evaluation of the initial tuning grid. When active and a cluster is supplied, grid points are distributed across workers and inner parallel flags are ignored for those fits.
parallel_qr_qp	Default: FALSE. Logical flag for parallel QR pivot reduction of partition-local inequality constraint columns. When active and a cluster is supplied, each partition's reducible QP block is handled independently across workers before the final QP matrix is assembled.
parallel_unconstrained	Default: FALSE. Logical flag for parallel unconstrained MLE for non-identity-link-Gaussian models.
parallel_find_neighbors	Default: TRUE. Logical flag for parallel neighbor identification.
parallel_penalty	Default: FALSE. Logical flag for parallel penalty matrix construction.
parallel_make_constraint	Default: TRUE. Logical flag for parallel constraint matrix generation.
unconstrained_fit_fxn	Default: unconstrained_fit_default. Custom function for fitting unconstrained models per partition.
keep_weighted_Lambda	Default: FALSE. Logical flag to retain GLM weights in penalty constraints using Tikhonov parameterization. Advised for non-canonical GLMs.
iterate_tune	Default: TRUE. Logical switch for iterative optimization during penalty tuning.
iterate_final_fit	Default: TRUE. Logical switch for iterative optimization in final model fitting.
blockfit	Default: TRUE. Logical switch for backfitting with mixed spline and non-interactive linear terms. When the blockfit conditions are met, both tuning and the final fit use blockfit_solve; otherwise the code uses get_B. Any failure falls back to get_B.
qp_score_function	Default: GLM score using family$mu.eta(eta) / family$variance(mu). Used for quadratic programming, blockfit, and GEE formulations. With dense VhalfInv, the same score weight is applied after whitening. Accepts arguments "X, y, mu, order_list, dispersion, VhalfInv, observation_weights, ...".
qp_observations	Default: NULL. Either a numeric vector of observation indices at which every active built-in QP constraint is evaluated, or a named list keyed by "var:qp_<type>" (or bare "qp_<type>") giving different built-in constraints different observation subsets. The known types are qp_range_lower, qp_range_upper, qp_positive_derivative, qp_negative_derivative, qp_positive_2ndderivative, qp_negative_2ndderivative, qp_monotonic_increase, and qp_monotonic_decrease. For range and monotonicity the canonical keys are the bare forms such as "qp_range_lower" and "qp_monotonic_increase", because those constraints are not tied to a specific variable; prefixed entries are still accepted and unioned. Derivative entries dispatch per variable, so different variables and constraint types may use different subsets. Unknown keys are ignored with a warning when include_warnings = TRUE.
qp_Amat	Default: NULL. Optional pre-built QP constraint matrix. In the current pipeline its presence marks QP handling as active, but the built-in constructor does not merge it into the assembled constraint set; use qp_Amat_fxn for custom assembled constraints.
qp_bvec	Default: NULL. Optional pre-built QP right-hand side paired with qp_Amat. Like qp_Amat, it is currently treated as an advanced placeholder rather than merged into the built-in constructor.
qp_meq	Default: 0. Optional number of equality constraints paired with qp_Amat. Like qp_Amat, it is currently treated as an advanced placeholder rather than merged into the built-in constructor.
qp_positive_derivative	Default: FALSE. Require nonnegative first derivatives. Accepts FALSE (inactive), TRUE (all predictors), or a character / integer vector selecting the predictor variables to constrain.
qp_negative_derivative	Default: FALSE. Require nonpositive first derivatives. Same input types as qp_positive_derivative; may be used simultaneously on different predictors.
qp_positive_2ndderivative	Default: FALSE. Require nonnegative second derivatives (convexity). Same input types as qp_positive_derivative.
qp_negative_2ndderivative	Default: FALSE. Require nonpositive second derivatives (concavity). Same input types as qp_positive_derivative.
qp_monotonic_increase	Default: FALSE. Logical only. Require fitted values to be nondecreasing in observation order.
qp_monotonic_decrease	Default: FALSE. Logical only. Require fitted values to be nonincreasing in observation order.
qp_range_upper	Default: NULL. Optional upper bound on constrained fitted values.
qp_range_lower	Default: NULL. Optional lower bound on constrained fitted values.
qr_pivot_inequality_constraints	Default: FALSE. Logical switch to reduce partition-local inequality constraint columns to QR pivot columns before solving. Built-in range and monotonicity constraints are left unchanged, and more generally any inequality columns spanning multiple partitions are also left unchanged.
qp_Amat_fxn	Default: NULL. Custom function generating Amat.
qp_bvec_fxn	Default: NULL. Custom function generating bvec.
qp_meq_fxn	Default: NULL. Custom function generating meq.
constraint_values	Default: cbind(). Optional matrix encoding nonzero equality targets paired with constraint_vectors. When left empty, added equality constraints are treated as homogeneous.
constraint_vectors	Default: cbind(). Optional matrix of user-supplied equality-constraint vectors, appended to the internally generated smoothness constraints.
return_G	Default: TRUE. Logical switch to return the unscaled unconstrained variance-covariance matrix \mathbf{G}.
return_Ghalf	Default: TRUE. Logical switch to return \mathbf{G}^{1/2}.
return_U	Default: TRUE. Logical switch to return the constraint projection matrix \mathbf{U}.
estimate_dispersion	Default: TRUE. Logical flag to estimate dispersion after fitting.
unbias_dispersion	Default: TRUE. Logical switch to multiply dispersion by N/(N - \mathrm{trace}(\mathbf{H})). Unlike lgspline, no wrapper-level auto-resolution is performed here.
return_varcovmat	Default: TRUE. Logical switch to return the variance-covariance matrix of estimated coefficients. Needed for Wald inference.
exact_varcovmat	Default: FALSE. Logical switch to replace the default asymptotic (Bayesian posterior) variance-covariance matrix with the exact frequentist variance-covariance matrix of the constrained estimator. The asymptotic version uses the Hessian of the penalized log-likelihood: \tilde{\sigma}^{2}\mathbf{U}\mathbf{G}\mathbf{U}^{\top}. The exact version additionally corrects for the penalty's contribution as a shrinkage prior, giving: \tilde{\sigma}^{2}\mathbf{U}\mathbf{G}\mathbf{U}^{\top} - \tilde{\sigma}^{2}\mathbf{U}\mathbf{G}\boldsymbol{\Lambda}\mathbf{G}\mathbf{U}^{\top} When a correlation structure is present (VhalfInv non-NULL), \mathbf{G}_{\mathrm{correct}} replaces the block-diagonal \mathbf{G}. For Gaussian identity link (with or without correlation structure), the result is the exact variance-covariance matrix of the constrained estimate. The returned object still stores the result in varcovmat. Requires return_varcovmat = TRUE.
return_lagrange_multipliers	Default: FALSE. Logical switch to return the Lagrangian multiplier vector.
custom_penalty_mat	Default: NULL. Optional p \times p custom penalty matrix for individual partitions, replacing the default ridge on linear/intercept terms. Run with dummy_fit = TRUE first to inspect expansion structure.
cluster_args	Default: c(custom_centers = NA, nstart = 10). Named vector of arguments controlling clustering. If the first argument is not NA, it is treated as custom cluster centers (typically an (K+1) \times q matrix). Otherwise, default k-means is used.
dummy_dividor	Default: 0.00000000000000000000012345672152894. Small numeric constant to prevent division by zero.
dummy_adder	Default: 0.000000000000000002234567210529. Small numeric constant to prevent division by zero.
verbose	Default: FALSE. Logical flag to print general progress messages.
verbose_tune	Default: FALSE. Logical flag to print detailed progress during penalty tuning.
dummy_fit	Default: FALSE. Runs the full pipeline but sets coefficients to zero, allowing inspection of design matrix structure, penalty matrices, and partitioning. Replaces the deprecated expansions_only argument.
auto_encode_factors	Default: TRUE. Compatibility flag carried through from higher-level preprocessing. Direct calls to lgspline.fit should usually supply already encoded predictors and use factor_groups when sum-to-zero constraints are needed.
observation_weights	Default: NULL. Numeric vector of observation-specific weights for generalized least squares estimation.
do_not_cluster_on_these	Default: c(). Predictor columns to exclude from clustering. Accepts numeric column indices or character column names.
neighbor_tolerance	Default: 1 + 1e-16. Numeric tolerance for determining neighboring partitions using k-means clustering. Intended for internal use.
no_intercept	Default: FALSE. Logical flag to constrain intercept to 0. Formulas with "0+" set this to TRUE automatically.
VhalfInv	Default: NULL. Fixed custom N \times N square-root-inverse covariance matrix \mathbf{V}^{-1/2}. Triggers GLS with known covariance. Post-fit inference recomputed from whitened Gram matrices.
Vhalf	Default: NULL. Fixed custom N \times N square-root covariance \mathbf{V}^{1/2}. Computed as inverse of VhalfInv if not supplied.
include_warnings	Default: TRUE. Logical switch to control display of warnings.
og_cols	Default: NULL. Original predictor names
factor_groups	Named list mapping original factor variable names to integer vectors of their corresponding one-hot indicator column positions within the predictor matrix. Each element enforces a sum-to-zero equality constraint on the linear-term coefficients of its indicator columns within every partition, ensuring identifiability when all factor levels are included without a reference/dropped level. For a group with indicator columns at positions j1, j2, ..., jm, the constraint is \sum_{i=1}^{m} \beta_{ji,k} = 0 for each partition k. Groups with fewer than two resolved positions are silently ignored. Populated automatically by process_input when auto_encode_factors = TRUE; users calling lgspline.fit directly should construct this list manually when passing one-hot encoded predictors without a reference level. Default NULL (no sum-to-zero constraints imposed).
spline_groups	Default: NULL. Optional list of predictor groups to fit as separate additive spline terms. For example, list(1, 2) fits two univariate spline terms with separate partitioning, while list(c(1, 2), 3) fits a joined bivariate smooth plus a separate univariate smooth. Any number of groups may be supplied. Single-group lists use the ordinary joined-spline path. In additive fits, pre-built qp_Amat/qp_bvec/qp_meq objects must be supplied as per-term lists; custom QP builder functions are evaluated separately for each term.
additive_spline_interaction_pairs	Default: NULL. Optional internal list of two-element index vectors marking explicit parametric interactions between separate additive spline terms, e.g. the x1:x2 in y ~ spl(x1) + spl(x2) + x1:x2. Normally supplied by process_input from formulas.
...	Additional arguments passed to the unconstrained model fitting function. For additive spline groups, additive_max_iter and additive_tol control the outer coordinate-update loop.

Details

lgspline.fit performs the following steps:

1. Polynomial expansion and predictor standardization.

2. Knot placement and partitioning (k-means or custom).

3. Constraint matrix \mathbf{A} construction. Only a linearly independent subset of columns is retained via pivoted QR decomposition.

4. Penalty tuning via exact leave-one-out by default, or generalized cross-validation when tuning_criterion = "gcv", or use of previously tuned penalties.

5. If spline_groups contains more than one group, each group is fit as an additive spline term with its own partitioning and constraints. Each conditional update is an ordinary lgspline.fit Newton/SQP fit with the other terms held fixed on the link scale.

6. Final coefficient estimation via one of three paths:

   • Blockfit option (when blockfit = TRUE, flat columns are non-empty, K > 0, and no correlation structure): Routes through blockfit_solve for backfitting with mixed spline and non-interactive linear terms. Falls back to get_B on failure.

   • Standard get_B path: Three internal computational paths: GEE (damped SQP with correlation structures), Gaussian identity (closed-form OLS projection), and general GLM (unconstrained fit + Lagrangian projection with Newton/Lagrangian projection updates).

7. Post-fit inference: \mathbf{U}, trace, dispersion, variance-covariance matrix, and optionally Lagrange multipliers. When VhalfInv is non-NULL, these are computed from the whitened Gram matrices \mathbf{X}^{\top}\mathbf{V}^{-1}\mathbf{X} via the full penalized GLS information \mathbf{G}_{\mathrm{correct}} = (\mathbf{X}^{\top}\mathbf{V}^{-1}\mathbf{X} + \boldsymbol{\Lambda})^{-1}.

Dummy fit. When dummy_fit = TRUE, an early-return path skips the expensive fitting steps (compute_G_eigen, get_B, trace computation, variance-covariance matrix) while retaining all penalty, partitioning, and design matrix information. Coefficients are set to zero. This replaces the deprecated expansions_only argument.

Value

A list containing the fitted model components, forming the core structure used internally by lgspline and its associated methods. This function is primarily intended for internal use or advanced users needing direct access to fitting components. The returned list contains numerous elements, typically including:

y

The original response vector provided.

ytilde

The fitted values on the original response scale. Set to rep(0, N) when dummy_fit = TRUE.

X

A list, with each element the design matrix (\mathbf{X}_{k}) for partition k, on the unstandardized expansion scale.

A

The constraint matrix (\mathbf{A}) encoding smoothness and any other linear equality constraints. Reduced to linearly independent columns via pivoted QR decomposition.

B

A list of the final fitted coefficient vectors (\boldsymbol{\beta}_{k}) for each partition k, on the original predictor/response scale.

B_raw

A list of fitted coefficient vectors on the internally standardized scale used during fitting.

K, p, q, P, N

Key dimensions: number of internal knots (K), basis functions per partition (p), original predictors (q), total coefficients (P), and sample size (N).

penalties

A list containing the final penalty components used (e.g., Lambda, L1, L2, L_predictor_list, L_partition_list). See compute_Lambda.

knot_scale_transf, knot_scale_inv_transf

Functions to transform predictors to/from the scale used for knot placement.

knots

Matrix or vector of knot locations on the original predictor scale (NULL if K=0 or q > 1).

partition_codes

Vector assigning each original observation to a partition.

partition_bounds

Internal representation of partition boundaries.

make_partition_list

List containing centers, knot midpoints, neighbor info, and assignment function from partitioning (NULL if K=0 or 1D). See make_partitions.

knot_expand_function, assign_partition

Internal functions for partitioning data. See knot_expand_list.

predict

The primary function embedded in the object for generating predictions on new data. For multi-predictor models, take_first_derivatives = TRUE returns derivatives as a named list of per-variable derivative vectors rather than a concatenated vector. See predict.lgspline.

family

The family object or custom list used.

estimate_dispersion, unbias_dispersion

Logical flags related to dispersion estimation settings.

sigmasq_tilde

The estimated (or fixed) dispersion parameter \tilde{\sigma}^{2}. For Gaussian identity fits with VhalfInv non-NULL, this is computed from whitened residuals \mathbf{V}^{-1/2}(\mathbf{y} - \hat{\mathbf{y}}), multiplied by the observation weights and the optional bias-correction factor. When estimate_dispersion = FALSE, set to 1. Omitted when dummy_fit = TRUE.

backtransform_coefficients, forwtransform_coefficients

Functions to convert coefficients between standardized and original scales.

mean_y, sd_y

Mean and standard deviation used for standardizing the response.

og_order, order_list

Information mapping original data order to partitioned order.

constraint_values, constraint_vectors

User-supplied additional linear equality constraints.

expansion_scales

Scaling factors applied to basis expansions during fitting (if standardize_expansions_for_fitting = TRUE).

take_derivative, take_interaction_2ndderivative, get_all_derivatives_insample

Functions related to computing derivatives of the fitted spline.

numerics, power1_cols, ..., nonspline_cols

Integer vectors storing column indices identifying different types of terms in the basis expansion.

return_varcovmat

Logical indicating if variance matrix calculation was requested.

exact_varcovmat

Not returned as a standalone component; this argument only controls whether varcovmat, when requested, is left as the default asymptotic/Laplace version or replaced by the exact frequentist correction available for Gaussian identity fits.

raw_expansion_names

Original generated names for basis expansion columns (before potential renaming if input predictors had names).

std_X, unstd_X

Functions to standardize/unstandardize design matrices according to expansion_scales.

parallel_cluster_supplied

Logical indicating if a parallel cluster was used.

weights

The original observation weights provided (potentially reformatted).

VhalfInv

The fixed \mathbf{V}^{-1/2} matrix if supplied.

quadprog_list

List containing components related to quadratic programming constraints, if used.

G

List of unscaled variance-covariance matrices \mathbf{G}_{k} per partition, returned if return_G = TRUE. When VhalfInv is non-NULL, recomputed from whitened Gram matrices. Omitted when dummy_fit = TRUE.

Ghalf

List of \mathbf{G}_{k}^{1/2} matrices, returned if return_Ghalf = TRUE. When VhalfInv is non-NULL, the full \mathbf{G}_{\mathrm{correct}}^{1/2} is used for posterior draws and variance-covariance computation. Omitted when dummy_fit = TRUE.

U

Constraint projection matrix \mathbf{U}, returned if return_U = TRUE. Omitted when dummy_fit = TRUE.

trace_XUGX

The effective degrees-of-freedom trace term. When VhalfInv is non-NULL, it is computed from the full penalized GLS information rather than the block-diagonal approximation. Omitted when dummy_fit = TRUE.

varcovmat

The final variance-covariance matrix of the estimated coefficients. Computed via the outer-product form \sigma^{2}(\mathbf{U}\mathbf{G}^{1/2})(\mathbf{U}\mathbf{G}^{1/2})^{\top} for numerical stability. When VhalfInv is non-NULL, uses the full \mathbf{G}_{\mathrm{correct}}^{1/2} in place of block-diagonal \mathbf{G}^{1/2}. Returned if return_varcovmat = TRUE. By default this is the asymptotic (Laplace/posterior) variance-covariance matrix; when exact_varcovmat = TRUE, it is replaced in-place by the exact frequentist correction available for Gaussian identity fits. Omitted when dummy_fit = TRUE.

lagrange_multipliers

Vector of Lagrangian multipliers if return_lagrange_multipliers = TRUE. For equality-only fits these follow the formulation (\mathbf{A}^{\top}\mathbf{G}\mathbf{A})^{-1}\mathbf{A}^{\top}(\hat{\boldsymbol{\beta}} - \boldsymbol{\beta_0}). When quadratic-programming constraints are active they are taken directly from solve.QP and therefore refer to the combined equality/inequality constraint system. NULL if no constraints are active

. Note that the exact components returned depend heavily on the function arguments (e.g., values of return_G, return_varcovmat, etc.) and whether dummy_fit = TRUE.

lgspline documentation built on Aug. 5, 2026, 1:10 a.m.