Normalize and Validate an Optimizer Algorithm Name for the fast_* C++ Backends

Internal helper shared by the package's fast_* GLM/survival/ordinal fitting wrappers (e.g. fast_logistic_regression, fast_coxph_regression) to resolve a user-supplied optimization_alg argument to one of the fixed set of optimizer names the underlying C++ backends actually implement, applying a model-specific default when none is supplied and rejecting anything else. This centralizes the default/validation logic so each fast_* wrapper does not have to repeat it.

Usage

.normalize_optimizer_algorithm(
  optimization_alg,
  allow_irls = FALSE,
  default = if (allow_irls) "irls" else "lbfgs"
)

Arguments

optimization_alg

Character string (possibly abbreviated) naming the desired optimizer, NULL, or missing entirely; see Details for resolution order.

allow_irls

Logical. Whether "irls" is a valid choice (and the default default) for this model; FALSE restricts the allowed set to c("lbfgs", "newton_raphson").

default

Character string used when optimization_alg is missing or NULL. Defaults to "irls" when allow_irls = TRUE, else "lbfgs".

Value

A validated, unabbreviated character string: one of "newton_raphson", "lbfgs", or (only when allow_irls = TRUE) "irls".

Details

The three possible optimizer names, when supported by a given model, correspond to distinct fitting algorithms in the C++ backends: "newton_raphson" (full Newton-Raphson using the analytic Hessian), "lbfgs" (limited-memory quasi-Newton, avoiding an explicit Hessian), and "irls" (iteratively reweighted least squares, the classical GLM-fitting algorithm — only meaningful, and only offered, for exponential-family GLMs, hence gated by allow_irls). Which optimizers a given fast_* function actually accepts (and which is its default) varies by model; this function only encodes the generic irls-vs-not-irls split, not per-model specifics.

optimization_alg is matched against the allowed set via match.arg, so unambiguous partial string matches (e.g. "newton") are accepted; an unmatched or ambiguous value raises match.arg's standard error rather than silently falling back to the default. missing(optimization_alg) or an explicit NULL both resolve to default before matching.

See also

match.arg, which performs the validation/partial-matching.