Merge branch 'develop' into vignette_antidepressant

.github/workflows/check_devlop.yaml

@@ -19,7 +19,6 @@ jobs:
       fail-fast: false
       matrix:
        config:
-         # - { image: "gowerc/rbmi:r363"}
          - { image: "gowerc/rbmi:r404"}
          - { image: "gowerc/rbmi:r410"}
 

.github/workflows/check_master.yaml

@@ -6,7 +6,7 @@ on:
       - main
       - master
 
-name: Check Develop
+name: Check Master
 
 jobs:
 

R/analyse.R

@@ -57,10 +57,14 @@
 #' requires that a vars object, as created by [set_vars()], is provided via
 #' the `vars` argument e.g. `analyse(imputeObj, vars = set_vars(...))`. Please
 #' see the documentation for [ancova()] for full details.
+#' Please also note that the theoretical justification for the conditional mean imputation
+#' method (`method = method_condmean()` in [draws()]) relies on the fact that ANCOVA is
+#' a linear transformation of the outcomes.
+#' Thus care is required when applying alternative analysis functions in this setting.
 #'
 #' The `delta` argument can be used to specify offsets to be applied
-#' to the outcome variable in the imputed datasets which can be used
-#' as part of a sensitivity or tipping point analysis. The
+#' to the outcome variable in the imputed datasets prior to the analysis.
+#' This is typically used for sensitivity or tipping point analysis. The
 #' delta dataset must contain columns `vars$subjid`, `vars$visit` (as specified
 #' in the original call to [draws()]) and `delta`. Essentially this data.frame
 #' is merged onto the imputed dataset by `vars$subjid` and `vars$visit` and then
@@ -175,13 +179,13 @@ analyse <- function(imputations, fun = ancova, delta = NULL, ...) {
 #' Extract imputed datasets
 #'
 #' @description
-#' Extracts the imputed datasets contained with an imputations object generated
+#' Extracts the imputed datasets contained within an imputations object generated
 #' by [impute()].
 #'
 #' @param imputations An imputations object as created by [impute()].
-#' @param index The indexes of the imputed data.frames to return. By default will
-#' return all data.frames within the imputations object
-#' (i.e. use this argument if you just want the "1st" data.frame).
+#' @param index The indexes of the imputed data.frames to return. By default,
+#' all data.frames within the imputations object will be returned
+#' (i.e. use this argument if you just want e.g. the first data.frame only).
 #' @param delta A data.frame containing the delta transformation to be
 #' applied to the imputed dataset. See [analyse()] for details on the
 #' format and specification of this data.frame.
@@ -336,7 +340,7 @@ print.analysis <- function(x, ...) {
         sprintf("Number of Results: %s", n_samp_string),
         sprintf("Analysis Function: %s", x$fun_name),
         sprintf("Delta Applied: %s", !is.null(x$delta)),
-        "Analysis Parameters:",
+        "Analysis Estimates:",
         sprintf("    %s", names(x$results[[1]])),
         ""
     )
@@ -441,7 +445,7 @@ validate_analyse_pars <- function(results, pars) {
 
     devnull <- lapply(
         results_unnested,
-        function(x){
+        function(x) {
             assert_that(
                 is.list(x),
                 all(pars %in% names(x)),
@@ -464,5 +468,3 @@ validate_analyse_pars <- function(results, pars) {
 
     return(invisible(TRUE))
 }
-
-

R/ancova.R

@@ -2,14 +2,15 @@
 #' Analysis of Covariance
 #'
 #' Performs an analysis of covariance between two groups returning the estimated
-#' "treatment effect" and least squared means estimates of each group.
+#' "treatment effect" (i.e. the contrast between the two treatment groups) and
+#' the least square means estimates in each group.
 #'
 #' @param data A data.frame containing the data to be used in the model
 #' @param vars A `vars` object as generated by [set_vars()]. Only the `group`,
 #' `visit`, `outcome` and `covariates` elements are required. See details.
 #' @param visits an optional character vector specifying which visits to
-#' fit the ancova model at. If `NULL` all available
-#' visits (as determined by `unique(data[[vars$visit]])`) will be used.
+#' fit the ancova model at. If `NULL`, a separate ancova model will be fit to the
+#' outcomes from each visits (as determined by `unique(data[[vars$visit]])`).
 #' See details.
 #'
 #' @details
@@ -21,7 +22,7 @@
 #' 4. Extract the "treatment effect" & least square means for each treatment group.
 #' 5. Repeat points 2-3 for all other values in `visits`.
 #'
-#' If no value for `visits` are provided then it will be set to
+#' If no value for `visits` is provided then it will be set to
 #' `unique(data[[vars$visit]])`.
 #'
 #' In order to meet the formatting standards set by [analyse()] the results
@@ -122,16 +123,16 @@ ancova <- function(data, vars, visits = NULL) {
 
 
 
-#' Implements analysis of Covariance
+#' Implements an Analysis of Covariance (ANCOVA)
 #'
 #' @description
 #' Performance analysis of covariance. See [ancova()] for full details.
 #'
 #' @param data The data.frame containing all of the data required for the model.
 #' @param outcome Character, the name of the outcome variable in `data`.
 #' @param group Character, the name of the group variable in `data`.
-#' @param covariates Character vector containing the name of any covariates
-#' to be used in the model as well as any interaction terms required.
+#' @param covariates Character vector containing the name of any additional covariates
+#' to be included in the model as well as any interaction terms.
 #'
 #' @details
 #' `group` must be a factor variable with only 2 levels.

R/bootstrap.R

@@ -17,14 +17,14 @@
 #' \dontrun{
 #' as_strata(c(1,1,2,2,2,1), c(5,6,5,5,6,5))
 #' }
-as_strata <- function(...){
+as_strata <- function(...) {
     x <- list(...)
-    assert_that(length(unique(vapply(x, length, numeric(1)))) == 1 )
+    assert_that(length(unique(vapply(x, length, numeric(1)))) == 1)
     df <- as.data.frame(x)
-    colnames(df) <- paste0("var", 1:length(x))
+    colnames(df) <- paste0("var", seq_along(x))
     df_unique <- unique(df)
-    df_unique[,"ID"] <- seq_len(nrow(df_unique))
-    df[,"ORDER"] <- seq_len(nrow(df))
+    df_unique[, "ID"] <- seq_len(nrow(df_unique))
+    df[, "ORDER"] <- seq_len(nrow(df))
     df_mapped <- merge(df, df_unique)
     df_mapped[["ID"]][order(df_mapped[["ORDER"]])]
 }
@@ -43,7 +43,7 @@ as_strata <- function(...){
 #' \dontrun{
 #' sample_ids( c("a", "b", "c", "d"), strata = c(1,1,2,2))
 #' }
-sample_ids <- function(ids, strata = rep(1, length(ids))){
+sample_ids <- function(ids, strata = rep(1, length(ids))) {
     res <- tapply(
         X = ids,
         INDEX = strata,
@@ -52,5 +52,5 @@ sample_ids <- function(ids, strata = rep(1, length(ids))){
             x[y]
         }
     )
-    return(unlist(res,use.names = FALSE))
+    return(unlist(res, use.names = FALSE))
 }

R/delta.R

@@ -141,7 +141,7 @@ delta_template <- function(
 ) {
     dat <- get_delta_template(imputations)
 
-    if(is.null(delta)) return(dat)
+    if (is.null(delta)) return(dat)
 
     ld <- imputations$data
 
@@ -193,7 +193,7 @@ delta_template <- function(
 #' for defining delta. See [delta_template()] for full details.
 #'
 #' @param imputations an imputations object created by [impute()].
-get_delta_template <- function(imputations){
+get_delta_template <- function(imputations) {
     ld <- imputations$data
     x <- lapply(
         ld$ids,