panelr (version 1.0.0)

predict.wbm: Predictions and simulations from within-between models

Description

These methods facilitate fairly straightforward predictions and simulations from wbm models.

Usage

# S3 method for wbm
predict(
  object,
  newdata = NULL,
  se.fit = FALSE,
  raw = FALSE,
  use.re.var = FALSE,
  re.form = NULL,
  type = c("link", "response"),
  allow.new.levels = TRUE,
  na.action = na.pass,
  ...
)
# S3 method for wbm
simulate(
  object,
  nsim = 1,
  seed = NULL,
  use.u = FALSE,
  newdata = NULL,
  raw = FALSE,
  newparams = NULL,
  re.form = NA,
  type = c("link", "response"),
  allow.new.levels = FALSE,
  na.action = na.pass,
  ...
)

Arguments

object

a fitted model object

newdata

data frame for which to evaluate predictions.

se.fit

Include standard errors with the predictions? Note that these standard errors by default include only fixed effects variance. See details for more info. Default is FALSE.

raw

Is newdata a merMod model frame or panel_data? TRUE indicates a merMod-style newdata, with all of the extra columns created by wbm.

use.re.var

If se.fit is TRUE, include random effects variance in standard errors? Default is FALSE.

re.form

(formula, NULL, or NA) specify which random effects to condition on when predicting. If NULL, include all random effects; if NA or ~0, include no random effects.

type

character string - either "link", the default, or "response" indicating the type of prediction object returned.

allow.new.levels

logical if new levels (or NA values) in newdata are allowed. If FALSE (default), such new values in newdata will trigger an error; if TRUE, then the prediction will use the unconditional (population-level) values for data with previously unobserved levels (or NAs).

na.action

function determining what should be done with missing values for fixed effects in newdata. The default is to predict NA: see na.pass.

...

When boot and se.fit are TRUE, any additional arguments are passed to lme4::bootMer().

nsim

positive integer scalar - the number of responses to simulate.

seed

an optional seed to be used in set.seed immediately before the simulation so as to generate a reproducible sample.

use.u

(logical) if TRUE, generate a simulation conditional on the current random-effects estimates; if FALSE generate new Normally distributed random-effects values. (Redundant with re.form, which is preferred: TRUE corresponds to re.form = NULL (condition on all random effects), while FALSE corresponds to re.form = ~0 (condition on none of the random effects).)

newparams

new parameters to use in evaluating predictions, specified as in the start parameter for lmer or glmer -- a list with components theta and beta and (for LMMs or GLMMs that estimate a scale parameter) sigma

Details

For wbm models, predict() operates in two main modes:

• raw = FALSE (the default): newdata is treated as panel-style data. If it is not already a panel_data() object, it is converted using the id and wave variables from the original model. The within / between decomposition and any detrending are recomputed for newdata before passing the resulting design matrix to lme4 via jtools::predict_merMod() on the underlying merMod object.

• raw = TRUE: newdata is expected to already be on the "model matrix" scale used by the fitted wbm object, including internal columns such as imean(...) and any processed interaction terms. In this case, panelr does not recompute within / between pieces and simply forwards newdata to jtools::predict_merMod().

When newdata is not panel_data and raw = FALSE, predict.wbm() will synthesize missing id or wave columns when possible in order to build a valid panel structure (for example, when re.form = ~0). Informational messages are emitted in these cases. For most within between use cases it is safer and more transparent to explicitly create a panel_data object with the desired id and wave variables before calling predict().

For models fit with model = "within", predictions from predict.wbm() reflect the within specification, which is parameterized using centered within unit effects and any specified between components. As a consequence, predict(wbm_obj) for a within model is not in general identical to predict(to_merMod(wbm_obj)) on the internal lmerMod / glmerMod object, even when using the same re.form argument, because the fixed effect structure differs. This is by design: predict.wbm() always works on the within between representation defined by the original wbm() call, while to_merMod() exposes the underlying mixed model fit directly.

Examples

data("WageData")
wages <- panel_data(WageData, id = id, wave = t)
model <- wbm(lwage ~ lag(union) + wks, data = wages)
# By default, assumes you're using the processed data for newdata
predict(model)