R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Define dose-response models

Mods	R Documentation

Define dose-response models

Description

The Mods functions allows to define a set of dose-response models. The function is used as input object for a number of other different functions.

The dose-response models used in this package (see drmodels for details) are of form

f(d) = theta0+theta1 f0(d,theta2)

where the parameter theta2 is the only non-linear parameter and can be one- or two-dimensional, depending on the used model.

One needs to hand over the effect at placebo and the maximum effect in the dose range, from which theta0,theta1 are then back-calculated, the output object is of class "Mods". This object can form the input for other functions to extract the mean response (getResp) or target doses (TD and ED) corresponding to the models. It is also needed as input to the functions powMCT, optDesign

Some models, for example the beta model (scal) and the linlog model (off) have parameters that are not estimated by the code, they need to be specified via the addArgs argument.

NOTE: If a decreasing effect is beneficial for the considered response variable it needs to specified here, either by using direction = "decreasing" or by specifying a negative "maxEff" argument.

Usage

Mods(..., doses, placEff = 0, maxEff,
     direction = c("increasing", "decreasing"), addArgs=NULL,
     fullMod = FALSE)

getResp(fmodels, doses)

## S3 method for class 'Mods'
plot(x, nPoints = 200, superpose = FALSE, 
     xlab = "Dose", ylab = "Model means", modNams = NULL, 
     plotTD = FALSE, Delta, ...)

Arguments

`...`	In function Mods: Dose-response model names with parameter values specifying the guesstimates for the theta2 parameters. See `drmodels` for a complete list of dose-response models implemented. See below for an example specification. In function plot.Mods: Additional arguments to the xyplot call.
`doses`	Dose levels to be used, this needs to include placebo.
`addArgs`	List containing two entries named "scal" and "off" for the "betaMod" and "linlog". When addArgs is NULL the following defaults are used list(scal = 1.2max(doses), off = 0.01max(doses), nodes = doses).
`fullMod`	Logical determining, whether the model parameters specified in the Mods function (via the ... argument) should be interpreted as standardized or the full model parameters.
`placEff, maxEff`	Specify used placebo effect and the maximum effect over placebo. Either a numeric vector of the same size as the number of candidate models or of length one. When these parameters are not specified placEff = 0 is assumed, for maxEff = 1 is assumed, if direction = "increasing" and maxEff = -1 is assumed, for direction = "decreasing".
`direction`	Character determining whether the beneficial direction is increasing or decreasing with increasing dose levels. This argument is ignored if maxEff is specified.
`fmodels`	An object of class Mods
`Delta`	Delta: The target effect size use for the target dose (TD) (Delta should be > 0).
`x`	Object of class Mods with type Mods
`nPoints`	Number of points for plotting
`superpose`	Logical determining, whether model plots should be superposed
`xlab, ylab`	Label for y-axis and x-axis.
`modNams`	When modNams == NULL, the names for the panels are determined by the underlying model functions, otherwise the contents of modNams are used.
`plotTD`	plotTD is a logical determining, whether the TD should be plotted. Delta is the target effect to estimate for the TD.

Value

Returns an object of class "Mods". The object contains the specified model parameter values and the derived linear parameters (based on "placEff" and "maxEff") in a list.

Author(s)

Bjoern Bornkamp

References

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

Examples

## Example on how to specify candidate models

## Suppose one would like to use the following models with the specified
## guesstimates for theta2, in a situation where the doses to be used are
## 0, 0.05, 0.2, 0.6, 1

## Model            guesstimate(s) for theta2 parameter(s) (name)
## linear           -
## linear in log    -
## Emax             0.05 (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)
## linInt           0.5 0.75 1 1 (perc of max-effect at doses)
## linInt           0.5 1 0.7 0.5 (perc of max-effect at doses)

## for the linInt model one specifies the effect over placebo for
## each active dose.
## The fixed "scal" parameter of the betaMod is set to 1.2
## The fixed "off"  parameter of the linlog is set to 0.1
## These (standardized) candidate models can be specified as follows

models <- Mods(linear = NULL, linlog = NULL, emax = c(0.05, 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),
               linInt = rbind(c(0.5, 0.75, 1, 1), c(0.5, 1, 0.7, 0.5)),
               doses = c(0, 0.05, 0.2, 0.6, 1),
               addArgs = list(scal=1.2, off=0.1))
## "models" now contains the candidate model set, as placEff, maxEff and
## direction were not specified a placebo effect of 0 and an effect of 1
## is assumed

## display of specified candidate set
plot(models)

## example for creating a candidate set with decreasing response 
doses <- c(0, 10, 25, 50, 100, 150)
fmodels <- Mods(linear = NULL, emax = 25,
                   logistic = c(50, 10.88111), exponential = 85,
                   betaMod = rbind(c(0.33, 2.31), c(1.39, 1.39)),
                   linInt = rbind(c(0, 1, 1, 1, 1),
                                  c(0, 0, 1, 1, 0.8)), 
                   doses=doses, placEff = 0.5, maxEff = -0.4,
                   addArgs=list(scal=200))
plot(fmodels)
## some customizations (different model names, symbols, line-width)
plot(fmodels, lwd = 3, pch = 3, cex=1.2, col="red",
     modNams = paste("mod", 1:8, sep="-"))

## for a full-model object one can calculate the responses
## in a matrix
getResp(fmodels, doses=c(0, 20, 100, 150))

## calculate doses giving an improvement of 0.3 over placebo
TD(fmodels, Delta=0.3, direction = "decreasing")
## discrete version
TD(fmodels, Delta=0.3, TDtype = "discrete", doses=doses, direction = "decreasing")
## doses giving 50% of the maximum effect
ED(fmodels, p=0.5)
ED(fmodels, p=0.5, EDtype = "discrete", doses=doses)

plot(fmodels, plotTD = TRUE, Delta = 0.3)

## example for specifying all model parameters (fullMod=TRUE)
fmods <- Mods(emax = c(0, 1, 0.1), linear = cbind(c(-0.4,0), c(0.2,0.1)),
              sigEmax = c(0, -1.1, 0.5, 3),
              doses = 0:4, fullMod = TRUE)
getResp(fmods, doses=seq(0,4,length=11))
## calculate doses giving an improvement of 0.3 over placebo
TD(fmods, Delta=0.3)
## discrete version
TD(fmods, Delta=0.3, TDtype = "discrete", doses=0:4)
## doses giving 50% of the maximum effect
ED(fmods, p=0.5)
ED(fmods, p=0.5, EDtype = "discrete", doses=0:4)
plot(fmods)

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(DoseFinding)
Loading required package: lattice
Loading required package: mvtnorm
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/DoseFinding/Mods.Rd_%03d_medium.png", width=480, height=480)
> ### Name: Mods
> ### Title: Define dose-response models
> ### Aliases: Mods getResp plot.Mods
> 
> ### ** Examples
> 
> ## Example on how to specify candidate models
> 
> ## Suppose one would like to use the following models with the specified
> ## guesstimates for theta2, in a situation where the doses to be used are
> ## 0, 0.05, 0.2, 0.6, 1
> 
> ## Model            guesstimate(s) for theta2 parameter(s) (name)
> ## linear           -
> ## linear in log    -
> ## Emax             0.05 (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)
> ## linInt           0.5 0.75 1 1 (perc of max-effect at doses)
> ## linInt           0.5 1 0.7 0.5 (perc of max-effect at doses)
> 
> ## for the linInt model one specifies the effect over placebo for
> ## each active dose.
> ## The fixed "scal" parameter of the betaMod is set to 1.2
> ## The fixed "off"  parameter of the linlog is set to 0.1
> ## These (standardized) candidate models can be specified as follows
> 
> models <- Mods(linear = NULL, linlog = NULL, emax = c(0.05, 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),
+                linInt = rbind(c(0.5, 0.75, 1, 1), c(0.5, 1, 0.7, 0.5)),
+                doses = c(0, 0.05, 0.2, 0.6, 1),
+                addArgs = list(scal=1.2, off=0.1))
> ## "models" now contains the candidate model set, as placEff, maxEff and
> ## direction were not specified a placebo effect of 0 and an effect of 1
> ## is assumed
> 
> ## display of specified candidate set
> plot(models)
> 
> ## example for creating a candidate set with decreasing response 
> doses <- c(0, 10, 25, 50, 100, 150)
> fmodels <- Mods(linear = NULL, emax = 25,
+                    logistic = c(50, 10.88111), exponential = 85,
+                    betaMod = rbind(c(0.33, 2.31), c(1.39, 1.39)),
+                    linInt = rbind(c(0, 1, 1, 1, 1),
+                                   c(0, 0, 1, 1, 0.8)), 
+                    doses=doses, placEff = 0.5, maxEff = -0.4,
+                    addArgs=list(scal=200))
> plot(fmodels)
> ## some customizations (different model names, symbols, line-width)
> plot(fmodels, lwd = 3, pch = 3, cex=1.2, col="red",
+      modNams = paste("mod", 1:8, sep="-"))
> 
> ## for a full-model object one can calculate the responses
> ## in a matrix
> getResp(fmodels, doses=c(0, 20, 100, 150))
       linear      emax  logistic exponential  betaMod1  betaMod2   linInt1
0   0.5000000 0.5000000 0.5000000   0.5000000 0.5000000 0.5000000 0.5000000
20  0.4466667 0.2925926 0.4799218   0.4780753 0.1034104 0.4033236 0.2333333
100 0.2333333 0.1266667 0.1039996   0.3146301 0.3264910 0.1000000 0.1000000
150 0.1000000 0.1000000 0.1000000   0.1000000 0.4600007 0.2318393 0.1000000
    linInt2
0      0.50
20     0.50
100    0.10
150    0.18
attr(,"parList")
attr(,"parList")$linear
[1]  0.500000000 -0.002666667

attr(,"parList")$emax
[1]  0.5000000 -0.4666667 25.0000000

attr(,"parList")$logistic
[1]  0.5040408 -0.4040820 50.0000000 10.8811100

attr(,"parList")$exponential
[1]  0.50000000 -0.08264711 85.00000000

attr(,"parList")$betaMod1
                              scal 
  0.50  -0.40   0.33   2.31 200.00 

attr(,"parList")$betaMod2
                              scal 
  0.50  -0.40   1.39   1.39 200.00 

attr(,"parList")$linInt1
[1] 0.5 0.5 0.1 0.1 0.1 0.1

attr(,"parList")$linInt2
[1] 0.50 0.50 0.50 0.10 0.10 0.18

> 
> ## calculate doses giving an improvement of 0.3 over placebo
> TD(fmodels, Delta=0.3, direction = "decreasing")
     linear        emax    logistic exponential    betaMod1    betaMod2 
 112.500000   45.000000   62.095220  130.265330    4.880978   56.762044 
    linInt1     linInt2 
  21.250000   43.750000 
> ## discrete version
> TD(fmodels, Delta=0.3, TDtype = "discrete", doses=doses, direction = "decreasing")
     linear        emax    logistic exponential    betaMod1    betaMod2 
        150          50         100         150          10         100 
    linInt1     linInt2 
         25          50 
> ## doses giving 50% of the maximum effect
> ED(fmodels, p=0.5)
     linear        emax    logistic exponential    betaMod1    betaMod2 
  75.000000   18.750000   50.215409  104.517639    1.255838   37.337384 
    linInt1     linInt2 
  17.500000   37.500000 
> ED(fmodels, p=0.5, EDtype = "discrete", doses=doses)
     linear        emax    logistic exponential    betaMod1    betaMod2 
        100          25         100         150          10          50 
    linInt1     linInt2 
         25          50 
> 
> plot(fmodels, plotTD = TRUE, Delta = 0.3)
> 
> ## example for specifying all model parameters (fullMod=TRUE)
> fmods <- Mods(emax = c(0, 1, 0.1), linear = cbind(c(-0.4,0), c(0.2,0.1)),
+               sigEmax = c(0, -1.1, 0.5, 3),
+               doses = 0:4, fullMod = TRUE)
> getResp(fmods, doses=seq(0,4,length=11))
         emax linear1 linear2    sigEmax
0   0.0000000   -0.40    0.00  0.0000000
0.4 0.8000000   -0.32    0.04 -0.3724868
0.8 0.8888889   -0.24    0.08 -0.8841444
1.2 0.9230769   -0.16    0.12 -1.0257960
1.6 0.9411765   -0.08    0.16 -1.0674248
2   0.9523810    0.00    0.20 -1.0830769
2.4 0.9600000    0.08    0.24 -1.0901427
2.8 0.9655172    0.16    0.28 -1.0937718
3.2 0.9696970    0.24    0.32 -1.0958198
3.6 0.9729730    0.32    0.36 -1.0970608
4   0.9756098    0.40    0.40 -1.0978558
attr(,"parList")
attr(,"parList")$emax
[1] 0.0 1.0 0.1

attr(,"parList")$linear1
[1] -0.4  0.2

attr(,"parList")$linear2
[1] 0.0 0.1

attr(,"parList")$sigEmax
[1]  0.0 -1.1  0.5  3.0

> ## calculate doses giving an improvement of 0.3 over placebo
> TD(fmods, Delta=0.3)
      emax    linear1    linear2    sigEmax 
0.04285714 1.50000000 3.00000000         NA 
> ## discrete version
> TD(fmods, Delta=0.3, TDtype = "discrete", doses=0:4)
   emax linear1 linear2 sigEmax 
      1       2       3      NA 
> ## doses giving 50% of the maximum effect
> ED(fmods, p=0.5)
     emax   linear1   linear2   sigEmax 
0.0952381 2.0000000 2.0000000 0.4993506 
> ED(fmods, p=0.5, EDtype = "discrete", doses=0:4)
   emax linear1 linear2 sigEmax 
      1       2       2       1 
> plot(fmods)
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>