From a289dff78e6257a29a8c9e15a4cac42652b2f97d Mon Sep 17 00:00:00 2001 From: sebastianbossert Date: Fri, 15 Dec 2023 12:53:45 +0000 Subject: [PATCH] First updates around documentation --- R/BMCPMod.R | 21 +++++++++++++-------- R/posterior.R | 16 +++++++++------- man/getContr.Rd | 4 ++-- man/getCritProb.Rd | 10 ++++++++-- man/getESS.Rd | 7 +++++-- man/getPosterior.Rd | 12 ++++++++---- man/performBayesianMCP.Rd | 7 ++++--- 7 files changed, 49 insertions(+), 28 deletions(-) diff --git a/R/BMCPMod.R b/R/BMCPMod.R index 76f2529..446ecc7 100644 --- a/R/BMCPMod.R +++ b/R/BMCPMod.R @@ -185,6 +185,8 @@ getContr <- function ( #' @title getCritProb #' +#' @description This function calculates multiplicity adjusted +#' #' @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 @@ -197,15 +199,17 @@ getCritProb <- function ( mods, dose_levels, - dose_weights, + dose_weights =NULL, + se_new_trial = NULL, alpha_crit_val = 0.025 ) { - contr <- DoseFinding::optContr( - models = mods, - doses = dose_levels, - w = dose_weights) + contr <- getContr(mods = mods, + dose_levels = dose_levels , + dose_weights = dose_weights, + se_new_trial = se_new_trial, + alpha_crit_val = alpha_crit_val) crit_prob <- stats::pnorm(DoseFinding::critVal( corMat = contr$corMat, @@ -317,13 +321,14 @@ addSignificance <- function ( #' @title performBayesianMCP #' -#' @description performs bayesian MCP Test step. +#' @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 #' -#' @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, specifying the critical value to be used for the testing (on the probability scale) #' -#' @return b_mcp test result +#' @return b_mcp test result, with information about p-values for the individual dose-response shapes #' #' @export performBayesianMCP <- function( diff --git a/R/posterior.R b/R/posterior.R index 599be98..c29e011 100644 --- a/R/posterior.R +++ b/R/posterior.R @@ -1,15 +1,16 @@ #' @title getPosterior #' -#' @description Either the patient level data or both the mu_hat as well as the sd_hat must to be provided. +#' @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. #' #' @param prior_list prior_list object #' @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 -#' @param se_hat vector of estimated standard deviations. -#' @param calc_ess tbd. Default NULL -#' +#' @param mu_hat vector of estimated mean values (per dose group). +#' @param se_hat vector of estimated standard deviations (per dose group). +#' @param calc_ess boolean variable, indicating whether effective sample size should be calculated. Default FALSE +#' @return posterior_list, a posterior list object is returned with information about (mixture) posterior distribution per dose group #' @export getPosterior <- function( prior_list, @@ -99,10 +100,11 @@ getPosteriorI <- function( #' @title getESS #' -#' @description blubber +#' @description This function calculates the effective sample size for every dose group via the RBesT function ess. #' -#' @param post_list blubb +#' @param post_list a posterior list object, for which the effective sample size (per dose group) should be calculated #' +#' @return a vector of the effective sample sizes (per dose group) #' @export getESS <- function ( diff --git a/man/getContr.Rd b/man/getContr.Rd index 0e64c19..809e932 100644 --- a/man/getContr.Rd +++ b/man/getContr.Rd @@ -22,9 +22,9 @@ getContr( \item{prior_list}{a prior_list object. Default NULL} -\item{sd_posterior}{tbd. Default NULL} +\item{sd_posterior}{a vector of positive numerics. Default NULL} -\item{se_new_trial}{tbd. Default NULL} +\item{se_new_trial}{a vector of positive numerics. Default NULL} } \value{ contr Object of class ‘⁠optContr⁠’. A list containing entries contMat and muMat, and CorrMat. Specified in the Dosefinding package. diff --git a/man/getCritProb.Rd b/man/getCritProb.Rd index 41ee06b..fa648bd 100644 --- a/man/getCritProb.Rd +++ b/man/getCritProb.Rd @@ -4,7 +4,13 @@ \alias{getCritProb} \title{getCritProb} \usage{ -getCritProb(mods, dose_levels, dose_weights, alpha_crit_val = 0.025) +getCritProb( + mods, + dose_levels, + dose_weights = NULL, + se_new_trial = NULL, + alpha_crit_val = 0.025 +) } \arguments{ \item{mods}{An object of class "Mods" as specified in the Dosefinding package.} @@ -19,5 +25,5 @@ getCritProb(mods, dose_levels, dose_weights, alpha_crit_val = 0.025) crit_pval multiplicity adjusted critical value on the probability scale. } \description{ -getCritProb +This function calculates multiplicity adjusted } diff --git a/man/getESS.Rd b/man/getESS.Rd index d3ee3ca..7f08776 100644 --- a/man/getESS.Rd +++ b/man/getESS.Rd @@ -7,8 +7,11 @@ getESS(post_list) } \arguments{ -\item{post_list}{blubb} +\item{post_list}{a posterior list object, for which the effective sample size (per dose group) should be calculated} +} +\value{ +a vector of the effective sample sizes (per dose group) } \description{ -blubber +This function calculates the effective sample size for every dose group via the RBesT function ess. } diff --git a/man/getPosterior.Rd b/man/getPosterior.Rd index 44e7560..36e0328 100644 --- a/man/getPosterior.Rd +++ b/man/getPosterior.Rd @@ -18,12 +18,16 @@ getPosterior( \item{data}{dataframe containing the information of dose and response. Default NULL Also a simulateData object can be provided.} -\item{mu_hat}{vector of estimated mean values} +\item{mu_hat}{vector of estimated mean values (per dose group).} -\item{se_hat}{vector of estimated standard deviations.} +\item{se_hat}{vector of estimated standard deviations (per dose group).} -\item{calc_ess}{tbd. Default NULL} +\item{calc_ess}{boolean variable, indicating whether effective sample size should be calculated. Default FALSE} +} +\value{ +posterior_list, a posterior list object is returned with information about (mixture) posterior distribution per dose group } \description{ -Either the patient level data or both the mu_hat as well as the sd_hat must to be provided. +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. } diff --git a/man/performBayesianMCP.Rd b/man/performBayesianMCP.Rd index 02dd385..545bcc3 100644 --- a/man/performBayesianMCP.Rd +++ b/man/performBayesianMCP.Rd @@ -7,15 +7,16 @@ performBayesianMCP(posterior_list, contr, crit_prob_adj) } \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, specifying the critical value to be used for the testing (on the probability scale)} } \value{ -b_mcp test result +b_mcp test result, with information about p-values for the individual dose-response shapes } \description{ -performs bayesian MCP Test step. +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 }