diff --git a/BayesianMCPMod.Rproj b/BayesianMCPMod.Rproj index 8e3c2eb..21a4da0 100644 --- a/BayesianMCPMod.Rproj +++ b/BayesianMCPMod.Rproj @@ -11,3 +11,7 @@ Encoding: UTF-8 RnwWeave: Sweave LaTeX: pdfLaTeX + +BuildType: Package +PackageUseDevtools: Yes +PackageInstallArgs: --no-multiarch --with-keep.source diff --git a/DESCRIPTION b/DESCRIPTION index 8744241..8ec6c9b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: BayesianMCPMod Title: Bayesian MCPMod -Version: 0.1.3-2 +Version: 0.1.3-3 Authors@R: c( person("Sebastian", "Bossert", role = "aut", diff --git a/R/BMCPMod.R b/R/BMCPMod.R index 0a3f56c..66522e0 100644 --- a/R/BMCPMod.R +++ b/R/BMCPMod.R @@ -1,11 +1,13 @@ #' @title assessDesign -#' -#' @param n_patients tbd -#' @param mods tbd -#' @param prior_list tbd -#' @param n_sim tbd -#' @param alpha_crit_val tbd -#' @param simple tbd +#'. +#' @description This function performs simulation based trial design evaluations for a set of specified dose-response models +#' +#' @param n_patients Vector specifying the planned number of patients per dose group +#' @param mods An object of class "Mods" as specified in the Dosefinding package. +#' @param prior_list a prior_list object specifying the utilized prior for the different dose groups +#' @param n_sim number of simulations to be performed +#' @param alpha_crit_val 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. #' #' @export assessDesign <- function ( @@ -65,14 +67,18 @@ assessDesign <- function ( #' @title getContrMat #' -#' @param mods tbd -#' @param dose_levels tbd -#' @param dose_weights tbd -#' @param prior_list tbd +#' @description This function calculates contrast vectors that are optimal for detecting certain alternatives. More information and link to publication will be added. +#' +#' @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 +#' @param prior_list a prior_list object +#' +#' @return contr_mat Object of class ‘⁠optContr⁠’. A list containing entries contMat and muMat, and CorrMat. Specified in the Dosefinding package. #' #' @export getContrMat <- function ( - + mods, dose_levels, dose_weights, @@ -93,10 +99,12 @@ getContrMat <- function ( #' @title getCritProb #' -#' @param mods tbd -#' @param dose_levels tbd -#' @param dose_weights tbd -#' @param alpha_crit_val tbd +#' @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 alpha_crit_val significance level. Default set to 0.025. +#' +#' @return crit_pval multiplicity adjusted critical value on the probability scale. #' #' @export getCritProb <- function ( @@ -104,7 +112,7 @@ getCritProb <- function ( mods, dose_levels, dose_weights, - alpha_crit_val + alpha_crit_val = 0.025 ) { @@ -125,10 +133,14 @@ getCritProb <- function ( #' @title performBayesianMCPMod #' -#' @param posteriors_list tbd -#' @param contr_mat tbd -#' @param crit_prob tbd -#' @param simple tbd +#' @description performs bayesian MCP Test step and modelling. +#' +#' @param posteriors_list a getPosterior object +#' @param contr_mat a getContrMat object, contrast matrix to be used for the testing step. +#' @param crit_prob a getCritProb object +#' @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. #' #' @export performBayesianMCPMod <- function ( @@ -206,9 +218,13 @@ addSignificance <- function ( #' @title BayesianMCP #' -#' @param posteriors_list tbd -#' @param contr_mat tbd -#' @param crit_prob tbd +#' @description performs bayesian MCP Test step. +#' +#' @param posteriors_list a getPosterior object +#' @param contr_mat a getContrMat object, contrast matrix to be used for the testing step. +#' @param crit_prob a getCritProb object, specifying the critical value to be used for the testing (on the probability scale) +#' +#' @return b_mcp test result #' #' @export performBayesianMCP <- function( diff --git a/R/modelling.R b/R/modelling.R index 7895095..1328d24 100644 --- a/R/modelling.R +++ b/R/modelling.R @@ -1,9 +1,15 @@ #' @title getModelFits #' -#' @param models tbd -#' @param dose_levels tbd -#' @param posterior tbd -#' @param simple tbd +#' @description Fits dose-response curves for the specified dose-repsonse 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. +#' +#' @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. #' #' @export getModelFits <- function ( diff --git a/R/plot.R b/R/plot.R index 9f8278b..efd1a4a 100644 --- a/R/plot.R +++ b/R/plot.R @@ -1,17 +1,19 @@ #' @title plot.modelFits -#' -#' @param x tbd An object of type modelFits -#' @param gAIC tbd -#' @param avg_fit tbd -#' @param cr_intv tbd -#' @param alpha_CrI tbd -#' @param cr_bands tbd -#' @param alpha_CrB tbd -#' @param n_bs_smpl tbd -#' @param acc_color tbd -#' @param ... tbd #' -#' @return tbd +#' @description plot function based on the ggplot2 package. Providing visualizations for each model and a average Fit. +#' More details to be added, as well as references. +#' @param x an object of type getModelFits +#' @param gAIC logical value indicating whether gAIC values are shown in the plot. Default TRUE +#' @param avg_fit logical value indicating whether average fit is presented in the plot. Default TRUE +#' @param cr_intv logical value indicating whether credible intervals are included in the plot. Default TRUE +#' @param alpha_CrI numerical value of the width of the credible intervals. Default is set to 0.05 (i.e 95% CI are shown). +#' @param cr_bands logical value indicating whether bootstrapped based credible bands are shown in the plot. Default FALSE +#' @param alpha_CrB numerical vector of the width of the credible bands. Default is set to 0.05 and 0.5 (i.e 95% CB and median are shown). +#' @param n_bs_smpl number of bootstrap samples being used. Default set to 1000. +#' @param acc_color color of the credible bands. Default set to "orange" +#' @param ... optional parameter to be passed. +#' +#' @return plts returns a ggplot2 object #' @export plot.modelFits <- function ( diff --git a/R/posterior.R b/R/posterior.R index df37f5e..5c12d44 100644 --- a/R/posterior.R +++ b/R/posterior.R @@ -1,9 +1,14 @@ #' @title getPriorList #' -#' @param hist_data tbd -#' @param dose_levels tbd -#' @param dose_names prior_list -#' @param robustify_weight tbd +#' @param hist_data historical trial summary level data, +#' needs to be provided as a dataframe. Including information of the +#' estimates and variability. +#' @param dose_levels vector of the different doseage levels +#' @param dose_names character vector of dose levels, +#' default NULL and will be automatically created +#' based on the dose levels parameter. +#' @param robustify_weight Null needs to be provided as a numeric +#' value for the weight of the robustification component #' #' @export getPriorList <- function ( @@ -11,7 +16,7 @@ getPriorList <- function ( hist_data, dose_levels, dose_names = NULL, - robustify_weight = 0.5 + robustify_weight = NULL ) { @@ -28,6 +33,10 @@ getPriorList <- function ( prior_ctr <- RBesT::automixfit(gmap) + if(is.null(robustify_weight) | !is.numeric(robustify_weight)) { + stop("robustify_weight needs to be provided and must be numeric") + } + if (!is.null(robustify_weight)) { prior_ctr <- suppressMessages(RBesT::robustify( @@ -63,24 +72,32 @@ getPriorList <- function ( #' @title getPosterior #' -#' @param data tbd -#' @param prior_list prior_list -#' @param mu_hat tbd -#' @param sd_hat tbd +#' @description Either the patient level data or both the mu_hat as well as the sd_hat must to be provided. +#' +#' @param data dataframe containing the information of dose and response. +#' Also a simulateData object can be provided. +#' @param prior_list prior_list object +#' @param mu_hat vector of estimated mean values +#' @param sd_hat vector of estimated standard deviations. #' #' @export getPosterior <- function( - data, + data = NULL, prior_list, mu_hat = NULL, sd_hat = NULL ) { - + if (is.null(data)){ + posterior_list <-getPosteriorI(data_i=NULL, prior_list = prior_list, + mu_hat = mu_hat, + sd_hat = sd_hat) + }else{ posterior_list <- lapply(split(data, data$simulation), getPosteriorI, prior_list = prior_list, mu_hat = mu_hat, sd_hat = sd_hat) + } if (length(posterior_list) == 1) { diff --git a/R/simulation.R b/R/simulation.R index 7c60082..3eb16ab 100644 --- a/R/simulation.R +++ b/R/simulation.R @@ -1,11 +1,18 @@ #' @title simulateData #' -#' @param n_patients tbd -#' @param dose_levels tbd -#' @param sd tbd -#' @param mods tbd -#' @param n_sim tbd -#' @param true_model tbd +#' @param n_patients vector containing number of patients as a numerical +#' value per dose-group. +#' @param dose_levels vector containing the different doseage levels. +#' @param sd standard deviation on patient level. +#' @param mods An object of class "Mods" as specified in the Dosefinding package. +#' @param n_sim number of simulations to be performed, +#' Default is 1000 +#' @param true_model Default value is NULL. +#' Assumed true underlying model. Provided via a String. e.g. "emax". +#' In case of NULL, all dose-response models, included in the mods input parameter will be used. +#' +#' @return sim_data one list object, containing patient level simulated data for all assumed true models. +#' Also providing information about simulation iteration, patient number as well as dosage levels. #' #' @export simulateData <- function( diff --git a/man/getContrMat.Rd b/man/getContrMat.Rd index d5393e3..6040050 100644 --- a/man/getContrMat.Rd +++ b/man/getContrMat.Rd @@ -7,14 +7,17 @@ getContrMat(mods, dose_levels, dose_weights, prior_list) } \arguments{ -\item{mods}{tbd} +\item{mods}{An object of class "Mods" as specified in the Dosefinding package.} -\item{dose_levels}{tbd} +\item{dose_levels}{vector containing the different doseage levels.} -\item{dose_weights}{tbd} +\item{dose_weights}{Vector specifying weights for the different doses} -\item{prior_list}{tbd} +\item{prior_list}{a prior_list object} +} +\value{ +contr_mat Object of class ‘⁠optContr⁠’. A list containing entries contMat and muMat, and CorrMat. Specified in the Dosefinding package. } \description{ -getContrMat +This function calculates contrast vectors that are optimal for detecting certain alternatives. More information and link to publication will be added. } diff --git a/man/getCritProb.Rd b/man/getCritProb.Rd index eeb1b2c..21d3482 100644 --- a/man/getCritProb.Rd +++ b/man/getCritProb.Rd @@ -4,16 +4,19 @@ \alias{getCritProb} \title{getCritProb} \usage{ -getCritProb(mods, dose_levels, dose_weights, alpha_crit_val) +getCritProb(mods, dose_levels, dose_weights, alpha_crit_val = 0.025) } \arguments{ -\item{mods}{tbd} +\item{mods}{An object of class "Mods" as specified in the Dosefinding package.} -\item{dose_levels}{tbd} +\item{dose_levels}{vector containing the different doseage levels.} -\item{dose_weights}{tbd} +\item{dose_weights}{Vector specifying weights for the different doses} -\item{alpha_crit_val}{tbd} +\item{alpha_crit_val}{significance level. Default set to 0.025.} +} +\value{ +crit_pval multiplicity adjusted critical value on the probability scale. } \description{ getCritProb diff --git a/man/getModelFits.Rd b/man/getModelFits.Rd index f186384..4a87f02 100644 --- a/man/getModelFits.Rd +++ b/man/getModelFits.Rd @@ -7,14 +7,19 @@ getModelFits(models, dose_levels, posterior, simple = FALSE) } \arguments{ -\item{models}{tbd} +\item{models}{list of model names for which a fit will be performed.} -\item{dose_levels}{tbd} +\item{dose_levels}{a vector containing the different dosage levels.} -\item{posterior}{tbd} +\item{posterior}{a getPosterior object, containing the (multivariate) posterior distribution per dosage level.} -\item{simple}{tbd} +\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. } \description{ -getModelFits +Fits dose-response curves for the specified dose-repsonse 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. } diff --git a/man/getPosterior.Rd b/man/getPosterior.Rd index 501f5de..22ac81f 100644 --- a/man/getPosterior.Rd +++ b/man/getPosterior.Rd @@ -7,14 +7,15 @@ getPosterior(data, prior_list, mu_hat = NULL, sd_hat = NULL) } \arguments{ -\item{data}{tbd} +\item{data}{dataframe containing the information of dose and response. +Also a simulateData object can be provided.} -\item{prior_list}{prior_list} +\item{prior_list}{prior_list object} -\item{mu_hat}{tbd} +\item{mu_hat}{vector of estimated mean values} -\item{sd_hat}{tbd} +\item{sd_hat}{vector of estimated standard deviations.} } \description{ -getPosterior +Either the patient level data or both the mu_hat as well as the sd_hat must to be provided. } diff --git a/man/getPriorList.Rd b/man/getPriorList.Rd index bb7e346..7fe0937 100644 --- a/man/getPriorList.Rd +++ b/man/getPriorList.Rd @@ -4,16 +4,26 @@ \alias{getPriorList} \title{getPriorList} \usage{ -getPriorList(hist_data, dose_levels, dose_names = NULL, robustify_weight = 0.5) +getPriorList( + hist_data, + dose_levels, + dose_names = NULL, + robustify_weight = NULL +) } \arguments{ -\item{hist_data}{tbd} +\item{hist_data}{historical trial summary level data, +needs to be provided as a dataframe. Including information of the +estimates and variability.} -\item{dose_levels}{tbd} +\item{dose_levels}{vector of the different doseage levels} -\item{dose_names}{prior_list} +\item{dose_names}{character vector of dose levels, +default NULL and will be automatically created +based on the dose levels parameter.} -\item{robustify_weight}{tbd} +\item{robustify_weight}{Null needs to be provided as a numeric +value for the weight of the robustification component} } \description{ getPriorList diff --git a/man/performBayesianMCP.Rd b/man/performBayesianMCP.Rd index e6b3543..66e13e5 100644 --- a/man/performBayesianMCP.Rd +++ b/man/performBayesianMCP.Rd @@ -7,12 +7,15 @@ performBayesianMCP(posteriors_list, contr_mat, crit_prob) } \arguments{ -\item{posteriors_list}{tbd} +\item{posteriors_list}{a getPosterior object} -\item{contr_mat}{tbd} +\item{contr_mat}{a getContrMat object, contrast matrix to be used for the testing step.} -\item{crit_prob}{tbd} +\item{crit_prob}{a getCritProb object} +} +\value{ +b_mcp test result } \description{ -BayesianMCP +performs bayesian MCP Test step. } diff --git a/man/performBayesianMCPMod.Rd b/man/performBayesianMCPMod.Rd index 83a4a06..1bc33dc 100644 --- a/man/performBayesianMCPMod.Rd +++ b/man/performBayesianMCPMod.Rd @@ -7,14 +7,17 @@ performBayesianMCPMod(posteriors_list, contr_mat, crit_prob, simple = FALSE) } \arguments{ -\item{posteriors_list}{tbd} +\item{posteriors_list}{a getPosterior object} -\item{contr_mat}{tbd} +\item{contr_mat}{a getContrMat object, contrast matrix to be used for the testing step.} -\item{crit_prob}{tbd} +\item{crit_prob}{a getCritProb object} -\item{simple}{tbd} +\item{simple}{boolean variable, defining whether simplified fit will be applied. Passed to the getModelFits function. Default FALSE.} +} +\value{ +bmcpmod test result as well as modelling result. } \description{ -performBayesianMCPMod +performs bayesian MCP Test step and modelling. } diff --git a/man/plot.modelFits.Rd b/man/plot.modelFits.Rd index 3b35078..0cb1c26 100644 --- a/man/plot.modelFits.Rd +++ b/man/plot.modelFits.Rd @@ -18,29 +18,30 @@ ) } \arguments{ -\item{x}{tbd An object of type modelFits} +\item{x}{an object of type getModelFits} -\item{gAIC}{tbd} +\item{gAIC}{logical value indicating whether gAIC values are shown in the plot. Default TRUE} -\item{avg_fit}{tbd} +\item{avg_fit}{logical value indicating whether average fit is presented in the plot. Default TRUE} -\item{cr_intv}{tbd} +\item{cr_intv}{logical value indicating whether credible intervals are included in the plot. Default TRUE} -\item{alpha_CrI}{tbd} +\item{alpha_CrI}{numerical value of the width of the credible intervals. Default is set to 0.05 (i.e 95\% CI are shown).} -\item{cr_bands}{tbd} +\item{cr_bands}{logical value indicating whether bootstrapped based credible bands are shown in the plot. Default FALSE} -\item{alpha_CrB}{tbd} +\item{alpha_CrB}{numerical vector of the width of the credible bands. Default is set to 0.05 and 0.5 (i.e 95\% CB and median are shown).} -\item{n_bs_smpl}{tbd} +\item{n_bs_smpl}{number of bootstrap samples being used. Default set to 1000.} -\item{acc_color}{tbd} +\item{acc_color}{color of the credible bands. Default set to "orange"} -\item{...}{tbd} +\item{...}{optional parameter to be passed.} } \value{ -tbd +plts returns a ggplot2 object } \description{ -plot.modelFits +plot function based on the ggplot2 package. Providing visualizations for each model and a average Fit. +More details to be added, as well as references. } diff --git a/man/simulateData.Rd b/man/simulateData.Rd index 32038df..9afd8da 100644 --- a/man/simulateData.Rd +++ b/man/simulateData.Rd @@ -14,17 +14,25 @@ simulateData( ) } \arguments{ -\item{n_patients}{tbd} +\item{n_patients}{vector containing number of patients as a numerical +value per dose-group.} -\item{dose_levels}{tbd} +\item{dose_levels}{vector containing the different doseage levels.} -\item{sd}{tbd} +\item{sd}{standard deviation on patient level.} -\item{mods}{tbd} +\item{mods}{An object of class "Mods" as specified in the Dosefinding package.} -\item{n_sim}{tbd} +\item{n_sim}{number of simulations to be performed, +Default is 1000} -\item{true_model}{tbd} +\item{true_model}{Default value is NULL. +Assumed true underlying model. Provided via a String. e.g. "emax". +In case of NULL, all dose-response models, included in the mods input parameter will be used.} +} +\value{ +sim_data one list object, containing patient level simulated data for all assumed true models. +Also providing information about simulation iteration, patient number as well as dosage levels. } \description{ simulateData diff --git a/vignettes/Simulation_Example.Rmd b/vignettes/Simulation_Example.Rmd index bcd8cef..8e43208 100644 --- a/vignettes/Simulation_Example.Rmd +++ b/vignettes/Simulation_Example.Rmd @@ -52,7 +52,8 @@ dose_levels <- c(0, 2.5, 5, 10, 20) prior_list <- getPriorList( hist_data = hist_data, - dose_levels = dose_levels) + dose_levels = dose_levels, + robustify_weight = 0.5) ``` diff --git a/vignettes/analysis_normal.Rmd b/vignettes/analysis_normal.Rmd index e84ebac..8420240 100644 --- a/vignettes/analysis_normal.Rmd +++ b/vignettes/analysis_normal.Rmd @@ -52,7 +52,7 @@ dose_levels <- c(0, 2.5, 5, 10) prior_list <- getPriorList( hist_data = hist_data, - dose_levels = dose_levels) + dose_levels = dose_levels,robustify_weight = 0.5) ``` @@ -92,16 +92,7 @@ n_patients <- c(150, 142, 147, 149) As outlined in citePaper, in a first step the posterior is calculated combining the prior information with the estimated results of the new trial. ```{r Trial results} -#Simulation of new trial -##Note: This step should not be required, as we provide summary measures directly from the new trial -data_emax <- simulateData( - n_patients = n_patients, - dose_levels = dose_levels, - sd = attr(prior_list, "sd_tot"), - mods = mods, - true_model = "emax") - -posterior <- getPosterior(prior=prior_list,data=data_emax, +posterior <- getPosterior(prior=prior_list, mu_hat = new_trial$rslt, sd_hat = new_trial$se) @@ -141,7 +132,7 @@ BMCP_result <- performBayesianMCP( #BMCP_result2 -BMCP_result +BMCP_result[1,1:5] ``` The testing step is significant indicating a non-flat dose-response shape. In detail the p-values for the emax model is the most significant one.