This is the predict() method for refmodel objects (returned by
get_refmodel() or init_refmodel()). It offers three types of output which
are all based on the reference model and new (or old) observations: Either
the linear predictor on link scale, the linear predictor transformed to
response scale, or the log posterior predictive density.
# S3 method for refmodel
predict(
object,
newdata = NULL,
ynew = NULL,
offsetnew = NULL,
weightsnew = NULL,
type = "response",
...
)In the following, \(N\), \(C_{\mathrm{cat}}\), and
\(C_{\mathrm{lat}}\) from help topic refmodel-init-get are used.
Furthermore, let \(C\) denote either \(C_{\mathrm{cat}}\) (if
type = "response") or \(C_{\mathrm{lat}}\) (if type = "link").
Then, if is.null(ynew), the returned object contains the reference
model's predictions (with the scale depending on argument type) as:
a length-\(N\) vector in case of (i) the traditional projection, (ii)
the latent projection with type = "link", or (iii) the latent projection
with type = "response" and object$family$cats being NULL;
an \(N \times C\) matrix in case of (i) the augmented-data
projection or (ii) the latent projection with type = "response" and
object$family$cats being not NULL.
If !is.null(ynew), the returned object is a length-\(N\) vector of log
posterior predictive densities evaluated at ynew.
An object of class refmodel (returned by get_refmodel() or
init_refmodel()).
Passed to argument newdata of the reference model's
extract_model_data function (see init_refmodel()). Provides the
predictor (and possibly also the response) data for the new (or old)
observations. May also be NULL for using the original dataset. If not
NULL, any NAs will trigger an error.
If not NULL, then this needs to be a vector of new (or old)
response values. See also section "Value" below. In case of (i) the
augmented-data projection or (ii) the latent projection with type = "response" and object$family$cats being not NULL, ynew is internally
coerced to a factor (using as.factor()). The levels of this factor
have to be a subset of object$family$cats (see extend_family()'s
arguments augdat_y_unqs and latent_y_unqs, respectively).
Passed to argument orhs of the reference model's
extract_model_data function (see init_refmodel()). Used to get the
offsets for the new (or old) observations.
Passed to argument wrhs of the reference model's
extract_model_data function (see init_refmodel()). Used to get the
weights for the new (or old) observations.
Usually only relevant if is.null(ynew), but for the latent
projection, this also affects the !is.null(ynew) case (see below). The
scale on which the predictions are returned, either "link" or
"response" (see predict.glm() but note that predict.refmodel() does
not adhere to the typical R convention of a default prediction on link
scale). For both scales, the predictions are averaged across the posterior
draws. In case of the latent projection, argument type is similar in
spirit to argument resp_oscale from other functions: If (i)
is.null(ynew), then argument type affects the predictions as described
above. In that case, note that type = "link" yields the linear predictors
without any modifications that may be due to the original response
distribution (e.g., for a brms::cumulative() model, the ordered
thresholds are not taken into account). If (ii) !is.null(ynew), then
argument type also affects the scale of the log posterior predictive
densities (type = "response" for the original response scale, type = "link" for the latent Gaussian scale).
Currently ignored.
Argument weightsnew is only relevant if !is.null(ynew).
In case of a multilevel reference model, group-level effects for new group
levels are drawn randomly from a (multivariate) Gaussian distribution. When
setting projpred.mlvl_pred_new to TRUE, all group levels from newdata
(even those that already exist in the original dataset) are treated as new
group levels (if is.null(newdata), all group levels from the original
dataset are considered as new group levels in that case).