Fast Identity-Link Binomial Regression, Estimate Only (C++ Backend)

Fits a binary-response GLM with the identity link (a linear probability / risk-difference model), \(\mu_i = \Pr(Y_i = 1) = x_i^\top \beta\) (constrained to \((10^{-8}, 1 - 10^{-8})\); no other link transformation is applied), via Fisher scoring (IRLS) with a step-halving line search that rejects any Newton step whose resulting \(\eta_i = x_i^\top \beta\) would leave the valid probability range or decrease the log-likelihood — this boundary-constrained line search, not a link-function transform, is what keeps fitted probabilities in \((0, 1)\) for this otherwise-unconstrained linear-in-\(\beta\) model. Regression coefficients on the identity-link scale are directly interpretable as risk differences: \(\beta_j\) is the change in \(\Pr(Y = 1)\) per unit change in covariate \(j\), in contrast to fast_log_binomial_regression_cpp's log-link coefficients (interpretable as log relative risks) or a standard logit-link model's log-odds-ratio coefficients.

Usage

fast_identity_binomial_regression_cpp(
  X,
  y_r,
  maxit = 100L,
  tol = 1e-06,
  fixed_idx = NULL,
  fixed_values = NULL,
  warm_start_beta = NULL,
  smart_cold_start = TRUE,
  warm_start_weights = NULL,
  warm_start_fisher_info = NULL
)

Arguments

X: A numeric matrix of predictors, \(n \times p\); include an explicit intercept column if desired (no implicit intercept).
y_r: A binary (0/1) numeric vector of responses, length \(n\).
maxit: Maximum number of Fisher-scoring iterations.
tol: Convergence tolerance, on the relative norm of the coefficient update step.
fixed_idx: Optional integer indices of coefficients to hold fixed rather than estimate.
fixed_values: Optional values to fix the parameters named by fixed_idx at.
warm_start_beta: Optional starting values for coefficients. If provided, smart_cold_start is ignored.
smart_cold_start: Logical. If TRUE (default) and no warm_start_beta is supplied, use an OLS-based initial guess.
warm_start_weights: Optional initial working weights for the first IRLS iteration.
warm_start_fisher_info: Optional initial Fisher Information matrix for the first IRLS iteration.

Value

A list with components b (estimated coefficients \(\hat\beta\), on the risk-difference/identity scale), mu_hat (fitted probabilities \(\hat\mu_i\), length \(n\)), working_weights (the final IRLS weights \(w_i\)), iterations (number of Fisher- scoring iterations performed), converged (logical; also requires all of b, mu_hat, working_weights to be finite), and fisher_information (the working-weights curvature matrix \(X^\top W X\)).

Details

Optimization. Each Fisher-scoring iteration solves a weighted least-squares step using working weights \(w_i = 1 / \max(\mu_i(1-\mu_i), 10^{-8})\) (the inverse Bernoulli variance, clamped away from 0 for stability near the boundary), then backtracks (halving the step size, down to a minimum step of \(10^{-8}\)) until the resulting \(\eta\) stays within \((10^{-8}, 1-10^{-8})\) for every observation and the log-likelihood does not decrease; a step that cannot be accepted at any halving depth terminates iteration without converged = TRUE. fixed_idx/fixed_values hold specific coefficients fixed rather than estimated; warm_start_beta (or, when absent, an OLS-based guess if smart_cold_start = TRUE) seeds the first iteration, and warm_start_weights/warm_start_fisher_info warm-start the first IRLS working-weights/curvature computation.

No guarantee of a feasible solution. Because the identity link has no inherent boundary protection, some \((X, y)\) configurations (e.g. extreme covariate values, near-perfect separation, or an ill-conditioned X) may have no interior maximum-likelihood solution reachable by this constrained line search; such cases surface as converged = FALSE rather than a silently invalid (out-of-range) fitted probability.

Usage

Arguments

Value

Details

See also