| Mods {DoseFinding} | 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) = \theta_0+\theta_1 f^0(d,\theta_2)
where the parameter \theta_2 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 \theta_0,\theta_1 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.
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, ...)
plotMods(ModsObj, nPoints = 200, superpose = FALSE,
xlab = "Dose", ylab = "Model means",
modNams = NULL, trafo = function(x) x)
Arguments
... |
In function Mods: |
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.2*max(doses), off = 0.01*max(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. |
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. |
ModsObj |
For function ‘plotMods’ the ‘ModsObj’ should contain an object of class ‘Mods’. |
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. |
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
See Also
Mods, drmodels, optDesign, powMCT
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)