nlme.predict: Prediction tool for nlme object

In qPharmetra/qpToolkit: qPharmetra R Tools

Prediction tool for nlme object

Description

Predict residuals, partial residuals or uncertainty predictions for an nlme.object. This function will also take different data set (argument newdata) to simulate out of the box although the nlme object does require the predictors, independent variable, and the grouping variable to be present.

Usage

## S3 method for class 'predict'
nlme(
  func,
  object,
  newdata = NULL,
  subset.modeldata,
  xrange = 50,
  nx = NULL,
  level = 1,
  method = "partial.residuals",
  use.etas = "estimated",
  uncertainty = FALSE,
  reference.subset = NULL,
  nrep = 20
)

Arguments

func	the function to evaluate over the model, e.g. effect ~ time | treatment the variables in func need to be evaluable in getData(object) and getCovariateFormula(object)
object	nlme object
newdata	a new data set, requiring the predictors, independent variable, and the grouping variable to be present.
subset.modeldata	character string to be evaluated over the data in order to subset the predictions and observations (e.g. "DOSE == 100")
xrange	number of equal-space independent varaible (x) default value = 50,
nx	number of bins of independenet ,
level	grouping level of the nlme object to create predictions at (defaults to 1, the highest grouping level)
method	Either one of 'partial.residuals' (default), 'prediction' (the traditional predict(nlme.object)), or 'residuals' (doing plot(resid ~ any.column).
use.etas	'estimated' (default) which uses the estimated deviations for each group level) or 'sampled' in case one wants to sample using the estimate of random variability
uncertainty	logical (defaults to F) determining if simulation should be done across uncertainty
reference.subset	character string to be evaluated over the data in order to subset the predictions and observations in ordeer to create a 'change from' perspective plot (works for method 'prediction' and 'partial residuals')
nrep	number of replicates to simulate. Defaults to 20.

Value

a graph or a multi-level list with observed and predicted output (class c('nlmefit','fit','list'))

Examples

pkpdData = example.pkpdData()
EFF.1comp.1abs <- function(dose, tob, cl, v, ka, keo)
{
  # Effect-site concentration for 1-compartment model, 1st-order absorption

  kel = cl / v

  # Define coefficients
  A = 1/(kel-ka) / (keo-ka)
  B = 1/(ka-kel) / (keo-kel)
  C = 1/(ka-keo) / (kel-keo)

  # Return effect-site concentration
  dose*ka*keo/v * (A*exp(-ka*tob) + B*exp(-kel*tob) + C*exp(-keo*tob))
}
fit.PD004.nlme = nlme.run(
  model = value ~ base + EFF.1comp.1abs(dose, time, cl * exp(cl.eta), v, ka, keo),
  data = pkpdData[pkpdData$type == "PD" & pkpdData$dose > 0 & pkpdData$value > 0.5, ],
  fixed = base + cl + v + ka + keo ~ 1,
  random = cl.eta ~ 1,
  groups = ~ id,
  start = c(base = 1, cl = 1, v = 10, ka = 1, keo = 0.01),
  problem = "True Model",
  reference = 4)
summary(fit.PD004.nlme$object)
nlme.extract(fit.PD004.nlme$object)$table

# simple fit vs time
fit.PD004.pred.nlme = nlme.predict(func = value ~ time , fit.PD004.nlme$object)
plot(fit.PD004.pred.nlme)
fit.PD004.pred.nlme = nlme.predict(
  func = value ~ time , fit.PD004.nlme$object, method = "partial.residuals"
)
plot(fit.PD004.pred.nlme) ## this is the same: PARTIAL RESIDUALS
fit.PD004.pred.nlme = nlme.predict(
  func = value ~ time , fit.PD004.nlme$object, method = "prediction"
)
plot(fit.PD004.pred.nlme) ## now we get simply the prediction for all xCovariate

## note that prediction and partial residual type of model fit plots are very different

# fit vs time by dose
fit.PD004.pred.nlme = nlme.predict(func = value ~ time | dose, fit.PD004.nlme$object)
plot(fit.PD004.pred.nlme)
fit.PD004.pred.nlme = nlme.predict(
  func = value ~ time | dose, fit.PD004.nlme$object, method = "residuals"
)
plot(fit.PD004.pred.nlme, yLimits = c(-1,1))
plot(fit.PD004.pred.nlme, yLimits = c(-1,1), abline = list(h = 0, lty = 2))

qPharmetra/qpToolkit documentation built on May 24, 2023, 8:52 a.m.