olmm-predict: Predict outcome probabilities and responses for `olmm` objects

Description

fitted and predict method for olmm objects. The function implements mainly the prediction methods of Skrondal and Rabe-Hesketh (2009).

Usage

# S3 method for olmm
fitted(object, ...)
# S3 method for olmm
predict(object, newdata = NULL,
        type = c("link", "response", "prob", "class", "ranef"),
        ranef = FALSE, na.action = na.pass, ...)

Arguments

object

a fitted olmm object.

newdata

data frame for which to evaluate predictions.

type

character string. type = "response" and type = "prob" yield response probabilities, type = "class" the response category with highest probability and type = "link" the linear predictor matrix. type = "ranef" yields the predicted random effects, see ranef.olmm.

ranef

logical or numeric matrix. See details.

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.

...

optional additional parameters. Includes offset and subset.

Value

A matrix or a vector of predicted values or response probabilities.

Details

If type = "link" and ranef = FALSE, the fixed effects components are computed. The random effect components are ignored.

If type = "link" and ranef = TRUE, the fixed effect components plus the random effect components are computed. The function will look for whether random coefficients are available for the subjects (i.e. clusters) in newdata. If so, it extracts the corresponding random effects as obtained by ranef. For new subjects in newdata the random effects are set to zero. If newdata does not contain a subject vector, the random effects are set to zero.

If type = "link" and ranef is a matrix, the fixed effect components plus the random effect components with the random coefficients from the assigned matrix are computed. Notice that newdata should contain a subject vector to assign the random coefficients. This prediction method is, amongst others, proposed in Skrondal and Rabe-Hesketh (2009), Sec. 7.1.

The two options type = "response" and type = "prob" are identical and type = "class" extracts the response category with the highest probability. Hence, the prediction mechanism is the same for all three options.

Given newdata contains a subject vector, type = "response" combined with ranef = FALSE yields for new subjects the population-averaged response probabilities (Skrondal and Rabe-Hesketh, Sec. 7.2) and for existing subjects the cluster-averaged prediction (Skrondal and Rabe-Hesketh 2009, Sec. 7.3). If no subject vector is assigned the function assumes that all subjects are new and therefore yields the population-averaged response probabilities (Skrondal and Rabe-Hesketh 2009, Sec. 7.2).

The option type = "response" combined with ranef = TRUE works equivalent to type = "link" combined with ranef = TRUE.

If the model does not contain random effects, the argument ranef is ignored.

References

Skrondal, A., S. Rabe-Hesketh (2009). Prediction in Multilevel Generalized Linear Models. Journal of the Royal Statistical Society A, 172(3), 659--687.

Examples

Run this code

# NOT RUN {
## ------------------------------------------------------------------- #
## Example: Schizophrenia
## ------------------------------------------------------------------- #

data(schizo)

## omit subject 1103 and the last observations of 1104 and 1105 
subs <- c(1:4, 8, 11)

dat.train <- schizo[-subs, ] # training data
dat.valid <- schizo[ subs, ] # test data

## fit the model
model <- olmm(imps79o ~ tx + sqrt(week) + tx:sqrt(week) + re(1|id), dat.train)

## prediction on the predictor scale
## ---------------------------------

## random effects are set equal zero
predict(model, newdata = dat.valid, type = "link", ranef = FALSE)

## .. or equally with self-defined random effects
ranef <- matrix(0, 3, 1)
rownames(ranef) <- c("1103", "1104", "1105")
predict(model, newdata = dat.valid, type = "link", ranef = ranef)

## use random effects for the subjects 1104 and 1105. 
predict(model, newdata = dat.valid, type = "link", ranef = TRUE)

## prediction on the response scale
## --------------------------------

## use random effects for the subjects 1104 and 1105. 
predict(model, newdata = dat.valid, type = "response", ranef = FALSE)
predict(model, newdata = dat.valid, type = "prob", ranef = FALSE) # .. or, equally
predict(model, newdata = dat.valid, type = "class", ranef = FALSE)

## treat all individuals as new (subject vector is deleted)
predict(model, newdata = dat.valid[,-1], type = "response", ranef = FALSE)

## use random effects for the subjects 1104 and 1105. 
predict(model, newdata = dat.valid, type = "response", ranef = TRUE)

## use self defined random effects
ranef <- matrix(0, 3, 1)
rownames(ranef) <- c("1103", "1104", "1105")
predict(model, newdata = dat.valid, type = "response", ranef = ranef)

## predict random effects
## ----------------------

head(predict(model, type = "ranef"))
head(ranef(model)) # .. or, equally
# }

Run the code above in your browser using DataCamp Workspace