sorted out most of the help documentation.

TODO:
* @examples
* unit tests

R/IPD_stats.R

@@ -164,7 +164,7 @@ new_strategy <- function(strategy, ...) {
 hat_Delta_stats <- function(AC.IPD, BC.ALD, strategy, CI = 0.95, ...) {
 
   AC_hat_Delta_stats <- IPD_stats(strategy, ipd = AC.IPD, ald = BC.ALD, ...) 
-  BC_hat_Delta_stats <- ALD_stats(data = BC.ALD) 
+  BC_hat_Delta_stats <- ALD_stats(ald = BC.ALD) 
 
   upper <- 0.5 + CI/2
   ci_range <- c(1-upper, upper)
@@ -238,7 +238,7 @@ IPD_stats.maic <- function(strategy,
                           statistic = maic.boot,
                           R = strategy$R,
                           formula = strategy$formula,
-                          dat_ALD = strategy$dat_ALD)   #TODO: swap ald
+                          ald = strategy$dat_ALD)
 
   list(mean = mean(maic_boot$t),
        var = var(maic_boot$t))

R/gcomp_ml.R

@@ -1,11 +1,11 @@
 
 #' G-computation maximum likelihood bootstrap
 #' 
-#' Using bootstrap resampling, calculates the log odds ratio
+#' Using bootstrap resampling, calculates the log odds ratio.
 #' 
 #' @param data Trial data 
 #' @param indices Indices sampled from rows of `data`
-#' @param formula Linear regression formula; default \eqn{y = X_3 + X_4 + \beta_t X_1 + \beta_t X_2"} 
+#' @param formula Linear regression formula; default \eqn{y = X_3 + X_4 + \beta_t X_1 + \beta_t X_2} 
 #'
 #' @return Mean difference in expected log-odds
 #' @export

R/maic.R

@@ -1,30 +1,30 @@
 
 #' Estimate MAIC weights 
 #' 
-#' \insertCite{Signorovitch2010}{mimR}
+#' Method is taken from
+#' \insertCite{Signorovitch2010}{mimR}.
 #' 
-#' 
-#' @param X.EM Centred S=1 effect modifiers; matrix or data frame
+#' @param X_EM Centred \eqn{S=1} effect modifiers; matrix or data frame
 #' @return Estimated weights for each individual; vector
 #' 
 #' @references
 #' \insertRef{Signorovitch2010}{mimR}
 #' 
-maic_weights <- function(X.EM) {
-  X.EM <- as.matrix(X.EM)
+maic_weights <- function(X_EM) {
+  X_EM <- as.matrix(X_EM)
 
-  N <- nrow(X.EM)    # number of individuals
-  K <- ncol(X.EM)    # number of covariates
+  N <- nrow(X_EM)    # number of individuals
+  K <- ncol(X_EM)    # number of covariates
   init <- rep(1, K)  # arbitrary starting point for optimizer
-  Q.min <- optim(fn=Q, X=X.EM, par=init, method="BFGS")
+  Q.min <- optim(fn=Q, X=X_EM, par=init, method="BFGS")
 
   # finite solution is the logistic regression parameters
   hat_beta <- Q.min$par
   log.hat_w <- rep(0, N)
 
-  # linear eqn for logistic
+  # linear equation for logistic
   for (k in seq_len(K)) {
-    log.hat_w <- log.hat_w + hat_beta[k]*X.EM[, k]
+    log.hat_w <- log.hat_w + hat_beta[k]*X_EM[, k]
   }
 
   exp(log.hat_w)
@@ -33,30 +33,30 @@ maic_weights <- function(X.EM) {
 
 #' MAIC bootstrap
 #' 
-#' @param data Original data
+#' @template args-ipd
 #' @param indices Vector of indices, same length as original,
 #'   which define the bootstrap sample
 #' @param formula Linear regression formula
-#' @param dat_ALD Aggregate-level data
-#' @return Fitted treatment coefficient is marginal effect for A vs C
+#' @template args-ald
+#' @return Fitted treatment coefficient is marginal effect for _A_ vs _C_
 #' 
-maic.boot <- function(data, indices, formula, dat_ALD) {
+maic.boot <- function(ipd, indices, formula, ald) {
 
-  dat <- data[indices, ]  # bootstrap sample
+  dat <- ipd[indices, ]  # bootstrap sample
 
   effect_modifier_names <- get_effect_modifiers(formula)
-  X.EM <- dat[, effect_modifier_names]
+  X_EM <- dat[, effect_modifier_names]
 
   ##TODO: why is this centering used in maic.boot() and not maic()?
 
   # BC effect modifier means, assumed fixed
-  mean_names <- get_mean_names(dat_ALD, effect_modifier_names)
+  mean_names <- get_mean_names(ald, effect_modifier_names)
 
   # centre AC effect modifiers on BC means
-  dat_ALD_means <- dat_ALD[, mean_names][rep(1, nrow(X.EM)), ]
-  X.EM <- X.EM - dat_ALD_means
+  dat_ALD_means <- ald[, mean_names][rep(1, nrow(X_EM)), ]
+  X_EM <- X_EM - dat_ALD_means
 
-  hat_w <- maic_weights(X.EM)
+  hat_w <- maic_weights(X_EM)
 
   treat_nm <- get_treatment_name(formula)
   formula_treat <- glue::glue("{formula[[2]]} ~ {treat_nm}")

R/marginal_stats.R

@@ -1,72 +1,81 @@
 
-#' marginal effect variance using the delta method
-#'
-#' \deqn{\frac{1}{n_C} + \frac{1}{n_{\bar{C}}} + \frac{1}{n_B} + \frac{1}{n_{\bar{B}}}}
+#' Marginal effect variance using the delta method
+#' 
+#' Calculate
+#' \deqn{\frac{1}{n_C} + \frac{1}{n_{\bar{C}}} + \frac{1}{n_B} + \frac{1}{n_{\bar{B}}}}.
 #'
-#' @param x x
-#' @param trials Trial labels
+#' @param ald Aggregate-level data
+#' @param treatments Treatment labels; default _B_ vs _C_
+#' @return Sum of variances
 #' @export
 #' 
-marginal_variance <- function(x, trials = list("B", "C")) {
-
-  trial_vars <- purrr::map_dbl(trials, ~trial_variance(x, .x))
+marginal_variance <- function(ald, treatments = list("B", "C")) {
+  trial_vars <- purrr::map_dbl(treatments, ~trial_variance(ald, .x))
   sum(trial_vars)
 }
 
 
-#' B vs C marginal treatment effect from reported event counts
-#'
-#' \deqn{\log(n_B n_{\bar{C}})  -log(n_C n_{\bar{B}})}
+#' Marginal treatment effect from reported event counts
+#' 
+#' Calculate
+#' \deqn{\log(n_B n_{\bar{C}}) - log(n_C n_{\bar{B}})}.
 #'
-#' @param x x
-#' @param trials Trial labels
+#' @param ald Aggregate-level data
+#' @param treatments Treatment labels; default _B_ vs _C_
 #' @return Trial effect difference
 #' @export
 #' 
-marginal_treatment_effect <- function(x, trials = list("B", "C")) {
-  trial_effect <- purrr::map_dbl(trials, ~trial_treatment_effect(x, .x))
+marginal_treatment_effect <- function(ald, treatments = list("B", "C")) {
+  trial_effect <- purrr::map_dbl(treatments, ~trial_treatment_effect(ald, .x))
   trial_effect[2] - trial_effect[1]
 }
 
 
-#' Trial variance
+#' Trial variance with aggregate data
 #'
-#' @param x x
-#' @param k k
+#' Calculate
+#' \deqn{1/(\sum y_k) + 1/(N_k - \sum y_k)}.
+#' 
+#' @param ald Aggregate-level data
+#' @param tid Treatment label
 #'
 #' @return Value
 #' @export
 #'
-trial_variance <- function(x, k) {
-  var_string <- glue::glue("1/x$y.{k}.sum + 1/(x$N.{k} - x$y.{k}.sum)")
+trial_variance <- function(ald, tid) {
+  var_string <- glue::glue("1/ald$y.{tid}.sum + 1/(ald$N.{tid} - ald$y.{tid}.sum)")
   eval(parse(text = var_string))
 }
 
 
-#' Trial treatment effect
-#'
-#' @param x x
-#' @param k k
+#' Trial treatment effect with aggregate data
+#' 
+#' Calculate
+#' \deqn{\log(\sum y_k (N_k - \sum y_k))}.
+#' 
+#' @param ald Aggregate-level data
+#' @param tid Treatment label
 #'
 #' @return Value
 #' @export
 #'
-trial_treatment_effect <- function(x, k) {
-  var_string <- glue::glue("log(x$y.{k}.sum*(x$N.{k} - x$y.{k}.sum))")
+trial_treatment_effect <- function(ald, tid) {
+  var_string <- glue::glue("log(ald$y.{tid}.sum*(ald$N.{tid} - ald$y.{tid}.sum))")
   eval(parse(text = var_string))
 }
 
 
-#' Aggregate-level data statistics
+#' Aggregate-level data mean and variance statistics
 #'
-#' @param data Data
-#' @param trials Trial labels; default `B`, `C`
+#' @param ald Aggregate-level trial data
+#' @param treatments Treatment labels; default `B`, `C`
 #'
-#' @return List of marginal treatment effect and variance
+#' @return List of marginal treatment effect mean and variance
+#' @seealso [marginal_treatment_effect()], [marginal_variance()]
 #' @export
 #'
-ALD_stats <- function(data, trials = list("B", "C")) {
-  list(mean = marginal_treatment_effect(data, trials),
-       var = marginal_variance(data, trials))
+ALD_stats <- function(ald, treatments = list("B", "C")) {
+  list(mean = marginal_treatment_effect(ald, treatments),
+       var = marginal_variance(ald, treatments))
 }