From cb4cf39ef75ca89ecdb587b5ba0b0c863745f760 Mon Sep 17 00:00:00 2001 From: sebastianbossert Date: Fri, 15 Dec 2023 14:19:09 +0000 Subject: [PATCH] Additional documentation around getContr and other functions --- R/BMCPMod.R | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/R/BMCPMod.R b/R/BMCPMod.R index 446ecc7..023d3c6 100644 --- a/R/BMCPMod.R +++ b/R/BMCPMod.R @@ -103,11 +103,22 @@ assessDesign <- function ( #' @title getContr #' -#' @description This function calculates contrast vectors that are optimal for detecting certain alternatives. More information and link to publication will be added. +#' @description 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 #' #' @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. Default NULL +#' @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 @@ -223,11 +234,11 @@ getCritProb <- function ( #' @title performBayesianMCPMod #' -#' @description performs bayesian MCP Test step and modelling. +#' @description performs bayesian MCP Test step and modelling in a combined fashion. See performBayesianMCP function for MCT Test step and getModelFits for the modelling step #' -#' @param posterior_list a getPosterior object +#' @param posterior_list a getPosterior object with information about the (mixture) posterior distribution per dose group #' @param contr a getContrMat object, contrast matrix to be used for the testing step. -#' @param crit_prob_adj a getCritProb object +#' @param crit_prob_adj a getCritProb object, specifying the critical value to be used for the testing (on the probability scale). #' @param simple boolean variable, defining whether simplified fit will be applied. Passed to the getModelFits function. Default FALSE. #' #' @return bmcpmod test result as well as modelling result. @@ -322,7 +333,8 @@ addSignificance <- function ( #' @title performBayesianMCP #' #' @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). #' #' @param posterior_list a getPosterior object with information about the (mixture) posterior distribution per dose group #' @param contr a getContrMat object, contrast matrix to be used for the testing step.