diff --git a/R/BMCPMod.R b/R/BMCPMod.R index 48681c0..953cf96 100644 --- a/R/BMCPMod.R +++ b/R/BMCPMod.R @@ -7,7 +7,7 @@ #' @param prior_list A prior_list object specifying the utilized prior for the different dose groups #' @param sd A positive value, specification of assumed sd #' @param n_sim Number of simulations to be performed -#' @param alpha_crit_val (Unadjusted) Critical value to be used for the MCT testing step. Passed to the getCritProb function for the calculation of adjusted critical values (on the probability scale). Default is 0.05. +#' @param alpha_crit_val (Unadjusted) Critical value to be used for the MCT testing step. Passed to the getCritProb() function for the calculation of adjusted critical values (on the probability scale). Default is 0.05. #' @param simple Boolean variable defining whether simplified fit will be applied. Passed to the getModelFits function. Default FALSE. #' @param reestimate Boolean variable defining whether critical value should be calculated with re-estimated contrasts (see getCritProb function for more details). Default FALSE #' @param contr Allows specification of a fixed contrasts matrix. Default NULL @@ -142,7 +142,7 @@ assessDesign <- function ( #' @title getContr #' -#' @description This function calculates contrast vectors that are optimal for detecting certain alternatives via applying the function optContr of the DoseFinding package. +#' @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 #' 1) 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 @@ -260,9 +260,9 @@ getContr <- function ( #' 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 #' 1) 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. +#' 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. #' 2) 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. +#' 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. @@ -318,12 +318,12 @@ getCritProb <- function ( #' @title performBayesianMCPMod #' -#' @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 +#' @description Performs bayesian MCT 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 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 contr An object of class ‘⁠optContr' as specified by the getContr() function, 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). -#' @param simple Boolean variable, defining whether simplified fit will be applied. Passed to the getModelFits function. Default FALSE. +#' @param simple Boolean variable, defining whether simplified fit will be applied. Passed to the getModelFits() function. Default FALSE. #' @examples #' # example code #' mods <- DoseFinding::Mods(linear = NULL, @@ -465,7 +465,7 @@ addSignificance <- function ( #' 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). #' @references Fleischer F, Bossert S, Deng Q, Loley C, Gierse J. Bayesian MCPMod. Pharmaceutical Statistics. 2022; 21(3): 654-670. doi:10.1002/pst.2193 #' @param posterior_list An object derived with getPosterior 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 contr An object of class ‘⁠optContr' as specified by the getContr() function, 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) #' #' @examples diff --git a/R/bootstrapping.R b/R/bootstrapping.R index ad9976c..a00db37 100644 --- a/R/bootstrapping.R +++ b/R/bootstrapping.R @@ -2,7 +2,7 @@ #' #' @description A function for the calculation of credible intervals to assess the uncertainty for the model fit. #' Hereby the credible intervals are calculated as follows. -#' Samples from the posterior distribution are drawn (via the RBesT function rmix) and for every sample the simplified fitting step (see getModelFits function) and a prediction is performed. +#' Samples from the posterior distribution are drawn (via the RBesT function rmix()) and for every sample the simplified fitting step (see getModelFits() function) and a prediction is performed. #' These fits are then used to identify the specified quantiles. #' This approach can be considered as the bayesian equivalent of the frequentist bootstrap approach described in O'Quigley et al. (2017). #' Instead of drawing n bootstrap samples from the sampling distribution of the trial dose-response estimates, here the samples are directly taken from the posterior distribution. diff --git a/R/modelling.R b/R/modelling.R index 07f227d..538a846 100644 --- a/R/modelling.R +++ b/R/modelling.R @@ -40,7 +40,7 @@ #' dose_levels = dose_levels, #' simple = TRUE) #' -#' @return 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. +#' @return An object of class modelFits. 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/plot.R b/R/plot.R index 6d8dc63..babb419 100644 --- a/R/plot.R +++ b/R/plot.R @@ -2,9 +2,9 @@ #' #' @description Plot function based on the ggplot2 package. Providing visualizations for each model and a average Fit. #' Black lines show the fitted dose response models and an AIC based average model. Dots indicate the posterior median and vertical lines show corresponding credible intervals (i.e. the variability of the posterior distribution of the respective dose group). -#' To assess the uncertainty of the model fit one can in addition visualize credible bands (default coloring as orange shaded areas). The calculation of these bands is performed via the getBootstrapQuantiles function. +#' To assess the uncertainty of the model fit one can in addition visualize credible bands (default coloring as orange shaded areas). The calculation of these bands is performed via the getBootstrapQuantiles() function. #' The default setting is that these credible bands are not calculated. -#' @param x An object of type getModelFits +#' @param x An object of type modelFits #' @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 diff --git a/R/posterior.R b/R/posterior.R index a661625..1fcaa53 100644 --- a/R/posterior.R +++ b/R/posterior.R @@ -1,9 +1,9 @@ #' @title getPosterior #' #' @description Either the patient level data or both mu_hat as well as sd_hat must to be provided. If patient level data is provided mu_hat and se_hat are calculated within the function using a linear model. -#' This function calculates the posterior for every dose group independently via the RBesT function postmix. +#' This function calculates the posterior for every dose group independently via the RBesT function postmix(). #' -#' @param prior_list prior_list object +#' @param prior_list a prior list with information about the prior to be used for every dose group #' @param data dataframe containing the information of dose and response. Default NULL #' Also a simulateData object can be provided. #' @param mu_hat vector of estimated mean values (per dose group). @@ -140,7 +140,7 @@ getPosteriorI <- function( #' @title getESS #' -#' @description This function calculates the effective sample size for every dose group via the RBesT function ess. +#' @description This function calculates the effective sample size for every dose group via the RBesT function ess(). #' #' @param post_list a posterior list object, for which the effective sample size (per dose group) should be calculated #' diff --git a/R/s3methods.R b/R/s3methods.R index 8c8b901..6ec9537 100644 --- a/R/s3methods.R +++ b/R/s3methods.R @@ -84,7 +84,7 @@ print.BayesianMCP <- function ( #' @param object A modelFits object containing information about the fitted #' model coefficients #' @param doses A vector specifying the doses for which a prediction should be -#' done getContrMat object, contrast matrix to be used for the testing step. +#' done #' @param ... currently without function #' @examples #' # example code diff --git a/R/simulation.R b/R/simulation.R index e2198e7..0157ec4 100644 --- a/R/simulation.R +++ b/R/simulation.R @@ -6,7 +6,7 @@ #' value per dose-group. #' @param dose_levels Vector containing the different dosage levels. #' @param sd Standard deviation on patient level. -#' @param mods An object of class "Mods" as specified in the Doseinding package. +#' @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. diff --git a/man/assessDesign.Rd b/man/assessDesign.Rd index 05ea0ef..8881513 100644 --- a/man/assessDesign.Rd +++ b/man/assessDesign.Rd @@ -29,7 +29,7 @@ assessDesign( \item{n_sim}{Number of simulations to be performed} -\item{alpha_crit_val}{(Unadjusted) Critical value to be used for the MCT testing step. Passed to the getCritProb function for the calculation of adjusted critical values (on the probability scale). Default is 0.05.} +\item{alpha_crit_val}{(Unadjusted) Critical value to be used for the MCT testing step. Passed to the getCritProb() function for the calculation of adjusted critical values (on the probability scale). Default is 0.05.} \item{simple}{Boolean variable defining whether simplified fit will be applied. Passed to the getModelFits function. Default FALSE.} diff --git a/man/getBootstrapQuantiles.Rd b/man/getBootstrapQuantiles.Rd index ff14a5b..44b9ecc 100644 --- a/man/getBootstrapQuantiles.Rd +++ b/man/getBootstrapQuantiles.Rd @@ -29,7 +29,7 @@ A data frame with entries doses, models, and quantiles \description{ A function for the calculation of credible intervals to assess the uncertainty for the model fit. Hereby the credible intervals are calculated as follows. -Samples from the posterior distribution are drawn (via the RBesT function rmix) and for every sample the simplified fitting step (see getModelFits function) and a prediction is performed. +Samples from the posterior distribution are drawn (via the RBesT function rmix()) and for every sample the simplified fitting step (see getModelFits() function) and a prediction is performed. These fits are then used to identify the specified quantiles. This approach can be considered as the bayesian equivalent of the frequentist bootstrap approach described in O'Quigley et al. (2017). Instead of drawing n bootstrap samples from the sampling distribution of the trial dose-response estimates, here the samples are directly taken from the posterior distribution. diff --git a/man/getContr.Rd b/man/getContr.Rd index b8a8511..b3a8b4f 100644 --- a/man/getContr.Rd +++ b/man/getContr.Rd @@ -30,7 +30,7 @@ getContr( 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 via applying the function optContr of the DoseFinding package. +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 \enumerate{ \item Bayesian approach: If dose_weights and a prior_list are provided an optimized contrasts for the posterior sample size is calculated. diff --git a/man/getCritProb.Rd b/man/getCritProb.Rd index 21ffc71..1699b87 100644 --- a/man/getCritProb.Rd +++ b/man/getCritProb.Rd @@ -32,9 +32,9 @@ when using non-informative priors the actual error level for falsely declaring a Hereby optimal contrasts of the frequentist MCPMod are applied and two options can be distinguished \enumerate{ \item 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. +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. \item 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. +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. } } \examples{ diff --git a/man/getESS.Rd b/man/getESS.Rd index 7f08776..231a0d4 100644 --- a/man/getESS.Rd +++ b/man/getESS.Rd @@ -13,5 +13,5 @@ getESS(post_list) a vector of the effective sample sizes (per dose group) } \description{ -This function calculates the effective sample size for every dose group via the RBesT function ess. +This function calculates the effective sample size for every dose group via the RBesT function ess(). } diff --git a/man/getModelFits.Rd b/man/getModelFits.Rd index 13faf0d..78e2813 100644 --- a/man/getModelFits.Rd +++ b/man/getModelFits.Rd @@ -16,7 +16,7 @@ getModelFits(models, dose_levels, posterior, simple = FALSE) \item{simple}{Boolean variable, defining whether simplified fit will be applied. Default FALSE.} } \value{ -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. +An object of class modelFits. 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-response models, based on the posterior distributions. diff --git a/man/getPosterior.Rd b/man/getPosterior.Rd index 7a03382..a8d9d18 100644 --- a/man/getPosterior.Rd +++ b/man/getPosterior.Rd @@ -13,7 +13,7 @@ getPosterior( ) } \arguments{ -\item{prior_list}{prior_list object} +\item{prior_list}{a prior list with information about the prior to be used for every dose group} \item{data}{dataframe containing the information of dose and response. Default NULL Also a simulateData object can be provided.} @@ -29,7 +29,7 @@ posterior_list, a posterior list object is returned with information about (mixt } \description{ Either the patient level data or both mu_hat as well as sd_hat must to be provided. If patient level data is provided mu_hat and se_hat are calculated within the function using a linear model. -This function calculates the posterior for every dose group independently via the RBesT function postmix. +This function calculates the posterior for every dose group independently via the RBesT function postmix(). } \examples{ # example code diff --git a/man/performBayesianMCP.Rd b/man/performBayesianMCP.Rd index 5caee5b..7120011 100644 --- a/man/performBayesianMCP.Rd +++ b/man/performBayesianMCP.Rd @@ -9,7 +9,7 @@ performBayesianMCP(posterior_list, contr, crit_prob_adj) \arguments{ \item{posterior_list}{An object derived with getPosterior 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{contr}{An object of class ‘⁠optContr' as specified by the getContr() function, contrast matrix to be used for the testing step} \item{crit_prob_adj}{A getCritProb object, specifying the critical value to be used for the testing (on the probability scale)} } diff --git a/man/performBayesianMCPMod.Rd b/man/performBayesianMCPMod.Rd index 46e8724..761d6a3 100644 --- a/man/performBayesianMCPMod.Rd +++ b/man/performBayesianMCPMod.Rd @@ -9,17 +9,17 @@ performBayesianMCPMod(posterior_list, contr, crit_prob_adj, simple = FALSE) \arguments{ \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{contr}{An object of class ‘⁠optContr' as specified by the getContr() function, contrast matrix to be used for the testing step.} \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.} +\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{ -performs bayesian MCP Test step and modelling in a combined fashion. See performBayesianMCP function for MCT Test step and getModelFits for the modelling step +Performs bayesian MCT Test step and modelling in a combined fashion. See performBayesianMCP() function for MCT Test step and getModelFits() for the modelling step } \examples{ # example code diff --git a/man/plot.modelFits.Rd b/man/plot.modelFits.Rd index 2998afb..8d6f3b9 100644 --- a/man/plot.modelFits.Rd +++ b/man/plot.modelFits.Rd @@ -18,7 +18,7 @@ ) } \arguments{ -\item{x}{An object of type getModelFits} +\item{x}{An object of type modelFits} \item{gAIC}{Logical value indicating whether gAIC values are shown in the plot. Default TRUE} @@ -44,7 +44,7 @@ A ggplot2 object \description{ Plot function based on the ggplot2 package. Providing visualizations for each model and a average Fit. Black lines show the fitted dose response models and an AIC based average model. Dots indicate the posterior median and vertical lines show corresponding credible intervals (i.e. the variability of the posterior distribution of the respective dose group). -To assess the uncertainty of the model fit one can in addition visualize credible bands (default coloring as orange shaded areas). The calculation of these bands is performed via the getBootstrapQuantiles function. +To assess the uncertainty of the model fit one can in addition visualize credible bands (default coloring as orange shaded areas). The calculation of these bands is performed via the getBootstrapQuantiles() function. The default setting is that these credible bands are not calculated. } \examples{ diff --git a/man/predict.modelFits.Rd b/man/predict.modelFits.Rd index 75b0439..88c4151 100644 --- a/man/predict.modelFits.Rd +++ b/man/predict.modelFits.Rd @@ -11,7 +11,7 @@ model coefficients} \item{doses}{A vector specifying the doses for which a prediction should be -done getContrMat object, contrast matrix to be used for the testing step.} +done} \item{...}{currently without function} } diff --git a/man/simulateData.Rd b/man/simulateData.Rd index 690bdd4..373cd46 100644 --- a/man/simulateData.Rd +++ b/man/simulateData.Rd @@ -22,7 +22,7 @@ value per dose-group.} \item{sd}{Standard deviation on patient level.} -\item{mods}{An object of class "Mods" as specified in the Doseinding package.} +\item{mods}{An object of class "Mods" as specified in the DoseFinding package.} \item{n_sim}{Number of simulations to be performed, Default is 1000}