Mods function

Define dose-response models

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.

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

getResp(fmodels, doses)

plotMods(
  ModsObj,
  nPoints = 200,
  superpose = FALSE,
  xlab = "Dose",
  ylab = "Model means",
  modNams = NULL,
  trafo = function(x) x
)

## 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.

• 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.

• 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.

• fmodels: An object of class Mods

• ModsObj: For function plotMods the ModsObj should contain an object of class 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.

• trafo: For function plotMods there is the option to plot the candidate model set on a transformed scale (e.g. probability scale if the candidate models are formulated on log-odds scale). The default for trafo is the identity function.

• x: Object of class Mods with type Mods

• plotTD: plotTD is a logical determining, whether the TD should be plotted. Delta is the target effect to estimate for the TD.

• Delta: Delta: The target effect size use for the target dose (TD) (Delta should be > 0).

Returns

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.

Details

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

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 from the data, they need to be specified via the addArgs argument.

The default plot method for Mods objects is based on a plot using the lattice package for backward compatibility. The function plotMods function implements a plot using the ggplot2 package.

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.

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 using default plot (based on lattice)
plot(models)
## display using ggplot2
plotMods(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)
plotMods(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)

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

See Also

Mods, drmodels, optDesign, powMCT

Author(s)

Bjoern Bornkamp