diff --git a/DESCRIPTION b/DESCRIPTION index d3cd9d3..2cb8726 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -13,7 +13,7 @@ Authors@R: c( person("Daniel", "Sabanes Bove", role = "aut", email = "daniel.sabanes_bove@rconis.com", comment = c(ORCID = "0000-0002-0176-9239")), person(given = "Novartis Pharma AG", role = c("cph", "fnd"))) -Imports: ggplot2, lattice, mvtnorm +Imports: ggplot2, lattice, mvtnorm, Rdpack Suggests: emmeans, numDeriv, @@ -48,3 +48,4 @@ URL: https://github.com/openpharma/DoseFinding, https://openpharma.github.io/Dos BugReports: https://github.com/openpharma/DoseFinding/issues Roxygen: list(markdown = TRUE) Config/testthat/edition: 3 +RdMacros: Rdpack diff --git a/NAMESPACE b/NAMESPACE index fcfd1f1..0955722 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -7,7 +7,7 @@ importFrom("stats", "AIC", "IQR", "acf", "approx", "as.formula", "pnorm", "predict", "qnorm", "qt", "quantile", "quasi", "sd", "terms", "uniroot", "var", "vcov") importFrom("utils", "setTxtProgressBar", "txtProgressBar", "browseURL") - +importFrom(Rdpack,reprompt) export(fitMod, defBnds, bFitMod, maFitMod, MCTtest, bMCTtest, MCPMod, betaMod, quadratic, emax, exponential,linear, linlog, logistic, sigEmax, linInt, betaModGrad, quadraticGrad, emaxGrad, exponentialGrad, diff --git a/R/DesignMCPModApp.R b/R/DesignMCPModApp.R index f3d84da..71ec224 100644 --- a/R/DesignMCPModApp.R +++ b/R/DesignMCPModApp.R @@ -2,8 +2,8 @@ #' #' #' This function starts the externally hosted DesignMCPMod Shiny App in a -#' browser window. The app was developed by Sophie Sun [aut, cre], Danyi Xiong -#' [aut], Bjoern Bornkamp [ctb], Frank Bretz [ctb], Ardalan Mirshani [ctb]. +#' browser window. The app was developed by Sophie Sun \[aut, cre\], Danyi Xiong +#' \[aut\], Bjoern Bornkamp \[ctb\], Frank Bretz \[ctb\], Ardalan Mirshani \[ctb\]. #' This app performs power and sample size calculations for a multiple contrast #' test for normal, binary and negative binomial outcomes. The app uses the #' DoseFinding package as calculation backend and the R code underlying the diff --git a/R/DoseFinding-package.R b/R/DoseFinding-package.R index 603ac19..a2b6f67 100644 --- a/R/DoseFinding-package.R +++ b/R/DoseFinding-package.R @@ -13,36 +13,23 @@ #' **MCPMod**: Performs MCPMod methodology\cr #' **sampSize**: General function for sample size calculation\cr #' -#' @references Bornkamp, B., Bretz, F., Dette, H. and Pinheiro, J. C. (2011). -#' Response-Adaptive Dose-Finding under model uncertainty, *Annals of -#' Applied Statistics*, **5**, 1611--1631 +#' @references +#' \insertRef{bornkamp2011}{DoseFinding} #' -#' 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 +#' \insertRef{bornkamp2009}{DoseFinding} #' -#' Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining multiple -#' comparisons and modeling techniques in dose-response studies, -#' *Biometrics*, **61**, 738--748 +#' \insertRef{bretz2005}{DoseFinding} #' -#' Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal -#' Designs for Dose Finding Studies, *Journal of the American Statisical -#' Association*, **103**, 1225--1237 +#' \insertRef{dette2008}{DoseFinding} #' -#' O'Quigley, J., Iasonos, A. and Bornkamp, B. (2017) Handbook of methods for -#' designing, monitoring, and analyzing dose-finding trials, CRC press, Part 3: -#' Dose-Finding Studies in Phase II +#' \insertRef{oquigley2017}{DoseFinding} #' -#' 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 +#' \insertRef{pinheiro2006}{DoseFinding} #' -#' Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based -#' dose finding under model uncertainty using general parametric models, -#' *Statistics in Medicine*, **33**, 1646--1661 +#' \insertRef{pinheiro2014}{DoseFinding} +#' +#' \insertRef{seber2003}{DoseFinding} #' -#' Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley -#' @keywords internal #' @examples #' #' data(IBScovars) @@ -211,13 +198,11 @@ #' @return Response value for model functions or matrix containing the gradient #' evaluations. #' @seealso [fitMod()] -#' @references MacDougall, J. (2006). Analysis of dose-response studies - Emax -#' model,*in* N. Ting (ed.), *Dose Finding in Drug Development*, -#' Springer, New York, pp. 127--145 +#' @references +#' \insertRef{macdougall2006}{DoseFinding} +#' +#' \insertRef{pinheiro2006}{DoseFinding} #' -#' 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 #' @examples #' #' ## some quadratic example shapes @@ -268,7 +253,7 @@ NULL #' Biometrics Dose Response data #' #' An example data set for dose response studies. This data set was used in -#' Bretz et al. (2005) to illustrate the MCPMod methodology. +#' \insertCite{bretz2005;textual}{DoseFinding} to illustrate the MCPMod methodology. #' #' @name biom #' @docType data @@ -278,9 +263,7 @@ NULL #' \item{`resp`}{a numeric vector containing the response values} #' \item{`dose`}{a numeric vector containing the dose values} #' } -#' @source Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining -#' multiple comparisons and modeling techniques in dose-response studies, -#' *Biometrics*, **61**, 738--748 +#' @source \insertRef{bretz2005}{DoseFinding} #' @keywords datasets NULL @@ -360,8 +343,7 @@ NULL #' \item{`dose`}{a numeric vector} #' \item{`resp`}{a numeric vector} #' } -#' @source Biesheuvel, E. and Hothorn, L. A. (2002). Many-to-one comparisons in -#' stratified designs, *Biometrical Journal*, **44**, 101--116 +#' @source \insertRef{biesheuvel2002}{DoseFinding} #' @keywords datasets NULL @@ -426,9 +408,7 @@ NULL #' \item{`id`}{Patient ID} #' \item{`time`}{time of measurement} #' } -#' @source Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) -#' Model-based dose finding under model uncertainty using general parametric -#' models, *Statistics in Medicine*, **33**, 1646--1661 +#' @source \insertRef{pinheiro2014}{DoseFinding} #' @keywords datasets #' @examples #' diff --git a/R/MCPMod.R b/R/MCPMod.R index 4767f72..4c19de4 100644 --- a/R/MCPMod.R +++ b/R/MCPMod.R @@ -5,7 +5,7 @@ #' #' Tests for a dose-response effect using a model-based multiple contrast test (see [MCTtest()]), selects one #' (or several) model(s) from the significant shapes, fits them using [fitMod()]. For details on the method -#' see Bretz et al. (2005). +#' see \insertCite{bretz2005;textual}{DoseFinding}. #' #' #' @aliases MCPMod predict.MCPMod plot.MCPMod @@ -17,7 +17,7 @@ #' \item `aveAIC`: Uses a weighted average of the models corresponding to #' the significant contrasts. The model weights are chosen by the formula: #' \eqn{w_i = \exp(-0.5AIC_i)/\sum_i(\exp(-0.5AIC_i))}{w_i = -#' exp(-0.5AIC_i)/sum(exp(-0.5AIC_i))} See Buckland et al. (1997) for details. +#' exp(-0.5AIC_i)/sum(exp(-0.5AIC_i))} See \insertCite{buckland1997;textual}{DoseFinding} for details. #' } For \samp{type = "general"} the "gAIC" is used. #' @param df Specify the degrees of freedom to use in case \samp{type = "general"}, for the call to #' [MCTtest()] and [fitMod()]. Infinite degrees of (\samp{df=Inf}) correspond to the multivariate @@ -44,30 +44,24 @@ #' objects and additional information (model selection criteria, dose estimates, selected models). #' @author Bjoern Bornkamp #' @seealso [MCTtest()], [fitMod()], [drmodels()] -#' @references 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 -#' -#' Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based dose finding under model uncertainty -#' using general parametric models, *Statistics in Medicine*, **33**, 1646--1661 -#' -#' Schorning, K., Bornkamp, B., Bretz, F., & Dette, H. (2016). Model selection -#' versus model averaging in dose finding studies. *Statistics in -#' Medicine*, **35**, 4021--4040 -#' -#' Xun, X. and Bretz, F. (2017) The MCP-Mod methodology: Practical Considerations and The DoseFinding R package, in -#' O'Quigley, J., Iasonos, A. and Bornkamp, B. (eds) Handbook of methods for designing, monitoring, and analyzing -#' dose-finding trials, CRC press -#' -#' 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. +#' @references +#' +#' \insertRef{buckland1997}{DoseFinding} +#' +#' \insertRef{bretz2005}{DoseFinding} +#' +#' \insertRef{pinheiro2006b}{DoseFinding} +#' +#' \insertRef{pinheiro2006}{DoseFinding} +#' +#' \insertRef{pinheiro2014}{DoseFinding} +#' +#' \insertRef{schorning2016}{DoseFinding} +#' +#' \insertRef{seber2003}{DoseFinding} +#' +#' \insertRef{xun2017}{DoseFinding} +#' #' @examples #' #' data(biom) diff --git a/R/MCTtest.R b/R/MCTtest.R index cec1904..7dfadfe 100644 --- a/R/MCTtest.R +++ b/R/MCTtest.R @@ -25,7 +25,7 @@ #' @param S The covariance matrix of \samp{resp} when \samp{type = "general"}, see Description. #' @param type Determines whether inference is based on an ANCOVA model under a homoscedastic normality assumption (when #' \samp{type = "normal"}), or estimates at the doses and their covariance matrix and degrees of freedom are specified -#' directly in \samp{resp}, \samp{S} and \samp{df}. See also [fitMod()] and Pinheiro et al. (2014). +#' directly in \samp{resp}, \samp{S} and \samp{df}. See also [fitMod()] and \insertCite{pinheiro2014}{DoseFinding}. #' @param addCovars Formula specifying additive linear covariates (for \samp{type = "normal"}) #' @param placAdj Logical, if true, it is assumed that placebo-adjusted #' estimates are specified in \samp{resp} (only possible for \samp{type = @@ -46,11 +46,11 @@ #' @return An object of class MCTtest, a list containing the output. #' @author Bjoern Bornkamp #' @seealso [powMCT()], [optContr()] -#' @references Hothorn, T., Bretz, F., and Westfall, P. (2008). Simultaneous Inference in General Parametric Models, -#' *Biometrical Journal*, **50**, 346--363 -#' -#' Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based dose finding under model uncertainty -#' using general parametric models, *Statistics in Medicine*, **33**, 1646--1661 +#' @references +#' \insertRef{hothorn2008}{DoseFinding} +#' +#' \insertRef{pinheiro2014}{DoseFinding} +#' #' @examples #' #' ## example without covariates @@ -278,9 +278,7 @@ critVal <- function(corMat, alpha = 0.025, df = NULL, #' @return Numeric containing the calculated p-values. #' @author Bjoern Bornkamp #' @seealso [MCTtest()], [optContr()] -#' @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 +#' @references \insertRef{pinheiro2006b}{DoseFinding} #' @examples #' data(biom) #' ## define shapes for which to calculate optimal contrasts diff --git a/R/Mods.R b/R/Mods.R index 817eae0..196958e 100644 --- a/R/Mods.R +++ b/R/Mods.R @@ -50,9 +50,7 @@ #' derived linear parameters (based on \samp{"placEff"} and \samp{"maxEff"}) in a list. #' @author Bjoern Bornkamp #' @seealso [Mods()], [drmodels()], [optDesign()], [powMCT()] -#' @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 +#' @references \insertRef{pinheiro2006b}{DoseFinding} #' @examples #' #' ## Example on how to specify candidate models diff --git a/R/bFitMod.R b/R/bFitMod.R index 488960c..126c10a 100644 --- a/R/bFitMod.R +++ b/R/bFitMod.R @@ -11,7 +11,8 @@ #' assumed, and a large number of samples is drawn from this distribution. For each draw the fitMod function with #' \samp{type = "general"} is used to fit the draws from the multivariate normal distribution. #' -#' Componentwise univariate slice samplers are implemented (see Neal, 2003) to sample from the posterior distribution. +#' Componentwise univariate slice samplers are implemented \insertCite{@see @neal2003}{DoseFinding} +#' to sample from the posterior distribution. #' #' @aliases bFitMod coef.bFitMod predict.bFitMod plot.bFitMod #' @param dose Numeric specifying the dose variable. @@ -54,7 +55,7 @@ #' additional information on the fitted model. #' @author Bjoern Bornkamp #' @seealso [fitMod()] -#' @references Neal, R. M. (2003), Slice sampling, Annals of Statistics, 31, 705-767 +#' @references \insertAllCited{} #' @examples #' data(biom) # ## produce first stage fit (using dose as factor) diff --git a/R/bMCTtest.R b/R/bMCTtest.R index 97b7e66..8197755 100644 --- a/R/bMCTtest.R +++ b/R/bMCTtest.R @@ -1,14 +1,14 @@ #' Performs Bayesian multiple contrast test #' #' This function performs a Bayesian multiple contrast test using normal mixture priors for the response on each dose, -#' as proposed in Fleischer et al. (2022). For a general description of the multiple contrast test see +#' as proposed in \insertCite{fleischer2022;textual}{DoseFinding}. For a general description of the multiple contrast test see #' [MCTtest()]. #' #' If \samp{type = "normal"}, an ANCOVA model based on a homoscedastic normality assumption is fitted and posteriors for #' dose-response and contrast vectors are obtained assuming a known variance. #' #' For \samp{type = "general"} it is assumed multivariate normally distributed estimates are specified in \samp{resp} -#' with covariance given by \samp{S}, which define the likelihood. Posteriors for dose-response and contrast vectors +#' with covariance given by \samp{S}, which define the likelihood. Posteriors for dose-response and contrast vectors #' are then obtained assuming a known covariance matrix S #' #' The multiple contrast test decision is based on the maximum posterior probability of a contrast being greater than @@ -17,7 +17,7 @@ #' contrast test if uninformative priors are used. #' #' For the default calculation of optimal contrasts the prior information is ignored (i.e. contrasts are calculated in -#' the same way as in [MCTtest()]). Fleischer et al. (2022) discuss using contrasts that take the prior +#' the same way as in [MCTtest()]). \insertCite{fleischer2022;textual}{DoseFinding} discuss using contrasts that take the prior #' effective sample sizes into account, which can be slightly more favourable for the Bayesian MCT test. Such #' alternative contrasts can be directly handed over via the \samp{contMat} argument. #' @@ -45,8 +45,7 @@ #' @author Marius Thomas #' @export #' @seealso [MCTtest()], [optContr()] -#' @references Fleischer, F., Bossert, S., Deng, Q., Loley, C. and Gierse, J. (2022). Bayesian MCP-Mod, -#' *Pharmaceutical Statistics*, **21**, 654--670 +#' @references \insertAllCited{} #' @examples #' #' @@ -277,7 +276,7 @@ print.bMCTtest <- function(x, digits = 3, eps = 1e-3, ...){ #' @return Returns a posterior multivariate normal mixture as a list of length 3, containing mixture weights, mean #' vectors and covariance matrices. #' @author Marius Thomas -#' @references Bernardo, J. M., and Smith, A. F. (1994). Bayesian theory. John Wiley & Sons. +#' @references \insertRef{bernardo1994}{DoseFinding} #' @export mvpostmix <- function(priormix, mu_hat, S_hat) { diff --git a/R/fitMod.R b/R/fitMod.R index 48f35dc..8cfec4e 100644 --- a/R/fitMod.R +++ b/R/fitMod.R @@ -47,8 +47,8 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' estimates obtained in a first stage fit, then \samp{resp} contains the estimates and \samp{S} is the estimated #' covariance matrix for the estimates in \samp{resp}. Statistical inference (e.g. confidence intervals) rely on #' asymptotic normality of the first stage estimates, which makes this method of interest only for sufficiently large -#' sample size for the first stage fit. A modified model-selection criterion can be applied to these model fits (see -#' also Pinheiro et al. 2014 for details). +#' sample size for the first stage fit. A modified model-selection criterion can be applied to these model fits +#' \insertCite{@see also @pinheiro2014 for details}{DoseFinding}. #' #' For details on the implemented numerical optimizer see the Details section below. #' @@ -60,9 +60,8 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' grid-search (with the grid size specified via \samp{control$gridSize}), or can directly be handed over via #' \samp{start}. #' -#' For details on the asymptotic approximation used for \samp{type = "normal"}, see Seber and Wild (2003, chapter 5). -#' For details on the asymptotic approximation used for \samp{type = "general"}, and the gAIC, see Pinheiro et al. -#' (2014). +#' For details on the asymptotic approximation used for \samp{type = "normal"}, see \insertCite{seber2003;textual}{DoseFinding}, Chapter 5. +#' For details on the asymptotic approximation used for \samp{type = "general"}, and the gAIC, see \insertCite{pinheiro2014;textual}{DoseFinding}. #' #' @aliases fitMod coef.DRMod vcov.DRMod predict.DRMod plot.DRMod logLik.DRMod AIC.DRMod gAIC gAIC.DRMod #' @param dose,resp Either vectors of equal length specifying dose and response values, or names of variables in the @@ -76,7 +75,7 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' the first stage fit. #' @param type Determines whether inference is based on an ANCOVA model under a homoscedastic normality assumption (when #' \samp{type = "normal"}), or estimates at the doses and their covariance matrix and degrees of freedom are specified -#' directly in \samp{resp}, \samp{S} and \samp{df}. See also the Description above and Pinheiro et al. (2014). +#' directly in \samp{resp}, \samp{S} and \samp{df}. See also the Description above and \insertCite{pinheiro2014;textual}{DoseFinding}. #' @param addCovars Formula specifying additional additive linear covariates (only for \samp{type = "normal"}) #' @param placAdj Logical, if true, it is assumed that placebo-adjusted #' estimates are specified in \samp{resp} (only possible for \samp{type = @@ -109,10 +108,9 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' residual sum of squares (or generalized residual sum of squares), #' @author Bjoern Bornkamp #' @seealso [defBnds()], [drmodels()] -#' @references Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based dose finding under model -#' uncertainty using general parametric models, *Statistics in Medicine*, **33**, 1646--1661 +#' @references +#' \insertAllCited{} #' -#' Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley. #' @examples #' #' ## Fit the emax model to the IBScovars data set diff --git a/R/guesst.R b/R/guesst.R index 7887c29..0f62ed1 100644 --- a/R/guesst.R +++ b/R/guesst.R @@ -1,8 +1,7 @@ #' Calculate guesstimates based on prior knowledge #' -#' Calculates guesstimates for standardized model parameter(s) using the general approach described in Pinheiro et al. -#' (2006). +#' Calculates guesstimates for standardized model parameter(s) using the general approach described in \insertCite{pinheiro2006;textual}{DoseFinding}. #' #' Calculates guesstimates for the parameters \eqn{\theta_2}{theta2} of the standardized model function based on the #' prior expected percentage of the maximum effect at certain dose levels. Note that this function should be used @@ -21,14 +20,14 @@ #' For the emax, sigmoid Emax and logistic model one can choose between a local and an asymptotic version. In the local #' version one explicitly forces the standardized model function to pass through the specified points (d,p). For the #' asymptotic version it assumed that the standardized model function is equal to 1 at the largest dose (this is the -#' approach described in Pinheiro et al. (2006)). If the local version is used, convergence problems with the underlying +#' approach described in \insertCite{pinheiro2006;textual}{DoseFinding}). If the local version is used, convergence problems with the underlying #' nonlinear optimization can occur. #' #' @param d Vector containing dose value(s). #' @param p Vector of expected percentages of the maximum effect achieved at d. #' @param model Character string. Should be one of "emax", "exponential", "quadratic", "betaMod", "sigEmax", "logistic". #' @param less Logical, only needed in case of quadratic model. Determines if d is smaller (\samp{less=TRUE}) or larger -#' (\samp{less=FALSE}) than dopt (see Pinheiro et al. (2006) for details). +#' (\samp{less=FALSE}) than dopt \insertCite{@see @pinheiro2006 for details}{DoseFinding}. #' @param local Logical indicating whether local or asymptotic version of guesstimate should be derived (defaults to #' \samp{FALSE}). Only needed for emax, logistic and sigEmax model. When \samp{local=TRUE} the maximum dose must be #' provided via \samp{Maxd}. @@ -38,12 +37,11 @@ #' @return Returns a numeric vector containing the guesstimates. #' @seealso [emax()], [logistic()], [betaMod()], [sigEmax()], #' [quadratic()], [exponential()], [plot.Mods()] -#' @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 +#' @references +#' \insertRef{bornkamp2009}{DoseFinding} +#' +#' \insertRef{pinheiro2006}{DoseFinding} #' -#' 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 #' @examples #' #' ## Emax model diff --git a/R/maFitMod.R b/R/maFitMod.R index 931b2b4..54f6792 100644 --- a/R/maFitMod.R +++ b/R/maFitMod.R @@ -2,8 +2,8 @@ #' averaging (bagging) #' #' This function fits dose-response models in a bootstrap model -#' averaging approach motivated by the bagging procedure (Breiman -#' 1996). Given summary estimates for the outcome at each dose, the +#' averaging approach motivated by the bagging procedure \insertCite{breiman1996}{DoseFinding}. +#' Given summary estimates for the outcome at each dose, the #' function samples summary data from the multivariate normal #' distribution. For each sample dose-response models are fit to these #' summary estimates and the best model @@ -33,7 +33,7 @@ #' was selected in each bootstrap and basic input parameters. #' @author Bjoern Bornkamp #' @seealso [fitMod()], [bFitMod()], [drmodels()] -#' @references Breiman, L. (1996). Bagging predictors. Machine learning, 24, 123-140. +#' @references \insertAllCited{} #' @examples #' data(biom) #' ## produce first stage fit (using dose as factor) diff --git a/R/optContr.R b/R/optContr.R index c9a578c..60d12ff 100644 --- a/R/optContr.R +++ b/R/optContr.R @@ -10,7 +10,7 @@ #' associated with the estimate of \eqn{\mu}{mu}. The optimal contrast is #' given by \deqn{c^{opt} \propto S^{-1}\left(\mu - \frac{\mu^{\prime}S^{-1}1} #' {1^\prime S^{-1} 1}\right),}{c propto S^(-1) (mu - mu'S^(-1)1)/(1'S^(-1)1),} -#' see Pinheiro et al. (2014). +#' see \insertCite{pinheiro2014;textual}{DoseFinding}. #' #' Note that the directionality (i.e. whether in "increase" in the response #' variable is beneficial or a "decrease", is inferred from the specified @@ -52,13 +52,10 @@ #' and muMat (i.e. contrast, mean and correlation matrix). #' @author Bjoern Bornkamp #' @seealso [MCTtest()] -#' @references Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining -#' multiple comparisons and modeling techniques in dose-response studies, -#' *Biometrics*, **61**, 738--748 +#' @references +#' \insertRef{bretz2005}{DoseFinding} #' -#' Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based -#' dose finding under model uncertainty using general parametric models, -#' *Statistics in Medicine*, **33**, 1646--1661 +#' \insertRef{pinheiro2014}{DoseFinding} #' @examples #' #' doses <- c(0,10,25,50,100,150) diff --git a/R/optDesign.R b/R/optDesign.R index 6e352d9..a19c692 100644 --- a/R/optDesign.R +++ b/R/optDesign.R @@ -4,7 +4,7 @@ #' #' Given a set of models (with full parameter values and model probabilities) the \samp{optDesign} function calculates #' the optimal design for estimating the dose-response model parameters (D-optimal) or the design for estimating the -#' target dose (TD-optimal design) (see Dette, Bretz, Pepelyshev and Pinheiro (2008)), or a mixture of these two +#' target dose (TD-optimal design) \insertCite{@see @dette2008}{DoseFinding}, or a mixture of these two #' criteria. The design can be plotted (together with the candidate models) using \samp{plot.design}. \samp{calcCrit} #' calculates the design criterion for a discrete set of design(s). \samp{rndDesign} provides efficient rounding for the #' calculated continous design to a finite sample size. @@ -26,7 +26,7 @@ #' \deqn{\sum_{m}p_m \log(v_m)}{sum_m p_m log(v_m)} where \eqn{p_m}{p_m} is the probability for model m and #' \eqn{v_m}{v_m} is proportional to the asymptotic #' variance of the TD estimate and given by \eqn{b_m'M_m^{-}b_m}{b_m'Minv_m -#' b_m} (see Dette et al. (2008), p. 1227 for details). +#' b_m} \insertCite{@see @dette2008, p. 1227 for details}{DoseFinding}. #' #' For \samp{designCrit = "Dopt&TD"} the code minimizes the design criterion #' \deqn{\sum_{m}p_m(-0.5\log(\det(M_m))/k_m+0.5\log(v_m))}{sum_m @@ -34,7 +34,7 @@ #' #' Again, for \samp{standDopt = FALSE} the \eqn{k_m}{k_m} are all assumed to be equal to one. #' -#' For details on the \samp{rndDesign} function, see Pukelsheim (1993), Chapter 12. +#' For details on the \samp{rndDesign} function, see \insertCite{pukelsheim1993;textual}{DoseFinding}, Chapter 12. #' #' @aliases optDesign plot.DRdesign calcCrit rndDesign #' @param models An object of class \samp{c(Mods, fullMod)}, see the [Mods()] function for details. When an TD @@ -68,7 +68,7 @@ #' required. #' @param optimizer Algorithm used for calculating the optimal design. Options "Nelder-Mead" and "nlminb" use the #' [optim()] and [nlminb()] function and use a trigonometric transformation to turn the -#' constrained optimization problem into an unconstrained one (see Atkinson, Donev and Tobias, 2007, pages 130,131). +#' constrained optimization problem into an unconstrained one \insertCite{@see @atkinson2007 pages 130,131}{DoseFinding}. #' #' Option "solnp" uses the solnp function from the Rsolnp package, which implements an optimizer for non-linear #' optimization under general constraints. @@ -96,18 +96,14 @@ #' algorithm. Alternatively one can use the solnp optimizer that is usually the most reliable, but not fastest option. #' @author Bjoern Bornkamp #' @seealso [Mods()], [drmodels()] -#' @references Atkinson, A.C., Donev, A.N. and Tobias, R.D. (2007). Optimum Experimental Designs, with SAS, Oxford -#' University Press -#' -#' Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal -#' Designs for Dose Finding Studies, *Journal of the American Statisical -#' Association*, **103**, 1225--1237 -#' -#' Pinheiro, J.C., Bornkamp, B. (2017) Designing Phase II Dose-Finding Studies: Sample Size, Doses and Dose Allocation -#' Weights, in O'Quigley, J., Iasonos, A. and Bornkamp, B. (eds) Handbook of methods for designing, monitoring, and -#' analyzing dose-finding trials, CRC press -#' -#' Pukelsheim, F. (1993). Optimal Design of Experiments, Wiley +#' @references +#' \insertRef{atkinson2007}{DoseFinding} +#' +#' \insertRef{dette2008}{DoseFinding} +#' +#' \insertRef{pinheiro2017}{DoseFinding} +#' +#' \insertRef{pukelsheim1993}{DoseFinding} #' @examples #' #' ## calculate designs for Emax model diff --git a/R/planMod.R b/R/planMod.R index 642a528..1573395 100644 --- a/R/planMod.R +++ b/R/planMod.R @@ -68,9 +68,7 @@ #' fitMod. #' @author Bjoern Bornkamp #' @seealso [fitMod()] -#' @references Pinheiro, J.C. and Bornkamp, B. (2017). Designing phase II dose-finding studies: sample size, -#' doses, and dose allocation weights. Handbook of Methods for Designing, Monitoring, and Analyzing Dose-Finding -#' Trials, Chapter 13, Chapman and Hall/CRC, 229-246. +#' @references \insertRef{pinheiro2017}{DoseFinding} #' #' @examples #' diff --git a/R/powMCT.R b/R/powMCT.R index 103d257..5c91f17 100644 --- a/R/powMCT.R +++ b/R/powMCT.R @@ -62,10 +62,7 @@ mvtnorm.control <- function(maxpts = 30000, abseps = 0.001, #' @author Bjoern Bornkamp #' @seealso [powN()], [sampSizeMCT()], #' [MCTtest()], [optContr()], [Mods()] -#' @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 +#' @references \insertRef{pinheiro2006b}{DoseFinding} #' @examples #' #' ## look at power under some dose-response alternatives diff --git a/R/powMCTInterim.R b/R/powMCTInterim.R index 5e426b7..8ee4b8e 100644 --- a/R/powMCTInterim.R +++ b/R/powMCTInterim.R @@ -21,8 +21,7 @@ #' \samp{mvtnorm.control} for details. #' @return Numeric containing the calculated power values #' @seealso [powMCT()] [MCTtest()], [optContr()] -#' @references Bornkamp, B., Zhou, J., Xi, D. and Cao W. (2025). Futility analyses for the MCP-Mod methodology based -#' on longitudinal models, *arXiv:2406.19965* +#' @references \insertRef{bornkamp2024}{DoseFinding} #' @examples #' #' # Setup the scenario. diff --git a/R/sampSize.R b/R/sampSize.R index e76a02f..dc274be 100644 --- a/R/sampSize.R +++ b/R/sampSize.R @@ -50,13 +50,11 @@ #' #' @author Jose Pinheiro, Bjoern Bornkamp #' @seealso [powMCT()] -#' @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 -#' -#' Pinheiro, J.C., Bornkamp, B. (2017) Designing Phase II Dose-Finding Studies: Sample Size, Doses and Dose Allocation -#' Weights, in O'Quigley, J., Iasonos, A. and Bornkamp, B. (eds) Handbook of methods for designing, monitoring, and -#' analyzing dose-finding trials, CRC press +#' @references +#' \insertRef{pinheiro2006b}{DoseFinding} +#' +#' \insertRef{pinheiro2017}{DoseFinding} +#' #' @examples #' #' ## sampSize examples diff --git a/_pkgdown.yml b/_pkgdown.yml index fab6879..4eff9da 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -3,6 +3,9 @@ template: bootstrap: 5 math-rendering: mathjax reference: +- title: Package +- contents: + - DoseFinding-package - title: Design dose-reponse trials - contents: - Mods diff --git a/inst/REFERENCES.bib b/inst/REFERENCES.bib new file mode 100644 index 0000000..4fcfb03 --- /dev/null +++ b/inst/REFERENCES.bib @@ -0,0 +1,299 @@ +@book{atkinson2007, + author = {Atkinson, AC and Donev, AN and Tobias, RD}, + title = {Optimum Experimental Designs, with SAS}, + publisher = {Oxford University Press}, + year = {2007} +} + +@Article{bays2020, + author = {Bays, Harold E and Kozlovski, Plamen and Shao, Qing and Proot, Pieter and Keefe, Deborah}, + title = {Licogliflozin, a Novel SGLT1 and 2 Inhibitor: Body Weight Effects in a Randomized Trial in Adults with Overweight or Obesity}, + journal = {Obesity}, + year = 2020, + volume = 28, + issue = 5, + doi = {10.1002/oby.22764}, + pages = {870-881}} + +@book{bernardo1994, + title={Bayesian theory}, + author={Bernardo, Jos{\'e} M and Smith, Adrian FM and Berliner, Mark}, + volume={586}, + year={1994}, + publisher={Wiley Online Library} +} + +@article{biesheuvel2002, + title={Many-to-one comparisons in stratified designs}, + author={Biesheuvel, Egbert and Hothorn, Ludwig A}, + journal={Biometrical Journal}, + volume={44}, + number={1}, + pages={101--116}, + year={2002}, + doi = {10.1002/1521-4036(200201)44:13.0.CO;2-H}, + publisher={Wiley Online Library} +} + +@Article{bornkamp2007, + author = {Bornkamp, Björn and Bretz, Frank and Dmitrienko, Alex and Enas, Greg and Gaydos, Brenda and Hsu, Chyi-Hung and König, Franz and Krams, Michael and Liu, Qing and Neuenschwander, Beat and Parke, Tom and Pinheiro, José and Roy, Amit and Sax, Rick and Shen, Frank}, + title = {Innovative approaches for designing and analyzing adaptive dose-ranging trials}, + journal = {Journal of Biopharmaceutical Statistics}, + year = 2007, + volume = 17, + issue = 6, + doi = {10.1080/10543400701643848}, + pages = {965-995}} + +@article{bornkamp2009, + title={MCPMod: An R package for the design and analysis of dose-finding studies}, + author={Bornkamp, Bj{\"o}rn and Pinheiro, Jos{\'e} and Bretz, Frank}, + journal={Journal of Statistical Software}, + volume={29}, + pages={1--23}, + doi={10.18637/jss.v029.i07}, + year={2009} +} + +@article{bornkamp2011, + title={Response-adaptive dose-finding under model uncertainty}, + author={Bornkamp, Bj{\"o}rn and Bretz, Frank and Dette, Holger and Pinheiro, Jos{\'e}}, + journal={The Annals of Applied Statistics}, + pages={1611--1631}, + year={2011}, + doi={10.1214/10-AOAS445}, + publisher={JSTOR} +} + +@misc{bornkamp2024, + title={Futility analyses for the MCP-Mod methodology based on longitudinal models}, + author={Björn Bornkamp and Jie Zhou and Dong Xi and Weihua Cao}, + year={2024}, + eprint={2406.19965}, + archivePrefix={arXiv}, + primaryClass={stat.ME}, + url={https://arxiv.org/abs/2406.19965} +} + +@Article{breiman1996, + author = {Breiman, Leo}, + title = {Baggin predictors}, + journal = {Machine Learning}, + year = 1996, + volume = 24, + issue = 2, + pages = {123-140}, + doi = {10.1007/bf00058655}} + +@article{bretz2005, + title={Combining multiple comparisons and modeling techniques in dose-response studies}, + author={Bretz, Frank and Pinheiro, Jos{\'e} C and Branson, Michael}, + journal={Biometrics}, + volume={61}, + number={3}, + pages={738--748}, + year={2005}, + doi = {10.1111/j.1541-0420.2005.00344.x}, + publisher={Wiley Online Library} +} + +@Article{bretz2010, + author = {Bretz, Frank and Dette, Holger and Pinheiro, José}, + title = {Practical considerations for optimal designs in clinical dose finding studies}, + journal = {Statistics in Medicine}, + year = 2010, + volume = 29, + issue = {7-8}, + pages = {731-742}, + doi = {10.1002/sim.3802}} + +@article{buckland1997, + title={Model selection: an integral part of inference}, + author={Buckland, Steven T and Burnham, Kenneth P and Augustin, Nicole H}, + journal={Biometrics}, + pages={603--618}, + year={1997}, + doi={10.2307/2533961}, + publisher={JSTOR} +} + +@article{dette2008, + title={Optimal designs for dose-finding studies}, + author={Dette, Holger and Bretz, Frank and Pepelyshev, Andrey and Pinheiro, Jose}, + journal={Journal of the American Statistical Association}, + volume={103}, + number={483}, + pages={1225--1237}, + year={2008}, + doi={10.1198/016214508000000427}, + publisher={Taylor \& Francis} +} + +@Article{fleischer2022, + title={Bayesian MCPMod}, + author={Fleischer, Frank and Bossert, Sebastian and Deng, Qiqi and Loley, Christina and Gierse, Jana}, + journal={Pharmaceutical Statistics}, + volume={21}, + number={3}, + pages={654--670}, + doi={10.1002/pst.2193}, + year={2022}, + publisher={Wiley} +} + +@Article{heinze2002, + author = {Heinze, Georg and Schemper, Michael}, + title = {A solution to the problem of separation in logistic regression}, + journal = {Statistics in Medicine}, + year = 2002, + volume = 21, + issue = 16, + pages = {2409-2419}, + doi = {10.1002/sim.1047}} + +@article{hothorn2008, + title={Simultaneous inference in general parametric models}, + author={Hothorn, Torsten and Bretz, Frank and Westfall, Peter}, + journal={Biometrical Journal}, + volume={50}, + number={3}, + pages={346--363}, + year={2008}, + doi={10.1002/bimj.200810425}, + publisher={Wiley Online Library} +} + +@incollection{macdougall2006, + title={Analysis of dose--response studies—Emax model}, + author={MacDougall, James}, + booktitle={Dose Finding in Drug Development}, + pages={127--145}, + year={2006}, + publisher={Springer} +} + +@Article{neal2003, + title={Slice sampling}, + author={Neal, Radford M}, + journal={The Annals of Statistics}, + volume={31}, + number={3}, + pages={705--767}, + year={2003}, + doi={10.1214/aos/1056562461}, + publisher={Institute of Mathematical Statistics} +} + +@incollection{oquigley2017, + title={Part III: Phase II Dose-Finding Trials}, + booktitle={Handbook of Methods for Designing, Monitoring, and Analyzing Dose-finding Trials}, + author={O'Quigley, John and Iasonos, Alexia and Bornkamp, Bj{\"o}rn}, + year={2017}, + publisher={CRC press} +} + +@Book{oquigley2017b, + title={Handbook of methods for designing, monitoring, and analyzing dose-finding trials}, + author={O'Quigley, John and Iasonos, Alexia and Bornkamp, Björn}, + year=2017, + publisher={CRC Press}, + doi = {10.1201/9781315151984}} + +@incollection{pinheiro2006, + title={Analysis of dose--response studies—modeling approaches}, + author={Pinheiro, Jos{\'e} C and Bretz, Frank and Branson, Michael}, + booktitle={Dose Finding in Drug Development}, + pages={146--171}, + year={2006}, + publisher={Springer} +} + +@Article{pinheiro2006b, + author = {Pinheiro, José and Bornkamp, Björn and Bretz, Frank}, + title = {Design and Analysis of Dose Finding Studies Combining Multiple Comparisons and Modeling Procedures}, + year = 2006, + volume = 16, + pages = {639-656}, + journal = {Journal of Biopharmaceutical Statistics}, + doi = {10.1080/10543400600860428}} + +@Article{pinheiro2014, + author = {Pinheiro, José and Bornkamp, Björn and Glimm, Ekkehard and Bretz, Frank}, + title = {Model-based dose finding under model uncertainty using general parametric models}, + year = 2014, + volume = 33, + pages = {1646-1661}, + journal = {Statistics in Medicine}, + doi = {10.1002/sim.6052}} + +@incollection{pinheiro2017, + title={Designing phase II dose-finding studies: sample size, doses, and dose allocation weights}, + author={Pinheiro, Jos{\'e} and Bornkamp, Bj{\"o}rn}, + booktitle={Handbook of Methods for Designing, Monitoring, and Analyzing Dose-Finding Trials}, + pages={229--246}, + year={2017}, + publisher={Chapman and Hall/CRC} +} + +@book{pukelsheim1993, + author = {Pukelsheim, Friedrich}, + title = {Optimal Design of Experiments}, + publisher = {Wiley}, + year = {1993} +} + +@Article{schorning2016, + author = {Schorning, Kirsten and Bornkamp, Björn and Bretz, Frank and Holger Dette}, + title = {Model selection versus model averaging in dose finding studies}, + journal = {Statistics in Medicine}, + year = 2016, + volume = 35, + issue = 22, + pages = {4021-4040}, + doi = {10.1002/sim.6991}} + +@book{seber2003, + title={Nonlinear Regression}, + author={Seber, George AF and Wild, CJ}, + year={2003}, + publisher={Wiley} +} + +@Article{thomas2014, + author = {Thomas, Neal and Sweeney, Kevin and Somayaji, Veena}, + title = {Meta-analysis of clinical dose response in a large drug development portfolio}, + journal = {Statistics in Biopharmaceutical Research}, + year = 2015, + volume = 6, + issue = 4, + pages = {302-217}, + doi = {10.1080/19466315.2014.924876}} + +@Article{thomas2017, + author = {Thomas, Neal and Roy, Dooti}, + title = {Analysis of Clinical Dose–Response in Small-Molecule Drug Development: 2009–2014}, + journal = {Statistics in Biopharmaceutical Research}, + year = 2017, + volume = 9, + issue = 2, + pages = {137-146}, + doi = {10.1080/19466315.2016.1256229}} + +@Article{verkindre2010, + author = { Verkindre, C. and Fukuchi, Y. and Flémale, A. and Takeda, A. and Overend, T. and Prasad, N. and Dolker, M.}, + title = {Sustained 24-h efficacy of NVA237, a once-daily long-acting muscarinic antagonist, in COPD patients}, + journal = {Respiratory Medicine}, + year = 2010, + volume = 104, + issue = 10, + pages = {1482-1489}, + doi = {10.1016/j.rmed.2010.04.006}} + +@incollection{xun2017, + title={The MCP-Mod methodology: Practical considerations and the DoseFinding R package}, + author={Xun, Xiaolei and Bretz, Frank}, + booktitle={Handbook of Methods for Designing, Monitoring, and Analyzing Dose-Finding Trials}, + pages={205--227}, + year={2017}, + publisher={Chapman and Hall/CRC} +} diff --git a/man/DesignMCPModApp.Rd b/man/DesignMCPModApp.Rd index e7df644..3b8170c 100644 --- a/man/DesignMCPModApp.Rd +++ b/man/DesignMCPModApp.Rd @@ -1,18 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DesignMCPModApp.R \name{DesignMCPModApp} \alias{DesignMCPModApp} \title{Start externally hosted DesignMCPMod Shiny App} -\description{ - - This function starts the externally hosted DesignMCPMod Shiny App in a - browser window. The app was developed by Sophie Sun [aut, cre], Danyi - Xiong [aut], Bjoern Bornkamp [ctb], Frank Bretz [ctb], Ardalan - Mirshani [ctb]. This app performs power and sample size calculations - for a multiple contrast test for normal, binary and negative binomial - outcomes. The app uses the DoseFinding package as calculation backend - and the R code underlying the calculations in the app can be extracted - from the app. - -} \usage{ - DesignMCPModApp() +DesignMCPModApp() +} +\description{ +This function starts the externally hosted DesignMCPMod Shiny App in a +browser window. The app was developed by Sophie Sun [aut, cre], Danyi Xiong +[aut], Bjoern Bornkamp [ctb], Frank Bretz [ctb], Ardalan Mirshani [ctb]. +This app performs power and sample size calculations for a multiple contrast +test for normal, binary and negative binomial outcomes. The app uses the +DoseFinding package as calculation backend and the R code underlying the +calculations in the app can be extracted from the app. } diff --git a/man/DoseFinding-package.Rd b/man/DoseFinding-package.Rd index 6526cc9..ccaa960 100644 --- a/man/DoseFinding-package.Rd +++ b/man/DoseFinding-package.Rd @@ -50,35 +50,21 @@ desTD <- optDesign(fmodels, weights, Delta=0.2, designCrit="TD") } \references{ -Bornkamp, B., Bretz, F., Dette, H. and Pinheiro, J. C. (2011). -Response-Adaptive Dose-Finding under model uncertainty, \emph{Annals of -Applied Statistics}, \strong{5}, 1611--1631 +\insertRef{bornkamp2011}{DoseFinding} -Bornkamp B., Pinheiro J. C., and Bretz, F. (2009). MCPMod: An R Package for -the Design and Analysis of Dose-Finding Studies, \emph{Journal of -Statistical Software}, \strong{29}(7), 1--23 +\insertRef{bornkamp2009}{DoseFinding} -Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining multiple -comparisons and modeling techniques in dose-response studies, -\emph{Biometrics}, \strong{61}, 738--748 +\insertRef{bretz2005}{DoseFinding} -Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal -Designs for Dose Finding Studies, \emph{Journal of the American Statisical -Association}, \strong{103}, 1225--1237 +\insertRef{dette2008}{DoseFinding} -O'Quigley, J., Iasonos, A. and Bornkamp, B. (2017) Handbook of methods for -designing, monitoring, and analyzing dose-finding trials, CRC press, Part 3: -Dose-Finding Studies in Phase II +\insertRef{oquigley2017}{DoseFinding} -Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and analysis of -dose finding studies combining multiple comparisons and modeling procedures, -\emph{Journal of Biopharmaceutical Statistics}, \strong{16}, 639--656 +\insertRef{pinheiro2006}{DoseFinding} -Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based -dose finding under model uncertainty using general parametric models, -\emph{Statistics in Medicine}, \strong{33}, 1646--1661 +\insertRef{pinheiro2014}{DoseFinding} -Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley +\insertRef{seber2003}{DoseFinding} } \seealso{ Useful links: @@ -107,4 +93,3 @@ Other contributors: } } -\keyword{internal} diff --git a/man/IBScovars.Rd b/man/IBScovars.Rd index 87e51d2..d38272a 100644 --- a/man/IBScovars.Rd +++ b/man/IBScovars.Rd @@ -1,32 +1,31 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DoseFinding-package.R -\docType{data} -\name{IBScovars} -\alias{IBScovars} -\title{Irritable Bowel Syndrome Dose Response data with covariates} -\format{ -A data frame with 369 observations on the following 2 variables. -\describe{ -\item{\code{gender}}{a factor specifying the gender} -\item{\code{dose}}{a numeric vector} -\item{\code{resp}}{a numeric vector} -} -} -\source{ -Biesheuvel, E. and Hothorn, L. A. (2002). Many-to-one comparisons in -stratified designs, \emph{Biometrical Journal}, \strong{44}, 101--116 -} -\usage{ -data(IBScovars) -} -\description{ -A subset of the data used by (Biesheuvel and Hothorn, 2002). The data are -part of a dose ranging trial on a compound for the treatment of the -irritable bowel syndrome with four active treatment arms, corresponding to -doses 1,2,3,4 and placebo. Note that the original dose levels have been -blinded in this data set for confidentiality. The primary endpoint was a -baseline adjusted abdominal pain score with larger values corresponding to a -better treatment effect. In total 369 patients completed the study, with -nearly balanced allocation across the doses. -} -\keyword{datasets} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DoseFinding-package.R +\docType{data} +\name{IBScovars} +\alias{IBScovars} +\title{Irritable Bowel Syndrome Dose Response data with covariates} +\format{ +A data frame with 369 observations on the following 2 variables. +\describe{ +\item{\code{gender}}{a factor specifying the gender} +\item{\code{dose}}{a numeric vector} +\item{\code{resp}}{a numeric vector} +} +} +\source{ +\insertRef{biesheuvel2002}{DoseFinding} +} +\usage{ +data(IBScovars) +} +\description{ +A subset of the data used by (Biesheuvel and Hothorn, 2002). The data are +part of a dose ranging trial on a compound for the treatment of the +irritable bowel syndrome with four active treatment arms, corresponding to +doses 1,2,3,4 and placebo. Note that the original dose levels have been +blinded in this data set for confidentiality. The primary endpoint was a +baseline adjusted abdominal pain score with larger values corresponding to a +better treatment effect. In total 369 patients completed the study, with +nearly balanced allocation across the doses. +} +\keyword{datasets} diff --git a/man/MCPMod.Rd b/man/MCPMod.Rd index ccc3057..fe15bf5 100644 --- a/man/MCPMod.Rd +++ b/man/MCPMod.Rd @@ -1,221 +1,158 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/MCPMod.R \name{MCPMod} \alias{MCPMod} \alias{predict.MCPMod} \alias{plot.MCPMod} -\title{ - MCPMod - Multiple Comparisons and Modeling -} -\description{ - Tests for a dose-response effect using a model-based multiple contrast - test (see \code{\link{MCTtest}}), selects one (or several) model(s) - from the significant shapes, fits them using \code{\link{fitMod}}. - For details on the method see Bretz et al. (2005). -} +\title{MCPMod - Multiple Comparisons and Modeling} \usage{ -MCPMod(dose, resp, data, models, S = NULL, type = c("normal", "general"), - addCovars = ~1, placAdj = FALSE, selModel = c("AIC", "maxT", "aveAIC"), - alpha = 0.025, df = NULL, critV = NULL, doseType = c("TD", "ED"), - Delta, p, pVal = TRUE, alternative = c("one.sided", "two.sided"), - na.action = na.fail, mvtcontrol = mvtnorm.control(), - bnds, control = NULL) +MCPMod( + dose, + resp, + data = NULL, + models = NULL, + S = NULL, + type = c("normal", "general"), + addCovars = ~1, + placAdj = FALSE, + selModel = c("AIC", "maxT", "aveAIC"), + alpha = 0.025, + df = NULL, + critV = NULL, + doseType = c("TD", "ED"), + Delta, + p, + pVal = TRUE, + alternative = c("one.sided", "two.sided"), + na.action = na.fail, + mvtcontrol = mvtnorm.control(), + bnds, + control = NULL +) + +\method{predict}{MCPMod}( + object, + predType = c("full-model", "ls-means", "effect-curve"), + newdata = NULL, + doseSeq = NULL, + se.fit = FALSE, + ... +) + +\method{plot}{MCPMod}( + x, + CI = FALSE, + level = 0.95, + plotData = c("means", "meansCI", "raw", "none"), + plotGrid = TRUE, + colMn = 1, + colFit = 1, + ... +) +} +\arguments{ +\item{dose, resp}{Either vectors of equal length specifying dose and response values, or names of variables in the +data frame specified in \samp{data}.} -\method{predict}{MCPMod}(object, - predType = c("full-model", "ls-means", "effect-curve"), - newdata = NULL, doseSeq = NULL, se.fit = FALSE, ...) +\item{data}{Data frame containing the variables referenced in dose and resp if \samp{data} is not specified it is +assumed that \samp{dose} and \samp{resp} are variables referenced from data (and no vectors)} +\item{models}{An object of class \samp{Mods}, see \code{\link[=Mods]{Mods()}} for details} +\item{S}{The covariance matrix of \samp{resp} when \samp{type = "general"}, see Description.} -\method{plot}{MCPMod}(x, CI = FALSE, level = 0.95, - plotData = c("means", "meansCI", "raw", "none"), - plotGrid = TRUE, colMn = 1, colFit = 1, ...) +\item{type}{Determines whether inference is based on an ANCOVA model under a homoscedastic normality assumption (when +\samp{type = "normal"}), or estimates at the doses and their covariance matrix and degrees of freedom are specified +directly in \samp{resp}, \samp{S} and \samp{df}. See also \code{\link[=fitMod]{fitMod()}} and \insertCite{pinheiro2014}{DoseFinding}.} -} -\arguments{ - \item{dose, resp}{ - Either vectors of equal length specifying dose and response values, - or names of variables in the data frame specified in \samp{data}. - } - \item{data}{ - Data frame containing the variables referenced in dose and resp if - \samp{data} is not specified it is assumed that \samp{dose} and - \samp{resp} are variables referenced from data (and no vectors) - } - \item{models}{ - An object of class \samp{"Mods"}, see \code{\link{Mods}} for - details - } - \item{S}{ - The covariance matrix of \samp{resp} when \samp{type = "general"}, - see Description. - } - \item{type}{ - Determines whether inference is based on an ANCOVA model under a - homoscedastic normality assumption (when \samp{type = "normal"}), or - estimates at the doses and their covariance matrix and degrees of - freedom are specified directly in \samp{resp}, \samp{S} and - \samp{df}. See also \code{\link{fitMod}} and Pinheiro et al. (2014). - } - \item{addCovars}{ - Formula specifying additive linear covariates (for \samp{type = "normal"}) -} -\item{placAdj}{ - Logical, if true, it is assumed that placebo-adjusted estimates are - specified in \samp{resp} (only possible for \samp{type = "general"}). -} -\item{selModel}{ - Optional character vector specifying the model selection criterion for - dose estimation. Possible values are - \itemize{ - \item \code{AIC}: Selects model with smallest AIC (this is the default) - \item \code{maxT}: Selects the model corresponding to the largest t-statistic. - \item \code{aveAIC}: Uses a weighted average of the models corresponding to the - significant contrasts. The model weights are chosen by the formula: - \eqn{w_i = \exp(-0.5AIC_i)/\sum_i(\exp(-0.5AIC_i))}{w_i = exp(-0.5AIC_i)/sum(exp(-0.5AIC_i))} - See Buckland et al. (1997) for details. - } - For \samp{type = "general"} the "gAIC" is used. +\item{addCovars}{Formula specifying additive linear covariates (for \samp{type = "normal"})} -} -\item{alpha}{ - Significance level for the multiple contrast test -} -\item{df}{ - Specify the degrees of freedom to use in case \samp{type = "general"}, - for the call to \code{\link{MCTtest}} and \code{\link{fitMod}}. - Infinite degrees of (\samp{df=Inf}) correspond to the multivariate - normal distribution. - For type = "normal" the degrees of freedom deduced from the AN(C)OVA fit are - used and this argument is ignored. -} -\item{critV}{ - Supply a pre-calculated critical value. If this argument is NULL, no - critical value will be calculated and the test decision is based on - the p-values. If \samp{critV = TRUE} the critical value will be calculated. -} - \item{doseType, Delta, p}{ - \samp{doseType} determines the dose to estimate, ED or TD (see also - \code{\link{Mods}}), and \samp{Delta} and \samp{p} need to be - specified depending on whether TD or ED is to be estimated. - See \code{\link{TD}} and \code{\link{ED}} for details. - } -\item{pVal}{ - Logical determining, whether p-values should be calculated. -} -\item{alternative}{ - Character determining the alternative for the multiple contrast - trend test. -} -\item{na.action}{ - A function which indicates what should happen when - the data contain NAs. -} -\item{mvtcontrol}{ - A list specifying additional control parameters for the \samp{qmvt} - and \samp{pmvt} calls in the code, see also \code{\link{mvtnorm.control}} - for details. -} -\item{bnds}{ - Bounds for non-linear parameters. This needs to be a list with list - entries corresponding to the selected bounds. The names of the list - entries need to correspond to the model names. The - \code{\link{defBnds}} function provides the default selection. -} -\item{control}{ - Control list for the optimization.\cr - A list with entries: "nlminbcontrol", "optimizetol" and "gridSize". - - The entry nlminbcontrol needs to be a list and is passed directly to - control argument in the nlminb function, that is used internally for - models with 2 nonlinear parameters (e.g. sigmoid Emax or beta model). - - The entry optimizetol is passed directly to the tol argument of the - optimize function, which is used for models with 1 nonlinear - parameters (e.g. Emax or exponential model). - - The entry gridSize needs to be a list with entries dim1 and dim2 - giving the size of the grid for the gridsearch in 1d or 2d models. -} -\item{object, x}{ - MCPMod object -} -\item{predType, newdata, doseSeq, se.fit, ...}{ - predType determines whether predictions are returned for the full - model (including potential covariates), the ls-means (SAS type) or the - effect curve (difference to placebo). - - newdata gives the covariates to use in producing the predictions (for - \samp{predType = "full-model"}), if missing the covariates used for fitting - are used. - - doseSeq dose-sequence on where to produce predictions (for - \samp{predType = "effect-curve"} and \samp{predType = "ls-means"}). If - missing the doses used for fitting are used. - - se.fit: logical determining, whether the standard error should be - calculated. - - \ldots: Additional arguments, for plot.MCPMod these are passed to - plot.DRMod. -} -\item{CI, level, plotData, plotGrid, colMn, colFit}{ - Arguments for plot method: \samp{CI} determines whether confidence - intervals should be plotted. \samp{level} determines the level of the - confidence intervals. \samp{plotData} determines how the data are plotted: - Either as means or as means with CI, raw data or none. In case of - \samp{type = "normal"} and covariates the ls-means are displayed, when - \samp{type = "general"} the option "raw" is not available. - \samp{colMn} and \samp{colFit} determine the colors of fitted model - and the raw means. -} +\item{placAdj}{Logical, if true, it is assumed that placebo-adjusted +estimates are specified in \samp{resp} (only possible for \samp{type = + "general"}).} -} -\value{ - An object of class \samp{MCPMod}, which contains the fitted - \samp{MCTtest} object as well as the \samp{DRMod} objects and - additional information (model selection criteria, dose estimates, - selected models). -} -\references{ -Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining -multiple comparisons and modeling techniques in dose-response -studies, \emph{Biometrics}, \bold{61}, 738--748 +\item{selModel}{Optional character vector specifying the model selection +criterion for dose estimation. Possible values are \itemize{ \item +\code{AIC}: Selects model with smallest AIC (this is the default) \item +\code{maxT}: Selects the model corresponding to the largest t-statistic. +\item \code{aveAIC}: Uses a weighted average of the models corresponding to +the significant contrasts. The model weights are chosen by the formula: +\eqn{w_i = \exp(-0.5AIC_i)/\sum_i(\exp(-0.5AIC_i))}{w_i = + exp(-0.5AIC_i)/sum(exp(-0.5AIC_i))} See \insertCite{buckland1997;textual}{DoseFinding} for details. +} For \samp{type = "general"} the "gAIC" is used.} + +\item{alpha}{Significance level for the multiple contrast test} + +\item{df}{Specify the degrees of freedom to use in case \samp{type = "general"}, for the call to +\code{\link[=MCTtest]{MCTtest()}} and \code{\link[=fitMod]{fitMod()}}. Infinite degrees of (\samp{df=Inf}) correspond to the multivariate +normal distribution. For type = "normal" the degrees of freedom deduced from the AN(C)OVA fit are used and this +argument is ignored.} -Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and analysis of dose finding studies -combining multiple comparisons and modeling procedures, \emph{Journal of Biopharmaceutical -Statistics}, \bold{16}, 639--656 +\item{critV}{Supply a pre-calculated critical value. If this argument is NULL, no critical value will be calculated +and the test decision is based on the p-values. If \samp{critV = TRUE} the critical value will be calculated.} -Pinheiro, J. C., Bretz, F., and Branson, M. (2006). Analysis of dose-response studies - modeling -approaches, \emph{in} N. Ting (ed.). \emph{Dose Finding in Drug Development}, Springer, New York, -pp. 146--171 +\item{doseType, Delta, p}{\samp{doseType} determines the dose to estimate, ED or TD (see also \code{\link[=Mods]{Mods()}}), and +\samp{Delta} and \samp{p} need to be specified depending on whether TD or ED is to be estimated. See +\code{\link[=TD]{TD()}} and \code{\link[=ED]{ED()}} for details.} -Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) -Model-based dose finding under model uncertainty using general -parametric models, \emph{Statistics in Medicine}, \bold{33}, -1646--1661 +\item{pVal}{Logical determining, whether p-values should be calculated.} -Schorning, K., Bornkamp, B., Bretz, F., & Dette, H. (2016). Model -selection versus model averaging in dose finding -studies. \emph{Statistics in Medicine}, \bold{35}, 4021--4040 +\item{alternative}{Character determining the alternative for the multiple contrast trend test.} -Xun, X. and Bretz, F. (2017) The MCP-Mod methodology: -Practical Considerations and The DoseFinding R package, -in O'Quigley, J., Iasonos, A. and Bornkamp, B. (eds) -Handbook of methods for designing, monitoring, and analyzing -dose-finding trials, CRC press +\item{na.action}{A function which indicates what should happen when the data contain NAs.} -Buckland, S. T., Burnham, K. P. and Augustin, N. H. (1997). Model selection an integral part -of inference, \emph{Biometrics}, \bold{53}, 603--618 +\item{mvtcontrol}{A list specifying additional control parameters for the \samp{qmvt} and \samp{pmvt} calls in the +code, see also \code{\link[=mvtnorm.control]{mvtnorm.control()}} for details.} -Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley. +\item{bnds}{Bounds for non-linear parameters. This needs to be a list with list entries corresponding to the selected +bounds. The names of the list entries need to correspond to the model names. The \code{\link[=defBnds]{defBnds()}} function +provides the default selection.} + +\item{control}{Control list for the optimization.\cr A list with entries: "nlminbcontrol", "optimizetol" and +"gridSize". + +The entry nlminbcontrol needs to be a list and is passed directly to control argument in the nlminb function, that +is used internally for models with 2 nonlinear parameters (e.g. sigmoid Emax or beta model). + +The entry optimizetol is passed directly to the tol argument of the optimize function, which is used for models +with 1 nonlinear parameters (e.g. Emax or exponential model). + +The entry gridSize needs to be a list with entries dim1 and dim2 giving the size of the grid for the gridsearch in +1d or 2d models.} + +\item{object, x}{MCPMod object} + +\item{predType, newdata, doseSeq, se.fit, ...}{predType determines whether predictions are returned for the full model +(including potential covariates), the ls-means (SAS type) or the effect curve (difference to placebo). + +newdata gives the covariates to use in producing the predictions (for \samp{predType = "full-model"}), if missing +the covariates used for fitting are used. + +doseSeq dose-sequence on where to produce predictions (for \samp{predType = + "effect-curve"} and \samp{predType = "ls-means"}). If missing the doses used +for fitting are used. + +se.fit: logical determining, whether the standard error should be calculated. + +\ldots: Additional arguments, for plot.MCPMod these are passed to plot.DRMod.} + +\item{CI, level, plotData, plotGrid, colMn, colFit}{Arguments for plot method: \samp{CI} determines whether confidence +intervals should be plotted. \samp{level} determines the level of the confidence intervals. \samp{plotData} +determines how the data are plotted: Either as means or as means with CI, raw data or none. In case of \samp{type = + "normal"} and covariates the ls-means are displayed, when \samp{type = "general"} the option "raw" is not +available. \samp{colMn} and \samp{colFit} determine the colors of fitted model and the raw means.} } -\author{ - Bjoern Bornkamp +\value{ +An object of class \samp{MCPMod}, which contains the fitted \samp{MCTtest} object as well as the \samp{DRMod} +objects and additional information (model selection criteria, dose estimates, selected models). } - -\seealso{ - \code{\link{MCTtest}}, \code{\link{fitMod}}, \code{\link{drmodels}} +\description{ +Tests for a dose-response effect using a model-based multiple contrast test (see \code{\link[=MCTtest]{MCTtest()}}), selects one +(or several) model(s) from the significant shapes, fits them using \code{\link[=fitMod]{fitMod()}}. For details on the method +see \insertCite{bretz2005;textual}{DoseFinding}. } \examples{ + data(biom) ## first define candidate model set (only need "standardized" models) models <- Mods(linear = NULL, emax=c(0.05,0.2), linInt=c(1, 1, 1, 1), @@ -229,7 +166,7 @@ summary(MM) # more information ## predict all significant dose-response models predict(MM, se.fit=TRUE, doseSeq=c(0,0.2,0.4, 0.9, 1), predType="ls-means") -## display all model functions +## display all model functions plot(MM, plotData="meansCI", CI=TRUE) ## now perform model-averaging @@ -262,5 +199,26 @@ plot(MM3, plotData="meansCI") ## this is useful, e.g. in simulation studies MM4 <- MCPMod(dose, resp, biom, models, Delta=0.5, critV = 2.31) } +\references{ +\insertRef{buckland1997}{DoseFinding} + +\insertRef{bretz2005}{DoseFinding} + +\insertRef{pinheiro2006b}{DoseFinding} + +\insertRef{pinheiro2006}{DoseFinding} +\insertRef{pinheiro2014}{DoseFinding} +\insertRef{schorning2016}{DoseFinding} + +\insertRef{seber2003}{DoseFinding} + +\insertRef{xun2017}{DoseFinding} +} +\seealso{ +\code{\link[=MCTtest]{MCTtest()}}, \code{\link[=fitMod]{fitMod()}}, \code{\link[=drmodels]{drmodels()}} +} +\author{ +Bjoern Bornkamp +} diff --git a/man/MCTpval.Rd b/man/MCTpval.Rd index 5401fa9..0182b29 100644 --- a/man/MCTpval.Rd +++ b/man/MCTpval.Rd @@ -57,9 +57,7 @@ test <- MCTtest(dose, resp, biom, models=modlist) attr(test$tStat, "pVal") } \references{ -Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and analysis of dose finding studies -combining multiple comparisons and modeling procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, -639--656 +\insertRef{pinheiro2006b}{DoseFinding} } \seealso{ \code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}} diff --git a/man/MCTtest.Rd b/man/MCTtest.Rd index 443c709..3d897a8 100644 --- a/man/MCTtest.Rd +++ b/man/MCTtest.Rd @@ -1,127 +1,92 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/MCTtest.R \name{MCTtest} \alias{MCTtest} -\title{ - Performs multiple contrast test -} -\description{ - This function performs a multiple contrast test. The contrasts are - either directly specified in \samp{contMat} or optimal contrasts - derived from the \samp{models} argument. The directionality of the - data (i.e. whether an increase or decrease in the response variable is - beneficial is inferred from the \samp{models} object, see - \code{\link{Mods}}). - - For \samp{type = "normal"} an ANCOVA model based on a homoscedastic - normality assumption (with additive covariates specified in - \samp{addCovars}) is fitted. - - For \samp{type = "general"} it is assumed multivariate normally - distributed estimates are specified in \samp{resp} with covariance - given by \samp{S}, and the contrast test statistic is calculated based - on this assumption. Degrees of freedom specified in \samp{df}. -} +\title{Performs multiple contrast test} \usage{ -MCTtest(dose, resp, data = NULL, models, S = NULL, type = c("normal", "general"), - addCovars = ~1, placAdj = FALSE, alpha = 0.025, df = NULL, - critV = NULL, pVal = TRUE, - alternative = c("one.sided", "two.sided"), na.action = na.fail, - mvtcontrol = mvtnorm.control(), contMat = NULL) - +MCTtest( + dose, + resp, + data = NULL, + models, + S = NULL, + type = c("normal", "general"), + addCovars = ~1, + placAdj = FALSE, + alpha = 0.025, + df = NULL, + critV = NULL, + pVal = TRUE, + alternative = c("one.sided", "two.sided"), + na.action = na.fail, + mvtcontrol = mvtnorm.control(), + contMat = NULL +) } \arguments{ - \item{dose, resp}{ - Either vectors of equal length specifying dose and response values, - or names of variables in the data frame specified in \samp{data}. - } - \item{data}{ - Data frame containing the variables referenced in dose and resp if - \samp{data} is not specified it is assumed that \samp{dose} and - \samp{resp} are variables referenced from data (and no vectors) - } - \item{models}{ - An object of class \samp{Mods}, see \code{\link{Mods}} for - details - } - \item{S}{ - The covariance matrix of \samp{resp} when \samp{type = "general"}, - see Description. - } - \item{type}{ - Determines whether inference is based on an ANCOVA model under a - homoscedastic normality assumption (when \samp{type = "normal"}), or - estimates at the doses and their covariance matrix and degrees of - freedom are specified directly in \samp{resp}, \samp{S} and - \samp{df}. See also \code{\link{fitMod}} and Pinheiro et al. (2014). - } - \item{addCovars}{ - Formula specifying additive linear covariates (for \samp{type = "normal"}) -} -\item{placAdj}{ - Logical, if true, it is assumed that placebo-adjusted estimates are - specified in \samp{resp} (only possible for \samp{type = "general"}). -} - \item{alpha}{ - Significance level for the multiple contrast test -} -\item{df}{ - Specify the degrees of freedom to use in case \samp{type = "general"}. - If this argument is missing \samp{df = Inf} is used (which corresponds - to the multivariate normal distribution). - For type = "normal" the degrees of freedom deduced from the AN(C)OVA fit are - used and this argument is ignored. -} -\item{critV}{ - Supply a pre-calculated critical value. If this argument is NULL, no - critical value will be calculated and the test decision is based on - the p-values. If \samp{critV = TRUE} the critical value will be calculated. -} - \item{pVal}{ - Logical determining, whether p-values should be calculated. -} -\item{alternative}{ - Character determining the alternative for the multiple contrast - trend test. -} -\item{na.action}{ - A function which indicates what should happen when - the data contain NAs. -} -\item{mvtcontrol}{ - A list specifying additional control parameters for the \samp{qmvt} - and \samp{pmvt} calls in the code, see also \code{\link{mvtnorm.control}} - for details. -} -\item{contMat}{ - Contrast matrix to apply to the ANCOVA dose-response estimates. The - contrasts need to be in the columns of the matrix (i.e. the column - sums need to be 0). -} -} -\details{ - Integrals over the multivariate t and multivariate normal distribution - are calculated using the \samp{mvtnorm} package. +\item{dose, resp}{Either vectors of equal length specifying dose and response values, or names of variables in the +data frame specified in \samp{data}.} + +\item{data}{Data frame containing the variables referenced in dose and resp if \samp{data} is not specified it is +assumed that \samp{dose} and \samp{resp} are variables referenced from data (and no vectors)} + +\item{models}{An object of class \samp{Mods}, see \code{\link[=Mods]{Mods()}} for details} + +\item{S}{The covariance matrix of \samp{resp} when \samp{type = "general"}, see Description.} + +\item{type}{Determines whether inference is based on an ANCOVA model under a homoscedastic normality assumption (when +\samp{type = "normal"}), or estimates at the doses and their covariance matrix and degrees of freedom are specified +directly in \samp{resp}, \samp{S} and \samp{df}. See also \code{\link[=fitMod]{fitMod()}} and \insertCite{pinheiro2014}{DoseFinding}.} + +\item{addCovars}{Formula specifying additive linear covariates (for \samp{type = "normal"})} + +\item{placAdj}{Logical, if true, it is assumed that placebo-adjusted +estimates are specified in \samp{resp} (only possible for \samp{type = + "general"}).} + +\item{alpha}{Significance level for the multiple contrast test} + +\item{df}{Specify the degrees of freedom to use in case \samp{type = "general"}. If this argument is missing +\samp{df = Inf} is used (which corresponds to the multivariate normal distribution). For type = "normal" the +degrees of freedom deduced from the AN(C)OVA fit are used and this argument is ignored.} + +\item{critV}{Supply a pre-calculated critical value. If this argument is NULL, no critical value will be calculated +and the test decision is based on the p-values. If \samp{critV = TRUE} the critical value will be calculated.} + +\item{pVal}{Logical determining, whether p-values should be calculated.} + +\item{alternative}{Character determining the alternative for the multiple contrast trend test.} + +\item{na.action}{A function which indicates what should happen when the data contain NAs.} + +\item{mvtcontrol}{A list specifying additional control parameters for the \samp{qmvt} and \samp{pmvt} calls in the +code, see also \code{\link[=mvtnorm.control]{mvtnorm.control()}} for details.} + +\item{contMat}{Contrast matrix to apply to the ANCOVA dose-response estimates. The contrasts need to be in the +columns of the matrix (i.e. the column sums need to be 0).} } \value{ - An object of class MCTtest, a list containing the output. -} -\references{ - Hothorn, T., Bretz, F., and Westfall, P. (2008). Simultaneous - Inference in General Parametric Models, \emph{Biometrical Journal}, - \bold{50}, 346--363 - - Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) - Model-based dose finding under model uncertainty using general - parametric models, \emph{Statistics in Medicine}, \bold{33}, - 1646--1661 +An object of class MCTtest, a list containing the output. } -\author{ - Bjoern Bornkamp +\description{ +This function performs a multiple contrast test. The contrasts are either directly specified in \samp{contMat} or +optimal contrasts derived from the \samp{models} argument. The directionality of the data (i.e. whether an increase +or decrease in the response variable is beneficial is inferred from the \samp{models} object, see +\code{\link[=Mods]{Mods()}}). } +\details{ +For \samp{type = "normal"} an ANCOVA model based on a homoscedastic normality assumption (with additive covariates +specified in \samp{addCovars}) is fitted. -\seealso{ - \code{\link{powMCT}}, \code{\link{optContr}} +For \samp{type = "general"} it is assumed multivariate normally distributed estimates are specified in \samp{resp} +with covariance given by \samp{S}, and the contrast test statistic is calculated based on this assumption. Degrees of +freedom specified in \samp{df}. + +Integrals over the multivariate t and multivariate normal distribution are calculated using the \samp{mvtnorm} +package. } \examples{ + ## example without covariates data(biom) ## define shapes for which to calculate optimal contrasts @@ -174,6 +139,16 @@ contMat <- rbind(-1, diag(4)) rownames(contMat) <- doses colnames(contMat) <- paste("D", doses[-1], sep="") MCTtest(dose, resp, data=biom, contMat = contMat) -} +} +\references{ +\insertRef{hothorn2008}{DoseFinding} +\insertRef{pinheiro2014}{DoseFinding} +} +\seealso{ +\code{\link[=powMCT]{powMCT()}}, \code{\link[=optContr]{optContr()}} +} +\author{ +Bjoern Bornkamp +} diff --git a/man/Mods.Rd b/man/Mods.Rd index 266c50e..35913c7 100644 --- a/man/Mods.Rd +++ b/man/Mods.Rd @@ -209,9 +209,7 @@ 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, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, -639--656 +\insertRef{pinheiro2006b}{DoseFinding} } \seealso{ \code{\link[=Mods]{Mods()}}, \code{\link[=drmodels]{drmodels()}}, \code{\link[=optDesign]{optDesign()}}, \code{\link[=powMCT]{powMCT()}} diff --git a/man/bFitMod.Rd b/man/bFitMod.Rd index 609d284..7e968d6 100644 --- a/man/bFitMod.Rd +++ b/man/bFitMod.Rd @@ -1,234 +1,211 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bFitMod.R \name{bFitMod} \alias{bFitMod} \alias{coef.bFitMod} \alias{predict.bFitMod} \alias{plot.bFitMod} -\title{ - Fit a dose-response model using Bayesian or bootstrap methods. -} -\description{ - For \samp{type = "Bayes"}, MCMC sampling from the posterior distribution of - the dose-response model is done. The function assumes a multivariate - normal distribution for \code{resp} with covariance matrix \code{S}, - and this is taken as likelihood function and combined with the prior - distributions specified in prior to form the posterior distribution. - - For \samp{type = "bootstrap"}, a multivariate normal distribution for - \code{resp} with covariance matrix \code{S} is assumed, and a large - number of samples is drawn from this distribution. For each draw the - fitMod function with \samp{type = "general"} is used to fit the draws - from the multivariate normal distribution. -} +\title{Fit a dose-response model using Bayesian or bootstrap methods.} \usage{ -bFitMod(dose, resp, model, S, placAdj = FALSE, - type = c("Bayes", "bootstrap"), - start = NULL, prior = NULL, nSim = 1000, - MCMCcontrol = list(), control = NULL, bnds, - addArgs = NULL) +bFitMod( + dose, + resp, + model, + S, + placAdj = FALSE, + type = c("Bayes", "bootstrap"), + start = NULL, + prior = NULL, + nSim = 1000, + MCMCcontrol = list(), + control = NULL, + bnds, + addArgs = NULL +) + +\method{predict}{bFitMod}( + object, + predType = c("full-model", "effect-curve"), + summaryFct = function(x) quantile(x, probs = c(0.025, 0.25, 0.5, 0.75, 0.975)), + doseSeq = NULL, + lenSeq = 101, + ... +) + +\method{plot}{bFitMod}( + x, + plotType = c("dr-curve", "effect-curve"), + quant = c(0.025, 0.5, 0.975), + plotData = c("means", "meansCI", "none"), + level = 0.95, + lenDose = 201, + ... +) \method{coef}{bFitMod}(object, ...) +} +\arguments{ +\item{dose}{Numeric specifying the dose variable.} + +\item{resp}{Numeric specifying the response estimate corresponding to the doses in \code{dose}} + +\item{model}{Dose-response model to fit, possible models are "linlog", "linear", "quadratic", "emax", "exponential", +"sigEmax", "betaMod" and "logistic", see \code{\link[=drmodels]{drmodels()}}.} + +\item{S}{Covariance matrix associated with the dose-response estimate specified via \code{resp}} + +\item{placAdj}{Whether or not estimates in "placAdj" are placebo-adjusted (note that the linear in log and the +logistic model cannot be fitted for placebo-adjusted data)} + +\item{type}{Character with allowed values "Bayes" and "bootstrap", Determining whether samples are drawn from the +posterior, or the bootstrap distribution.} + +\item{start}{Optional starting values for the dose-response parameters in the MCMC algorithm.} + +\item{prior}{List containing the information regarding the prior distributions for \samp{type = "Bayes"}. The list +needs to have as many entries as there are model parameters. The ordering of the list entries should be the same as +in the arguments list of the model see (see \code{\link[=drmodels]{drmodels()}}). For example for the Emax model the first +entry determines the prior for e0, the second to eMax and the third to ed50. + +For each list entry the user has the choice to choose from 4 possible +distributions: \itemize{ \item \code{norm}: Vector of length 2 giving mean +and standard deviation. \item \code{t}: Vector of length 3 giving median, +scale and degrees of freedom of the t-distribution. \item \code{lnorm}: +Vector of length 2 giving mean and standard deviation on log scale. \item +\code{beta}: Vector of length 4 giving lower and upper bound of the beta +prior as well as the alpha and beta parameters of the beta distribution }} + +\item{nSim}{Desired number of samples to produce with the algorithm} + +\item{MCMCcontrol}{List of control parameters for the MCMC algorithm +\itemize{ \item \code{thin} Thinning rate. Must be a positive integer. +\item \code{w} Numeric of same length as number of parameters in the model, +specifies the width parameters of the slice sampler. \item \code{adapt} +Logical whether to adapt the \code{w} (width) parameter of the slice sampler +in a short trial run. The widths are chosen as IQR/1.3 of the trial run. }} + +\item{control}{Same as the control argument in \code{\link[=fitMod]{fitMod()}}.} + +\item{bnds}{Bounds for non-linear parameters, in case \samp{type = "bootstrap"}. If missing the the default bounds +from \code{\link[=defBnds]{defBnds()}} is used.} + +\item{addArgs}{List containing two entries named "scal" and "off" for the "betaMod" and "linlog" model. When addArgs +is NULL the following defaults are used \samp{list(scal = 1.2*max(doses), off = 0.01*max(doses))}} + +\item{predType, summaryFct, doseSeq, lenSeq}{Arguments for the predict method. + +\samp{predType}: predType determines whether predictions are returned for the dose-response curve or the effect +curve (difference to placebo). -\method{predict}{bFitMod}(object, predType = c("full-model", "effect-curve"), - summaryFct = function(x) quantile(x, probs = c(0.025, 0.25, 0.5, 0.75, 0.975)), - doseSeq = NULL, lenSeq = 101, ...) +\samp{summaryFct}: If equal to NULL predictions are calculated for each sampled parameter value. Otherwise a +summary function is applied to the dose-response predictions for each parameter value. The default is to calculate +0.025, 0.25, 0.5, 0.75, 0.975 quantiles of the predictions for each dose. -\method{plot}{bFitMod}(x, plotType = c("dr-curve", "effect-curve"), - quant = c(0.025, 0.5, 0.975), - plotData = c("means", "meansCI", "none"), - level = 0.95, lenDose = 201, ...) +\samp{doseSeq}: Where to calculate predictions. If not specified predictions are calculated on a grid of length +\samp{lenSeq} between minimum and maximum dose. +\samp{lenSeq}: Length of the default grid where to calculate predictions.} + +\item{...}{Additional arguments are ignored.} + +\item{x, object}{A bFitMod object} + +\item{plotType, quant, plotData, level, lenDose}{Arguments for plot method. + +\samp{plotType}: Determining whether the dose-response curve or the effect curve should be plotted. + +\samp{quant}: Vector of quantiles to display in plot + +\samp{plotData}: Determines how the original data are plotted: Either as means or as means with CI or not. The +level of the CI is determined by the argument \samp{level}. + +\samp{level}: Level for CI, when plotData is equal to \samp{meansCI}. + +\samp{lenDose}: Number of grid values to use for display.} } -\arguments{ - \item{dose}{ Numeric specifying the dose variable. } - \item{resp}{ Numeric specifying the response estimate - corresponding to the doses in \code{dose}} - \item{S}{ Covariance matrix associated with the dose-response - estimate specified via \code{resp}} - \item{model}{ Dose-response model to fit, possible models are - "linlog", "linear", "quadratic", "emax", "exponential", - "sigEmax", "betaMod" and "logistic", see \code{\link{drmodels}}. - } - \item{placAdj}{ Whether or not estimates in "placAdj" are - placebo-adjusted (note that the linear in log and - the logistic model cannot be fitted for placebo-adjusted data) - } - \item{type}{ - Character with allowed values "Bayes" and "bootstrap", Determining - whether samples are drawn from the posterior, or the bootstrap - distribution. - } - \item{start}{ Optional starting values for the dose-response - parameters in the MCMC algorithm. - } - \item{prior}{ - List containing the information regarding the prior distributions - for \samp{type = "Bayes"}. - The list needs to have as many entries as there are model - parameters. The ordering of the list entries should be the same as - in the arguments list of the model see (see \code{\link{drmodels}}). - For example for the Emax model the first entry determines the prior - for e0, the second to eMax and the third to ed50. - - For each list entry the user has the choice to choose - from 4 possible distributions: - \itemize{ - \item \code{norm}: Vector of length 2 giving mean and standard deviation. - \item \code{t}: Vector of length 3 giving median, scale and degrees - of freedom of the t-distribution. - \item \code{lnorm}: Vector of length 2 giving mean and standard - deviation on log scale. - \item \code{beta}: Vector of length 4 giving lower and upper bound - of the beta prior as well as the alpha and beta parameters of the - beta distribution - } - } - \item{nSim}{ - Desired number of samples to produce with the algorithm - } - \item{MCMCcontrol}{ - List of control parameters for the MCMC algorithm - \itemize{ - \item \code{thin} Thinning rate. Must be a positive integer. - \item \code{w} Numeric of same length as number of parameters in - the model, specifies the width parameters of the slice sampler. - \item \code{adapt} Logical whether to adapt the \code{w} (width) - parameter of the slice sampler in a short trial run. The widths - are chosen as IQR/1.3 of the trial run. - } - } - \item{control}{ - Same as the control argument in \code{\link{fitMod}}. - } - \item{bnds}{ - Bounds for non-linear parameters, in case \samp{type = - "bootstrap"}. If missing the the default bounds from - \code{\link{defBnds}} is used. - } - \item{addArgs}{ - List containing two entries named "scal" and "off" for the "betaMod" - and "linlog" model. When addArgs is NULL the following defaults are - used \samp{list(scal = 1.2*max(doses), off = 0.01*max(doses))}} - \item{x, object}{ - A bFitMod object - } - \item{predType, summaryFct, doseSeq, lenSeq}{ - Arguments for the predict method. - - \samp{predType}: predType determines whether predictions are returned - for the dose-response curve or the effect curve (difference to placebo). - - \samp{summaryFct}: If equal to NULL predictions are calculated for - each sampled parameter value. Otherwise a summary function is - applied to the dose-response predictions for each parameter value. - The default is to calculate 0.025, 0.25, 0.5, 0.75, 0.975 quantiles - of the predictions for each dose. - - \samp{doseSeq}: Where to calculate predictions. If not specified - predictions are calculated on a grid of length \samp{lenSeq} between - minimum and maximum dose. - - \samp{lenSeq}: Length of the default grid where to calculate - predictions. - } - \item{plotType, quant, plotData, level, lenDose}{ - Arguments for plot method. - - \samp{plotType}: Determining whether the dose-response curve or the - effect curve should be plotted. - - \samp{quant}: Vector of quantiles to display in plot - - \samp{plotData}: Determines how the original data are plotted: - Either as means or as means with CI or not. The level of the CI is - determined by the argument \samp{level}. - - \samp{level}: Level for CI, when plotData is equal to - \samp{meansCI}. - - \samp{lenDose}: Number of grid values to use for display. - } - \item{...}{ - Additional arguments are ignored. +\value{ +An object of class bFitMod, which is a list containing the matrix of posterior simulations plus some +additional information on the fitted model. } - +\description{ +For \samp{type = "Bayes"}, MCMC sampling from the posterior distribution of the dose-response model is done. The +function assumes a multivariate normal distribution for \code{resp} with covariance matrix \code{S}, and this is +taken as likelihood function and combined with the prior distributions specified in prior to form the posterior +distribution. } \details{ - Componentwise univariate slice samplers are implemented (see Neal, - 2003) to sample from the posterior distribution. +For \samp{type = "bootstrap"}, a multivariate normal distribution for \code{resp} with covariance matrix \code{S} is +assumed, and a large number of samples is drawn from this distribution. For each draw the fitMod function with +\samp{type = "general"} is used to fit the draws from the multivariate normal distribution. + +Componentwise univariate slice samplers are implemented \insertCite{@see @neal2003}{DoseFinding} +to sample from the posterior distribution. } -\value{ - An object of class bFitMod, which is a list containing the matrix of - posterior simulations plus some additional information on the fitted - model. +\examples{ +data(biom) +anMod <- lm(resp~factor(dose)-1, data=biom) +drFit <- coef(anMod) +S <- vcov(anMod) +dose <- sort(unique(biom$dose)) +## define prior list +## normal prior for E0 (mean=0 and sdev=10) +## normal prior for Emax (mean=0 and sdev=100) +## beta prior for ED50: bounds: [0,1.5] parameters shape1=0.45, shape2=1.7 +prior <- list(norm = c(0, 10), norm = c(0,100), beta=c(0,1.5,0.45,1.7)) +## now fit an emax model +gsample <- bFitMod(dose, drFit, S, model = "emax", + start = c(0, 1, 0.1), nSim = 1000, prior = prior) +## summary information +gsample +## samples are stored in +head(gsample$samples) +## predict 0.025, 0.25, 0.5, 0.75, 0.975 Quantile at 0, 0.5 and 1 +predict(gsample, doseSeq = c(0, 0.5, 1)) +## simple plot function +plot(gsample) + +## now look at bootstrap distribution +gsample <- bFitMod(dose, drFit, S, model = "emax", type = "bootstrap", + nSim = 100, bnds = defBnds(1)$emax) +plot(gsample) + +## now fit linear interpolation +prior <- list(norm = c(0,1000), norm = c(0,1000), + norm = c(0,1000), norm = c(0,1000), norm = c(0,100)) +gsample <- bFitMod(dose, drFit, S, model = "linInt", + start = rep(1,5), nSim = 1000, prior = prior) +gsample <- bFitMod(dose, drFit, S, model = "linInt", type = "bootstrap", + nSim = 100) + +## data fitted on placebo adjusted scale +data(IBScovars) +anovaMod <- lm(resp~factor(dose)+gender, data=IBScovars) +drFit <- coef(anovaMod)[2:5] # placebo adjusted estimates at doses +vCov <- vcov(anovaMod)[2:5,2:5] +dose <- sort(unique(IBScovars$dose))[-1] +prior <- list(norm = c(0,100), beta=c(0,6,0.45,1.7)) +## Bayes fit +gsample <- bFitMod(dose, drFit, vCov, model = "emax", placAdj=TRUE, + start = c(1, 0.1), nSim = 1000, prior = prior) +## bootstrap fit +gsample <- bFitMod(dose, drFit, vCov, model = "emax", placAdj=TRUE, + type = "bootstrap", start = c(1, 0.1), + nSim = 100, prior = prior, bnds = c(0.01,6)) +## calculate target dose estimate +TD(gsample, Delta = 0.2) +## now fit linear interpolation +prior <- list(norm = c(0,1000), norm = c(0,1000), norm = c(0,1000), norm = c(0,100)) +gsample <- bFitMod(dose, drFit, vCov, model = "linInt", placAdj=TRUE, + start = rep(1,4), nSim = 1000, prior = prior) +gsample <- bFitMod(dose, drFit, vCov, model = "linInt", type = "bootstrap", + placAdj = TRUE, nSim = 100) } \references{ - Neal, R. M. (2003), Slice sampling, Annals of Statistics, 31, 705-767 +\insertAllCited{} } -\author{ - Bjoern Bornkamp -} - \seealso{ - \code{\link{fitMod}} +\code{\link[=fitMod]{fitMod()}} } -\examples{ - data(biom) - ## produce first stage fit (using dose as factor) - anMod <- lm(resp~factor(dose)-1, data=biom) - drFit <- coef(anMod) - S <- vcov(anMod) - dose <- sort(unique(biom$dose)) - ## define prior list - ## normal prior for E0 (mean=0 and sdev=10) - ## normal prior for Emax (mean=0 and sdev=100) - ## beta prior for ED50: bounds: [0,1.5] parameters shape1=0.45, shape2=1.7 - prior <- list(norm = c(0, 10), norm = c(0,100), beta=c(0,1.5,0.45,1.7)) - ## now fit an emax model - gsample <- bFitMod(dose, drFit, S, model = "emax", - start = c(0, 1, 0.1), nSim = 1000, prior = prior) - ## summary information - gsample - ## samples are stored in - head(gsample$samples) - ## predict 0.025, 0.25, 0.5, 0.75, 0.975 Quantile at 0, 0.5 and 1 - predict(gsample, doseSeq = c(0, 0.5, 1)) - ## simple plot function - plot(gsample) - - ## now look at bootstrap distribution - gsample <- bFitMod(dose, drFit, S, model = "emax", type = "bootstrap", - nSim = 100, bnds = defBnds(1)$emax) - plot(gsample) - - ## now fit linear interpolation - prior <- list(norm = c(0,1000), norm = c(0,1000), - norm = c(0,1000), norm = c(0,1000), norm = c(0,100)) - gsample <- bFitMod(dose, drFit, S, model = "linInt", - start = rep(1,5), nSim = 1000, prior = prior) - gsample <- bFitMod(dose, drFit, S, model = "linInt", type = "bootstrap", - nSim = 100) - - ## data fitted on placebo adjusted scale - data(IBScovars) - anovaMod <- lm(resp~factor(dose)+gender, data=IBScovars) - drFit <- coef(anovaMod)[2:5] # placebo adjusted estimates at doses - vCov <- vcov(anovaMod)[2:5,2:5] - dose <- sort(unique(IBScovars$dose))[-1] - prior <- list(norm = c(0,100), beta=c(0,6,0.45,1.7)) - ## Bayes fit - gsample <- bFitMod(dose, drFit, vCov, model = "emax", placAdj=TRUE, - start = c(1, 0.1), nSim = 1000, prior = prior) - ## bootstrap fit - gsample <- bFitMod(dose, drFit, vCov, model = "emax", placAdj=TRUE, - type = "bootstrap", start = c(1, 0.1), - nSim = 100, prior = prior, bnds = c(0.01,6)) - ## calculate target dose estimate - TD(gsample, Delta = 0.2) - ## now fit linear interpolation - prior <- list(norm = c(0,1000), norm = c(0,1000), norm = c(0,1000), norm = c(0,100)) - gsample <- bFitMod(dose, drFit, vCov, model = "linInt", placAdj=TRUE, - start = rep(1,4), nSim = 1000, prior = prior) - gsample <- bFitMod(dose, drFit, vCov, model = "linInt", type = "bootstrap", - placAdj = TRUE, nSim = 100) +\author{ +Bjoern Bornkamp } - diff --git a/man/bMCTtest.Rd b/man/bMCTtest.Rd index c1655fc..b2e0248 100644 --- a/man/bMCTtest.Rd +++ b/man/bMCTtest.Rd @@ -32,7 +32,7 @@ assumed that \samp{dose} and \samp{resp} are variables referenced from data (and \item{type}{Determines whether inference is based on an ANCOVA model under a homoscedastic normality assumption (when \samp{type = "normal"}), or estimates at the doses and their covariance matrix and degrees of freedom are specified -directly in \samp{resp}, \samp{S} and \samp{df}. See also \code{\link[=fitMod]{fitMod()}} and Pinheiro et al. (2014).} +directly in \samp{resp}, \samp{S} and \samp{df}. See also \code{\link[=fitMod]{fitMod()}} and \insertCite{pinheiro2014}{DoseFinding}.} \item{prior}{List of length equal to the number of doses with the prior for each arm. Each element needs to be of class \samp{normMix} (See \samp{RBesT} package documentation). It is assumed that the i-th component of the prior @@ -63,7 +63,7 @@ An object of class bMCTtest, a list containing the output. } \description{ This function performs a Bayesian multiple contrast test using normal mixture priors for the response on each dose, -as proposed in Fleischer et al. (2022). For a general description of the multiple contrast test see +as proposed in \insertCite{fleischer2022;textual}{DoseFinding}. For a general description of the multiple contrast test see \code{\link[=MCTtest]{MCTtest()}}. } \details{ @@ -71,7 +71,7 @@ If \samp{type = "normal"}, an ANCOVA model based on a homoscedastic normality as dose-response and contrast vectors are obtained assuming a known variance. For \samp{type = "general"} it is assumed multivariate normally distributed estimates are specified in \samp{resp} -with covariance given by \samp{S}, which define the likelihood. Posteriors for dose-response and contrast vectors +with covariance given by \samp{S}, which define the likelihood. Posteriors for dose-response and contrast vectors are then obtained assuming a known covariance matrix S The multiple contrast test decision is based on the maximum posterior probability of a contrast being greater than @@ -80,7 +80,7 @@ values. In the latter case the Bayesian test will give approximately the same re contrast test if uninformative priors are used. For the default calculation of optimal contrasts the prior information is ignored (i.e. contrasts are calculated in -the same way as in \code{\link[=MCTtest]{MCTtest()}}). Fleischer et al. (2022) discuss using contrasts that take the prior +the same way as in \code{\link[=MCTtest]{MCTtest()}}). \insertCite{fleischer2022;textual}{DoseFinding} discuss using contrasts that take the prior effective sample sizes into account, which can be slightly more favourable for the Bayesian MCT test. Such alternative contrasts can be directly handed over via the \samp{contMat} argument. @@ -192,8 +192,7 @@ bMCTtest(dose, resp, biom, models=modlist, prior = prior, contMat = cmat) } \references{ -Fleischer, F., Bossert, S., Deng, Q., Loley, C. and Gierse, J. (2022). Bayesian MCP-Mod, -\emph{Pharmaceutical Statistics}, \strong{21}, 654--670 +\insertAllCited{} } \seealso{ \code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}} diff --git a/man/biom.Rd b/man/biom.Rd index f1c43ea..2f84caa 100644 --- a/man/biom.Rd +++ b/man/biom.Rd @@ -1,26 +1,24 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DoseFinding-package.R -\docType{data} -\name{biom} -\alias{biom} -\title{Biometrics Dose Response data} -\format{ -A data frame with 100 observations on the following 2 variables. -\describe{ -\item{\code{resp}}{a numeric vector containing the response values} -\item{\code{dose}}{a numeric vector containing the dose values} -} -} -\source{ -Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining -multiple comparisons and modeling techniques in dose-response studies, -\emph{Biometrics}, \strong{61}, 738--748 -} -\usage{ -data(biom) -} -\description{ -An example data set for dose response studies. This data set was used in -Bretz et al. (2005) to illustrate the MCPMod methodology. -} -\keyword{datasets} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DoseFinding-package.R +\docType{data} +\name{biom} +\alias{biom} +\title{Biometrics Dose Response data} +\format{ +A data frame with 100 observations on the following 2 variables. +\describe{ +\item{\code{resp}}{a numeric vector containing the response values} +\item{\code{dose}}{a numeric vector containing the dose values} +} +} +\source{ +\insertRef{bretz2005}{DoseFinding} +} +\usage{ +data(biom) +} +\description{ +An example data set for dose response studies. This data set was used in +\insertCite{bretz2005;textual}{DoseFinding} to illustrate the MCPMod methodology. +} +\keyword{datasets} diff --git a/man/defBnds.Rd b/man/defBnds.Rd index 4f43580..7214595 100644 --- a/man/defBnds.Rd +++ b/man/defBnds.Rd @@ -1,48 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/fitMod.R \name{defBnds} \alias{defBnds} -\title{ - Calculates default bounds for non-linear parameters in dose-response - models -} -\description{ - Calculates reasonable bounds for non-linear parameters for the - built-in non-linear regression model based on the dose range under - investigation. - - For the logistic model the first row corresponds to the ED50 parameter and the - second row to the delta parameter. For the sigmoid Emax model the - first row corresponds to the ED50 parameter and the second row to the - h parameter, while for the beta model first and second row correspond - to the delta1 and delta2 parameters. See \code{\link{logistic}}, - \code{\link{sigEmax}} and \code{\link{betaMod}} for details. -} +\title{Calculates default bounds for non-linear parameters in dose-response models} \usage{ - defBnds(mD, emax = c(0.001, 1.5)*mD, - exponential = c(0.1, 2)*mD, - logistic = matrix(c(0.001, 0.01, 1.5, 1/2)*mD, 2), - sigEmax = matrix(c(0.001*mD, 0.5, 1.5*mD, 10), 2), - betaMod = matrix(c(0.05,0.05,4,4), 2)) +defBnds( + mD, + emax = c(0.001, 1.5) * mD, + exponential = c(0.1, 2) * mD, + logistic = matrix(c(0.001, 0.01, 1.5, 1/2) * mD, 2), + sigEmax = matrix(c(0.001 * mD, 0.5, 1.5 * mD, 10), 2), + betaMod = matrix(c(0.05, 0.05, 4, 4), 2) +) } \arguments{ - \item{mD}{ - Maximum dose in the study. -} - \item{emax, exponential, logistic, sigEmax, betaMod}{ - values for the nonlinear parameters for these model-functions -} +\item{mD}{Maximum dose in the study.} + +\item{emax, exponential, logistic, sigEmax, betaMod}{values for the nonlinear parameters for these model-functions} } \value{ - List containing bounds for the model parameters. +List containing bounds for the model parameters. } -\author{ - Bjoern Bornkamp +\description{ +Calculates reasonable bounds for non-linear parameters for the built-in non-linear regression model based on the dose +range under investigation. } -\seealso{ -\code{\link{fitMod}} +\details{ +For the logistic model the first row corresponds to the ED50 parameter and the second row to the delta parameter. For +the sigmoid Emax model the first row corresponds to the ED50 parameter and the second row to the h parameter, while +for the beta model first and second row correspond to the delta1 and delta2 parameters. See \code{\link[=logistic]{logistic()}}, +\code{\link[=sigEmax]{sigEmax()}} and \code{\link[=betaMod]{betaMod()}} for details. } \examples{ + defBnds(mD = 1) defBnds(mD = 200) } - - +\seealso{ +\code{\link[=fitMod]{fitMod()}} +} +\author{ +Bjoern Bornkamp +} diff --git a/man/drmodels.Rd b/man/drmodels.Rd index 09c92e9..557a488 100644 --- a/man/drmodels.Rd +++ b/man/drmodels.Rd @@ -239,13 +239,9 @@ linIntGrad(dose = (0:4)/4, resp=c(0,0.5,1,1,1), nodes=(0:4)/4) } \references{ -MacDougall, J. (2006). Analysis of dose-response studies - Emax -model,\emph{in} N. Ting (ed.), \emph{Dose Finding in Drug Development}, -Springer, New York, pp. 127--145 +\insertRef{macdougall2006}{DoseFinding} -Pinheiro, J. C., Bretz, F. and Branson, M. (2006). Analysis of dose-response -studies - modeling approaches, \emph{in} N. Ting (ed.). \emph{Dose Finding -in Drug Development}, Springer, New York, pp. 146--171 +\insertRef{pinheiro2006}{DoseFinding} } \seealso{ \code{\link[=fitMod]{fitMod()}} diff --git a/man/fitMod.Rd b/man/fitMod.Rd index 0089dca..18172c4 100644 --- a/man/fitMod.Rd +++ b/man/fitMod.Rd @@ -75,7 +75,7 @@ the first stage fit.} \item{type}{Determines whether inference is based on an ANCOVA model under a homoscedastic normality assumption (when \samp{type = "normal"}), or estimates at the doses and their covariance matrix and degrees of freedom are specified -directly in \samp{resp}, \samp{S} and \samp{df}. See also the Description above and Pinheiro et al. (2014).} +directly in \samp{resp}, \samp{S} and \samp{df}. See also the Description above and \insertCite{pinheiro2014;textual}{DoseFinding}.} \item{addCovars}{Formula specifying additional additive linear covariates (only for \samp{type = "normal"})} @@ -159,8 +159,8 @@ and an inverse weighting matrix is specified in \samp{S}, \samp{type = estimates obtained in a first stage fit, then \samp{resp} contains the estimates and \samp{S} is the estimated covariance matrix for the estimates in \samp{resp}. Statistical inference (e.g. confidence intervals) rely on asymptotic normality of the first stage estimates, which makes this method of interest only for sufficiently large -sample size for the first stage fit. A modified model-selection criterion can be applied to these model fits (see -also Pinheiro et al. 2014 for details). +sample size for the first stage fit. A modified model-selection criterion can be applied to these model fits +\insertCite{@see also @pinheiro2014 for details}{DoseFinding}. For details on the implemented numerical optimizer see the Details section below. @@ -172,9 +172,8 @@ for 2 nonlinear parameters the \code{\link[=nlminb]{nlminb()}} function is used. grid-search (with the grid size specified via \samp{control$gridSize}), or can directly be handed over via \samp{start}. -For details on the asymptotic approximation used for \samp{type = "normal"}, see Seber and Wild (2003, chapter 5). -For details on the asymptotic approximation used for \samp{type = "general"}, and the gAIC, see Pinheiro et al. -(2014). +For details on the asymptotic approximation used for \samp{type = "normal"}, see \insertCite{seber2003;textual}{DoseFinding}, Chapter 5. +For details on the asymptotic approximation used for \samp{type = "general"}, and the gAIC, see \insertCite{pinheiro2014;textual}{DoseFinding}. } \examples{ @@ -251,10 +250,7 @@ gAIC(gfit2) } \references{ -Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based dose finding under model -uncertainty using general parametric models, \emph{Statistics in Medicine}, \strong{33}, 1646--1661 - -Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley. +\insertAllCited{} } \seealso{ \code{\link[=defBnds]{defBnds()}}, \code{\link[=drmodels]{drmodels()}} diff --git a/man/glycobrom.Rd b/man/glycobrom.Rd index ed427da..57708ae 100644 --- a/man/glycobrom.Rd +++ b/man/glycobrom.Rd @@ -1,62 +1,62 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DoseFinding-package.R -\docType{data} -\name{glycobrom} -\alias{glycobrom} -\title{Glycopyrronium Bromide dose-response data} -\format{ -A data frame with 5 summary estimates (one per dose). Variables: -A data frame with 5 summary estimates (one per dose). Variables: -\describe{ -\item{\code{dose}}{a numeric vector containing the dose values} -\item{\code{fev1}}{a numeric vector containing the least square -mean per dose} -\item{\code{sdev}}{a numeric vector containing the standard errors -of the least square means per dose} -\item{\code{n}}{Number of participants analyzed per treatment group} -} -} -\source{ -http://clinicaltrials.gov/ct2/show/results/NCT00501852 -} -\usage{ -data(glycobrom) -} -\description{ -Data from a clinical study evaluating Efficacy and Safety of Four Doses of -Glycopyrronium Bromide in Patients With Stable Chronic Obstructive Pulmonary -Disease (COPD). This data set was obtained from clinicaltrials.gov -(NCT00501852). The study design was a 4 period incomplete cross-over -design. The primary endpoint is the trough forced expiratory volume in 1 -second (FEV1) following 7 days of Treatment. -} -\details{ -The data given here are summary estimates (least-square means) for each -dose. -} -\examples{ - - ## simulate a full data set with given means and sdv (here we ignore - ## the original study was a cross-over design, and simulate a parallel - ## group design) - simData <- function(mn, sd, n, doses, fixed = TRUE){ - ## simulate data with means (mns) and standard deviations (sd), for - ## fixed = TRUE, the data set will have observed means and standard - ## deviations as given in mns and sd - resp <- numeric(sum(n)) - uppind <- cumsum(n) - lowind <- c(0,uppind)+1 - for(i in 1:length(n)){ - rv <- rnorm(n[i]) - if(fixed) - rv <- scale(rv) - resp[lowind[i]:uppind[i]] <- mn[i] + sd[i]*rv - } - data.frame(doses=rep(doses, n), resp=resp) - } - data(glycobrom) - fullDat <- simData(glycobrom$fev1, glycobrom$sdev, glycobrom$n, - glycobrom$dose) - -} -\keyword{datasets} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DoseFinding-package.R +\docType{data} +\name{glycobrom} +\alias{glycobrom} +\title{Glycopyrronium Bromide dose-response data} +\format{ +A data frame with 5 summary estimates (one per dose). Variables: +A data frame with 5 summary estimates (one per dose). Variables: +\describe{ +\item{\code{dose}}{a numeric vector containing the dose values} +\item{\code{fev1}}{a numeric vector containing the least square +mean per dose} +\item{\code{sdev}}{a numeric vector containing the standard errors +of the least square means per dose} +\item{\code{n}}{Number of participants analyzed per treatment group} +} +} +\source{ +http://clinicaltrials.gov/ct2/show/results/NCT00501852 +} +\usage{ +data(glycobrom) +} +\description{ +Data from a clinical study evaluating Efficacy and Safety of Four Doses of +Glycopyrronium Bromide in Patients With Stable Chronic Obstructive Pulmonary +Disease (COPD). This data set was obtained from clinicaltrials.gov +(NCT00501852). The study design was a 4 period incomplete cross-over +design. The primary endpoint is the trough forced expiratory volume in 1 +second (FEV1) following 7 days of Treatment. +} +\details{ +The data given here are summary estimates (least-square means) for each +dose. +} +\examples{ + + ## simulate a full data set with given means and sdv (here we ignore + ## the original study was a cross-over design, and simulate a parallel + ## group design) + simData <- function(mn, sd, n, doses, fixed = TRUE){ + ## simulate data with means (mns) and standard deviations (sd), for + ## fixed = TRUE, the data set will have observed means and standard + ## deviations as given in mns and sd + resp <- numeric(sum(n)) + uppind <- cumsum(n) + lowind <- c(0,uppind)+1 + for(i in 1:length(n)){ + rv <- rnorm(n[i]) + if(fixed) + rv <- scale(rv) + resp[lowind[i]:uppind[i]] <- mn[i] + sd[i]*rv + } + data.frame(doses=rep(doses, n), resp=resp) + } + data(glycobrom) + fullDat <- simData(glycobrom$fev1, glycobrom$sdev, glycobrom$n, + glycobrom$dose) + +} +\keyword{datasets} diff --git a/man/guesst.Rd b/man/guesst.Rd index 7067b19..ce07609 100644 --- a/man/guesst.Rd +++ b/man/guesst.Rd @@ -1,137 +1,133 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/guesst.R -\name{guesst} -\alias{guesst} -\title{Calculate guesstimates based on prior knowledge} -\usage{ -guesst( - d, - p, - model = c("emax", "exponential", "logistic", "quadratic", "betaMod", "sigEmax"), - less = TRUE, - local = FALSE, - dMax, - Maxd, - scal -) -} -\arguments{ -\item{d}{Vector containing dose value(s).} - -\item{p}{Vector of expected percentages of the maximum effect achieved at d.} - -\item{model}{Character string. Should be one of "emax", "exponential", "quadratic", "betaMod", "sigEmax", "logistic".} - -\item{less}{Logical, only needed in case of quadratic model. Determines if d is smaller (\samp{less=TRUE}) or larger -(\samp{less=FALSE}) than dopt (see Pinheiro et al. (2006) for details).} - -\item{local}{Logical indicating whether local or asymptotic version of guesstimate should be derived (defaults to -\samp{FALSE}). Only needed for emax, logistic and sigEmax model. When \samp{local=TRUE} the maximum dose must be -provided via \samp{Maxd}.} - -\item{dMax}{Dose at which maximum effect occurs, only needed for the beta model} - -\item{Maxd}{Maximum dose to be administered in the trial} - -\item{scal}{Scale parameter, only needed for the beta model} -} -\value{ -Returns a numeric vector containing the guesstimates. -} -\description{ -Calculates guesstimates for standardized model parameter(s) using the general approach described in Pinheiro et al. -(2006). -} -\details{ -Calculates guesstimates for the parameters \eqn{\theta_2}{theta2} of the standardized model function based on the -prior expected percentage of the maximum effect at certain dose levels. Note that this function should be used -together with the \code{\link[=plot.Mods]{plot.Mods()}} function to ensure that the guesstimates are reflecting the prior beliefs. - -For the logistic and sigmoid emax models at least two pairs (d,p) need to be specified. - -For the beta model the dose at which the maximum effect occurs (dMax) has to be specified in addition to the (d,p) -pair. - -For the exponential model the maximum dose administered (Maxd) needs to be specified in addition to the (d,p) pair. - -For the quadratic model one (d,p) pair is needed. It is advisable to specify the location of the maximum within the -dose range with this pair. - -For the emax, sigmoid Emax and logistic model one can choose between a local and an asymptotic version. In the local -version one explicitly forces the standardized model function to pass through the specified points (d,p). For the -asymptotic version it assumed that the standardized model function is equal to 1 at the largest dose (this is the -approach described in Pinheiro et al. (2006)). If the local version is used, convergence problems with the underlying -nonlinear optimization can occur. -} -\examples{ - -## Emax model -## Expected percentage of maximum effect: 0.8 is associated with -## dose 0.3 (d,p)=(0.3, 0.8), dose range [0,1] -emx1 <- guesst(d=0.3, p=0.8, model="emax") -emax(0.3,0,1,emx1) -## local approach -emx2 <- guesst(d=0.3, p=0.8, model="emax", local = TRUE, Maxd = 1) -emax(0.3,0,1,emx2)/emax(1,0,1,emx2) -## plot models -models <- Mods(emax=c(emx1, emx2), doses=c(0,1)) -plot(models) - -## Logistic model -## Select two (d,p) pairs (0.2, 0.6) and (0.2, 0.95) -lgc1 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "logistic") -logistic(c(0.2,0.6), 0, 1, lgc1[1], lgc1[2]) -## local approach -lgc2 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "logistic", - local = TRUE, Maxd = 1) -r0 <- logistic(0, 0, 1, lgc2[1], lgc2[2]) -r1 <- logistic(1, 0, 1, lgc2[1], lgc2[2]) -(logistic(c(0.2,0.6), 0, 1, lgc2[1], lgc2[2])-r0)/(r1-r0) -## plot models -models <- Mods(logistic = rbind(lgc1, lgc2), doses=c(0,1)) -plot(models) - -## Beta Model -## Select one pair (d,p): (0.4,0.8) -## dose, where maximum occurs: 0.8 -bta <- guesst(d=0.4, p=0.8, model="betaMod", dMax=0.8, scal=1.2, Maxd=1) -## plot -models <- Mods(betaMod = bta, doses=c(0,1), addArgs = list(scal = 1.2)) -plot(models) - -## Sigmoid Emax model -## Select two (d,p) pairs (0.2, 0.6) and (0.2, 0.95) -sgE1 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "sigEmax") -sigEmax(c(0.2,0.6), 0, 1, sgE1[1], sgE1[2]) -## local approach -sgE2 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "sigEmax", - local = TRUE, Maxd = 1) -sigEmax(c(0.2,0.6), 0, 1, sgE2[1], sgE2[2])/sigEmax(1, 0, 1, sgE2[1], sgE2[2]) -models <- Mods(sigEmax = rbind(sgE1, sgE2), doses=c(0,1)) -plot(models) - -## Quadratic model -## For the quadratic model it is assumed that the maximum effect occurs at -## dose 0.7 -quad <- guesst(d = 0.7, p = 1, "quadratic") -models <- Mods(quadratic = quad, doses=c(0,1)) -plot(models) - -## exponential model -## (d,p) = (0.8,0.5) -expo <- guesst(d = 0.8, p = 0.5, "exponential", Maxd=1) -models <- Mods(exponential = expo, doses=c(0,1)) -plot(models) -} -\references{ -Bornkamp B., Pinheiro J. C., and Bretz, F. (2009). MCPMod: An R -Package for the Design and Analysis of Dose-Finding Studies, \emph{Journal -of Statistical Software}, \strong{29}(7), 1--23 - -Pinheiro, J. C., Bretz, F., and Branson, M. (2006). Analysis of dose-response studies - modeling approaches, -\emph{in} N. Ting (ed.), \emph{Dose Finding in Drug Development}, Springer, New York, pp. 146--171 -} -\seealso{ -\code{\link[=emax]{emax()}}, \code{\link[=logistic]{logistic()}}, \code{\link[=betaMod]{betaMod()}}, \code{\link[=sigEmax]{sigEmax()}}, -\code{\link[=quadratic]{quadratic()}}, \code{\link[=exponential]{exponential()}}, \code{\link[=plot.Mods]{plot.Mods()}} -} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/guesst.R +\name{guesst} +\alias{guesst} +\title{Calculate guesstimates based on prior knowledge} +\usage{ +guesst( + d, + p, + model = c("emax", "exponential", "logistic", "quadratic", "betaMod", "sigEmax"), + less = TRUE, + local = FALSE, + dMax, + Maxd, + scal +) +} +\arguments{ +\item{d}{Vector containing dose value(s).} + +\item{p}{Vector of expected percentages of the maximum effect achieved at d.} + +\item{model}{Character string. Should be one of "emax", "exponential", "quadratic", "betaMod", "sigEmax", "logistic".} + +\item{less}{Logical, only needed in case of quadratic model. Determines if d is smaller (\samp{less=TRUE}) or larger +(\samp{less=FALSE}) than dopt \insertCite{@see @pinheiro2006 for details}{DoseFinding}.} + +\item{local}{Logical indicating whether local or asymptotic version of guesstimate should be derived (defaults to +\samp{FALSE}). Only needed for emax, logistic and sigEmax model. When \samp{local=TRUE} the maximum dose must be +provided via \samp{Maxd}.} + +\item{dMax}{Dose at which maximum effect occurs, only needed for the beta model} + +\item{Maxd}{Maximum dose to be administered in the trial} + +\item{scal}{Scale parameter, only needed for the beta model} +} +\value{ +Returns a numeric vector containing the guesstimates. +} +\description{ +Calculates guesstimates for standardized model parameter(s) using the general approach described in \insertCite{pinheiro2006;textual}{DoseFinding}. +} +\details{ +Calculates guesstimates for the parameters \eqn{\theta_2}{theta2} of the standardized model function based on the +prior expected percentage of the maximum effect at certain dose levels. Note that this function should be used +together with the \code{\link[=plot.Mods]{plot.Mods()}} function to ensure that the guesstimates are reflecting the prior beliefs. + +For the logistic and sigmoid emax models at least two pairs (d,p) need to be specified. + +For the beta model the dose at which the maximum effect occurs (dMax) has to be specified in addition to the (d,p) +pair. + +For the exponential model the maximum dose administered (Maxd) needs to be specified in addition to the (d,p) pair. + +For the quadratic model one (d,p) pair is needed. It is advisable to specify the location of the maximum within the +dose range with this pair. + +For the emax, sigmoid Emax and logistic model one can choose between a local and an asymptotic version. In the local +version one explicitly forces the standardized model function to pass through the specified points (d,p). For the +asymptotic version it assumed that the standardized model function is equal to 1 at the largest dose (this is the +approach described in \insertCite{pinheiro2006;textual}{DoseFinding}). If the local version is used, convergence problems with the underlying +nonlinear optimization can occur. +} +\examples{ + +## Emax model +## Expected percentage of maximum effect: 0.8 is associated with +## dose 0.3 (d,p)=(0.3, 0.8), dose range [0,1] +emx1 <- guesst(d=0.3, p=0.8, model="emax") +emax(0.3,0,1,emx1) +## local approach +emx2 <- guesst(d=0.3, p=0.8, model="emax", local = TRUE, Maxd = 1) +emax(0.3,0,1,emx2)/emax(1,0,1,emx2) +## plot models +models <- Mods(emax=c(emx1, emx2), doses=c(0,1)) +plot(models) + +## Logistic model +## Select two (d,p) pairs (0.2, 0.6) and (0.2, 0.95) +lgc1 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "logistic") +logistic(c(0.2,0.6), 0, 1, lgc1[1], lgc1[2]) +## local approach +lgc2 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "logistic", + local = TRUE, Maxd = 1) +r0 <- logistic(0, 0, 1, lgc2[1], lgc2[2]) +r1 <- logistic(1, 0, 1, lgc2[1], lgc2[2]) +(logistic(c(0.2,0.6), 0, 1, lgc2[1], lgc2[2])-r0)/(r1-r0) +## plot models +models <- Mods(logistic = rbind(lgc1, lgc2), doses=c(0,1)) +plot(models) + +## Beta Model +## Select one pair (d,p): (0.4,0.8) +## dose, where maximum occurs: 0.8 +bta <- guesst(d=0.4, p=0.8, model="betaMod", dMax=0.8, scal=1.2, Maxd=1) +## plot +models <- Mods(betaMod = bta, doses=c(0,1), addArgs = list(scal = 1.2)) +plot(models) + +## Sigmoid Emax model +## Select two (d,p) pairs (0.2, 0.6) and (0.2, 0.95) +sgE1 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "sigEmax") +sigEmax(c(0.2,0.6), 0, 1, sgE1[1], sgE1[2]) +## local approach +sgE2 <- guesst(d = c(0.2, 0.6), p = c(0.2, 0.95), "sigEmax", + local = TRUE, Maxd = 1) +sigEmax(c(0.2,0.6), 0, 1, sgE2[1], sgE2[2])/sigEmax(1, 0, 1, sgE2[1], sgE2[2]) +models <- Mods(sigEmax = rbind(sgE1, sgE2), doses=c(0,1)) +plot(models) + +## Quadratic model +## For the quadratic model it is assumed that the maximum effect occurs at +## dose 0.7 +quad <- guesst(d = 0.7, p = 1, "quadratic") +models <- Mods(quadratic = quad, doses=c(0,1)) +plot(models) + +## exponential model +## (d,p) = (0.8,0.5) +expo <- guesst(d = 0.8, p = 0.5, "exponential", Maxd=1) +models <- Mods(exponential = expo, doses=c(0,1)) +plot(models) +} +\references{ +\insertRef{bornkamp2009}{DoseFinding} + +\insertRef{pinheiro2006}{DoseFinding} +} +\seealso{ +\code{\link[=emax]{emax()}}, \code{\link[=logistic]{logistic()}}, \code{\link[=betaMod]{betaMod()}}, \code{\link[=sigEmax]{sigEmax()}}, +\code{\link[=quadratic]{quadratic()}}, \code{\link[=exponential]{exponential()}}, \code{\link[=plot.Mods]{plot.Mods()}} +} diff --git a/man/maFitMod.Rd b/man/maFitMod.Rd index 212e7e8..d0f739c 100644 --- a/man/maFitMod.Rd +++ b/man/maFitMod.Rd @@ -96,8 +96,8 @@ was selected in each bootstrap and basic input parameters. } \description{ This function fits dose-response models in a bootstrap model -averaging approach motivated by the bagging procedure (Breiman -1996). Given summary estimates for the outcome at each dose, the +averaging approach motivated by the bagging procedure \insertCite{breiman1996}{DoseFinding}. +Given summary estimates for the outcome at each dose, the function samples summary data from the multivariate normal distribution. For each sample dose-response models are fit to these summary estimates and the best model @@ -117,7 +117,7 @@ plot(mFit, plotData = "meansCI") ED(mFit, direction = "increasing", p = 0.9) } \references{ -Breiman, L. (1996). Bagging predictors. Machine learning, 24, 123-140. +\insertAllCited{} } \seealso{ \code{\link[=fitMod]{fitMod()}}, \code{\link[=bFitMod]{bFitMod()}}, \code{\link[=drmodels]{drmodels()}} diff --git a/man/migraine.Rd b/man/migraine.Rd index f5c8fb5..ce3983e 100644 --- a/man/migraine.Rd +++ b/man/migraine.Rd @@ -1,28 +1,28 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DoseFinding-package.R -\docType{data} -\name{migraine} -\alias{migraine} -\title{Migraine Dose Response data} -\format{ -A data frame with 517 columns corresponding to the patients that -completed the trial -\describe{ -\item{\code{dose}}{a numeric vector containing the dose values} -\item{\code{painfree}}{number of treatment responders} -\item{\code{ntrt}}{number of subject per treatment group} -} -} -\source{ -http://clinicaltrials.gov/ct2/show/results/NCT00712725 -} -\usage{ -data(migraine) -} -\description{ -Data set obtained from clinicaltrials.gov (NCT00712725). This was -randomized placebo controlled dose-response trial for treatment of acute -migraine. The primary endpoint was "pain freedom at 2 hours postdose" (a -binary measurement). -} -\keyword{datasets} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DoseFinding-package.R +\docType{data} +\name{migraine} +\alias{migraine} +\title{Migraine Dose Response data} +\format{ +A data frame with 517 columns corresponding to the patients that +completed the trial +\describe{ +\item{\code{dose}}{a numeric vector containing the dose values} +\item{\code{painfree}}{number of treatment responders} +\item{\code{ntrt}}{number of subject per treatment group} +} +} +\source{ +http://clinicaltrials.gov/ct2/show/results/NCT00712725 +} +\usage{ +data(migraine) +} +\description{ +Data set obtained from clinicaltrials.gov (NCT00712725). This was +randomized placebo controlled dose-response trial for treatment of acute +migraine. The primary endpoint was "pain freedom at 2 hours postdose" (a +binary measurement). +} +\keyword{datasets} diff --git a/man/mvpostmix.Rd b/man/mvpostmix.Rd index 21e7f01..e6829a0 100644 --- a/man/mvpostmix.Rd +++ b/man/mvpostmix.Rd @@ -1,32 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bMCTtest.R \name{mvpostmix} \alias{mvpostmix} \title{Prior to posterior updating for a multivariate normal mixture} -\description{ - Calculate conjugate posterior mixture of multivariate normals with known covariance matrix -} \usage{ mvpostmix(priormix, mu_hat, S_hat) } \arguments{ - \item{priormix}{ - Prior multivariate normal mixture given as a list of length 3. The - first list entry contains the mixture weights, the second component - the mean vectors and the third component of the list the covariance matrices. - } - \item{mu_hat}{ - estimated mean response for each dose - } - \item{S_hat}{ - estimated covariance matrix - } +\item{priormix}{Prior multivariate normal mixture given as a list of length 3. The first list entry contains the +mixture weights, the second component the mean vectors and the third component of the list the covariance matrices.} + +\item{mu_hat}{estimated mean response for each dose} + +\item{S_hat}{estimated covariance matrix} } \value{ - Returns a posterior multivariate normal mixture as a list of length 3, - containing mixture weights, mean vectors and covariance matrices. +Returns a posterior multivariate normal mixture as a list of length 3, containing mixture weights, mean +vectors and covariance matrices. +} +\description{ +Calculate conjugate posterior mixture of multivariate normals with known covariance matrix } \references{ - Bernardo, J. M., and Smith, A. F. (1994). Bayesian theory. John Wiley & Sons. +\insertRef{bernardo1994}{DoseFinding} } \author{ - Marius Thomas +Marius Thomas } diff --git a/man/neurodeg.Rd b/man/neurodeg.Rd index c5a6962..ca84139 100644 --- a/man/neurodeg.Rd +++ b/man/neurodeg.Rd @@ -1,79 +1,77 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/DoseFinding-package.R -\docType{data} -\name{neurodeg} -\alias{neurodeg} -\title{Neurodegenerative disease simulated longitudinal dose-finding data set} -\format{ -A data frame with 100 observations on the following 2 variables. -\describe{ -\item{\code{resp}}{a numeric vector containing the response values} -\item{\code{dose}}{a numeric vector containing the dose values} -\item{\code{id}}{Patient ID} -\item{\code{time}}{time of measurement} -} -} -\source{ -Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) -Model-based dose finding under model uncertainty using general parametric -models, \emph{Statistics in Medicine}, \strong{33}, 1646--1661 -} -\usage{ -data(neurodeg) -} -\description{ -This simulated data set is motivated by a real Phase 2 clinical study of a -new drug for a neurodegenerative disease. The state of the disease is -measured through a functional scale, with smaller values corresponding to -more severe neurodeterioration. The goal of the drug is to reduce the rate -of disease progression, which is measured by the linear slope of the -functional scale over time. -} -\details{ -The trial design includes placebo and four doses: 1, 3, 10, and 30 mg, with -balanced allocation of 50 patients per arm. Patients are followed up for one -year, with measurements of the functional scale being taken at baseline and -then every three months. - -The functional scale response is assumed to be normally distributed and, -based on historical data, it is believed that the longitudinal progression -of the functional scale over the one year of follow up can be modeled a -simple linear trend. See the example below on how to analyse this type of -data. - -This data set was used in Pinheiro et al. (2014) to illustrate the -generalized MCPMod methodology. -} -\examples{ - -\dontrun{ -## reproduce analysis from Pinheiro et al. (2014) -data(neurodeg) -## first fit the linear mixed effect model -library(nlme) -fm <- lme(resp ~ as.factor(dose):time, neurodeg, ~time|id, method = "ML") -muH <- fixef(fm)[-1] # extract estimates -covH <- vcov(fm)[-1,-1] - -## derive optimal contrasts for candidate shapes -doses <- c(0, 1, 3, 10, 30) -mod <- Mods(emax = 1.11, quadratic= -0.022, exponential = 8.867, - linear = NULL, doses = doses) # -contMat <- optContr(mod, S=covH) # calculate optimal contrasts -## multiple contrast test -MCTtest(doses, muH, S=covH, type = "general", critV = TRUE, - contMat=contMat) -## fit the emax model -fitMod(doses, muH, S=covH, model="emax", type = "general", - bnds=c(0.1, 10)) - - -## alternatively one can also fit the model using nlme -nlme(resp ~ b0 + (e0 + eM * dose/(ed50 + dose))*time, neurodeg, - fixed = b0 + e0 + eM + ed50 ~ 1, random = b0 + e0 ~ 1 | id, - start = c(200, -4.6, 1.6, 3.2)) -## both approaches lead to rather similar results -} - -} -\keyword{datasets} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/DoseFinding-package.R +\docType{data} +\name{neurodeg} +\alias{neurodeg} +\title{Neurodegenerative disease simulated longitudinal dose-finding data set} +\format{ +A data frame with 100 observations on the following 2 variables. +\describe{ +\item{\code{resp}}{a numeric vector containing the response values} +\item{\code{dose}}{a numeric vector containing the dose values} +\item{\code{id}}{Patient ID} +\item{\code{time}}{time of measurement} +} +} +\source{ +\insertRef{pinheiro2014}{DoseFinding} +} +\usage{ +data(neurodeg) +} +\description{ +This simulated data set is motivated by a real Phase 2 clinical study of a +new drug for a neurodegenerative disease. The state of the disease is +measured through a functional scale, with smaller values corresponding to +more severe neurodeterioration. The goal of the drug is to reduce the rate +of disease progression, which is measured by the linear slope of the +functional scale over time. +} +\details{ +The trial design includes placebo and four doses: 1, 3, 10, and 30 mg, with +balanced allocation of 50 patients per arm. Patients are followed up for one +year, with measurements of the functional scale being taken at baseline and +then every three months. + +The functional scale response is assumed to be normally distributed and, +based on historical data, it is believed that the longitudinal progression +of the functional scale over the one year of follow up can be modeled a +simple linear trend. See the example below on how to analyse this type of +data. + +This data set was used in Pinheiro et al. (2014) to illustrate the +generalized MCPMod methodology. +} +\examples{ + +\dontrun{ +## reproduce analysis from Pinheiro et al. (2014) +data(neurodeg) +## first fit the linear mixed effect model +library(nlme) +fm <- lme(resp ~ as.factor(dose):time, neurodeg, ~time|id, method = "ML") +muH <- fixef(fm)[-1] # extract estimates +covH <- vcov(fm)[-1,-1] + +## derive optimal contrasts for candidate shapes +doses <- c(0, 1, 3, 10, 30) +mod <- Mods(emax = 1.11, quadratic= -0.022, exponential = 8.867, + linear = NULL, doses = doses) # +contMat <- optContr(mod, S=covH) # calculate optimal contrasts +## multiple contrast test +MCTtest(doses, muH, S=covH, type = "general", critV = TRUE, + contMat=contMat) +## fit the emax model +fitMod(doses, muH, S=covH, model="emax", type = "general", + bnds=c(0.1, 10)) + + +## alternatively one can also fit the model using nlme +nlme(resp ~ b0 + (e0 + eM * dose/(ed50 + dose))*time, neurodeg, + fixed = b0 + e0 + eM + ed50 ~ 1, random = b0 + e0 ~ 1 | id, + start = c(200, -4.6, 1.6, 3.2)) +## both approaches lead to rather similar results +} + +} +\keyword{datasets} diff --git a/man/optContr.Rd b/man/optContr.Rd index fe8792e..36e02ff 100644 --- a/man/optContr.Rd +++ b/man/optContr.Rd @@ -79,7 +79,7 @@ mean vector under the alternative and \eqn{S}{S} the covariance matrix associated with the estimate of \eqn{\mu}{mu}. The optimal contrast is given by \deqn{c^{opt} \propto S^{-1}\left(\mu - \frac{\mu^{\prime}S^{-1}1} {1^\prime S^{-1} 1}\right),}{c propto S^(-1) (mu - mu'S^(-1)1)/(1'S^(-1)1),} -see Pinheiro et al. (2014). +see \insertCite{pinheiro2014;textual}{DoseFinding}. } \details{ Note that the directionality (i.e. whether in "increase" in the response @@ -123,13 +123,9 @@ optContr(models, doses=dosPlac, S = S, placAdj = TRUE, } } \references{ -Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining -multiple comparisons and modeling techniques in dose-response studies, -\emph{Biometrics}, \strong{61}, 738--748 +\insertRef{bretz2005}{DoseFinding} -Pinheiro, J. C., Bornkamp, B., Glimm, E. and Bretz, F. (2014) Model-based -dose finding under model uncertainty using general parametric models, -\emph{Statistics in Medicine}, \strong{33}, 1646--1661 +\insertRef{pinheiro2014}{DoseFinding} } \seealso{ \code{\link[=MCTtest]{MCTtest()}} diff --git a/man/optDesign.Rd b/man/optDesign.Rd index 59a5946..4e0aa9f 100644 --- a/man/optDesign.Rd +++ b/man/optDesign.Rd @@ -83,7 +83,7 @@ required.} \item{optimizer}{Algorithm used for calculating the optimal design. Options "Nelder-Mead" and "nlminb" use the \code{\link[=optim]{optim()}} and \code{\link[=nlminb]{nlminb()}} function and use a trigonometric transformation to turn the -constrained optimization problem into an unconstrained one (see Atkinson, Donev and Tobias, 2007, pages 130,131). +constrained optimization problem into an unconstrained one \insertCite{@see @atkinson2007 pages 130,131}{DoseFinding}. Option "solnp" uses the solnp function from the Rsolnp package, which implements an optimizer for non-linear optimization under general constraints. @@ -124,7 +124,7 @@ there are parameters in the dose-response models selected in \code{models} (othe \description{ Given a set of models (with full parameter values and model probabilities) the \samp{optDesign} function calculates the optimal design for estimating the dose-response model parameters (D-optimal) or the design for estimating the -target dose (TD-optimal design) (see Dette, Bretz, Pepelyshev and Pinheiro (2008)), or a mixture of these two +target dose (TD-optimal design) \insertCite{@see @dette2008}{DoseFinding}, or a mixture of these two criteria. The design can be plotted (together with the candidate models) using \samp{plot.design}. \samp{calcCrit} calculates the design criterion for a discrete set of design(s). \samp{rndDesign} provides efficient rounding for the calculated continous design to a finite sample size. @@ -147,7 +147,7 @@ For \samp{designCrit = "TD"} the code minimizes the design criterion \deqn{\sum_{m}p_m \log(v_m)}{sum_m p_m log(v_m)} where \eqn{p_m}{p_m} is the probability for model m and \eqn{v_m}{v_m} is proportional to the asymptotic variance of the TD estimate and given by \eqn{b_m'M_m^{-}b_m}{b_m'Minv_m -b_m} (see Dette et al. (2008), p. 1227 for details). +b_m} \insertCite{@see @dette2008, p. 1227 for details}{DoseFinding}. For \samp{designCrit = "Dopt&TD"} the code minimizes the design criterion \deqn{\sum_{m}p_m(-0.5\log(\det(M_m))/k_m+0.5\log(v_m))}{sum_m @@ -155,7 +155,7 @@ p_m(-0.5log(det(M_m))/k_m+0.5log(v_m))} Again, for \samp{standDopt = FALSE} the \eqn{k_m}{k_m} are all assumed to be equal to one. -For details on the \samp{rndDesign} function, see Pukelsheim (1993), Chapter 12. +For details on the \samp{rndDesign} function, see \insertCite{pukelsheim1993;textual}{DoseFinding}, Chapter 12. } \note{ In some cases (particularly when the number of doses is large, e.g. 7 or larger) it might be necessary to allow @@ -250,18 +250,13 @@ optDesign(doses = c(0,0.05,0.2,0.6,1), optimizer = "nlminb") } \references{ -Atkinson, A.C., Donev, A.N. and Tobias, R.D. (2007). Optimum Experimental Designs, with SAS, Oxford -University Press +\insertRef{atkinson2007}{DoseFinding} -Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal -Designs for Dose Finding Studies, \emph{Journal of the American Statisical -Association}, \strong{103}, 1225--1237 +\insertRef{dette2008}{DoseFinding} -Pinheiro, J.C., Bornkamp, B. (2017) Designing Phase II Dose-Finding Studies: Sample Size, Doses and Dose Allocation -Weights, in O'Quigley, J., Iasonos, A. and Bornkamp, B. (eds) Handbook of methods for designing, monitoring, and -analyzing dose-finding trials, CRC press +\insertRef{pinheiro2017}{DoseFinding} -Pukelsheim, F. (1993). Optimal Design of Experiments, Wiley +\insertRef{pukelsheim1993}{DoseFinding} } \seealso{ \code{\link[=Mods]{Mods()}}, \code{\link[=drmodels]{drmodels()}} diff --git a/man/planMod.Rd b/man/planMod.Rd index e7d60b3..e8d3902 100644 --- a/man/planMod.Rd +++ b/man/planMod.Rd @@ -172,7 +172,7 @@ plot(pObj, type = "ED", p = 0.5) } } \references{ -TBD +\insertRef{pinheiro2017}{DoseFinding} } \seealso{ \code{\link[=fitMod]{fitMod()}} diff --git a/man/powMCT.Rd b/man/powMCT.Rd index 174322c..e6aa0f3 100644 --- a/man/powMCT.Rd +++ b/man/powMCT.Rd @@ -114,10 +114,7 @@ powMCT(linMat, altModels = fmodels, placAdj=TRUE, } } \references{ -Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and -analysis of dose finding studies combining multiple comparisons and modeling -procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, -639--656 +\insertRef{pinheiro2006b}{DoseFinding} } \seealso{ \code{\link[=powN]{powN()}}, \code{\link[=sampSizeMCT]{sampSizeMCT()}}, diff --git a/man/powMCTInterim.Rd b/man/powMCTInterim.Rd index b3c05a8..9eb2297 100644 --- a/man/powMCTInterim.Rd +++ b/man/powMCTInterim.Rd @@ -93,8 +93,7 @@ powMCTInterim( ) } \references{ -Bornkamp, B., Zhou, J., Xi, D. and Cao W. (2025). Futility analyses for the MCP-Mod methodology based -on longitudinal models, \emph{arXiv:2406.19965} +\insertRef{bornkamp2024}{DoseFinding} } \seealso{ \code{\link[=powMCT]{powMCT()}} \code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}} diff --git a/man/sampSize.Rd b/man/sampSize.Rd index 3fb8df9..6b04bbc 100644 --- a/man/sampSize.Rd +++ b/man/sampSize.Rd @@ -163,13 +163,9 @@ powN(upperN = 100, lowerN=10, step = 10, contMat = contMat, } } \references{ -Pinheiro, J. C., Bornkamp, B., and Bretz, F. (2006). Design and analysis of dose finding studies -combining multiple comparisons and modeling procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, -639--656 +\insertRef{pinheiro2006b}{DoseFinding} -Pinheiro, J.C., Bornkamp, B. (2017) Designing Phase II Dose-Finding Studies: Sample Size, Doses and Dose Allocation -Weights, in O'Quigley, J., Iasonos, A. and Bornkamp, B. (eds) Handbook of methods for designing, monitoring, and -analyzing dose-finding trials, CRC press +\insertRef{pinheiro2017}{DoseFinding} } \seealso{ \code{\link[=powMCT]{powMCT()}} diff --git a/vignettes/analysis_normal.Rmd b/vignettes/analysis_normal.Rmd index 15e3dcf..989c563 100644 --- a/vignettes/analysis_normal.Rmd +++ b/vignettes/analysis_normal.Rmd @@ -1,7 +1,7 @@ --- title: "Continuous data MCP-Mod" output: rmarkdown::html_vignette -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' csl: american-statistical-association.csl link-citations: yes vignette: > diff --git a/vignettes/binary_data.Rmd b/vignettes/binary_data.Rmd index 8c313da..98a15c4 100644 --- a/vignettes/binary_data.Rmd +++ b/vignettes/binary_data.Rmd @@ -1,7 +1,7 @@ --- title: "Binary Data MCP-Mod" output: rmarkdown::html_vignette -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' link-citations: yes csl: american-statistical-association.csl vignette: > diff --git a/vignettes/faq.Rmd b/vignettes/faq.Rmd index a6b28e8..fdca21c 100644 --- a/vignettes/faq.Rmd +++ b/vignettes/faq.Rmd @@ -4,7 +4,7 @@ output: rmarkdown::html_vignette: toc: true toc_depth: 2 -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' link-citations: yes csl: american-statistical-association.csl vignette: > @@ -209,7 +209,7 @@ _Consequence of model misspecification:_ Omission of the “correct” dose-response shape from the set of candidate models might not necessarily have severe consequences, if other models can pick up the omitted shape. This can be evaluated for the MCP part (impact on -power) using explicit calculations (see @pinheiro2006 and [the +power) using explicit calculations (see @pinheiro2006b and [the vignette on sample size](sample_size.html)). For the Mod part (impact on estimation precision for dose-response and dose estimation) using simulations see `?planMod`. diff --git a/vignettes/longitudinal_data.Rmd b/vignettes/longitudinal_data.Rmd index 2a8c3bc..2a116fd 100644 --- a/vignettes/longitudinal_data.Rmd +++ b/vignettes/longitudinal_data.Rmd @@ -1,7 +1,7 @@ --- title: "Longitudinal Data MCP-Mod" output: rmarkdown::html_vignette -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' link-citations: yes csl: american-statistical-association.csl vignette: > diff --git a/vignettes/mult_regimen.Rmd b/vignettes/mult_regimen.Rmd index 04258c6..17ef06a 100644 --- a/vignettes/mult_regimen.Rmd +++ b/vignettes/mult_regimen.Rmd @@ -1,7 +1,7 @@ --- title: "Multiple Regimen MCP-Mod" output: rmarkdown::html_vignette -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' link-citations: yes csl: american-statistical-association.csl vignette: > diff --git a/vignettes/overview.Rmd b/vignettes/overview.Rmd index b337977..0a8a44c 100644 --- a/vignettes/overview.Rmd +++ b/vignettes/overview.Rmd @@ -2,7 +2,7 @@ title: "Overview DoseFinding package" output: rmarkdown::html_vignette: -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' link-citations: yes csl: american-statistical-association.csl vignette: > diff --git a/vignettes/refs.bib b/vignettes/refs.bib deleted file mode 100644 index 73bacd6..0000000 --- a/vignettes/refs.bib +++ /dev/null @@ -1,136 +0,0 @@ -@article{bretz2005, - title={Combining multiple comparisons and modeling techniques in dose-response studies}, - author={Bretz, Frank and Pinheiro, Jos{\'e} C and Branson, Michael}, - journal={Biometrics}, - volume={61}, - number={3}, - pages={738--748}, - year={2005}, - doi = {10.1111/j.1541-0420.2005.00344.x}, - publisher={Wiley Online Library} -} - -@Article{bays2020, - author = {Bays, Harold E and Kozlovski, Plamen and Shao, Qing and Proot, Pieter and Keefe, Deborah}, - title = {Licogliflozin, a Novel SGLT1 and 2 Inhibitor: Body Weight Effects in a Randomized Trial in Adults with Overweight or Obesity}, - journaltitle = {Obesity}, - year = 2020, - volume = 28, - issue = 5, - doi = {10.1002/oby.22764}, - pages = {870-881}} - -@Article{bornkamp2007, - author = {Bornkamp, Björn and Bretz, Frank and Dmitrienko, Alex and Enas, Greg and Gaydos, Brenda and Hsu, Chyi-Hung and König, Franz and Krams, Michael and Liu, Qing and Neuenschwander, Beat and Parke, Tom and Pinheiro, José and Roy, Amit and Sax, Rick and Shen, Frank}, - title = {Innovative approaches for designing and analyzing adaptive dose-ranging trials}, - journaltitle = {Journal of Biopharmaceutical Statistics}, - year = 2007, - volume = 17, - issue = 6, - doi = {10.1080/10543400701643848}, - pages = {965-995}} - -@Article{breiman1996, - author = {Breiman, Leo}, - title = {Baggin predictors}, - journaltitle = {Machine Learning}, - year = 1996, - volume = 24, - issue = 2, - pages = {123-140}, - doi = {10.1007/bf00058655}} - -@Article{bretz2010, - author = {Bretz, Frank and Dette, Holger and Pinheiro, José}, - title = {Practical considerations for optimal designs in clinical dose finding studies}, - journaltitle = {Statistics in Medicine}, - year = 2010, - volume = 29, - issue = {7-8}, - pages = {731-742}, - doi = {10.1002/sim.3802}} - -@Article{heinze2002, - author = {Heinze, Georg and Schemper, Michael}, - title = {A solution to the problem of separation in logistic regression}, - journaltitle = {Statistics in Medicine}, - year = 2002, - volume = 21, - issue = 16, - pages = {2409-2419}, - doi = {10.1002/sim.1047}} - -@Book{oquigley2017, - title={Handbook of methods for designing, monitoring, and analyzing dose-finding trials}, - author={O'Quigley, John and Iasonos, Alexia and Bornkamp, Björn}, - year=2017, - publisher={CRC Press}, - doi = {10.1201/9781315151984}} - -@Article{pinheiro2006, - author = {Pinheiro, José and Bornkamp, Björn and Bretz, Frank}, - title = {Design and Analysis of Dose Finding Studies Combining Multiple Comparisons and Modeling Procedures}, - year = 2006, - volume = 16, - pages = {639-656}, - journaltitle = {Journal of Biopharmaceutical Statistics}, - doi = {10.1080/10543400600860428}} - -@Article{pinheiro2014, - author = {Pinheiro, José and Bornkamp, Björn and Glimm, Ekkehard and Bretz, Frank}, - title = {Model-based dose finding under model uncertainty using general parametric models}, - year = 2014, - volume = 33, - pages = {1646-1661}, - journaltitle = {Statistics in Medicine}, - doi = {10.1002/sim.6052}} - -@Article{schorning2016, - author = {Schorning, Kirsten and Bornkamp, Björn and Bretz, Frank and Holger Dette}, - title = {Model selection versus model averaging in dose finding studies}, - journaltitle = {Statistics in Medicine}, - year = 2016, - volume = 35, - issue = 22, - pages = {4021-4040}, - doi = {10.1002/sim.6991}} - -@Article{thomas2014, - author = {Thomas, Neal and Sweeney, Kevin and Somayaji, Veena}, - title = {Meta-analysis of clinical dose response in a large drug development portfolio}, - journaltitle = {Statistics in Biopharmaceutical Research}, - year = 2015, - volume = 6, - issue = 4, - pages = {302-217}, - doi = {10.1080/19466315.2014.924876}} - -@Article{thomas2017, - author = {Thomas, Neal and Roy, Dooti}, - title = {Analysis of Clinical Dose–Response in Small-Molecule Drug Development: 2009–2014}, - journaltitle = {Statistics in Biopharmaceutical Research}, - year = 2017, - volume = 9, - issue = 2, - pages = {137-146}, - doi = {10.1080/19466315.2016.1256229}} - -@Article{verkindre2010, - author = { Verkindre, C. and Fukuchi, Y. and Flémale, A. and Takeda, A. and Overend, T. and Prasad, N. and Dolker, M.}, - title = {Sustained 24-h efficacy of NVA237, a once-daily long-acting muscarinic antagonist, in COPD patients}, - journaltitle = {Respiratory Medicine}, - year = 2010, - volume = 104, - issue = 10, - pages = {1482-1489}, - doi = {10.1016/j.rmed.2010.04.006}} - -@misc{bornkamp2024, - title={Futility analyses for the MCP-Mod methodology based on longitudinal models}, - author={Björn Bornkamp and Jie Zhou and Dong Xi and Weihua Cao}, - year={2024}, - eprint={2406.19965}, - archivePrefix={arXiv}, - primaryClass={stat.ME}, - url={https://arxiv.org/abs/2406.19965} -} \ No newline at end of file diff --git a/vignettes/sample_size.Rmd b/vignettes/sample_size.Rmd index 45ed145..42ec92c 100644 --- a/vignettes/sample_size.Rmd +++ b/vignettes/sample_size.Rmd @@ -1,7 +1,7 @@ --- title: "Sample size calculations for MCP-Mod" output: rmarkdown::html_vignette -bibliography: refs.bib +bibliography: '`r system.file("REFERENCES.bib", package = "DoseFinding")`' vignette: > %\VignetteIndexEntry{Sample size template for MCP-Mod for normally distributed data} %\VignetteEngine{knitr::rmarkdown} @@ -167,7 +167,7 @@ improvement over placebo) is usually several-fold higher than the sample size needed to have adequate power for the MCP-part. This should not come as a surprise as dose-estimation is primarily a comparison among the investigational doses, while the MCP-part -establishes an effect versus placebo. Chapter 12 in @oquigley2017 +establishes an effect versus placebo. Chapter 12 in @oquigley2017b illustrates this with simulations, based on the `planMod` function (see `?planMod` for example usage).