Learn R Programming

DoseFinding (version 0.5-5)

MCPMod: Perform MCPMod analysis of a data set

Description

Tests for a dose-response effect using a model-based multiple contrast test (see MCPtest), selects one (or several) model(s) from the significant shapes, fits them using fitDRModel and estimates the MED or the ED (see MED.DRMod, ED.DRMod). For details see Bretz et al. (2005).

Usage

MCPMod(formula, data, models = NULL, addCovars = ~1,
     contMat = NULL, critV = NULL, off = NULL, scal = NULL,
     alpha = 0.025, alternative = c("one.sided", "two.sided"),
     direction = c("increasing", "decreasing"),
     selModel = c("maxT", "AIC", "BIC", "aveAIC", "aveBIC"),
     doseEst = c("MED2", "MED1", "MED3", "ED", "MED1old", "MED2old", "MED3old"),
     doseEstPar = NULL, std = TRUE, start = NULL,
     uModPars = NULL, addArgs = NULL, clinRel = NULL,
     lenDose = 101, pWeights = NULL, fitControl = fit.control(),
     optimizer = c("nls", "nls&bndnls", "bndnls"), pVal = TRUE,
     testOnly = FALSE, mvtcontrol = mvtnorm.control(),
     na.action = na.fail, bnds = NULL, uGrad = NULL)

Arguments

formula
A formula object specifying the names of the response and the dose variable contained in 'data' (in the form response ~ dose). Additional covariates need to be specified via the addCovars argument, see below for details.
data
Data frame containing the dose response data and possible additional covariates specified in the argument 'addCovars'. The code assumes that there are columns corresponding to the dose and the response variable are named "dose" and "resp".
models
A list specifying the candidate models. The names of the list entries should be equal to the names of the model functions. The list entries should be equal to the guesstimates. See the Examples (ii) for details on this topic. If the
addCovars
Additional covariates to be adjusted for linearily in the model should be specified as a formula (as is standard in R). By default there is only an intercept included in the model (note that an intercept should always be included). See the
contMat
Optional matrix containing the optimal contrasts in the columns. The names of the columns should be equal to the names of the underlying model functions. If specified the code does not calculate the optimal contrasts.
critV
Critical value, if NULL, no critical value will be calculated, and the test decision will be based on the p-values. If critV = TRUE the critical value will be calculated (the test decision will be based on the critical value). If critV is e
off
Fixed 'offset' parameter needed when the linear in log model is used. See the documentation of the linear in log model: linlog. When off = NULL by default (maximum dose)*0.1 is u
scal
Fixed scale parameter needed when the beta model is used. See the documentation of the beta model: betaMod. When scal = NULL by default (maximum dose)*1.2 is used for scal<
alpha
Level of significance for the multiple contrast test (defaults to 0.025)
alternative
Character determining the alternative for the multiple contrast trend test. Note that two sided alternatives, in most situations, do not really make sense. When the contrast matrix is handed over via the 'contMat' argument the alternative a
direction
Character determining the trend direction of the data, which one wants to investigate (e.g., if one wants to investigate whether the response gets larger with increasing dose, direction should be equal to "increasing").
selModel
Optional character vector specifying the model selection criterion for dose estimation. Possible values are "maxT": Selects the model corresponding to the largest t-statistic (this is the default). "AIC": Selects model with smallest AIC "BIC":
doseEst
Determines which dose estimator to use, possible values are "MED2", "MED1", "MED3", "MED1old", "MED2old", "MED3old" and "ED". The MED1-MED3 estimators calculate the MED based on the dose effect curve. The dose effect curve takes the differe
doseEstPar
Numeric, defining parameter used for dose estimators. For the MED-type estimators doseEstPar determines the confidence level gamma used in the estimator. The used confidence level is given by 1-2*doseEstPar. The de
std
Optional logical value determining, whether standardized versions should be assumed for calculation of the optimal contrasts. If FALSE all model parameters need to be specified in the models argument (also location and scale parameters).
start
List containing starting values for the nls fitting algorithm. 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 corresponding names for the model paramete
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.
clinRel
Numeric of length one, specifying the clinical relevance threshold (needed for the MED estimate).
lenDose
Numeric vector specifying the number of points in the dose-range to search for the dose estimate, defaults to 101.
pWeights
Optional vector specifying prior weights for the different models. Should be a named vector with names matching the names of the models list. Only relevant if selModel = "aveAIC" or "aveBIC"
fitControl
List of parameters to be used when fitting the dose response models, see the fit.control function for details.
optimizer
Type of optimizer to be used for calculating the parameter estimates of the dose-response model. Option "nls" uses the nls function with "plinear" option. Option "bndnls" uses a non-linear least squares algorithm with simple
pVal
Optional logical determining whether p-values should be calculated, defaults to TRUE. If the critical value is supplied, p-values will not be calculated.
testOnly
Logical value determining, whether only the multiple comparisons test should be performed. See Examples (v) below. If you are really only interested in the testing part consider using the MCPtest
mvtcontrol
A list specifying additional control parameters for the qmvt and pmvt calls in the code, see also mvtnorm.control for details.
na.action
A function which indicates what should happen when the data contain NAs.
bnds
A list containing bounds for non-linear parameters, needed when optimizer="bndnls". The list elements should correspond to the bounds for the individual models, the list elements should be named according to the underlying dose-response mode
uGrad
Function to return the gradient of a user defined model, see Examples (iii) below.

Value

  • An object of class MCPMod, with the following entries:
  • signfLogical indicating, whether multiple contrast test is significant
  • model1Model with largest contrast test statistic
  • model2Model(s) used for estimation of target doses
  • inputA list with information on input parameters for the MCPMod function: formula, models, off, scal, alpha, alpha, first entry of alternative, direction, first entry of selModel, doseEst, std, doseEstPar, uModArgs, addArgs, start, uGrad, clinRel, lenDose, pVal, testOnly, first entry of optimizer, addCovars
  • dataThe data set.
  • contMatThe contrast matrix.
  • corMatThe correlation matrix.
  • cValThe critical value for the multiple contrast test.
  • tStatThe contrast test-statistics. If 'pVal=TRUE' the p-values are also attached.
  • fmList containing the dose-response model(s) used for dose-estimation. These are all DRMod objects, which can be further used. See the fitDRModel function for details on DRMod objects and methods that can be applied to DRMod objects. Note that the data set used for fitting the DRMod object is not included in the objects, so that most methods (for example the predict method when se.fit = T or the vcov method) require to specify the data on which the model was fitted via the data argument of the methods.
  • estDoseEstimated dose(s), in case of model averaging the dose estimates under the individual models are attached.
  • Note: If testOnly=TRUE, or no model is significant, the object does not contain fm and estDose entries

Details

This function performs the multiple comparisons and modelling (MCPMod) procedure presented in Bretz et al. (2005). The method consists of two steps: (i) MCP step (apply MCPtest function): The function calculates the optimal contrasts (if not supplied) and the contrast test statistics. In the calculation of the critical value and p-values multiplicity is taken into account. (ii) Modelling step (apply fitDRModel function): If there is at least one significant contrast, one model or a combination of models is chosen (depending on the selModel argument) for dose estimation. In case of non-convergence of certain non-linear models the remaining significant models are used. Finally the target dose is estimated. Built in models are the linear, linear in log, emax, sigmoid emax, logistic, exponential, quadratic and beta model (for their definitions see Dose-Response Models). Users may hand over their own model functions for details have a look at the Example (iii).

References

Bornkamp B., Pinheiro J. C., and Bretz, F. (2009). MCPMod: An R Package for the Design and Analysis of Dose-Finding Studies, Journal of Statistical Software, 29(7), 1--23 Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining multiple comparisons and modeling techniques in dose-response studies, Biometrics, 61, 738--748 Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and analysis of dose finding studies combining multiple comparisons and modeling procedures, Journal of Biopharmaceutical Statistics, 16, 639--656 Pinheiro, J. C., Bretz, F., and Branson, M. (2006). Analysis of dose-response studies - modeling approaches, in N. Ting (ed.). Dose Finding in Drug Development, Springer, New York, pp. 146--171 Bretz, F., Pinheiro, J. C., and Branson, M. (2004), On a hybrid method in dose-finding studies, Methods of Information in Medicine, 43, 457--460 Buckland, S. T., Burnham, K. P. and Augustin, N. H. (1997). Model selection an integral part of inference, Biometrics, 53, 603--618 Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley.

See Also

MCPtest, fitDRModel, plot.MCPMod, predict.MCPMod, logistic, sigEmax, linlog, linear, quadratic, emax, betaMod, exponential, mvtnorm.control, getBnds

Examples

Run this code
## (i)
## example from Biometrics paper p. 743
data(biom)
models <- list(linear = NULL, linlog = NULL, emax = 0.2,
            exponential = c(0.279,0.15), quadratic = c(-0.854,-1))
dfe <- MCPMod(resp ~ dose, biom, models, alpha = 0.05, doseEstPar = 0.05,
           pVal = TRUE, selModel = "maxT", doseEst = "MED2old",
           clinRel = 0.4, off = 1)
## detailed information is available via summary
summary(dfe)
## plots data with selected model function
plot(dfe)

## example with IBS data
## now explicitly calculate critical value and perform
## model averaging based on the AIC
data(IBScovars)
models <- list(emax = 0.2, quadratic = -0.2, linlog = NULL)
dfe2 <- MCPMod(resp ~ dose, IBScovars, models, alpha = 0.05, critV = TRUE,
             pVal = TRUE, selModel = "aveAIC",
             clinRel = 0.25, off = 1)
dfe2
## illustrate some methods for MCPMod objects
summary(dfe2)
plot(dfe2, complData = TRUE)
plot(dfe2, CI = TRUE, clinRel = TRUE)

## use different optimizer (and include some models
## not converging using nls)
models <- list(quadratic = -0.2, linlog = NULL, betaMod = c(1,1),
               sigEmax = rbind(c(0.2,1), c(1, 3)))
dfe3 <- MCPMod(resp ~ dose, IBScovars, models, alpha = 0.05, pVal = TRUE,
             selModel = "aveAIC", clinRel = 0.25, off = 1,
             scal = 6, optimizer = "bndnls")
plot(dfe3)

## use additional linear covariates
data(IBScovars)
models <- list(emax = 0.2, quadratic = -0.2, linlog = NULL)
dfe4 <- MCPMod(resp ~ dose, IBScovars, models, addCovars = ~gender,
             alpha = 0.05, pVal = TRUE,
             selModel = "aveAIC", clinRel = 0.25, off = 1)
plot(dfe4, CI = TRUE) # plot method now only plots the effect curves

## simulate dose-response data
set.seed(1)
dfData <- genDFdata(model = "emax", argsMod = c(e0 = 0.2, eMax = 1, 
          ed50 = 0.05), doses = c(0,0.05,0.2,0.6,1), n=20, sigma=0.5)
models <- list(emax = 0.1, logistic = c(0.2, 0.08), 
             betaMod = c(1, 1))
## hand over starting values manually
start <- list(emax = c(ed50 = 0.1), logistic = c(ed50=0.05, delta =
              0.1), betaMod = c(delta1 = 0.5, delta2 = 0.5))
dfe5 <- MCPMod(resp ~ dose, dfData, models, clinRel = 0.4, critV = 1.891, 
           scal = 1.5, start = start)

## (ii) Example for constructing a model list

## Contrasts to be included:
## Model             guesstimate(s) for stand. model parameter(s) (name)
## linear            -
## linear in log     -
## Emax              0.2 (ED50)
## Emax              0.3 (ED50)
## exponential       0.7 (delta)
## quadratic        -0.85 (delta)
## logistic          0.4  0.09 (ED50, delta)
## logistic          0.3  0.1 (ED50, delta)
## betaMod           0.3  1.3 (delta1, delta2) 
## sigmoid Emax      0.5  2 (ED50, h)
##
## For each model class exactly one list entry needs to be used.
## The names for the list entries need to be written exactly 
## as the model functions ("linear", "linlog", "quadratic", "emax", 
## "exponential", "logistic", "betaMod", "sigEmax").
## For models with no parameter in the standardized model just NULL is 
## specified as list entry.
## For models with one parameter a vector needs to be used with length
## equal to the number of contrasts to be used for this model class.
## For the models with two parameters in the standardized model a vector
## is used to hand over the contrast, if it is desired to use just one
## contrast. Otherwise a matrix with the guesstimates in the rows needs to
## be used. For the above example the models list has to look like this

list(linear = NULL, linlog = NULL, emax = c(0.2, 0.3),
     exponential = 0.7, quadratic = -0.85, logistic =
     rbind(c(0.4, 0.09), c(0.3, 0.1)),
     betaMod = c(0.3, 1.3), sigEmax = c(0.5, 2))

## Additional parameters (which will not be estimated) are the "off"
## parameter for the linlog model and the "scal" parameter for the
## beta model, which are not handed over in the model list.

## (iii) example for incorporation of a usermodel 
## simulate dose response data
dats <- genDFdata("sigEmax", c(e0 = 0, eMax = 1, ed50 = 2, h = 2),
              n = 50, sigma = 1, doses = 0:10)
## define usermodel
userMod <- function(dose, a, b, d){
  a + b*dose/(dose + d)
}
## define gradient
userModGrad <- 
    function(dose, a, b, d) cbind(1, dose/(dose+d), -b*dose/(dose+d)^2)    
## name starting values for nls
start <- list(userMod=c(a=1, b=2, d=2))       
models <- list(userMod=c(0, 1, 1), linear = NULL)
dfe6 <- MCPMod(resp ~ dose, dats, models, clinRel = 0.4, selModel="AIC",
         start = start, uGrad = userModGrad)

## (iv) Contrast matrix and critical value handed over and not calculated
## simulate dose response data
dat <- genDFdata(mu = (0:4)/4, n = 20, 
                       sigma = 1, doses = (0:4)/4)
## construct optimal contrasts and critical value with planMM
doses <- (0:4)/4
mods <- list(linear = NULL, quadratic = -0.7)
pM <- planMM(mods, doses, 20)
fit <- MCPMod(resp ~ dose, dat, models = NULL, clinRel = 0.3,
           contMat = pM$contMat, critV = pM$critVal)

## (v) Use self constructed contrasts (and hand them over)
mu1 <- c(1, 2, 2, 2, 2)                      
mu2 <- c(1, 1, 2, 2, 2)                      
mu3 <- c(1, 1, 1, 2, 2)                      
mMat <- cbind(mu1, mu2, mu3)              
dimnames(mMat)[[1]] <- doses               
pM <- planMM(muMat = mMat, doses = doses, n = 20, cV = FALSE)
## use MCPMod only for testing part (see also MCPtest function)
fit <- MCPMod(resp ~ dose, dat, models = NULL, contMat = pM$contMat,
        pVal = TRUE, testOnly = TRUE, critV=TRUE)
summary(fit)

Run the code above in your browser using DataLab