update docs for multiarm extension

R/get_marginal_effect.R

@@ -35,10 +35,11 @@
 #'
 #' @param contrast a string indicating choice of contrast. Defaults to 'diff' for a risk difference. See \link[beeca]{apply_contrast}.
 #'
-#' @param reference a string indicating which treatment group should be considered as
-#' the reference level. Accepted values are one of the levels in the treatment
-#' variable. Default to the first level used in the `glm` object. This parameter influences the calculation of treatment effects
-#' relative to the chosen reference group.
+#' @param reference a string or list of strings indicating which treatment
+#' group(s) to use as reference level for pairwise comparisons. Accepted values
+#' must be a subset of the levels in the treatment variable. Default to the
+#' first n-1 treatment levels used in the `glm` object. This parameter influences
+#' the calculation of treatment effects relative to the chosen reference group.
 #'
 #' @param mod for Ye's method, the implementation of open-source RobinCar package
 #' has an additional variance decomposition step when estimating the robust variance,

R/predict_counterfactuals.R

@@ -17,19 +17,18 @@
 #' @return an updated `glm` object appended with an
 #' additional component `counterfactual.predictions`.
 #'
-#' This component contains a tibble with two columns: `cf_pred_0` and `cf_pred_1`,
-#' representing counterfactual predictions for each level of the
-#' treatment variable. A descriptive `label` attribute explains the counterfactual
-#' scenario associated with each column.
+#' This component contains a tibble with columns representing counterfactual
+#' predictions for each level of the treatment variable. A descriptive `label`
+#' attribute explains the counterfactual scenario associated with each column.
 #'
 #' @importFrom stats predict
 #' @importFrom dplyr as_tibble
 #' @export
 #'
 #' @details
-#' The function works by creating two new datasets from the original data used
-#' to fit the GLM model. In these datasets, the treatment variable
-#' is set to each of its levels across all records (e.g., patients).
+#' The function works by creating new datasets from the original data used
+#' to fit the GLM model. In these datasets, the treatment variable for all
+#' records (e.g., patients) is set to each possible treatment level.
 #'
 #' Predictions are then made for each dataset based on the fitted GLM model,
 #' simulating the response variable under each treatment condition.

README.md

@@ -24,7 +24,7 @@ Motivated by the recent [FDA guidance (2023)](https://www.fda.gov/regulatory-inf
 
 ## Scope
 
-The package is designed to estimate marginal (unconditional) estimands in a binary endpoint setting with covariate adjustment. It is suited for 2-arm clinical trials with or without covariate adaptive (stratified permuted block or biased coin) randomization where the summary measure of the marginal estimand is one of (risk difference, odds ratio, risk ratio, log odds ratio, log risk ratio). For practical considerations on the implications of covariate adjustment in superiority vs non-inferiority trials, please see [Nicholas et al. (2015)](https://doi.org/10.1002/sim.6447) and [Morris et al. (2022)](https://doi.org/10.1186/s13063-022-06097-z).
+The package is designed to estimate marginal (unconditional) estimands in a binary endpoint setting with covariate adjustment. It is suited for clinical trials with or without covariate adaptive (stratified permuted block or biased coin) randomization where the summary measure of the marginal estimand is one of (risk difference, odds ratio, risk ratio, log odds ratio, log risk ratio). For practical considerations on the implications of covariate adjustment in superiority vs non-inferiority trials, please see [Nicholas et al. (2015)](https://doi.org/10.1002/sim.6447) and [Morris et al. (2022)](https://doi.org/10.1186/s13063-022-06097-z).
 
 ## Example
 

vignettes/estimand_and_implementations.Rmd

@@ -56,11 +56,10 @@ See [Magirr et al. (2024)](https://osf.io/9mp58/) for discussion of the estimand
 
 ## Analysis example
 
-In the following example, we will use an example CDISC clinical trial dataset in ADaM format (`?trial02_cdisc`).
-We will only include the two treatment arms of interest for the analysis: "Xanomeline High Dose" and "Placebo".
-Below we show how to describe and perform an adjusted analysis targeting marginal risk difference between the two arms.  
+In the following example, we will use an example CDISC clinical trial dataset in ADaM format (`?trial02_cdisc`) with three treatment arms.
+Below we show how to describe and perform an adjusted analysis targeting marginal risk difference comparing the two active arms against placebo.  
 
-A logistic regression model will be used to estimate the average treatment effect between Xanomeline High Dose and Placebo. The model will adjust for baseline values of patient sex, race and age. Difference in marginal response proportions with p-value and corresponding 95% confidence interval will be estimated from the logistic regression model using the methodology described in Ge et al. 2011 with sandwich variance estimator (Liu et al. 2023). The sandwich estimator provides robustness to model-misspecification.
+A logistic regression model will be used to estimate the average treatment effect for Xanomeline High Dose vs Placebo and Xanomeline Low Dose vs Placebo. The model will adjust for baseline values of patient sex, race and age. Difference in marginal response proportions with p-value and corresponding 95% confidence interval will be estimated from the logistic regression model using the methodology described in Ge et al. 2011 with sandwich variance estimator (Liu et al. 2023). The sandwich estimator provides robustness to model-misspecification.
 
 ```{r, message=FALSE, warning=FALSE}
 library(beeca)