diff --git a/DESCRIPTION b/DESCRIPTION index db87ccb..a3b24bc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -38,3 +38,4 @@ RoxygenNote: 7.3.2 Encoding: UTF-8 URL: https://github.com/openpharma/DoseFinding, https://openpharma.github.io/DoseFinding/ BugReports: https://github.com/openpharma/DoseFinding/issues +Roxygen: list(markdown = TRUE) diff --git a/R/DoseFinding-package.R b/R/DoseFinding-package.R index d04cfda..603ac19 100644 --- a/R/DoseFinding-package.R +++ b/R/DoseFinding-package.R @@ -6,28 +6,28 @@ #' #' @details #' The main functions are:\cr -#' \bold{MCTtest}: Implements a multiple contrast tests\cr -#' \bold{powMCT}: Power calculations for multiple contrast tests\cr -#' \bold{fitMod}: Fits non-linear dose-response models\cr -#' \bold{optDesign}: Calculates optimal designs for dose-response models\cr -#' \bold{MCPMod}: Performs MCPMod methodology\cr -#' \bold{sampSize}: General function for sample size calculation\cr +#' **MCTtest**: Implements a multiple contrast tests\cr +#' **powMCT**: Power calculations for multiple contrast tests\cr +#' **fitMod**: Fits non-linear dose-response models\cr +#' **optDesign**: Calculates optimal designs for dose-response models\cr +#' **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, \emph{Annals of -#' Applied Statistics}, \bold{5}, 1611--1631 +#' Response-Adaptive Dose-Finding under model uncertainty, *Annals of +#' Applied Statistics*, **5**, 1611--1631 #' #' 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}, \bold{29}(7), 1--23 +#' the Design and Analysis of Dose-Finding Studies, *Journal of +#' Statistical Software*, **29**(7), 1--23 #' #' Bretz, F., Pinheiro, J. C., and Branson, M. (2005), Combining multiple #' comparisons and modeling techniques in dose-response studies, -#' \emph{Biometrics}, \bold{61}, 738--748 +#' *Biometrics*, **61**, 738--748 #' #' Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal -#' Designs for Dose Finding Studies, \emph{Journal of the American Statisical -#' Association}, \bold{103}, 1225--1237 +#' Designs for Dose Finding Studies, *Journal of the American Statisical +#' Association*, **103**, 1225--1237 #' #' O'Quigley, J., Iasonos, A. and Bornkamp, B. (2017) Handbook of methods for #' designing, monitoring, and analyzing dose-finding trials, CRC press, Part 3: @@ -35,11 +35,11 @@ #' #' 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 +#' *Journal of Biopharmaceutical Statistics*, **16**, 639--656 #' #' 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 +#' *Statistics in Medicine*, **33**, 1646--1661 #' #' Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley #' @keywords internal @@ -82,19 +82,19 @@ #' #' Below are the definitions of the model functions: #' -#' \bold{Emax model} \deqn{}{f(d,theta)=E0+Emax d/(ED50 + d).}\deqn{ +#' **Emax model** \deqn{}{f(d,theta)=E0+Emax d/(ED50 + d).}\deqn{ #' f(d,\theta)=E_0+E_{max}\frac{d}{ED_{50}+d}}{f(d,theta)=E0+Emax d/(ED50 + #' d).} #' -#' \bold{Sigmoid Emax Model} \deqn{}{f(d,theta)=E0+Emax d^h/(ED50^h + +#' **Sigmoid Emax Model** \deqn{}{f(d,theta)=E0+Emax d^h/(ED50^h + #' d^h).}\deqn{ #' f(d,\theta)=E_0+E_{max}\frac{d^h}{ED^h_{50}+d^h}}{f(d,theta)=E0+Emax #' d^h/(ED50^h + d^h).} #' -#' \bold{Exponential Model} \deqn{}{f(d,theta)=E0+E1 (exp(d/delta)-1).}\deqn{ +#' **Exponential Model** \deqn{}{f(d,theta)=E0+E1 (exp(d/delta)-1).}\deqn{ #' f(d,\theta)=E_0+E_1(\exp(d/\delta)-1)}{f(d,theta)=E0+E1 (exp(d/delta)-1).} #' -#' \bold{Beta model} \deqn{}{f(d,theta)=E0+Emax +#' **Beta model** \deqn{}{f(d,theta)=E0+Emax #' B(delta1,delta2)(d/scal)^delta1(1-d/scal)^delta2}\deqn{ #' f(d,\theta)=E_0+E_{max}B(\delta_1,\delta_2)(d/scal)^{\delta_1}(1-d/scal)^{\delta_2} #' }{f(d,theta)=E0+Emax B(delta1,delta2)(d/scal)^delta1(1-d/scal)^delta2} @@ -105,71 +105,71 @@ #' \delta_2^{\delta_2})}{B(delta1,delta2)=(delta1+delta2)^(delta1+delta2)/(delta1^delta1 #' delta2^delta2).} and \eqn{scal}{scal} is a fixed dose scaling parameter. #' -#' \bold{Linear Model} \deqn{}{f(d,theta)=E0+delta d.}\deqn{ +#' **Linear Model** \deqn{}{f(d,theta)=E0+delta d.}\deqn{ #' f(d,\theta)=E_0+\delta d}{f(d,theta)=E0+delta d.} #' -#' \bold{Linear in log Model} \deqn{}{f(d,theta)=E0+delta log(d + off),}\deqn{ +#' **Linear in log Model** \deqn{}{f(d,theta)=E0+delta log(d + off),}\deqn{ #' f(d,\theta)=E_0+\delta \log(d + off)}{f(d,theta)=E0+delta log(d + off),} #' here \eqn{off}{off} is a fixed offset parameter. #' -#' \bold{Logistic Model} \deqn{ +#' **Logistic Model** \deqn{ #' f(d, \theta) = E_0 + E_{\max}/\left\{1 + \exp\left[ \left(ED_{50} - d #' \right)/\delta \right] \right\}}{f(d,theta)=E0+Emax/(1 + exp((ED50-d)/delta)).} #' -#' \bold{Quadratic Model} \deqn{}{f(d,theta)=E0+beta1 d+beta2 d^2.}\deqn{ +#' **Quadratic Model** \deqn{}{f(d,theta)=E0+beta1 d+beta2 d^2.}\deqn{ #' f(d,\theta)=E_0+\beta_1d+\beta_2d^2}{f(d,theta)=E0+beta1 d+beta2 d^2.} The #' standardized model equation for the quadratic model is \eqn{d+\delta #' d^2}{d+delta d^2}, with \eqn{\delta=\beta_2/\beta_1}{delta=beta2/beta1}. #' -#' \bold{Linear Interpolation model}\cr The linInt model provides linear +#' **Linear Interpolation model**\cr The linInt model provides linear #' interpolation at the values defined by the nodes vector. In virtually all #' situations the nodes vector is equal to the doses used in the analysis. For -#' example the \code{\link{Mods}} and the \code{\link{fitMod}} function +#' example the [Mods()] and the [fitMod()] function #' automatically use the doses that are used in the context of the function -#' call as nodes. The guesstimates specified in the \code{\link{Mods}} function +#' call as nodes. The guesstimates specified in the [Mods()] function #' need to be the treatment effects at the active doses standardized to the -#' interval [0,1] (see the examples in the \code{\link{Mods}} function). +#' interval \[0,1\] (see the examples in the [Mods()] function). #' #' @details -#' The \bold{Emax model} is used to represent monotone, concave dose-response +#' The **Emax model** is used to represent monotone, concave dose-response #' shapes. To distinguish it from the more general sigmoid emax model it is #' sometimes also called hyperbolic emax model. #' -#' The \bold{sigmoid Emax} model is an extension of the (hyperbolic) Emax model +#' The **sigmoid Emax** model is an extension of the (hyperbolic) Emax model #' by introducing an additional parameter h, that determines the steepness of #' the curve at the ed50 value. The sigmoid Emax model describes monotonic, #' sigmoid dose-response relationships. In the toxicology literature this model #' is also called four-parameter log-logistic (4pLL) model. #' -#' The \bold{quadratic} model is intended to capture a possible non-monotonic +#' The **quadratic** model is intended to capture a possible non-monotonic #' dose-response relationship. #' -#' The \bold{exponential model} is intended to capture a possible sub-linear or +#' The **exponential model** is intended to capture a possible sub-linear or #' a convex dose-response relationship. #' -#' The \bold{beta model} is intended to capture non-monotone dose-response +#' The **beta model** is intended to capture non-monotone dose-response #' relationships and is more flexible than the quadratic model. The kernel of #' the beta model function consists of the kernel of the density function of a -#' beta distribution on the interval [0,scal]. The parameter scal is not +#' beta distribution on the interval \[0,scal\]. The parameter scal is not #' estimated but needs to be set to a value larger than the maximum dose. It #' can be set in most functions (\samp{fitMod}, \samp{Mods}) via the #' \samp{addArgs} argument, when omitted a value of \samp{1.2*(maximum dose)} #' is used as default, where the maximum dose is inferred from other input to #' the respective function. #' -#' The \bold{linear in log-dose} model is intended to capture concave shapes. -#' The parameter \code{off} is not estimated in the code but set to a +#' The **linear in log-dose** model is intended to capture concave shapes. +#' The parameter `off` is not estimated in the code but set to a #' pre-specified value. It can be set in most functions (\samp{fitMod}, #' \samp{Mods}) via the \samp{addArgs} argument, when omitted a value of #' \samp{0.01*(maximum dose)} is used as default, where the maximum dose is #' inferred from other input to the respective function. #' -#' The \bold{logistic model} is intended to capture general monotone, sigmoid +#' The **logistic model** is intended to capture general monotone, sigmoid #' dose-response relationships. The logistic model and the sigmoid Emax model #' are closely related: The sigmoid Emax model is a logistic model in #' log(dose). #' -#' The \bold{linInt model} provids linear interpolation of the means at the +#' The **linInt model** provids linear interpolation of the means at the #' doses. This can be used as a "nonparametric" estimate of the dose-response #' curve, but is probably most interesting for specifying a "nonparametric" #' truth during planning and assess how well parametric models work under a @@ -210,14 +210,14 @@ #' linIntGrad(dose, resp, nodes, ...) #' @return Response value for model functions or matrix containing the gradient #' evaluations. -#' @seealso \code{\link{fitMod}} +#' @seealso [fitMod()] #' @references MacDougall, J. (2006). Analysis of dose-response studies - Emax -#' model,\emph{in} N. Ting (ed.), \emph{Dose Finding in Drug Development}, +#' model,*in* N. Ting (ed.), *Dose Finding in Drug Development*, #' Springer, New York, pp. 127--145 #' #' 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 +#' studies - modeling approaches, *in* N. Ting (ed.). *Dose Finding +#' in Drug Development*, Springer, New York, pp. 146--171 #' @examples #' #' ## some quadratic example shapes @@ -275,12 +275,12 @@ NULL #' @usage data(biom) #' @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{`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, -#' \emph{Biometrics}, \bold{61}, 738--748 +#' *Biometrics*, **61**, 738--748 #' @keywords datasets NULL @@ -303,12 +303,12 @@ NULL #' @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 +#' \item{`dose`}{a numeric vector containing the dose values} +#' \item{`fev1`}{a numeric vector containing the least square #' mean per dose} -#' \item{\code{sdev}}{a numeric vector containing the standard errors +#' \item{`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} +#' \item{`n`}{Number of participants analyzed per treatment group} #' } #' @source http://clinicaltrials.gov/ct2/show/results/NCT00501852 #' @keywords datasets @@ -356,12 +356,12 @@ NULL #' @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} +#' \item{`gender`}{a factor specifying the gender} +#' \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, \emph{Biometrical Journal}, \bold{44}, 101--116 +#' stratified designs, *Biometrical Journal*, **44**, 101--116 #' @keywords datasets NULL @@ -381,9 +381,9 @@ NULL #' 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} +#' \item{`dose`}{a numeric vector containing the dose values} +#' \item{`painfree`}{number of treatment responders} +#' \item{`ntrt`}{number of subject per treatment group} #' } #' @source http://clinicaltrials.gov/ct2/show/results/NCT00712725 #' @keywords datasets @@ -421,14 +421,14 @@ NULL #' @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} +#' \item{`resp`}{a numeric vector containing the response values} +#' \item{`dose`}{a numeric vector containing the dose values} +#' \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, \emph{Statistics in Medicine}, \bold{33}, 1646--1661 +#' models, *Statistics in Medicine*, **33**, 1646--1661 #' @keywords datasets #' @examples #' diff --git a/R/MCPMod.R b/R/MCPMod.R index af43edd..4767f72 100644 --- a/R/MCPMod.R +++ b/R/MCPMod.R @@ -3,8 +3,8 @@ #' MCPMod - Multiple Comparisons and Modeling #' -#' 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 +#' 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). #' #' @@ -12,22 +12,22 @@ #' @inheritParams MCTtest #' @param 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 +#' `AIC`: Selects model with smallest AIC (this is the default) \item +#' `maxT`: Selects the model corresponding to the largest t-statistic. +#' \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. #' } 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 -#' \code{\link{MCTtest}} and \code{\link{fitMod}}. Infinite degrees of (\samp{df=Inf}) correspond to the multivariate +#' [MCTtest()] and [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. -#' @param doseType,Delta,p \samp{doseType} determines the dose to estimate, ED or TD (see also \code{\link{Mods}}), and +#' @param doseType,Delta,p \samp{doseType} determines the dose to estimate, ED or TD (see also [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. +#' [TD()] and [ED()] for details. #' @param 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 +#' bounds. The names of the list entries need to correspond to the model names. The [defBnds()] function #' provides the default selection. #' @param control Control list for the optimization.\cr A list with entries: "nlminbcontrol", "optimizetol" and #' "gridSize". @@ -43,29 +43,29 @@ #' @return 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). #' @author Bjoern Bornkamp -#' @seealso \code{\link{MCTtest}}, \code{\link{fitMod}}, \code{\link{drmodels}} +#' @seealso [MCTtest()], [fitMod()], [drmodels()] #' @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 +#' 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, \emph{Journal of Biopharmaceutical Statistics}, \bold{16}, 639--656 +#' 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, -#' \emph{in} N. Ting (ed.). \emph{Dose Finding in Drug Development}, Springer, New York, pp. 146--171 +#' *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, \emph{Statistics in Medicine}, \bold{33}, 1646--1661 +#' 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. \emph{Statistics in -#' Medicine}, \bold{35}, 4021--4040 +#' 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, -#' \emph{Biometrics}, \bold{53}, 603--618 +#' *Biometrics*, **53**, 603--618 #' #' Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley. #' @examples diff --git a/R/MCTtest.R b/R/MCTtest.R index 55357c8..cec1904 100644 --- a/R/MCTtest.R +++ b/R/MCTtest.R @@ -5,7 +5,7 @@ #' 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()]). #' #' For \samp{type = "normal"} an ANCOVA model based on a homoscedastic normality assumption (with additive covariates #' specified in \samp{addCovars}) is fitted. @@ -21,11 +21,11 @@ #' data frame specified in \samp{data}. #' @param 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) -#' @param models An object of class \samp{Mods}, see \code{\link{Mods}} for details +#' @param models An object of class \samp{Mods}, see [Mods()] for details #' @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 \code{\link{fitMod}} and Pinheiro et al. (2014). +#' directly in \samp{resp}, \samp{S} and \samp{df}. See also [fitMod()] and Pinheiro et al. (2014). #' @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 = @@ -40,17 +40,17 @@ #' @param alternative Character determining the alternative for the multiple contrast trend test. #' @param na.action A function which indicates what should happen when the data contain NAs. #' @param 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. +#' code, see also [mvtnorm.control()] for details. #' @param 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). #' @return An object of class MCTtest, a list containing the output. #' @author Bjoern Bornkamp -#' @seealso \code{\link{powMCT}}, \code{\link{optContr}} +#' @seealso [powMCT()], [optContr()] #' @references Hothorn, T., Bretz, F., and Westfall, P. (2008). Simultaneous Inference in General Parametric Models, -#' \emph{Biometrical Journal}, \bold{50}, 346--363 +#' *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, \emph{Statistics in Medicine}, \bold{33}, 1646--1661 +#' using general parametric models, *Statistics in Medicine*, **33**, 1646--1661 #' @examples #' #' ## example without covariates @@ -220,16 +220,16 @@ print.MCTtest <- function(x, digits = 3, eps = 1e-3, ...){ #' Calculate critical value for multiple contrast test #' #' Calculation of the critical value for a maximum contrast test. This is based on the equicoordinate quantile function -#' of the multivariate normal or t distribution as implemented in the \code{qmvt} function from the mvtnorm package. +#' of the multivariate normal or t distribution as implemented in the `qmvt` function from the mvtnorm package. #' #' @inheritParams MCTtest #' @param corMat Correlation matrix of contrasts #' @param df Specify the degrees of freedom to use, if this argument is missing \samp{df = Inf} is used (which #' corresponds to the multivariate normal distribution). #' @param control 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. +#' see also [mvtnorm.control()] for details. #' @author Bjoern Bornkamp -#' @seealso \code{\link{powMCT}}, \code{\link{optContr}}, \code{\link{MCTtest}} +#' @seealso [powMCT()], [optContr()], [MCTtest()] #' @examples #' #' R <- matrix(c(1,0.5,0.5,1), nrow=2) @@ -268,7 +268,7 @@ critVal <- function(corMat, alpha = 0.025, df = NULL, #' #' Calculate multiplicity adjusted p-values for a maximum contrast test corresponding to a set of contrasts and given a #' set of observed test statistics. This function is exported as it may be a useful building block and used in more -#' complex testing situations that are not covered by \code{\link{MCTtest}}. Most users probably don't need to use this +#' complex testing situations that are not covered by [MCTtest()]. Most users probably don't need to use this #' function. #' #' @inheritParams critVal @@ -277,9 +277,9 @@ critVal <- function(corMat, alpha = 0.025, df = NULL, #' @param tStat Vector of contrast test statistics #' @return Numeric containing the calculated p-values. #' @author Bjoern Bornkamp -#' @seealso \code{\link{MCTtest}}, \code{\link{optContr}} +#' @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, \emph{Journal of Biopharmaceutical Statistics}, \bold{16}, +#' combining multiple comparisons and modeling procedures, *Journal of Biopharmaceutical Statistics*, **16**, #' 639--656 #' @examples #' data(biom) diff --git a/R/Mods.R b/R/Mods.R index 6751187..817eae0 100644 --- a/R/Mods.R +++ b/R/Mods.R @@ -5,7 +5,7 @@ #' The Mods functions allows to define a set of dose-response models. The function is used as input object for a number #' of other different functions. #' -#' The dose-response models used in this package (see \code{\link{drmodels}} for details) are of form +#' The dose-response models used in this package (see [drmodels()] for details) are of form #' #' \deqn{f(d) = \theta_0+\theta_1 f^0(d,\theta_2)}{f(d) = theta0+theta1 #' f0(d,theta2)} @@ -16,8 +16,8 @@ #' One needs to hand over the effect at placebo and the maximum effect in the dose range, from which #' \eqn{\theta_0,\theta_1}{theta0,theta1} are then back-calculated, the output object is of class \samp{"Mods"}. This #' object can form the input for other functions to extract the mean response (\samp{getResp}) or target doses -#' (\code{\link{TD}} and \code{\link{ED}}) corresponding to the models. It is also needed as input to the functions -#' \code{\link{powMCT}}, \code{\link{optDesign}} +#' ([TD()] and [ED()]) corresponding to the models. It is also needed as input to the functions +#' [powMCT()], [optDesign()] #' #' Some models, for example the beta model (\samp{scal}) and the linlog model (\samp{off}) have parameters that are not #' estimated from the data, they need to be specified via the \samp{addArgs} argument. @@ -32,7 +32,7 @@ #' #' @aliases Mods getResp plot.Mods plotMods #' @param ... In function Mods:\cr Dose-response model names with parameter values specifying the guesstimates for the -#' \eqn{\theta_2}{theta2} parameters. See \code{\link{drmodels}} for a complete list of dose-response models +#' \eqn{\theta_2}{theta2} parameters. See [drmodels()] for a complete list of dose-response models #' implemented. See below for an example specification.\cr \cr In function plot.Mods:\cr Additional arguments to the #' \samp{xyplot} call. #' @param doses Dose levels to be used, this needs to include placebo. @@ -49,9 +49,9 @@ #' @return Returns an object of class \samp{"Mods"}. The object contains the specified model parameter values and the #' derived linear parameters (based on \samp{"placEff"} and \samp{"maxEff"}) in a list. #' @author Bjoern Bornkamp -#' @seealso \code{\link{Mods}}, \code{\link{drmodels}}, \code{\link{optDesign}}, \code{\link{powMCT}} +#' @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, \emph{Journal of Biopharmaceutical Statistics}, \bold{16}, +#' combining multiple comparisons and modeling procedures, *Journal of Biopharmaceutical Statistics*, **16**, #' 639--656 #' @examples #' @@ -309,8 +309,8 @@ plot.Mods <- function(x, nPoints = 200, superpose = FALSE, xlab = "Dose", } -#' Calculate dose estimates for a fitted dose-response model (via \code{\link{fitMod}}, \code{\link{bFitMod}}) -#' or \code{\link{maFitMod}}) or a \code{\link{Mods}} object +#' Calculate dose estimates for a fitted dose-response model (via [fitMod()], [bFitMod()]) +#' or [maFitMod()]) or a [Mods()] object #' #' @description The TD (target dose) is defined as the dose that achieves a target effect of Delta over placebo (if #' there are multiple such doses, the smallest is chosen): @@ -329,7 +329,7 @@ plot.Mods <- function(x, nPoints = 200, superpose = FALSE, xlab = "Dose", #' \deqn{ED_p=\min\{x|f(x) > f(0) + p(f(dmax)-f(0))}{ EDp=min{x|f(x) > f(0) + p(f(dmax)-f(0))}} #' #' Note that this definition of the EDp is different from traditional definition based on the Emax model, -#' where the EDp is defined relative to the \emph{asymptotic} maximum effect (rather than the maximum effect in the observed dose-range). +#' where the EDp is defined relative to the *asymptotic* maximum effect (rather than the maximum effect in the observed dose-range). #' #' ED or TD calculation for bootstrap model averaging (maFit) objects is based on first calculating the pointwise median dose-response curve estimate. Then calculating the dose estimate based on this curve. #' @@ -351,8 +351,8 @@ plot.Mods <- function(x, nPoints = 200, superpose = FALSE, xlab = "Dose", #' @return Returns the dose estimate #' #' @author Bjoern Bornkamp -#' @seealso \code{\link{Mods}}, \code{\link{drmodels}}, -#' \code{\link{fitMod}}, \code{\link{bFitMod}} +#' @seealso [Mods()], [drmodels()], +#' [fitMod()], [bFitMod()] #' #' @examples #' ## example for creating a "full-model" candidate set placebo response @@ -593,4 +593,4 @@ ED <- function(object, p, EDtype = c("continuous", "discrete"), return(NA) } } -} \ No newline at end of file +} diff --git a/R/bFitMod.R b/R/bFitMod.R index 8f0404a..488960c 100644 --- a/R/bFitMod.R +++ b/R/bFitMod.R @@ -3,11 +3,11 @@ #' Fit a dose-response model using Bayesian or bootstrap methods. #' #' 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 +#' function assumes a multivariate normal distribution for `resp` with covariance matrix `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 +#' For \samp{type = "bootstrap"}, a multivariate normal distribution for `resp` with covariance matrix `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. #' @@ -15,10 +15,10 @@ #' #' @aliases bFitMod coef.bFitMod predict.bFitMod plot.bFitMod #' @param dose Numeric specifying the dose variable. -#' @param resp Numeric specifying the response estimate corresponding to the doses in \code{dose} -#' @param S Covariance matrix associated with the dose-response estimate specified via \code{resp} +#' @param resp Numeric specifying the response estimate corresponding to the doses in `dose` +#' @param S Covariance matrix associated with the dose-response estimate specified via `resp` #' @param model Dose-response model to fit, possible models are "linlog", "linear", "quadratic", "emax", "exponential", -#' "sigEmax", "betaMod" and "logistic", see \code{\link{drmodels}}. +#' "sigEmax", "betaMod" and "logistic", see [drmodels()]. #' @param 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) #' @param type Character with allowed values "Bayes" and "bootstrap", Determining whether samples are drawn from the @@ -26,26 +26,26 @@ #' @param start Optional starting values for the dose-response parameters in the MCMC algorithm. #' @param 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 +#' in the arguments list of the model see (see [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}: +#' distributions: \itemize{ \item `norm`: Vector of length 2 giving mean +#' and standard deviation. \item `t`: Vector of length 3 giving median, +#' scale and degrees of freedom of the t-distribution. \item `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 +#' `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 } #' @param nSim Desired number of samples to produce with the algorithm #' @param 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 +#' \itemize{ \item `thin` Thinning rate. Must be a positive integer. +#' \item `w` Numeric of same length as number of parameters in the model, +#' specifies the width parameters of the slice sampler. \item `adapt` +#' Logical whether to adapt the `w` (width) parameter of the slice sampler #' in a short trial run. The widths are chosen as IQR/1.3 of the trial run. } -#' @param control Same as the control argument in \code{\link{fitMod}}. +#' @param control Same as the control argument in [fitMod()]. #' @param bnds Bounds for non-linear parameters, in case \samp{type = "bootstrap"}. If missing the the default bounds -#' from \code{\link{defBnds}} is used. +#' from [defBnds()] is used. #' @param 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))} #' @param x,object A bFitMod object @@ -53,7 +53,7 @@ #' @return An object of class bFitMod, which is a list containing the matrix of posterior simulations plus some #' additional information on the fitted model. #' @author Bjoern Bornkamp -#' @seealso \code{\link{fitMod}} +#' @seealso [fitMod()] #' @references Neal, R. M. (2003), Slice sampling, Annals of Statistics, 31, 705-767 #' @examples #' data(biom) diff --git a/R/bMCTtest.R b/R/bMCTtest.R index 04547a1..97b7e66 100644 --- a/R/bMCTtest.R +++ b/R/bMCTtest.R @@ -2,7 +2,7 @@ #' #' 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 -#' \code{\link{MCTtest}}. +#' [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. @@ -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 \code{\link{MCTtest}}). Fleischer et al. (2022) discuss using contrasts that take the prior +#' the same way as in [MCTtest()]). Fleischer et al. (2022) 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. #' @@ -37,16 +37,16 @@ #' \samp{critV} this is used to derive critical values for Bayesian decision rule. #' @param contMat Contrast matrix to apply to the posterior dose-response estimates. The contrasts need to be in the #' columns of the matrix (i.e. the column sums need to be 0). If not specified optimal contrasts are calculated using -#' \code{\link{optContr}}. +#' [optContr()]. #' @param critV Supply a critical value for the maximum posterior probability of the contrasts being greater than zero #' that needs to be surpassed to establish a non-flat dose-response. If this argument is NULL, this will be derived #' from critical values for frequentist MCP-Mod using the provided \samp{alpha}. #' @return An object of class bMCTtest, a list containing the output. #' @author Marius Thomas #' @export -#' @seealso \code{\link{MCTtest}}, \code{\link{optContr}} +#' @seealso [MCTtest()], [optContr()] #' @references Fleischer, F., Bossert, S., Deng, Q., Loley, C. and Gierse, J. (2022). Bayesian MCP-Mod, -#' \emph{Pharmaceutical Statistics}, \bold{21}, 654--670 +#' *Pharmaceutical Statistics*, **21**, 654--670 #' @examples #' #' diff --git a/R/drmodels.R b/R/drmodels.R index 7945554..0e8bde3 100644 --- a/R/drmodels.R +++ b/R/drmodels.R @@ -15,7 +15,7 @@ emax <- function(dose, e0, eMax, ed50){ #' @rdname drmodels #' @param ... Just included for convenience in the gradient functions, so that -#' for example \code{quadratic(dose, e0=0, b1=1, b2=3)} will not throw an error +#' for example `quadratic(dose, e0=0, b1=1, b2=3)` will not throw an error #' (although the gradient of the quadratic model is independent of e0, b1 and #' b2). #' @usage NULL diff --git a/R/fitMod.R b/R/fitMod.R index 45713f5..48f35dc 100644 --- a/R/fitMod.R +++ b/R/fitMod.R @@ -8,15 +8,15 @@ #' #' 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. +#' for the beta model first and second row correspond to the delta1 and delta2 parameters. See [logistic()], +#' [sigEmax()] and [betaMod()] for details. #' #' #' @param mD Maximum dose in the study. #' @param emax,exponential,logistic,sigEmax,betaMod values for the nonlinear parameters for these model-functions #' @return List containing bounds for the model parameters. #' @author Bjoern Bornkamp -#' @seealso \code{\link{fitMod}} +#' @seealso [fitMod()] #' @examples #' #' defBnds(mD = 1) @@ -34,7 +34,7 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' Fit non-linear dose-response model #' #' Fits a dose-response model. Built-in dose-response models are "linlog", "linear", "quadratic", "emax", "exponential", -#' "sigEmax", "betaMod" and "logistic" (see \code{\link{drmodels}}). +#' "sigEmax", "betaMod" and "logistic" (see [drmodels()]). #' #' When \samp{type = "normal"} ordinary least squares is used and additional additive covariates can be specified in #' \samp{addCovars}. The underlying assumption is hence normally distributed data and homoscedastic variance. @@ -55,8 +55,8 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' Details on numerical optimizer for model-fitting:\cr For linear models fitting is done using numerical linear algebra #' based on the QR decomposition. For nonlinear models numerical optimization is performed only in the nonlinear #' parameters in the model and optimizing over the linear parameters in each iteration (similar as the Golub-Pereyra -#' implemented in \code{\link{nls}}). For models with 1 nonlinear parameter the \code{\link{optimize}} function is used -#' for 2 nonlinear parameters the \code{\link{nlminb}} function is used. The starting value is generated using a +#' implemented in [nls()]). For models with 1 nonlinear parameter the [optimize()] function is used +#' for 2 nonlinear parameters the [nlminb()] function is used. The starting value is generated using a #' grid-search (with the grid size specified via \samp{control$gridSize}), or can directly be handed over via #' \samp{start}. #' @@ -70,7 +70,7 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' @param 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) #' @param model The dose-response model to be used for fitting the data. Built-in models are "linlog", "linear", -#' "quadratic", "emax", "exponential", "sigEmax", "betaMod" and "logistic" (see \link{drmodels}). +#' "quadratic", "emax", "exponential", "sigEmax", "betaMod" and "logistic" (see [drmodels]). #' @param S The inverse weighting matrix used in case, when \samp{type = "general"}, see Description. For later #' inference statements (vcov or predict methods) it is assumed this is the estimated covariance of the estimates in #' the first stage fit. @@ -81,11 +81,11 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' @param placAdj Logical, if true, it is assumed that placebo-adjusted #' estimates are specified in \samp{resp} (only possible for \samp{type = #' "general"}). -#' @param bnds Bounds for non-linear parameters. If missing the the default bounds from \code{\link{defBnds}} is used. +#' @param bnds Bounds for non-linear parameters. If missing the the default bounds from [defBnds()] is used. #' #' When the dose-response model has only one non-linear parameter (for example Emax or exponential model), \samp{bnds} #' needs to be a vector containing upper and lower bound. For models with two non-linear parameters \samp{bnds} needs -#' to be a matrix containing the bounds in the rows, see the Description section of \code{\link{defBnds}} for details +#' to be a matrix containing the bounds in the rows, see the Description section of [defBnds()] for details #' on the formatting of the bounds for the individual models. #' @param df Degrees of freedom to use in case of \samp{type = "general"}. If this argument is missing \samp{df = Inf} #' is used. For \samp{type = "normal"} this argument is ignored as the exact degrees of freedom can be deduced from @@ -108,9 +108,9 @@ defBnds <- function(mD, emax = c(0.001, 1.5)*mD, #' @return An object of class DRMod. Essentially a list containing information about the fitted model coefficients, the #' residual sum of squares (or generalized residual sum of squares), #' @author Bjoern Bornkamp -#' @seealso \code{\link{defBnds}}, \code{\link{drmodels}} +#' @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, \emph{Statistics in Medicine}, \bold{33}, 1646--1661 +#' uncertainty using general parametric models, *Statistics in Medicine*, **33**, 1646--1661 #' #' Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley. #' @examples diff --git a/R/guesst.R b/R/guesst.R index 11b570d..7887c29 100644 --- a/R/guesst.R +++ b/R/guesst.R @@ -6,7 +6,7 @@ #' #' 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}} function to ensure that the guesstimates are reflecting the prior beliefs. +#' together with the [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. #' @@ -36,14 +36,14 @@ #' @param Maxd Maximum dose to be administered in the trial #' @param scal Scale parameter, only needed for the beta model #' @return Returns a numeric vector containing the guesstimates. -#' @seealso \code{\link{emax}}, \code{\link{logistic}}, \code{\link{betaMod}}, \code{\link{sigEmax}}, -#' \code{\link{quadratic}}, \code{\link{exponential}}, \code{\link{plot.Mods}} +#' @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, \emph{Journal -#' of Statistical Software}, \bold{29}(7), 1--23 +#' Package for the Design and Analysis of Dose-Finding Studies, *Journal +#' of Statistical Software*, **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 +#' *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 cf5abea..931b2b4 100644 --- a/R/maFitMod.R +++ b/R/maFitMod.R @@ -12,17 +12,17 @@ #' @aliases predict.maFit plot.maFit print.maFit #' @param dose Numeric specifying the dose variable. #' @param resp Numeric specifying the response estimate corresponding -#' to the doses in \code{dose} +#' to the doses in `dose` #' @param S Covariance matrix associated with the dose-response -#' estimate specified via \code{resp} +#' estimate specified via `resp` #' @param models dose-response models to fit #' @param nSim Number of bootstrap simulations #' @param control Same as the control argument in -#' \code{\link{fitMod}}. +#' [fitMod()]. #' @param 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 +#' names. The [defBnds()] function provides the default #' selection. #' @param addArgs List containing two entries named "scal" and "off" #' for the "betaMod" and "linlog" model. When addArgs is NULL the @@ -32,7 +32,7 @@ #' dose-response models \samp{DRMod} objects, information on which model #' was selected in each bootstrap and basic input parameters. #' @author Bjoern Bornkamp -#' @seealso \code{\link{fitMod}}, \code{\link{bFitMod}}, \code{\link{drmodels}} +#' @seealso [fitMod()], [bFitMod()], [drmodels()] #' @references Breiman, L. (1996). Bagging predictors. Machine learning, 24, 123-140. #' @examples #' data(biom) diff --git a/R/optContr.R b/R/optContr.R index e655bc8..d835236 100644 --- a/R/optContr.R +++ b/R/optContr.R @@ -14,7 +14,7 @@ #' #' Note that the directionality (i.e. whether in "increase" in the response #' variable is beneficial or a "decrease", is inferred from the specified -#' \samp{models} object, see \code{\link{Mods}} for details). +#' \samp{models} object, see [Mods()] for details). #' #' Constrained contrasts (type = "constrained") add the additional constraint #' in the optimization that the sign of the contrast coefficient for control @@ -51,14 +51,14 @@ #' @return Object of class \samp{optContr}. A list containing entries contMat #' and muMat (i.e. contrast, mean and correlation matrix). #' @author Bjoern Bornkamp -#' @seealso \code{\link{MCTtest}} +#' @seealso [MCTtest()] #' @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 +#' *Biometrics*, **61**, 738--748 #' #' 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 +#' *Statistics in Medicine*, **33**, 1646--1661 #' @examples #' #' doses <- c(0,10,25,50,100,150) diff --git a/R/optDesign.R b/R/optDesign.R index 8924ece..6e352d9 100644 --- a/R/optDesign.R +++ b/R/optDesign.R @@ -37,7 +37,7 @@ #' For details on the \samp{rndDesign} function, see Pukelsheim (1993), Chapter 12. #' #' @aliases optDesign plot.DRdesign calcCrit rndDesign -#' @param models An object of class \samp{c(Mods, fullMod)}, see the \code{\link{Mods}} function for details. When an TD +#' @param models An object of class \samp{c(Mods, fullMod)}, see the [Mods()] function for details. When an TD #' optimal design should be calculated, the TD needs to exist for all models. If a D-optimal design should be #' calculated, you need at least as many doses as there are parameters in the specified models. #' @param probs Vector of model probabilities for the models specified in \samp{models}, assumed in the same order as @@ -59,7 +59,7 @@ #' #' For \samp{optimizer = "exact"} one always needs to specify the total sample size via \samp{n}. #' @param control List containing control parameters passed down to numerical optimization algorithms -#' (\code{\link{optim}}, \code{\link{nlminb}} or solnp function).\cr +#' ([optim()], [nlminb()] or solnp function).\cr #' #' For \samp{type = "exact"} this should be a list with possible entries \samp{maxvls1} and \samp{maxvls2}, #' determining the maximum number of designs allowed for passing to the criterion function (default @@ -67,7 +67,7 @@ #' addition there can be an entry \samp{groupSize} in case the patients are allocated a minimum group size is #' required. #' @param optimizer Algorithm used for calculating the optimal design. Options "Nelder-Mead" and "nlminb" use the -#' \code{\link{optim}} and \code{\link{nlminb}} function and use a trigonometric transformation to turn 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). #' #' Option "solnp" uses the solnp function from the Rsolnp package, which implements an optimizer for non-linear @@ -90,18 +90,18 @@ #' The first argument of \samp{userCrit} should be the vector of design weights, while the second argument should be #' the \samp{doses} argument (see example below). Additional arguments to \samp{userCrit} can be passed via ... #' @param ... For function \samp{optDesign} these are additional arguments passed to \samp{userCrit}.\cr \cr For -#' function \samp{plot.design} these are additional parameters passed to \code{\link{plot.Mods}}.\cr +#' function \samp{plot.design} these are additional parameters passed to [plot.Mods()].\cr #' @note In some cases (particularly when the number of doses is large, e.g. 7 or larger) it might be necessary to allow #' a larger number of iterations in the algorithm (via the argument \samp{control}), particularly for the Nelder-Mead #' algorithm. Alternatively one can use the solnp optimizer that is usually the most reliable, but not fastest option. #' @author Bjoern Bornkamp -#' @seealso \code{\link{Mods}}, \code{\link{drmodels}} +#' @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, \emph{Journal of the American Statisical -#' Association}, \bold{103}, 1225--1237 +#' 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 @@ -376,7 +376,7 @@ optDesign <- function(models, probs, doses, #' @param design Argument for \samp{rndDesign} and \samp{calcCrit} functions: Numeric vector (or matrix) of allocation #' weights for the different doses. The rows of the matrices need to sum to 1. Alternatively also an object of class #' "DRdesign" can be used for \samp{rndDesign}. Note that there should be at least as many design points available as -#' there are parameters in the dose-response models selected in \code{models} (otherwise the code returns an NA). +#' there are parameters in the dose-response models selected in `models` (otherwise the code returns an NA). #' #' @rdname optDesign #' @export diff --git a/R/planMod.R b/R/planMod.R index 83a9f2b..9678047 100644 --- a/R/planMod.R +++ b/R/planMod.R @@ -8,26 +8,26 @@ #' method applied to planMod objects. The implemented metrics are \itemize{ #' \item Root of the mean-squared error to estimate the placebo-adjusted #' dose-response averaged over the used dose-levels, i.e. a rather discrete set -#' (\code{dRMSE}). Available via the print method of planMod objects. \item +#' (`dRMSE`). Available via the print method of planMod objects. \item #' Root of the mean-squared error to estimate the placebo-adjusted -#' dose-response (\code{cRMSE}) averaged over fine (almost continuous) grid at +#' dose-response (`cRMSE`) averaged over fine (almost continuous) grid at #' 101 equally spaced values between placebo and the maximum dose. NOTE: #' Available via the summary method applied to planMod objects. \item Ratio of #' the placebo-adjusted mean-squared error (at the observed doses) of -#' model-based vs ANOVA approach (\code{Eff-vs-ANOVA}). This can be interpreted +#' model-based vs ANOVA approach (`Eff-vs-ANOVA`). This can be interpreted #' on the sample size scale. NOTE: Available via the summary method applied to #' planMod objects. \item Power that the (unadjusted) one-sided \samp{1-alpha} #' confidence interval comparing the dose with maximum effect vs placebo is #' larger than \samp{tau}. By default \samp{alpha = 0.025} and \samp{tau = 0} -#' (\code{Pow(maxDose)}). Available via the print method of planMod objects. -#' \item Probability that the EDp estimate is within the true [EDpLB, EDpUB] +#' (`Pow(maxDose)`). Available via the print method of planMod objects. +#' \item Probability that the EDp estimate is within the true \[EDpLB, EDpUB\] #' (by default \samp{p=0.5}, \samp{pLB=0.25} and \samp{pUB=0.75}). This metric #' gives an idea on the ability to characterize the increasing part of the -#' dose-response curve (\code{P(EDp)}). Available via the print method of +#' dose-response curve (`P(EDp)`). Available via the print method of #' planMod objects. \item Length of the quantile range for a target dose (TD #' or EDp). This is calculated by taking the difference of the dUB and dLB #' quantile of the empirical distribution of the dose estimates. -#' (\code{lengthTDCI} and \code{lengthEDpCI}). It is NOT calculated by +#' (`lengthTDCI` and `lengthEDpCI`). It is NOT calculated by #' calculating confidence interval lengths in each simulated data-set and #' taking the mean. NOTE: Available via the summary method of planMod objects. #' } @@ -38,14 +38,14 @@ #' @aliases planMod plot.planMod summary.planMod #' @param model Character vector determining the dose-response model(s) to be used for fitting the data. When more than #' one dose-response model is provided the best fitting model is chosen using the AIC. Built-in models are "linlog", -#' "linear", "quadratic", "emax", "exponential", "sigEmax", "betaMod" and "logistic" (see \link{drmodels}). +#' "linear", "quadratic", "emax", "exponential", "sigEmax", "betaMod" and "logistic" (see [drmodels]). #' @param altModels An object of class \samp{Mods}, defining the true mean vectors under which operating characteristics #' should be calculated. #' @param n,sigma,S Either a vector \samp{n} and \samp{sigma} or \samp{S} need to be specified. When \samp{n} and #' \samp{sigma} are specified it is assumed computations are made for a normal homoscedastic ANOVA model with group #' sample sizes given by \samp{n} and residual standard deviation \samp{sigma}, i.e. the covariance matrix used for -#' the estimates is thus \code{sigma^2*diag(1/n)} and the degrees of freedom are calculated as -#' \code{sum(n)-nrow(contMat)}. When a single number is specified for \samp{n} it is assumed this is the sample size +#' the estimates is thus `sigma^2*diag(1/n)` and the degrees of freedom are calculated as +#' `sum(n)-nrow(contMat)`. When a single number is specified for \samp{n} it is assumed this is the sample size #' per group and balanced allocations are used.\cr #' #' When \samp{S} is specified this will be used as covariance matrix for the estimates. @@ -62,12 +62,12 @@ #' effect Windows, as the mclapply function is used internally. #' @param showSimProgress In case of simulations show the progress using a progress-bar. #' @param 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 +#' bounds. The names of the list entries need to correspond to the model names. The [defBnds()] function #' provides the default selection. -#' @param addArgs See the corresponding argument in function \code{\link{fitMod}}. This argument is directly passed to +#' @param addArgs See the corresponding argument in function [fitMod()]. This argument is directly passed to #' fitMod. #' @author Bjoern Bornkamp -#' @seealso \code{\link{fitMod}} +#' @seealso [fitMod()] #' @references TBD #' @examples #' @@ -340,8 +340,8 @@ print.planMod <- function(x, digits = 3,...){ #' @param len Number of equally spaced points to determine the mean-squared error on a grid (cRMSE). #' @param Delta Additional arguments determining what dose estimate to plot, when \samp{type = "ED"} or \samp{type = #' "TD"} -#' @param dLB,dUB Which quantiles to use for calculation of \code{lengthTDCI} and \code{lengthEDpCI}. By default dLB = -#' 0.05 and dUB = 0.95, so that this corresponds to a 90\% interval. +#' @param dLB,dUB Which quantiles to use for calculation of `lengthTDCI` and `lengthEDpCI`. By default dLB = +#' 0.05 and dUB = 0.95, so that this corresponds to a 90% interval. #' @param ... Additional arguments (currently ignored) #' #' @rdname planMod diff --git a/R/powMCT.R b/R/powMCT.R index db8b7ff..103d257 100644 --- a/R/powMCT.R +++ b/R/powMCT.R @@ -36,8 +36,8 @@ mvtnorm.control <- function(maxpts = 30000, abseps = 0.001, #' computations are made for a normal homoscedastic ANOVA model with group #' sample sizes given by \samp{n} and residual standard deviation \samp{sigma}, #' i.e. the covariance matrix used for the estimates is thus -#' \code{sigma^2*diag(1/n)} and the degrees of freedom are calculated as -#' \code{sum(n)-nrow(contMat)}. When a single number is specified for \samp{n} +#' `sigma^2*diag(1/n)` and the degrees of freedom are calculated as +#' `sum(n)-nrow(contMat)`. When a single number is specified for \samp{n} #' it is assumed this is the sample size per group and balanced allocations are #' used.\cr #' @@ -46,7 +46,7 @@ mvtnorm.control <- function(maxpts = 30000, abseps = 0.001, #' @param placAdj Logical, if true, it is assumed that the standard deviation #' or variance matrix of the placebo-adjusted estimates are specified in #' \samp{sigma} or \samp{S}, respectively. The contrast matrix has to be -#' produced on placebo-adjusted scale, see \code{\link{optContr}}, so that the +#' produced on placebo-adjusted scale, see [optContr()], so that the #' coefficients are no longer contrasts (i.e. do not sum to 0). #' @param alternative Character determining the alternative for the multiple #' contrast trend test. @@ -60,11 +60,11 @@ mvtnorm.control <- function(maxpts = 30000, abseps = 0.001, #' \samp{mvtnorm.control} for details. #' @return Numeric containing the calculated power values #' @author Bjoern Bornkamp -#' @seealso \code{\link{powN}}, \code{\link{sampSizeMCT}}, -#' \code{\link{MCTtest}}, \code{\link{optContr}}, \code{\link{Mods}} +#' @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, \emph{Journal of Biopharmaceutical Statistics}, \bold{16}, +#' procedures, *Journal of Biopharmaceutical Statistics*, **16**, #' 639--656 #' @examples #' diff --git a/R/powMCTInterim.R b/R/powMCTInterim.R index eb39396..4a1581a 100644 --- a/R/powMCTInterim.R +++ b/R/powMCTInterim.R @@ -15,13 +15,13 @@ #' conditional power should be calculated. For conditional power #' mu_assumed needs to be specified. #' @param mu_assumed Mean vector to assume for the second stage (only used when type is -#' \samp{conditional}). If \code{NULL} (default), the first stage estimates \code{mu_0t} are used. +#' \samp{conditional}). If `NULL` (default), the first stage estimates `mu_0t` are used. #' @param control A list specifying additional control parameters for the \samp{pmvnorm} calls in the code, see also #' \samp{mvtnorm.control} for details. #' @return Numeric containing the calculated power values -#' @seealso \code{\link{powMCT}} \code{\link{MCTtest}}, \code{\link{optContr}} +#' @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, \emph{arXiv:2406.19965} +#' on longitudinal models, *arXiv:2406.19965* #' @examples #' #' # Setup the scenario. diff --git a/R/sampSize.R b/R/sampSize.R index 9cf96b9..e76a02f 100644 --- a/R/sampSize.R +++ b/R/sampSize.R @@ -16,8 +16,8 @@ #' #' #' @aliases sampSize sampSizeMCT targN plot.targN powN -#' @param upperN,lowerN Upper and lower bound for the target sample size. \code{lowerN} defaults to -#' \code{floor(upperN/2)}. +#' @param upperN,lowerN Upper and lower bound for the target sample size. `lowerN` defaults to +#' `floor(upperN/2)`. #' @param targFunc,target The target function needs to take as an input the vector of sample sizes in the different dose #' groups. For \samp{sampSize} it needs to return a univariate number. For function \samp{targN} it should return a #' numerical vector.\cr \cr Example: \samp{targFunc} could be a function that calculates the power of a test, and @@ -33,25 +33,25 @@ #' size is iterated in bisection search algorithm. #' @param verbose Logical value indicating if a trace of the iteration progress of the bisection search algorithm should #' be displayed. -#' @param ... Arguments directly passed to the \code{\link{powMCT}} function in the \samp{sampSizeMCT} and \samp{powN} +#' @param ... Arguments directly passed to the [powMCT()] function in the \samp{sampSizeMCT} and \samp{powN} #' function. #' #' The \samp{placAdj} argument needs to be \samp{FALSE} (which is the default value for this argument). If sample size #' calculations are desired for a placebo-adjusted formulation use \samp{sampSize} or \samp{targN} directly. #' -#' In case \code{S} is specified, the specified matrix needs to be proportional to the (hypothetical) covariance +#' In case `S` is specified, the specified matrix needs to be proportional to the (hypothetical) covariance #' matrix of one single observation. The covariance matrix used for sample size calculation is 1/N*S, where N is the #' total sample size. Hence \samp{Ntype == "total"} needs to be used if -#' \code{S} is specified. When \code{S} is specified, automatically \samp{df = +#' `S` is specified. When `S` is specified, automatically \samp{df = #' Inf} is assumed in the underlying \samp{powMCT} calls. #' #' For a homoscedastic normally distributed response variable only \samp{sigma} needs to be specified, as the sample #' size \samp{n} is iterated in the different \samp{powMCT} calls. #' #' @author Jose Pinheiro, Bjoern Bornkamp -#' @seealso \code{\link{powMCT}} +#' @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, \emph{Journal of Biopharmaceutical Statistics}, \bold{16}, +#' 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 @@ -220,7 +220,7 @@ print.sampSize <- function(x, ...){ #' Sample size calculations for multiple contrast tests #' -#' @param ... Arguments directly passed to the \code{\link{powMCT}} function in the \samp{sampSizeMCT} and \samp{powN} +#' @param ... Arguments directly passed to the [powMCT()] function in the \samp{sampSizeMCT} and \samp{powN} #' function. #' @param power,sumFct power is a numeric defining the desired summary power to achieve (in \samp{sampSizeMCT}). sumFct #' needs to be a function that combines the power values under the different alternatives into one value (in @@ -278,7 +278,7 @@ Use sampSize directly in case exact df are required.") #' Calculate target function for given sample size #' #' @param step Only needed for functions \samp{targN} and \samp{powN}. Stepsize for the sample size at which the target -#' function is calculated. The steps are calculated via \code{seq(lowerN,upperN,by=step)}. +#' function is calculated. The steps are calculated via `seq(lowerN,upperN,by=step)`. #' @param power,sumFct power is a numeric defining the desired summary power to achieve (in \samp{sampSizeMCT}). #' @rdname sampSize #' @export diff --git a/man/DoseFinding-package.Rd b/man/DoseFinding-package.Rd index f967278..65a7180 100644 --- a/man/DoseFinding-package.Rd +++ b/man/DoseFinding-package.Rd @@ -12,12 +12,12 @@ normal and general response variable. } \details{ The main functions are:\cr -\bold{MCTtest}: Implements a multiple contrast tests\cr -\bold{powMCT}: Power calculations for multiple contrast tests\cr -\bold{fitMod}: Fits non-linear dose-response models\cr -\bold{optDesign}: Calculates optimal designs for dose-response models\cr -\bold{MCPMod}: Performs MCPMod methodology\cr -\bold{sampSize}: General function for sample size calculation\cr +\strong{MCTtest}: Implements a multiple contrast tests\cr +\strong{powMCT}: Power calculations for multiple contrast tests\cr +\strong{fitMod}: Fits non-linear dose-response models\cr +\strong{optDesign}: Calculates optimal designs for dose-response models\cr +\strong{MCPMod}: Performs MCPMod methodology\cr +\strong{sampSize}: General function for sample size calculation\cr } \examples{ @@ -52,19 +52,19 @@ 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}, \bold{5}, 1611--1631 +Applied Statistics}, \strong{5}, 1611--1631 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}, \bold{29}(7), 1--23 +Statistical Software}, \strong{29}(7), 1--23 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 +\emph{Biometrics}, \strong{61}, 738--748 Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal Designs for Dose Finding Studies, \emph{Journal of the American Statisical -Association}, \bold{103}, 1225--1237 +Association}, \strong{103}, 1225--1237 O'Quigley, J., Iasonos, A. and Bornkamp, B. (2017) Handbook of methods for designing, monitoring, and analyzing dose-finding trials, CRC press, Part 3: @@ -72,11 +72,11 @@ Dose-Finding Studies in Phase II 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 +\emph{Journal of Biopharmaceutical Statistics}, \strong{16}, 639--656 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 +\emph{Statistics in Medicine}, \strong{33}, 1646--1661 Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley } diff --git a/man/IBScovars.Rd b/man/IBScovars.Rd index e20de82..87e51d2 100644 --- a/man/IBScovars.Rd +++ b/man/IBScovars.Rd @@ -6,15 +6,15 @@ \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} - } +\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}, \bold{44}, 101--116 +stratified designs, \emph{Biometrical Journal}, \strong{44}, 101--116 } \usage{ data(IBScovars) diff --git a/man/MCTpval.Rd b/man/MCTpval.Rd index e148121..5401fa9 100644 --- a/man/MCTpval.Rd +++ b/man/MCTpval.Rd @@ -25,7 +25,7 @@ MCTpval( \item{alternative}{Character determining the alternative for the multiple contrast trend test.} \item{control}{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.} +see also \code{\link[=mvtnorm.control]{mvtnorm.control()}} for details.} } \value{ Numeric containing the calculated p-values. @@ -33,7 +33,7 @@ Numeric containing the calculated p-values. \description{ Calculate multiplicity adjusted p-values for a maximum contrast test corresponding to a set of contrasts and given a set of observed test statistics. This function is exported as it may be a useful building block and used in more -complex testing situations that are not covered by \code{\link{MCTtest}}. Most users probably don't need to use this +complex testing situations that are not covered by \code{\link[=MCTtest]{MCTtest()}}. Most users probably don't need to use this function. } \examples{ @@ -58,11 +58,11 @@ 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}, \bold{16}, - 639--656 +combining multiple comparisons and modeling procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, +639--656 } \seealso{ -\code{\link{MCTtest}}, \code{\link{optContr}} +\code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}} } \author{ Bjoern Bornkamp diff --git a/man/Mods.Rd b/man/Mods.Rd index a09f980..266c50e 100644 --- a/man/Mods.Rd +++ b/man/Mods.Rd @@ -43,7 +43,7 @@ plotMods( } \arguments{ \item{...}{In function Mods:\cr Dose-response model names with parameter values specifying the guesstimates for the -\eqn{\theta_2}{theta2} parameters. See \code{\link{drmodels}} for a complete list of dose-response models +\eqn{\theta_2}{theta2} parameters. See \code{\link[=drmodels]{drmodels()}} for a complete list of dose-response models implemented. See below for an example specification.\cr \cr In function plot.Mods:\cr Additional arguments to the \samp{xyplot} call.} @@ -90,14 +90,14 @@ be plotted. \samp{Delta} is the target effect to estimate for the TD.} } \value{ Returns an object of class \samp{"Mods"}. The object contains the specified model parameter values and the - derived linear parameters (based on \samp{"placEff"} and \samp{"maxEff"}) in a list. +derived linear parameters (based on \samp{"placEff"} and \samp{"maxEff"}) in a list. } \description{ The Mods functions allows to define a set of dose-response models. The function is used as input object for a number of other different functions. } \details{ -The dose-response models used in this package (see \code{\link{drmodels}} for details) are of form +The dose-response models used in this package (see \code{\link[=drmodels]{drmodels()}} for details) are of form \deqn{f(d) = \theta_0+\theta_1 f^0(d,\theta_2)}{f(d) = theta0+theta1 f0(d,theta2)} @@ -108,8 +108,8 @@ depending on the used model. One needs to hand over the effect at placebo and the maximum effect in the dose range, from which \eqn{\theta_0,\theta_1}{theta0,theta1} are then back-calculated, the output object is of class \samp{"Mods"}. This object can form the input for other functions to extract the mean response (\samp{getResp}) or target doses -(\code{\link{TD}} and \code{\link{ED}}) corresponding to the models. It is also needed as input to the functions -\code{\link{powMCT}}, \code{\link{optDesign}} +(\code{\link[=TD]{TD()}} and \code{\link[=ED]{ED()}}) corresponding to the models. It is also needed as input to the functions +\code{\link[=powMCT]{powMCT()}}, \code{\link[=optDesign]{optDesign()}} Some models, for example the beta model (\samp{scal}) and the linlog model (\samp{off}) have parameters that are not estimated from the data, they need to be specified via the \samp{addArgs} argument. @@ -210,11 +210,11 @@ 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}, \bold{16}, - 639--656 +combining multiple comparisons and modeling procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, +639--656 } \seealso{ -\code{\link{Mods}}, \code{\link{drmodels}}, \code{\link{optDesign}}, \code{\link{powMCT}} +\code{\link[=Mods]{Mods()}}, \code{\link[=drmodels]{drmodels()}}, \code{\link[=optDesign]{optDesign()}}, \code{\link[=powMCT]{powMCT()}} } \author{ Bjoern Bornkamp diff --git a/man/bMCTtest.Rd b/man/bMCTtest.Rd index e7bf38d..c1655fc 100644 --- a/man/bMCTtest.Rd +++ b/man/bMCTtest.Rd @@ -26,13 +26,13 @@ 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{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}} and Pinheiro et al. (2014).} +directly in \samp{resp}, \samp{S} and \samp{df}. See also \code{\link[=fitMod]{fitMod()}} and Pinheiro et al. (2014).} \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 @@ -48,11 +48,11 @@ posterior mixture is part of the result object under "posterior".} \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.} +code, see also \code{\link[=mvtnorm.control]{mvtnorm.control()}} for details.} \item{contMat}{Contrast matrix to apply to the posterior dose-response estimates. The contrasts need to be in the columns of the matrix (i.e. the column sums need to be 0). If not specified optimal contrasts are calculated using -\code{\link{optContr}}.} +\code{\link[=optContr]{optContr()}}.} \item{critV}{Supply a critical value for the maximum posterior probability of the contrasts being greater than zero that needs to be surpassed to establish a non-flat dose-response. If this argument is NULL, this will be derived @@ -64,7 +64,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 -\code{\link{MCTtest}}. +\code{\link[=MCTtest]{MCTtest()}}. } \details{ If \samp{type = "normal"}, an ANCOVA model based on a homoscedastic normality assumption is fitted and posteriors for @@ -80,12 +80,12 @@ 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}}). Fleischer et al. (2022) discuss using contrasts that take the prior +the same way as in \code{\link[=MCTtest]{MCTtest()}}). Fleischer et al. (2022) 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. For analysis with covariate adjustment, covariate-adjusted \samp{resp} and \samp{S} can be supplied together with -using \samp{type = "general"}. See `vignette("binary_data")` vignette "Design and analysis template MCP-Mod for binary data" for an example +using \samp{type = "general"}. See \code{vignette("binary_data")} vignette "Design and analysis template MCP-Mod for binary data" for an example on how to obtain covariate adjusted estimates. } \examples{ @@ -193,10 +193,10 @@ 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}, \bold{21}, 654--670 +\emph{Pharmaceutical Statistics}, \strong{21}, 654--670 } \seealso{ -\code{\link{MCTtest}}, \code{\link{optContr}} +\code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}} } \author{ Marius Thomas diff --git a/man/biom.Rd b/man/biom.Rd index b64c463..f1c43ea 100644 --- a/man/biom.Rd +++ b/man/biom.Rd @@ -6,15 +6,15 @@ \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} +\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}, \bold{61}, 738--748 +\emph{Biometrics}, \strong{61}, 738--748 } \usage{ data(biom) diff --git a/man/critVal.Rd b/man/critVal.Rd index 3cc26ce..be9200d 100644 --- a/man/critVal.Rd +++ b/man/critVal.Rd @@ -23,7 +23,7 @@ corresponds to the multivariate normal distribution).} \item{alternative}{Character determining the alternative for the multiple contrast trend test.} \item{control}{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.} +see also \code{\link[=mvtnorm.control]{mvtnorm.control()}} for details.} } \description{ Calculation of the critical value for a maximum contrast test. This is based on the equicoordinate quantile function @@ -38,7 +38,7 @@ critVal(R, alpha = 0.05, df = Inf) } \seealso{ -\code{\link{powMCT}}, \code{\link{optContr}}, \code{\link{MCTtest}} +\code{\link[=powMCT]{powMCT()}}, \code{\link[=optContr]{optContr()}}, \code{\link[=MCTtest]{MCTtest()}} } \author{ Bjoern Bornkamp diff --git a/man/drmodels.Rd b/man/drmodels.Rd index 8587171..09c92e9 100644 --- a/man/drmodels.Rd +++ b/man/drmodels.Rd @@ -101,19 +101,19 @@ Dose-response model functions and gradients. Below are the definitions of the model functions: -\bold{Emax model} \deqn{}{f(d,theta)=E0+Emax d/(ED50 + d).}\deqn{ +\strong{Emax model} \deqn{}{f(d,theta)=E0+Emax d/(ED50 + d).}\deqn{ f(d,\theta)=E_0+E_{max}\frac{d}{ED_{50}+d}}{f(d,theta)=E0+Emax d/(ED50 + d).} -\bold{Sigmoid Emax Model} \deqn{}{f(d,theta)=E0+Emax d^h/(ED50^h + +\strong{Sigmoid Emax Model} \deqn{}{f(d,theta)=E0+Emax d^h/(ED50^h + d^h).}\deqn{ f(d,\theta)=E_0+E_{max}\frac{d^h}{ED^h_{50}+d^h}}{f(d,theta)=E0+Emax d^h/(ED50^h + d^h).} -\bold{Exponential Model} \deqn{}{f(d,theta)=E0+E1 (exp(d/delta)-1).}\deqn{ +\strong{Exponential Model} \deqn{}{f(d,theta)=E0+E1 (exp(d/delta)-1).}\deqn{ f(d,\theta)=E_0+E_1(\exp(d/\delta)-1)}{f(d,theta)=E0+E1 (exp(d/delta)-1).} -\bold{Beta model} \deqn{}{f(d,theta)=E0+Emax +\strong{Beta model} \deqn{}{f(d,theta)=E0+Emax B(delta1,delta2)(d/scal)^delta1(1-d/scal)^delta2}\deqn{ f(d,\theta)=E_0+E_{max}B(\delta_1,\delta_2)(d/scal)^{\delta_1}(1-d/scal)^{\delta_2} }{f(d,theta)=E0+Emax B(delta1,delta2)(d/scal)^delta1(1-d/scal)^delta2} @@ -124,49 +124,49 @@ delta2^delta2).}\deqn{ \delta_2^{\delta_2})}{B(delta1,delta2)=(delta1+delta2)^(delta1+delta2)/(delta1^delta1 delta2^delta2).} and \eqn{scal}{scal} is a fixed dose scaling parameter. -\bold{Linear Model} \deqn{}{f(d,theta)=E0+delta d.}\deqn{ +\strong{Linear Model} \deqn{}{f(d,theta)=E0+delta d.}\deqn{ f(d,\theta)=E_0+\delta d}{f(d,theta)=E0+delta d.} -\bold{Linear in log Model} \deqn{}{f(d,theta)=E0+delta log(d + off),}\deqn{ +\strong{Linear in log Model} \deqn{}{f(d,theta)=E0+delta log(d + off),}\deqn{ f(d,\theta)=E_0+\delta \log(d + off)}{f(d,theta)=E0+delta log(d + off),} here \eqn{off}{off} is a fixed offset parameter. -\bold{Logistic Model} \deqn{ +\strong{Logistic Model} \deqn{ f(d, \theta) = E_0 + E_{\max}/\left\{1 + \exp\left[ \left(ED_{50} - d \right)/\delta \right] \right\}}{f(d,theta)=E0+Emax/(1 + exp((ED50-d)/delta)).} -\bold{Quadratic Model} \deqn{}{f(d,theta)=E0+beta1 d+beta2 d^2.}\deqn{ +\strong{Quadratic Model} \deqn{}{f(d,theta)=E0+beta1 d+beta2 d^2.}\deqn{ f(d,\theta)=E_0+\beta_1d+\beta_2d^2}{f(d,theta)=E0+beta1 d+beta2 d^2.} The standardized model equation for the quadratic model is \eqn{d+\delta d^2}{d+delta d^2}, with \eqn{\delta=\beta_2/\beta_1}{delta=beta2/beta1}. -\bold{Linear Interpolation model}\cr The linInt model provides linear +\strong{Linear Interpolation model}\cr The linInt model provides linear interpolation at the values defined by the nodes vector. In virtually all situations the nodes vector is equal to the doses used in the analysis. For -example the \code{\link{Mods}} and the \code{\link{fitMod}} function +example the \code{\link[=Mods]{Mods()}} and the \code{\link[=fitMod]{fitMod()}} function automatically use the doses that are used in the context of the function -call as nodes. The guesstimates specified in the \code{\link{Mods}} function +call as nodes. The guesstimates specified in the \code{\link[=Mods]{Mods()}} function need to be the treatment effects at the active doses standardized to the -interval [0,1] (see the examples in the \code{\link{Mods}} function). +interval [0,1] (see the examples in the \code{\link[=Mods]{Mods()}} function). } \details{ -The \bold{Emax model} is used to represent monotone, concave dose-response +The \strong{Emax model} is used to represent monotone, concave dose-response shapes. To distinguish it from the more general sigmoid emax model it is sometimes also called hyperbolic emax model. -The \bold{sigmoid Emax} model is an extension of the (hyperbolic) Emax model +The \strong{sigmoid Emax} model is an extension of the (hyperbolic) Emax model by introducing an additional parameter h, that determines the steepness of the curve at the ed50 value. The sigmoid Emax model describes monotonic, sigmoid dose-response relationships. In the toxicology literature this model is also called four-parameter log-logistic (4pLL) model. -The \bold{quadratic} model is intended to capture a possible non-monotonic +The \strong{quadratic} model is intended to capture a possible non-monotonic dose-response relationship. -The \bold{exponential model} is intended to capture a possible sub-linear or +The \strong{exponential model} is intended to capture a possible sub-linear or a convex dose-response relationship. -The \bold{beta model} is intended to capture non-monotone dose-response +The \strong{beta model} is intended to capture non-monotone dose-response relationships and is more flexible than the quadratic model. The kernel of the beta model function consists of the kernel of the density function of a beta distribution on the interval [0,scal]. The parameter scal is not @@ -176,19 +176,19 @@ can be set in most functions (\samp{fitMod}, \samp{Mods}) via the is used as default, where the maximum dose is inferred from other input to the respective function. -The \bold{linear in log-dose} model is intended to capture concave shapes. +The \strong{linear in log-dose} model is intended to capture concave shapes. The parameter \code{off} is not estimated in the code but set to a pre-specified value. It can be set in most functions (\samp{fitMod}, \samp{Mods}) via the \samp{addArgs} argument, when omitted a value of \samp{0.01*(maximum dose)} is used as default, where the maximum dose is inferred from other input to the respective function. -The \bold{logistic model} is intended to capture general monotone, sigmoid +The \strong{logistic model} is intended to capture general monotone, sigmoid dose-response relationships. The logistic model and the sigmoid Emax model are closely related: The sigmoid Emax model is a logistic model in log(dose). -The \bold{linInt model} provids linear interpolation of the means at the +The \strong{linInt model} provids linear interpolation of the means at the doses. This can be used as a "nonparametric" estimate of the dose-response curve, but is probably most interesting for specifying a "nonparametric" truth during planning and assess how well parametric models work under a @@ -248,5 +248,5 @@ studies - modeling approaches, \emph{in} N. Ting (ed.). \emph{Dose Finding in Drug Development}, Springer, New York, pp. 146--171 } \seealso{ -\code{\link{fitMod}} +\code{\link[=fitMod]{fitMod()}} } diff --git a/man/fitMod.Rd b/man/fitMod.Rd index a5a40c2..0089dca 100644 --- a/man/fitMod.Rd +++ b/man/fitMod.Rd @@ -81,14 +81,14 @@ directly in \samp{resp}, \samp{S} and \samp{df}. See also the Description above \item{placAdj}{Logical, if true, it is assumed that placebo-adjusted estimates are specified in \samp{resp} (only possible for \samp{type = -"general"}).} + "general"}).} -\item{bnds}{Bounds for non-linear parameters. If missing the the default bounds from \code{\link{defBnds}} is used. +\item{bnds}{Bounds for non-linear parameters. If missing the the default bounds from \code{\link[=defBnds]{defBnds()}} is used. - When the dose-response model has only one non-linear parameter (for example Emax or exponential model), \samp{bnds} - needs to be a vector containing upper and lower bound. For models with two non-linear parameters \samp{bnds} needs - to be a matrix containing the bounds in the rows, see the Description section of \code{\link{defBnds}} for details - on the formatting of the bounds for the individual models.} +When the dose-response model has only one non-linear parameter (for example Emax or exponential model), \samp{bnds} +needs to be a vector containing upper and lower bound. For models with two non-linear parameters \samp{bnds} needs +to be a matrix containing the bounds in the rows, see the Description section of \code{\link[=defBnds]{defBnds()}} for details +on the formatting of the bounds for the individual models.} \item{df}{Degrees of freedom to use in case of \samp{type = "general"}. If this argument is missing \samp{df = Inf} is used. For \samp{type = "normal"} this argument is ignored as the exact degrees of freedom can be deduced from @@ -101,14 +101,14 @@ a grid optimization is performed and the best value is used as starting value fo \item{control}{A list with entries: "nlminbcontrol", "optimizetol" and "gridSize". - The entry nlminbcontrol needs to be a list and it is passed directly to control argument in the nlminb function, - that is used internally for models with 2 nonlinear parameters. +The entry nlminbcontrol needs to be a list and it is passed directly to control argument in the nlminb function, +that is used internally for models with 2 nonlinear parameters. - The entry optimizetol is passed directly to the tol argument of the optimize function, which is used for models - with 1 nonlinear parameters. +The entry optimizetol is passed directly to the tol argument of the optimize function, which is used for models +with 1 nonlinear parameters. - 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.} +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{addArgs}{List containing two entries named "scal" and "off" for the "betaMod" and "linlog" model. When addArgs is NULL the following defaults is used \samp{list(scal = 1.2*max(doses), off = 0.01*max(doses))}.} @@ -121,31 +121,31 @@ is NULL the following defaults is used \samp{list(scal = 1.2*max(doses), off = 0 ignored.} \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). +(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 predType = "full-model"), if missing the - covariates used for fitting are used. +newdata gives the covariates to use in producing the predictions (for predType = "full-model"), if missing the +covariates used for fitting are used. - doseSeq dose-sequence on where to produce predictions (for predType = "effect-curve" and predType = "ls-means"). If - missing the doses used for fitting are used. +doseSeq dose-sequence on where to produce predictions (for predType = "effect-curve" and predType = "ls-means"). If +missing the doses used for fitting are used. - se.fit: logical determining, whether the standard error should be calculated.} +se.fit: logical determining, whether the standard error should be calculated.} \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. + "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{k}{Penalty to use for model-selection criterion (AIC uses 2, BIC uses log(n)).} } \value{ An object of class DRMod. Essentially a list containing information about the fitted model coefficients, the - residual sum of squares (or generalized residual sum of squares), +residual sum of squares (or generalized residual sum of squares), } \description{ Fits a dose-response model. Built-in dose-response models are "linlog", "linear", "quadratic", "emax", "exponential", -"sigEmax", "betaMod" and "logistic" (see \code{\link{drmodels}}). +"sigEmax", "betaMod" and "logistic" (see \code{\link[=drmodels]{drmodels()}}). } \details{ When \samp{type = "normal"} ordinary least squares is used and additional additive covariates can be specified in @@ -167,8 +167,8 @@ For details on the implemented numerical optimizer see the Details section below Details on numerical optimizer for model-fitting:\cr For linear models fitting is done using numerical linear algebra based on the QR decomposition. For nonlinear models numerical optimization is performed only in the nonlinear parameters in the model and optimizing over the linear parameters in each iteration (similar as the Golub-Pereyra -implemented in \code{\link{nls}}). For models with 1 nonlinear parameter the \code{\link{optimize}} function is used -for 2 nonlinear parameters the \code{\link{nlminb}} function is used. The starting value is generated using a +implemented in \code{\link[=nls]{nls()}}). For models with 1 nonlinear parameter the \code{\link[=optimize]{optimize()}} function is used +for 2 nonlinear parameters the \code{\link[=nlminb]{nlminb()}} function is used. The starting value is generated using a grid-search (with the grid size specified via \samp{control$gridSize}), or can directly be handed over via \samp{start}. @@ -252,12 +252,12 @@ 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}, \bold{33}, 1646--1661 +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. +Seber, G.A.F. and Wild, C.J. (2003). Nonlinear Regression, Wiley. } \seealso{ -\code{\link{defBnds}}, \code{\link{drmodels}} +\code{\link[=defBnds]{defBnds()}}, \code{\link[=drmodels]{drmodels()}} } \author{ Bjoern Bornkamp diff --git a/man/glycobrom.Rd b/man/glycobrom.Rd index dbbe497..ed427da 100644 --- a/man/glycobrom.Rd +++ b/man/glycobrom.Rd @@ -6,15 +6,15 @@ \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} - } +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 diff --git a/man/guesst.Rd b/man/guesst.Rd index d65bdf5..7067b19 100644 --- a/man/guesst.Rd +++ b/man/guesst.Rd @@ -45,7 +45,7 @@ Calculates guesstimates for standardized model parameter(s) using the general ap \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}} function to ensure that the guesstimates are reflecting the prior beliefs. +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. @@ -126,12 +126,12 @@ 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}, \bold{29}(7), 1--23 +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 +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}}, \code{\link{logistic}}, \code{\link{betaMod}}, \code{\link{sigEmax}}, - \code{\link{quadratic}}, \code{\link{exponential}}, \code{\link{plot.Mods}} +\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 b8d7b65..212e7e8 100644 --- a/man/maFitMod.Rd +++ b/man/maFitMod.Rd @@ -6,7 +6,7 @@ \alias{plot.maFit} \alias{print.maFit} \title{Fit dose-response models via bootstrap model - averaging (bagging)} +averaging (bagging)} \usage{ maFitMod(dose, resp, S, models, nSim = 1000, control, bnds, addArgs = NULL) @@ -43,18 +43,18 @@ estimate specified via \code{resp}} \item{nSim}{Number of bootstrap simulations} \item{control}{Same as the control argument in -\code{\link{fitMod}}.} +\code{\link[=fitMod]{fitMod()}}.} \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 +names. The \code{\link[=defBnds]{defBnds()}} function provides the default selection.} \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))}} + = 0.01*max(doses))}} \item{object}{Object of class maFit} @@ -91,8 +91,8 @@ scale). The default for \samp{trafo} is the identity function.} } \value{ An object of class \samp{maFit}, which contains the fitted - dose-response models \samp{DRMod} objects, information on which model - was selected in each bootstrap and basic input parameters. +dose-response models \samp{DRMod} objects, information on which model +was selected in each bootstrap and basic input parameters. } \description{ This function fits dose-response models in a bootstrap model @@ -120,7 +120,7 @@ ED(mFit, direction = "increasing", p = 0.9) Breiman, L. (1996). Bagging predictors. Machine learning, 24, 123-140. } \seealso{ -\code{\link{fitMod}}, \code{\link{bFitMod}}, \code{\link{drmodels}} +\code{\link[=fitMod]{fitMod()}}, \code{\link[=bFitMod]{bFitMod()}}, \code{\link[=drmodels]{drmodels()}} } \author{ Bjoern Bornkamp diff --git a/man/migraine.Rd b/man/migraine.Rd index 3a665e0..f5c8fb5 100644 --- a/man/migraine.Rd +++ b/man/migraine.Rd @@ -6,12 +6,12 @@ \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} - } +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 diff --git a/man/neurodeg.Rd b/man/neurodeg.Rd index 094049e..c5a6962 100644 --- a/man/neurodeg.Rd +++ b/man/neurodeg.Rd @@ -6,17 +6,17 @@ \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} - } +\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}, \bold{33}, 1646--1661 +models, \emph{Statistics in Medicine}, \strong{33}, 1646--1661 } \usage{ data(neurodeg) diff --git a/man/optContr.Rd b/man/optContr.Rd index 0bf5041..fe8792e 100644 --- a/man/optContr.Rd +++ b/man/optContr.Rd @@ -78,13 +78,13 @@ non-centrality parameter of the underlying contrast test statistic: 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),} +{1^\prime S^{-1} 1}\right),}{c propto S^(-1) (mu - mu'S^(-1)1)/(1'S^(-1)1),} see Pinheiro et al. (2014). } \details{ Note that the directionality (i.e. whether in "increase" in the response variable is beneficial or a "decrease", is inferred from the specified -\samp{models} object, see \code{\link{Mods}} for details). +\samp{models} object, see \code{\link[=Mods]{Mods()}} for details). Constrained contrasts (type = "constrained") add the additional constraint in the optimization that the sign of the contrast coefficient for control @@ -125,14 +125,14 @@ 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}, \bold{61}, 738--748 +\emph{Biometrics}, \strong{61}, 738--748 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 +\emph{Statistics in Medicine}, \strong{33}, 1646--1661 } \seealso{ -\code{\link{MCTtest}} +\code{\link[=MCTtest]{MCTtest()}} } \author{ Bjoern Bornkamp diff --git a/man/optDesign.Rd b/man/optDesign.Rd index 4d19fd4..59a5946 100644 --- a/man/optDesign.Rd +++ b/man/optDesign.Rd @@ -43,7 +43,7 @@ rndDesign(design, n, eps = 1e-04) \method{plot}{DRdesign}(x, models, lwdDes = 10, colDes = rgb(0, 0, 0, 0.3), ...) } \arguments{ -\item{models}{An object of class \samp{c(Mods, fullMod)}, see the \code{\link{Mods}} function for details. When an TD +\item{models}{An object of class \samp{c(Mods, fullMod)}, see the \code{\link[=Mods]{Mods()}} function for details. When an TD optimal design should be calculated, the TD needs to exist for all models. If a D-optimal design should be calculated, you need at least as many doses as there are parameters in the specified models.} @@ -68,47 +68,47 @@ standardization this is done in the optimal design literature).} situations.} \item{nold, n}{When calculating an optimal design at an interim analysis, \samp{nold} specifies the vector of sample - sizes already allocated to the different doses, and \samp{n} gives sample size for the next cohort. +sizes already allocated to the different doses, and \samp{n} gives sample size for the next cohort. - For \samp{optimizer = "exact"} one always needs to specify the total sample size via \samp{n}.} +For \samp{optimizer = "exact"} one always needs to specify the total sample size via \samp{n}.} \item{control}{List containing control parameters passed down to numerical optimization algorithms - (\code{\link{optim}}, \code{\link{nlminb}} or solnp function).\cr +(\code{\link[=optim]{optim()}}, \code{\link[=nlminb]{nlminb()}} or solnp function).\cr - For \samp{type = "exact"} this should be a list with possible entries \samp{maxvls1} and \samp{maxvls2}, - determining the maximum number of designs allowed for passing to the criterion function (default - \samp{maxvls2=1e5}) and for creating the initial unrestricted matrix of designs (default \samp{maxvls1=1e6}). In - addition there can be an entry \samp{groupSize} in case the patients are allocated a minimum group size is - required.} +For \samp{type = "exact"} this should be a list with possible entries \samp{maxvls1} and \samp{maxvls2}, +determining the maximum number of designs allowed for passing to the criterion function (default +\samp{maxvls2=1e5}) and for creating the initial unrestricted matrix of designs (default \samp{maxvls1=1e6}). In +addition there can be an entry \samp{groupSize} in case the patients are allocated a minimum group size is +required.} \item{optimizer}{Algorithm used for calculating the optimal design. Options "Nelder-Mead" and "nlminb" use the - \code{\link{optim}} and \code{\link{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). +\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). - Option "solnp" uses the solnp function from the Rsolnp package, which implements an optimizer for non-linear - optimization under general constraints. +Option "solnp" uses the solnp function from the Rsolnp package, which implements an optimizer for non-linear +optimization under general constraints. - Option "exact" tries all given combinations of \samp{n} patients to the given dose groups (subject to the bounds - specified via \samp{lowbnd} and \samp{uppbnd}) and reports the best design. When patients are only allowed to be - allocated in groups of a certain \samp{groupSize}, this can be adjusted via the control argument. - \samp{n/groupSize} and \samp{length(doses)} should be rather small for this approach to be feasible. +Option "exact" tries all given combinations of \samp{n} patients to the given dose groups (subject to the bounds +specified via \samp{lowbnd} and \samp{uppbnd}) and reports the best design. When patients are only allowed to be +allocated in groups of a certain \samp{groupSize}, this can be adjusted via the control argument. +\samp{n/groupSize} and \samp{length(doses)} should be rather small for this approach to be feasible. - When the number of doses is small (<8) usually \samp{"Nelder-Mead"} and \samp{"nlminb"} are best suited - (\samp{"nlminb"} is usually a bit faster but less stable than \samp{"Nelder-Mead"}). For a larger number of doses - \samp{"solnp"} is the most reliable option (but also slowest) (\samp{"Nelder-Mead"} and \samp{"nlminb"} often - fail). When the sample size is small \samp{"exact"} provides the optimal solution rather quickly.} +When the number of doses is small (<8) usually \samp{"Nelder-Mead"} and \samp{"nlminb"} are best suited +(\samp{"nlminb"} is usually a bit faster but less stable than \samp{"Nelder-Mead"}). For a larger number of doses +\samp{"solnp"} is the most reliable option (but also slowest) (\samp{"Nelder-Mead"} and \samp{"nlminb"} often +fail). When the sample size is small \samp{"exact"} provides the optimal solution rather quickly.} \item{lowbnd, uppbnd}{Vectors of the same length as dose vector specifying upper and lower limits for the allocation weights. This option is only available when using the "solnp" and "exact" optimizers.} \item{userCrit}{User defined design criterion, should be a function that given a vector of allocation weights and the - doses returns the criterion function. When specified \samp{models} does not need to be handed over. +doses returns the criterion function. When specified \samp{models} does not need to be handed over. - The first argument of \samp{userCrit} should be the vector of design weights, while the second argument should be - the \samp{doses} argument (see example below). Additional arguments to \samp{userCrit} can be passed via ...} +The first argument of \samp{userCrit} should be the vector of design weights, while the second argument should be +the \samp{doses} argument (see example below). Additional arguments to \samp{userCrit} can be passed via ...} \item{...}{For function \samp{optDesign} these are additional arguments passed to \samp{userCrit}.\cr \cr For -function \samp{plot.design} these are additional parameters passed to \code{\link{plot.Mods}}.\cr} +function \samp{plot.design} these are additional parameters passed to \code{\link[=plot.Mods]{plot.Mods()}}.\cr} \item{design}{Argument for \samp{rndDesign} and \samp{calcCrit} functions: Numeric vector (or matrix) of allocation weights for the different doses. The rows of the matrices need to sum to 1. Alternatively also an object of class @@ -159,8 +159,8 @@ For details on the \samp{rndDesign} function, see Pukelsheim (1993), 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 - a larger number of iterations in the algorithm (via the argument \samp{control}), particularly for the Nelder-Mead - algorithm. Alternatively one can use the solnp optimizer that is usually the most reliable, but not fastest option. +a larger number of iterations in the algorithm (via the argument \samp{control}), particularly for the Nelder-Mead +algorithm. Alternatively one can use the solnp optimizer that is usually the most reliable, but not fastest option. } \examples{ @@ -251,20 +251,20 @@ optDesign(doses = c(0,0.05,0.2,0.6,1), } \references{ Atkinson, A.C., Donev, A.N. and Tobias, R.D. (2007). Optimum Experimental Designs, with SAS, Oxford - University Press +University Press - Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal +Dette, H., Bretz, F., Pepelyshev, A. and Pinheiro, J. C. (2008). Optimal Designs for Dose Finding Studies, \emph{Journal of the American Statisical -Association}, \bold{103}, 1225--1237 +Association}, \strong{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 +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 +Pukelsheim, F. (1993). Optimal Design of Experiments, Wiley } \seealso{ -\code{\link{Mods}}, \code{\link{drmodels}} +\code{\link[=Mods]{Mods()}}, \code{\link[=drmodels]{drmodels()}} } \author{ Bjoern Bornkamp diff --git a/man/planMod.Rd b/man/planMod.Rd index 29149f8..e7d60b3 100644 --- a/man/planMod.Rd +++ b/man/planMod.Rd @@ -58,13 +58,13 @@ one dose-response model is provided the best fitting model is chosen using the A should be calculated.} \item{n, sigma, S}{Either a vector \samp{n} and \samp{sigma} or \samp{S} need to be specified. When \samp{n} and - \samp{sigma} are specified it is assumed computations are made for a normal homoscedastic ANOVA model with group - sample sizes given by \samp{n} and residual standard deviation \samp{sigma}, i.e. the covariance matrix used for - the estimates is thus \code{sigma^2*diag(1/n)} and the degrees of freedom are calculated as - \code{sum(n)-nrow(contMat)}. When a single number is specified for \samp{n} it is assumed this is the sample size - per group and balanced allocations are used.\cr +\samp{sigma} are specified it is assumed computations are made for a normal homoscedastic ANOVA model with group +sample sizes given by \samp{n} and residual standard deviation \samp{sigma}, i.e. the covariance matrix used for +the estimates is thus \code{sigma^2*diag(1/n)} and the degrees of freedom are calculated as +\code{sum(n)-nrow(contMat)}. When a single number is specified for \samp{n} it is assumed this is the sample size +per group and balanced allocations are used.\cr - When \samp{S} is specified this will be used as covariance matrix for the estimates.} +When \samp{S} is specified this will be used as covariance matrix for the estimates.} \item{doses}{Doses to use} @@ -86,10 +86,10 @@ effect Windows, as the mclapply function is used internally.} \item{showSimProgress}{In case of simulations show the progress using a progress-bar.} \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 +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{addArgs}{See the corresponding argument in function \code{\link{fitMod}}. This argument is directly passed to +\item{addArgs}{See the corresponding argument in function \code{\link[=fitMod]{fitMod()}}. This argument is directly passed to fitMod.} \item{object, digits}{object: A planMod object. digits: Digits in summary output} @@ -175,7 +175,7 @@ plot(pObj, type = "ED", p = 0.5) TBD } \seealso{ -\code{\link{fitMod}} +\code{\link[=fitMod]{fitMod()}} } \author{ Bjoern Bornkamp diff --git a/man/powMCT.Rd b/man/powMCT.Rd index 90009a0..174322c 100644 --- a/man/powMCT.Rd +++ b/man/powMCT.Rd @@ -43,7 +43,7 @@ estimates.} \item{placAdj}{Logical, if true, it is assumed that the standard deviation or variance matrix of the placebo-adjusted estimates are specified in \samp{sigma} or \samp{S}, respectively. The contrast matrix has to be -produced on placebo-adjusted scale, see \code{\link{optContr}}, so that the +produced on placebo-adjusted scale, see \code{\link[=optContr]{optContr()}}, so that the coefficients are no longer contrasts (i.e. do not sum to 0).} \item{alternative}{Character determining the alternative for the multiple @@ -116,12 +116,12 @@ 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}, \bold{16}, +procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{16}, 639--656 } \seealso{ -\code{\link{powN}}, \code{\link{sampSizeMCT}}, -\code{\link{MCTtest}}, \code{\link{optContr}}, \code{\link{Mods}} +\code{\link[=powN]{powN()}}, \code{\link[=sampSizeMCT]{sampSizeMCT()}}, +\code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}}, \code{\link[=Mods]{Mods()}} } \author{ Bjoern Bornkamp diff --git a/man/powMCTInterim.Rd b/man/powMCTInterim.Rd index 2fee1bd..506c081 100644 --- a/man/powMCTInterim.Rd +++ b/man/powMCTInterim.Rd @@ -96,5 +96,5 @@ Bornkamp, B., Zhou, J., Xi, D. and Cao W. (2025). Futility analyses for the MCP- on longitudinal models, \emph{arXiv:2406.19965} } \seealso{ -\code{\link{powMCT}} \code{\link{MCTtest}}, \code{\link{optContr}} +\code{\link[=powMCT]{powMCT()}} \code{\link[=MCTtest]{MCTtest()}}, \code{\link[=optContr]{optContr()}} } diff --git a/man/sampSize.Rd b/man/sampSize.Rd index e120529..3fb8df9 100644 --- a/man/sampSize.Rd +++ b/man/sampSize.Rd @@ -77,7 +77,7 @@ size is iterated in bisection search algorithm.} \item{verbose}{Logical value indicating if a trace of the iteration progress of the bisection search algorithm should be displayed.} -\item{...}{Arguments directly passed to the \code{\link{powMCT}} function in the \samp{sampSizeMCT} and \samp{powN} +\item{...}{Arguments directly passed to the \code{\link[=powMCT]{powMCT()}} function in the \samp{sampSizeMCT} and \samp{powN} function.} \item{power, sumFct}{power is a numeric defining the desired summary power to achieve (in \samp{sampSizeMCT}).} @@ -164,15 +164,15 @@ 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}, \bold{16}, - 639--656 +combining multiple comparisons and modeling procedures, \emph{Journal of Biopharmaceutical Statistics}, \strong{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 +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 } \seealso{ -\code{\link{powMCT}} +\code{\link[=powMCT]{powMCT()}} } \author{ Jose Pinheiro, Bjoern Bornkamp diff --git a/man/targdose.Rd b/man/targdose.Rd index 264d670..b3fd8f7 100644 --- a/man/targdose.Rd +++ b/man/targdose.Rd @@ -4,8 +4,8 @@ \alias{Target doses} \alias{TD} \alias{ED} -\title{Calculate dose estimates for a fitted dose-response model (via \code{\link{fitMod}}, \code{\link{bFitMod}}) - or \code{\link{maFitMod}}) or a \code{\link{Mods}} object} +\title{Calculate dose estimates for a fitted dose-response model (via \code{\link[=fitMod]{fitMod()}}, \code{\link[=bFitMod]{bFitMod()}}) +or \code{\link[=maFitMod]{maFitMod()}}) or a \code{\link[=Mods]{Mods()}} object} \usage{ TD( object, @@ -85,8 +85,8 @@ ED(fmodels, p=0.5, EDtype = "discrete", doses=doses) plot(fmodels, plotTD = TRUE, Delta = 0.3) } \seealso{ -\code{\link{Mods}}, \code{\link{drmodels}}, -\code{\link{fitMod}}, \code{\link{bFitMod}} +\code{\link[=Mods]{Mods()}}, \code{\link[=drmodels]{drmodels()}}, +\code{\link[=fitMod]{fitMod()}}, \code{\link[=bFitMod]{bFitMod()}} } \author{ Bjoern Bornkamp