Merge pull request #3 from Boehringer-Ingelheim/documentation

Documentation

BayesianMCPMod.Rproj

@@ -11,3 +11,7 @@ Encoding: UTF-8
 
 RnwWeave: Sweave
 LaTeX: pdfLaTeX
+
+BuildType: Package
+PackageUseDevtools: Yes
+PackageInstallArgs: --no-multiarch --with-keep.source

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",

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,18 +99,20 @@ 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 (
 
   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(

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 (

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 (
 

R/posterior.R

@@ -1,17 +1,22 @@
 #' @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 (
 
   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) {
 

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(