Fast Ordinary Least Squares (OLS) Regression with Variance (C++ Backend)

As fast_ols_cpp, but additionally computes the classical OLS variance estimate \(\hat\sigma^2 = \mathrm{SSE} / (n - p)\) (with \(\mathrm{SSE} = y^\top y - \hat\beta^\top X^\top y\) on the fixed-parameter-adjusted response, and \(p\) the number of free — non-fixed — columns) and the sampling variance of two coefficients, \(\widehat{\mathrm{Var}}(\hat\beta_k) = \hat\sigma^2 \, [(X^\top X)^{-1}]_{kk}\), obtained from the same Cholesky (LDLT) factorization used to solve for \(\hat\beta\), without forming the full inverse matrix. If the LDLT decomposition fails (rank-deficient \(X\)), this function falls back to a QR solve exactly as fast_ols_cpp does, but in that case no variance quantities are computed: ssq_b_j, ssq_b_2, and XtX are omitted from the result and converged is FALSE.

Usage

fast_ols_with_var_cpp(X, y, j = 2L, fixed_idx = NULL, fixed_values = NULL)

Arguments

X

A numeric matrix of predictor variables. It is assumed that an intercept column (e.g., a column of ones) is already included in X if desired.

y

A numeric vector of the (continuous) response variable.

j

This function will compute the variance of the jth (1-indexed) coefficient estimator. Default is 2 (conventionally the treatment effect).

fixed_idx

Optional integer vector of 1-indexed columns of X whose coefficients should be held fixed at fixed_values rather than estimated.

fixed_values

Optional numeric vector, parallel to fixed_idx, of the fixed coefficient values.

Value

A list containing the following components (the last four only present when the LDLT solve succeeds):

b

A numeric vector of the estimated regression coefficients \(\hat\beta\).

converged

TRUE if the LDLT solve succeeded, FALSE if the QR fallback was used.

sigma2_hat

The estimated residual variance \(\hat\sigma^2\).

XtX

The (free-coefficient) \(X^\top X\) matrix, expanded back to full \(p \times p\) shape with zeros in the fixed-coefficient rows/columns.

ssq_b_j

The variance of the \(j\)-th coefficient estimator, NA if j indexes a fixed coefficient.

ssq_b_2

The variance of the second coefficient estimator specifically (typically the treatment effect), regardless of what j is; equal to ssq_b_j when j = 2. NA if the second column is a fixed coefficient.

Fixed (offset) coefficients

fixed_idx (1-indexed columns of X) and fixed_values optionally hold a subset of coefficients at caller-supplied constant values rather than estimating them: those columns' contribution \(X_{\mathrm{fixed}} \beta_{\mathrm{fixed}}\) is subtracted out of y first, and only the remaining ("free") columns are fit by least squares; the fixed coefficients are then copied back into \(\hat\beta\) unchanged. This is used, e.g., to fit a model with a known/offset intercept without re-estimating it.

See also

fast_ols_cpp for the estimate-only counterpart.