R: Projection onto submodel(s)

project {projpred}

R Documentation

Projection onto submodel(s)

Description

Project the posterior of the reference model onto the parameter space of a single submodel consisting of a specific combination of predictor terms or (after variable selection) onto the parameter space of a single or multiple submodels of specific sizes.

Usage

project(
  object,
  nterms = NULL,
  solution_terms = NULL,
  refit_prj = TRUE,
  ndraws = 400,
  nclusters = NULL,
  seed = sample.int(.Machine$integer.max, 1),
  regul = 1e-04,
  ...
)

Arguments

`object`	An object which can be used as input to `get_refmodel()` (in particular, objects of class `refmodel`).
`nterms`	Only relevant if `object` is of class `vsel` (returned by `varsel()` or `cv_varsel()`). Ignored if `!is.null(solution_terms)`. Number of terms for the submodel (the corresponding combination of predictor terms is taken from `object`). If a numeric vector, then the projection is performed for each element of this vector. If `NULL` (and `is.null(solution_terms)`), then the value suggested by the variable selection is taken (see function `suggest_size()`). Note that `nterms` does not count the intercept, so use `nterms = 0` for the intercept-only model.
`solution_terms`	If not `NULL`, then this needs to be a character vector of predictor terms for the submodel onto which the projection will be performed. Argument `nterms` is ignored in that case. For an `object` which is not of class `vsel`, `solution_terms` must not be `NULL`.
`refit_prj`	A single logical value indicating whether to fit the submodels (again) (`TRUE`) or to retrieve the fitted submodels from `object` (`FALSE`). For an `object` which is not of class `vsel`, `refit_prj` must be `TRUE`.
`ndraws`	Only relevant if `refit_prj` is `TRUE`. Number of posterior draws to be projected. Ignored if `nclusters` is not `NULL` or if the reference model is of class `datafit` (in which case one cluster is used). If both (`nclusters` and `ndraws`) are `NULL`, the number of posterior draws from the reference model is used for `ndraws`. See also section "Details" below.
`nclusters`	Only relevant if `refit_prj` is `TRUE`. Number of clusters of posterior draws to be projected. Ignored if the reference model is of class `datafit` (in which case one cluster is used). For the meaning of `NULL`, see argument `ndraws`. See also section "Details" below.
`seed`	Pseudorandom number generation (PRNG) seed by which the same results can be obtained again if needed. If `NULL`, no seed is set and therefore, the results are not reproducible. See `set.seed()` for details. Here, this seed is used for clustering the reference model's posterior draws (if `!is.null(nclusters)`) and for drawing new group-level effects when predicting from a multilevel submodel (however, not yet in case of a GAMM).
`regul`	A number giving the amount of ridge regularization when projecting onto (i.e., fitting) submodels which are GLMs. Usually there is no need for regularization, but sometimes we need to add some regularization to avoid numerical problems.
`...`	Arguments passed to `get_refmodel()` (if `get_refmodel()` is actually used; see argument `object`) as well as to the divergence minimizer (if `refit_prj` is `TRUE`).

Details

Arguments ndraws and nclusters are automatically truncated at the number of posterior draws in the reference model (which is 1 for datafits). Using less draws or clusters in ndraws or nclusters than posterior draws in the reference model may result in slightly inaccurate projection performance. Increasing these arguments affects the computation time linearly.

Value

If the projection is performed onto a single submodel (i.e., length(nterms) == 1 || !is.null(solution_terms)), an object of class projection which is a list containing the following elements:

dis: Projected draws for the dispersion parameter.
kl: The KL divergence from the submodel to the reference model.
weights: Weights for the projected draws.
solution_terms: A character vector of the submodel's predictor terms, ordered in the way in which the terms were added to the submodel.
submodl: A list containing the submodel fits (one fit per projected draw).
p_type: A single logical value indicating whether the reference model's posterior draws have been clustered for the projection (TRUE) or not (FALSE).
refmodel: The reference model object.

If the projection is performed onto more than one submodel, the output from above is returned for each submodel, giving a list with one element for each submodel.

Examples

if (requireNamespace("rstanarm", quietly = TRUE)) {
  # Data:
  dat_gauss <- data.frame(y = df_gaussian$y, df_gaussian$x)

  # The "stanreg" fit which will be used as the reference model (with small
  # values for `chains` and `iter`, but only for technical reasons in this
  # example; this is not recommended in general):
  fit <- rstanarm::stan_glm(
    y ~ X1 + X2 + X3 + X4 + X5, family = gaussian(), data = dat_gauss,
    QR = TRUE, chains = 2, iter = 500, refresh = 0, seed = 9876
  )

  # Variable selection (here without cross-validation and with small values
  # for `nterms_max`, `nclusters`, and `nclusters_pred`, but only for the
  # sake of speed in this example; this is not recommended in general):
  vs <- varsel(fit, nterms_max = 3, nclusters = 5, nclusters_pred = 10,
               seed = 5555)

  # Projection onto the best submodel with 2 predictor terms (with a small
  # value for `nclusters`, but only for the sake of speed in this example;
  # this is not recommended in general):
  prj_from_vs <- project(vs, nterms = 2, nclusters = 10, seed = 9182)

  # Projection onto an arbitrary combination of predictor terms (with a small
  # value for `nclusters`, but only for the sake of speed in this example;
  # this is not recommended in general):
  prj <- project(fit, solution_terms = c("X1", "X3", "X5"), nclusters = 10,
                 seed = 9182)
}

[Package projpred version 2.1.2 Index]