predict.vcmm_fit: Predictions from a fitted VCMM

In cevcmm: Communication-Efficient Varying Coefficient Mixed-Effects Models

Predictions from a fitted VCMM

Description

Produces predicted responses at new (X, t) (and optionally Z) values, using the paper's subject-specific predictor

\hat y_i = \tilde{\mathbf x}_i^{\top} \hat{\tilde\beta} + \mathbf z_i^{\top} \hat\alpha

by default (Jalili and Lin, 2025, Section 5). For the alternative "new groups not seen in training" scenario, pass include_random = FALSE to use the marginal predictor \hat y_i = \tilde{\mathbf x}_i^{\top} \hat{\tilde\beta}.

Usage

## S3 method for class 'vcmm_fit'
predict(object, newdata, include_random = TRUE, se.fit = FALSE, ...)

Arguments

object	A vcmm_fit object.
newdata	A named list or data frame. See Details.
include_random	Logical. If TRUE (default) and newdata\$Z is supplied, adds Z\hat\alpha to the prediction. Set FALSE for the marginal predictor (new groups scenario).
se.fit	Logical. If TRUE, also returns per-prediction standard errors.
...	Unused.

Details

newdata format. A named list (or data frame whose columns match these names) containing:

• t: numeric vector of length N_{\mathrm{new}}.

• X: numeric matrix N_{\mathrm{new}} \times K (or length-N_{\mathrm{new}} vector when K = 1) of varying- coefficient covariates, in the same column order used at fit time.

• Z: optional N_{\mathrm{new}} \times q random- effects design matrix. Must follow the same column-stacking convention as the training Z so that Z %*% alpha references the appropriate random-effect slots.

Standard errors. With se.fit = TRUE the per-prediction standard error is the square root of [W, Z]\,\hat\sigma_\varepsilon^2 K^{-1}\,[W, Z]^{\top} when include_random = TRUE (joint uncertainty of fixed and random effects), where W is the spline-expanded fixed-effects row; the random-effect block is omitted when include_random = FALSE. These are confidence-interval SEs on the mean; for prediction intervals add \hat\sigma_\varepsilon^2 to the variance.

Value

Either a numeric vector of length N_{\mathrm{new}}, or (when se.fit = TRUE) a list with components fit and se.fit.

References

Jalili, L. and Lin, L.-H. (2025). Scalable and Communication-Efficient Varying Coefficient Mixed-Effects Models.

See Also

varying_coef, vcov.vcmm_fit.

Examples

set.seed(1)
n <- 400
t <- runif(n); x <- runif(n); Z <- matrix(rnorm(n * 3), n, 3)
y <- 2 + sin(2 * pi * t) * x +
     as.vector(Z %*% rnorm(3, sd = 0.5)) + rnorm(n, sd = 0.5)

fit <- vcmm(y, X = x, Z = Z, t = t,
            control = vcmm_control(sigma_eps = 0.5, sigma_alpha = 0.5))

# Default: subject-specific predictor (training-group prediction)
yhat_train <- predict(fit, newdata = list(t = t, X = x, Z = Z))
mean((y - yhat_train)^2)  # ~ sigma_eps^2 = 0.25

# Marginal predictor (new groups scenario)
yhat_marg <- predict(fit, newdata = list(t = t, X = x, Z = Z),
                      include_random = FALSE)

cevcmm documentation built on July 24, 2026, 5:07 p.m.