From 1700b38c72879ca310e8044f2617a7e34f32c5e4 Mon Sep 17 00:00:00 2001 From: sebastianbossert Date: Mon, 18 Dec 2023 15:01:04 +0000 Subject: [PATCH] Updates around documentation of functions and vignette. --- R/BMCPMod.R | 23 +++++++++++++++-------- R/bootstrapping.R | 11 +++++++++-- R/modelling.R | 12 +++++++++--- R/s3methods.R | 8 ++++---- man/getContr.Rd | 23 +++++++++++++++++------ man/getCritProb.Rd | 12 ++++++++++-- man/getModelFits.Rd | 13 ++++++++++--- man/performBayesianMCP.Rd | 5 +++-- man/performBayesianMCPMod.Rd | 6 +++--- vignettes/analysis_normal.Rmd | 14 +++++++++----- 10 files changed, 89 insertions(+), 38 deletions(-) diff --git a/R/BMCPMod.R b/R/BMCPMod.R index efeeede..ff7e72f 100644 --- a/R/BMCPMod.R +++ b/R/BMCPMod.R @@ -117,11 +117,11 @@ assessDesign <- function ( #' regular MCPMod for this specific vector of standard errors. For the actual evaluation this vector of standard errors is translated into a (diagonal) matrix of variances #' #' @param mods An object of class "Mods" as specified in the Dosefinding package. -#' @param dose_levels vector containing the different doseage levels. -#' @param dose_weights Vector specifying weights for the different doses. Please note that in case this information should be provided Default NULL -#' @param prior_list a prior_list object. Default NULL -#' @param sd_posterior a vector of positive numerics. Default NULL -#' @param se_new_trial a vector of positive numerics. Default NULL +#' @param dose_levels vector containing the different dosage levels. +#' @param dose_weights Vector specifying weights for the different doses. Please note that in case this information is provided together with a prior (i.e. Option i) is planned) these two inputs should be provided on the same scale (e.g. patient numbers). Default NULL +#' @param prior_list a prior_list object, only required as input for Option i). Default NULL +#' @param sd_posterior a vector of positive values with information about the variability of the posterior distribution, only required for Option iii). Default NULL +#' @param se_new_trial a vector of positive values with information about the observed variability, only required for Option iv). Default NULL #' #' @return contr Object of class ‘⁠optContr⁠’. A list containing entries contMat and muMat, and CorrMat. Specified in the Dosefinding package. #' @@ -196,11 +196,18 @@ getContr <- function ( #' @title getCritProb #' -#' @description This function calculates multiplicity adjusted +#' @description This function calculates multiplicity adjusted critical values. The critical values are calculated in such a way that +#' when using non-informative priors the actual error level for falsely declaring a significant trial in the Bayesian MCPMod is controlled (by the specified alpha level). +#' Hereby optimal contrasts of the frequentist MCPMod are applied and two options can be distinguished +#' i) Frequentist approach: If only dose_weights are provided optimal contrast vectors are calculated from the +#' regular MCPMod for these specific weights and the corresponding critical value for this set of contrasts is calculated via the critVal function of the DoseFinding package. +#' ii) Frequentist approach+re-estimation:If only a se_new_trial (i.e. the estimated variability per dose group of a new trial) is provided, optimal contrast vectors are calculated from the +#' regular MCPMod for this specific vector of standard errors. Here as well the critical value for this set of contrasts is calculated via the critVal function of the DoseFinding package. #' #' @param mods An object of class "Mods" as specified in the Dosefinding package. #' @param dose_levels vector containing the different dosage levels. -#' @param dose_weights Vector specifying weights for the different doses +#' @param dose_weights Vector specifying weights for the different doses, only required for Option i). Default NULL +#' @param se_new_trial a vector of positive values, only required for Option ii). Default NULL #' @param alpha_crit_val significance level. Default set to 0.025. #' #' @return crit_pval multiplicity adjusted critical value on the probability scale. @@ -339,7 +346,7 @@ addSignificance <- function ( #' @param contr a getContrMat object, contrast matrix to be used for the testing step. #' @param crit_prob_adj a getCritProb object, specifying the critical value to be used for the testing (on the probability scale) #' -#' @return b_mcp test result, with information about p-values for the individual dose-response shapes +#' @return b_mcp test result, with information about p-values for the individual dose-response shapes and overall significance #' #' @export performBayesianMCP <- function( diff --git a/R/bootstrapping.R b/R/bootstrapping.R index 0957703..2829637 100644 --- a/R/bootstrapping.R +++ b/R/bootstrapping.R @@ -1,7 +1,14 @@ #' @title getBootstrapQuantiles #' -#' @param model_fits tbd -#' @param quantiles tbd +#' @description A function to Calculate credible intervals to assess the uncertainty for the model fit. one can in addition visualize credible intervals (yellow shaded areas, the default is set to 50% and 95%). These credible intervals are calculated as follows. +#' Samples from the posterior distribution are drawn and for every sample the simplified fitting step and a prediction is performed. These fits are then used to identify and visualize the specified quantiles. +#' The bootstrap based quantiles can also directly be calculated and displayed via the gotbootstrapQuantiles function.dose-response curves for the specified dose-response models, based on the posterior distributions. +#' For the simplified fit, multivariate normal distributions will be approximated and reduced by one-dimensional normal distributions. +#' For the default case, the Nelder-Mead algorithm is used. +#' +#' +#' @param model_fits an object of class modelFits, i.e. information about fitted models & corresponding model coefficients as well as the posterior distribution that was the basis for the model fitting +#' @param quantiles a vector of quantiles that should be evaluated #' @param n_samples tbd #' @param doses tbd #' @param avg_fit tbd diff --git a/R/modelling.R b/R/modelling.R index 66f9302..343206d 100644 --- a/R/modelling.R +++ b/R/modelling.R @@ -2,14 +2,20 @@ #' #' @description Fits dose-response curves for the specified dose-response models, based on the posterior distributions. #' For the simplified fit, multivariate normal distributions will be approximated and reduced by one-dimensional normal distributions. -#' For the default case, the Nelder-Mead algorithm is used. Will be further updated and links to publication as well as references will be added. -#' +#' For the default case, the Nelder-Mead algorithm is used. +#' In detail, for both approaches the mean vector and the covariance $\Sigma_{l}^{-1}$ of the mixture posterior distributions and the corresponding posterior weights $\omega_{l}^{*}$ for $l \in {1,...,L}$ is used as basis +#' For the full fit a GLS estimator is used to minimize the following expression for the respective dose-response models $m$ +#' $$ +#' \hat{\theta}_{m}=argmin_{\theta_{m}} \sum_{i=l}^{L^{*}} \omega_{l}^{*}(\theta_{l_{i}}^{Y}-f(dose_{i},\hat{\theta}_{m}))'\Sigma_{l}^{-1}(\theta_{l_{i}}^{Y}-f(dose_{i},\hat{\theta}_{m})) +#' $$ +#' Herefore the function nloptr of the nloptr package is utilized. +#' In the simplified case $L=1$ as the dimension of the posterior is reduced to 1 first. #' @param models list of model names for which a fit will be performed. #' @param dose_levels a vector containing the different dosage levels. #' @param posterior a getPosterior object, containing the (multivariate) posterior distribution per dosage level. #' @param simple boolean variable, defining whether simplified fit will be applied. Default FALSE. #' -#' @return model_fits returns a list, containing information about the fitted model coefficients, the prediction per dose group as well as maximum effect and generalized AIC per model. +#' @return model_fits returns a list, containing information about the fitted model coefficients, the prediction per dose group as well as maximum effect and generalized AIC (and corresponding weight) per model. #' #' @export getModelFits <- function ( diff --git a/R/s3methods.R b/R/s3methods.R index f4cc5f0..1f704d2 100644 --- a/R/s3methods.R +++ b/R/s3methods.R @@ -36,12 +36,12 @@ print.BayesianMCPMod <- function ( cat("Model Significance Frequencies\n") print(model_success, ...) - if (!is.na(attr(x$BayesianMCP, "ess_avg"))) { +# if (!is.na(attr(x$BayesianMCP, "ess_avg"))) {#Note SB: I have taken this out, as vignettes didn't work - cat("Average Posterior ESS\n") - print(attr(x$BayesianMCP, "ess_avg"), ...) + # cat("Average Posterior ESS\n") + # print(attr(x$BayesianMCP, "ess_avg"), ...) - } + # } } diff --git a/man/getContr.Rd b/man/getContr.Rd index 809e932..647a75d 100644 --- a/man/getContr.Rd +++ b/man/getContr.Rd @@ -16,19 +16,30 @@ getContr( \arguments{ \item{mods}{An object of class "Mods" as specified in the Dosefinding package.} -\item{dose_levels}{vector containing the different doseage levels.} +\item{dose_levels}{vector containing the different dosage levels.} -\item{dose_weights}{Vector specifying weights for the different doses. Default NULL} +\item{dose_weights}{Vector specifying weights for the different doses. Please note that in case this information is provided together with a prior (i.e. Option i) is planned) these two inputs should be provided on the same scale (e.g. patient numbers). Default NULL} -\item{prior_list}{a prior_list object. Default NULL} +\item{prior_list}{a prior_list object, only required as input for Option i). Default NULL} -\item{sd_posterior}{a vector of positive numerics. Default NULL} +\item{sd_posterior}{a vector of positive values with information about the variability of the posterior distribution, only required for Option iii). Default NULL} -\item{se_new_trial}{a vector of positive numerics. Default NULL} +\item{se_new_trial}{a vector of positive values with information about the observed variability, only required for Option iv). Default NULL} } \value{ contr Object of class ‘⁠optContr⁠’. A list containing entries contMat and muMat, and CorrMat. Specified in the Dosefinding package. } \description{ -This function calculates contrast vectors that are optimal for detecting certain alternatives. More information and link to publication will be added. +This function calculates contrast vectors that are optimal for detecting certain alternatives via applying the function optContr of the DoseFinding package. +Hereby 4 different options can be distinguished that are automatically executed based on the input that is provided +i) Bayesian approach: If dose_weights and a prior_list are provided an optimized contrasts for the posterior sample size is calculated. +In detail, in a first step the dose_weights (typically the number of patients per dose group) and the prior information is combined by calculating for +each dose group a posterior effective sample. Based on this posterior effective sample sizes the allocation ratio is derived, which allows for a calculation on +pseudo-optimal contrasts via regular MCPMod.are calculated from the +regular MCPMod for these specific weights +ii) Frequentist approach: If only dose_weights are provided optimal contrast vectors are calculated from the +regular MCPMod for these specific weights +iii)Bayesian approach + re-estimation: If only a sd_posterior (i.e. variability of the posterior distribution) is provided, pseudo-optimal contrasts based on these posterior weights will be calculated +iv) Frequentist approach+re-estimation:If only a se_new_trial (i.e. the estimated variability per dose group of a new trial) is provided, optimal contrast vectors are calculated from the +regular MCPMod for this specific vector of standard errors. For the actual evaluation this vector of standard errors is translated into a (diagonal) matrix of variances } diff --git a/man/getCritProb.Rd b/man/getCritProb.Rd index fa648bd..e5f3335 100644 --- a/man/getCritProb.Rd +++ b/man/getCritProb.Rd @@ -17,7 +17,9 @@ getCritProb( \item{dose_levels}{vector containing the different dosage levels.} -\item{dose_weights}{Vector specifying weights for the different doses} +\item{dose_weights}{Vector specifying weights for the different doses, only required for Option i). Default NULL} + +\item{se_new_trial}{a vector of positive values, only required for Option ii). Default NULL} \item{alpha_crit_val}{significance level. Default set to 0.025.} } @@ -25,5 +27,11 @@ getCritProb( crit_pval multiplicity adjusted critical value on the probability scale. } \description{ -This function calculates multiplicity adjusted +This function calculates multiplicity adjusted critical values. The critical values are calculated in such a way that +when using non-informative priors the actual error level for falsely declaring a significant trial in the Bayesian MCPMod is controlled (by the specified alpha level). +Hereby optimal contrasts of the frequentist MCPMod are applied and two options can be distinguished +i) Frequentist approach: If only dose_weights are provided optimal contrast vectors are calculated from the +regular MCPMod for these specific weights and the corresponding critical value for this set of contrasts is calculated via the critVal function of the DoseFinding package. +ii) Frequentist approach+re-estimation:If only a se_new_trial (i.e. the estimated variability per dose group of a new trial) is provided, optimal contrast vectors are calculated from the +regular MCPMod for this specific vector of standard errors. Here as well the critical value for this set of contrasts is calculated via the critVal function of the DoseFinding package. } diff --git a/man/getModelFits.Rd b/man/getModelFits.Rd index 4a87f02..7292b80 100644 --- a/man/getModelFits.Rd +++ b/man/getModelFits.Rd @@ -16,10 +16,17 @@ getModelFits(models, dose_levels, posterior, simple = FALSE) \item{simple}{boolean variable, defining whether simplified fit will be applied. Default FALSE.} } \value{ -model_fits returns a list, containing information about the fitted model coefficients, the prediction per dose group as well as maximum effect and generalized AIC per model. +model_fits returns a list, containing information about the fitted model coefficients, the prediction per dose group as well as maximum effect and generalized AIC (and corresponding weight) per model. } \description{ -Fits dose-response curves for the specified dose-repsonse models, based on the posterior distributions. +Fits dose-response curves for the specified dose-response models, based on the posterior distributions. For the simplified fit, multivariate normal distributions will be approximated and reduced by one-dimensional normal distributions. -For the default case, the Nelder-Mead algorithm is used. Will be further updated and links to publication as well as references will be added. +For the default case, the Nelder-Mead algorithm is used. +In detail, for both approaches the mean vector and the covariance $\Sigma_{l}^{-1}$ of the mixture posterior distributions and the corresponding posterior weights $\omega_{l}^{\emph{}$ for $l \in {1,...,L}$ is used as basis +For the full fit a GLS estimator is used to minimize the following expression for the respective dose-response models $m$ +$$ +\hat{\theta}\emph{{m}=argmin}{\theta_{m}} \sum_{i=l}^{L^{}}} \omega_{l}^{*}(\theta_{l_{i}}^{Y}-f(dose_{i},\hat{\theta}\emph{{m}))'\Sigma}{l}^{-1}(\theta_{l_{i}}^{Y}-f(dose_{i},\hat{\theta}_{m})) +$$ +Herefore the function nloptr of the nloptr package is utilized. +In the simplified case $L=1$ as the dimension of the posterior is reduced to 1 first. } diff --git a/man/performBayesianMCP.Rd b/man/performBayesianMCP.Rd index 545bcc3..702a9c5 100644 --- a/man/performBayesianMCP.Rd +++ b/man/performBayesianMCP.Rd @@ -14,9 +14,10 @@ performBayesianMCP(posterior_list, contr, crit_prob_adj) \item{crit_prob_adj}{a getCritProb object, specifying the critical value to be used for the testing (on the probability scale)} } \value{ -b_mcp test result, with information about p-values for the individual dose-response shapes +b_mcp test result, with information about p-values for the individual dose-response shapes and overall significance } \description{ performs bayesian MCP Test step, as described in Fleischer et al. (Bayesian MCPMod. Pharmaceutical Statistics. 2022; 21(3): 654-670.) -Tests for a dose-response effect using a model-based multiple contrast test based on the (provided) posterior distribution. In particular for every dose-response candidate is calculated that the contrast is bigger than 0 given the data observed +Tests for a dose-response effect using a model-based multiple contrast test based on the (provided) posterior distribution. In particular for every dose-response candidate the posterior probability is calculated that the contrast is bigger than 0 (based on the posterior distribution of the dose groups). +In order to obtain significant test decision we consider the maximum of the posterior probabilities across the different models. This maximum is compared with a (multiplicity adjusted) critical value (on the probability scale). } diff --git a/man/performBayesianMCPMod.Rd b/man/performBayesianMCPMod.Rd index 6359109..58d7249 100644 --- a/man/performBayesianMCPMod.Rd +++ b/man/performBayesianMCPMod.Rd @@ -7,11 +7,11 @@ performBayesianMCPMod(posterior_list, contr, crit_prob_adj, simple = FALSE) } \arguments{ -\item{posterior_list}{a getPosterior object} +\item{posterior_list}{a getPosterior object with information about the (mixture) posterior distribution per dose group} \item{contr}{a getContrMat object, contrast matrix to be used for the testing step.} -\item{crit_prob_adj}{a getCritProb object} +\item{crit_prob_adj}{a getCritProb object, specifying the critical value to be used for the testing (on the probability scale).} \item{simple}{boolean variable, defining whether simplified fit will be applied. Passed to the getModelFits function. Default FALSE.} } @@ -19,5 +19,5 @@ performBayesianMCPMod(posterior_list, contr, crit_prob_adj, simple = FALSE) bmcpmod test result as well as modelling result. } \description{ -performs bayesian MCP Test step and modelling. +performs bayesian MCP Test step and modelling in a combined fashion. See performBayesianMCP function for MCT Test step and getModelFits for the modelling step } diff --git a/vignettes/analysis_normal.Rmd b/vignettes/analysis_normal.Rmd index c597fa2..d6863c5 100644 --- a/vignettes/analysis_normal.Rmd +++ b/vignettes/analysis_normal.Rmd @@ -285,12 +285,16 @@ getBootstrapQuantiles(fit, quantiles = c(0.025,0.5, 0.975), doses = c(0, 2.5,4, Technical note: The median quantile of the bootstrap based procedure is not necessary similar to the main model fit, as they are derived via different procedures (main fit, i.e. black lines in the plot, show the best fit of a certain model based on minimizing the residuals for the posterior distribution while bootstrap based 50% quantile indicates the median fit of the random sampling and fitting procedure). # Additional notes -It is also possible to perform the testing and modelling step in combined fashion via the performBayesianMCPMod function. +It is also possible to perform the testing and modelling step in a combined fashion via the performBayesianMCPMod function. + ```{r} -#performBayesianMCPMod( - # posterior_list = posterior, - # contr = contr_mat, - # crit_prob_adj = crit_pval) +overall_result<-performBayesianMCPMod( + posterior_list = posterior, + contr = contr_mat, + crit_prob_adj = crit_pval, + simple = FALSE) + +overall_result$Mod ```