fitDRModel: Fit a non-linear regression model with linear covariates.

Description

Fits a non-linear regression model (possibly with linear covariates) by minimizing the least squares criterion. The implemented algorithms are based on the idea performing the non-linear optimization only for the non-linear parameters and solving linear least squares problems in each iteration (see Golub and Pereyra, 2003 for a review). The optimizer "nls" uses the nls function with plinear option. Option "bndnls" imposes bounds on the non-linear parameters (a sufficient condition for existence of the least squares estimate, see for example Seber and Wild (2003)), and is described in more details below, see the argument 'optimizer'.

Usage

fitDRModel(formula, data, model = NULL, addCovars = ~1, na.action = na.fail,
     optimizer = c("nls", "nls&bndnls", "bndnls"), bnds = NULL, start = NULL,
     nlscontrol = nls.control(), gridSize =
     list(dim1 = 30, dim2 = 144), nlminbcontrol = list(),
     optimizetol = .Machine$double.eps^0.5, off = NULL,
     scal = NULL, keep.data = TRUE, uModPars = NULL, addArgs = NULL)

Arguments

formula

A formula object specifying the response and the dose variable (in the form response ~ dose). Additional covariates need to be specified via the addCovars argument, see below for details.

data

Dose response data frame containing the variables needed for fitting the non-linear model.

model

The non-linear model to be used for fitting the data. Built-in models are "linlog", "linear", "quadratic", "emax", "exponential", "sigEmax", "betaMod" and "logistic" (see Dose-Response Models).

addCovars

Formula specifying additional (linear) covariates

na.action

A function which indicates what should happen when the data contain NAs.

optimizer

A character specifying the optimizer to be used. Option "nls" uses the nls function with "plinear" option. Option "bndnls" uses a non-linear least squares algorithm with simple box constraints on the (non-linear) parameters (th

bnds

Bounds for non-linear parameters, needed when optimizer="bndnls". When the dose-response model has only one non-linear parameter (for example Emax or exponential model), bnds needs to be a vector containing upper and lower boun

start

List containing starting values for the "nls" fitting algorithm (for "bndnls" no starting values are needed). The names of the list elements need to be equal to the names of the model functions. The names of the starting vector should equal the

nlscontrol

List of parameters to be used in the calls to the nls function. See also nls.control function.

gridSize

List with two components (dim1, dim2) giving the size of the grid used for "bndnls" optimization for 1-dim and 2-dim case (in 2-dim case the smallest generalized lattice point set larger than or equal to the number given is used)

nlminbcontrol

List of parameters to be used in the calls to the nlminb function. See the control argument of nlminb for details.

optimizetol

tol parameter of the one dimensional optimize function. See optimize for details.

off

Fixed offset parameter needed when the linear in log model is used. See also documentation of the linear in log model: "linlog". A reasonable default is to use (maximum dose)*0.1 for off.

scal

Fixed scale parameter needed when the beta model is used. See also documentation of the beta model: betaMod. A reasonable default is to use (maximum dose)*1.2 for scal.

keep.data

Logical: should the data argument be saved as part of the model object?

uModPars

Optional character vector with names/expressions of user-defined model parameters (names(start) used by default).

addArgs

Optional character vector with names of additional arguments (variables) to user-defined model.

Value

An object of class DRMod. A list with entries
coefA vector containing the coefficients of the fitted model. See also coef.DRMod
RSS2The residual sum of squares of the fitted model
dfThe degrees of freedom of the fit
addCovarsThe formula for the additional covariates used for fitting
Additionally the object contains a variety of additional information as attributes.

References

Golub, G. and Pereyra, V. (2003). Seperable nonlinear least squares: the variable projection method and its applications, Inverse Problems, 19, R1--R26 Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley.

Examples

Run this code

# Example (i): Overview of capabilities
data(biom)
fitemax <- fitDRModel(resp ~ dose, biom, "emax")

# a lot of things can be done with a DRMod object
# basic information
fitemax
# a bit more information
summary(fitemax)
# predicting
predict(fitemax, newdata=data.frame(dose = c(0,0.5,1)))
# predictions with standard error
predict(fitemax, newdata=data.frame(dose = c(0,0.5,1)), se.fit = TRUE)
# plotting
plot(fitemax, type = "DRCurve")
plot(fitemax, type = "EffectCurve") # difference from placebo
# extracting coefficients
coef(fitemax)
# (asymptotic) covariance matrix of estimates
vcov(fitemax)
# confidence intervals for estimates
intervals(fitemax, level = 0.95)
# fitted log-likelihood
logLik(fitemax)
# extracting AIC (or BIC)
AIC(fitemax)
# calculate the minimum effective dose
MED(fitemax, type = "MED2", clinRel = 0.2, gamma = c(0.05, 0.1))
# calculate effective dose
ED(fitemax, p = 0.5)

# quite a few models are built in
fitsigEmax <- fitDRModel(resp ~ dose, biom, "sigEmax")
plot(fitsigEmax, type = "DRCurve")

fitlog <- fitDRModel(resp ~ dose, biom, "logistic")
plot(fitlog, type = "DRCurve")

fitQuad <- fitDRModel(resp ~ dose, biom, "quadratic")
plot(fitQuad, type = "DRCurve")

# need additional scal parameter for beta model
fitBeta <- fitDRModel(resp ~ dose, biom, "betaMod", scal = 1.2)
plot(fitBeta, type = "DRCurve")

# additionally there is the exponential, the linear
# and linear in log model... 

# Example (ii): Fitting with linear covariates
# specify those via addCovars
data(IBScovars)
fitemax <- fitDRModel(resp ~ dose, IBScovars, "emax", addCovars = ~gender)
plot(fitemax, type = "EffectCurve")
plot(fitemax, type = "DRCurve", addCovarVals=data.frame(gender = as.factor(1)))
plot(fitemax, type = "DRCurve", addCovarVals=data.frame(gender = as.factor(2)))

# for logistic model use bndnls (plain nls does not converge)
fitlog <- fitDRModel(resp ~ dose, IBScovars, "logistic", addCovars = ~gender,
                     optimizer = "bndnls", bnds = rbind(c(1,4), c(0,1)))
# optimum lies on the boundary of bound
plot(fitlog, type = "EffectCurve")

# Example (iii): fitting a user model
# is a cubic polynomial model
userModel <- function(dose, par0, par1, par2, par3){
  par0+par1*dose+par2*dose^2+par3*dose^3
}

userModelGrad <- function(dose, par0, par1, par2, par3){
  cbind(1, dose, dose^2, dose^3)  
}

fit <- fitDRModel(resp ~ dose, biom, "userModel", addCovars = ~1, 
     start = c(par0=0.2, par1=3, par2=-5, par3=3),
     uModPars = NULL, addArgs = NULL)
plot(fit, uGrad = userModelGrad)

Run the code above in your browser using DataLab