From f7186193fc3e1c4977f39400557b09c48820cb91 Mon Sep 17 00:00:00 2001 From: Nathan Green Date: Wed, 13 Dec 2023 17:49:36 +0000 Subject: [PATCH] work on the help documentation --- R/IPD_stats.R | 106 ++++++++++++++++++--------------- R/gcomp_ml.R | 22 ++++--- R/gcomp_stan.R | 7 ++- man/IPD_stats.Rd | 34 ++++++++--- man/gcomp_ml.boot.Rd | 8 +-- man/gcomp_ml_log_odds_ratio.Rd | 11 ++-- man/gcomp_stan.Rd | 7 ++- man/hat_Delta_stats.Rd | 11 +++- man/strategy.Rd | 45 +++++++++++--- 9 files changed, 161 insertions(+), 90 deletions(-) diff --git a/R/IPD_stats.R b/R/IPD_stats.R index 6f76486..96476ff 100644 --- a/R/IPD_stats.R +++ b/R/IPD_stats.R @@ -3,19 +3,33 @@ #' @rdname strategy #' -#' @section Matching-adjusted indirect comparison (MAIC): +#' @section Matching-adjusted indirect comparison (MAIC): +#' +#' MAIC is a form of non-parametric likelihood reweighting method +#' which allows the propensity score logistic +#' regression model to be estimated without IPD in the _AC_ population. +#' The mean outcomes \eqn{\mu_{t(AC)}} on treatment \eqn{t = A,B} in the _AC_ +#' target population are estimated by taking a weighted average of the +#' outcomes \eqn{Y} of the \eqn{N} individuals in arm \eqn{t} of the _AB_ population +#' #' Used to compare marginal #' treatment effects where there are cross-trial differences in effect modifiers #' and limited patient-level data. +#' +#' \deqn{ +#' \hat{Y}_{} = \frac{\sum_{i=1}^{N} Y_{it(AB)} w_{it}}{\sum _{i=1}^{N} w_{it}} +#' } +#' where the weight \eqn{w_{it}} assigned to the \eqn{i}-th individual receiving treatment +#' \eqn{t} is equal to the odds of being enrolled in the _AC_ trial vs the _AB_ trial. +#' #' #' The default formula is #' \deqn{ -#' y = X3 + X4 + trt*X1 + trt*X2 +#' y = X_3 + X_4 + \beta_{t}X_1 + \beta_{t}X_2 #' } #' -#' @param formula Linear regression formula object #' @param R The number of resamples used for the non-parametric bootstrap -#' @param ald Aggregate-level data +#' @param dat_ALD Aggregate-level data #' #' @return `maic` class object #' @export @@ -31,16 +45,27 @@ strategy_maic <- function(formula = as.formula("y ~ X3 + X4 + trt*X1 + trt*X2"), #' @rdname strategy #' -#' @section Simulated treatment comparison (STC): +#' @section Simulated treatment comparison (STC): #' Outcome regression-based method which targets a conditional treatment effect. +#' STC is a modification of the covariate adjustment method. +#' An outcome model is fitted using IPD in the _AB_ trial +#' +#' \deqn{ +#' g(\mu_{t(AB)}(X)) = \beta_0 + \beta_1^T X + (\beta_B + \beta_2^T X^{EM}) I(t=B) +#' } +#' where \eqn{\beta_0} is an intercept term, \eqn{\beta_1} is a vector of coefficients for +#' prognostic variables, \eqn{\beta_B} is the relative effect of treatment _B_ compared +#' to _A_ at \eqn{X=0}, \eqn{\beta_2} is a vector of coefficients for effect +#' modifiers \eqn{X^{EM}} subvector of the full covariate vector \eqn{X}), and +#' \eqn{\mu_{t(AB)}(X)} is the expected outcome of an individual assigned +#' treatment \eqn{t} with covariate values \eqn{X} which is transformed onto a +#' chosen linear predictor scale with link function \eqn{g(\cdot)}. #' #' The default formula is #' \deqn{ -#' y = X3 + X4 + trt*(X1 - mean(X1)) + trt*(X2 - mean(X2)) +#' y = X_3 + X_4 + \beta_t(X_1 - \bar{X_1}) + \beta_t(X_2 - \bar{X2}) #' } #' -#' @param formula Linear regression formula object -#' #' @return `stc` class object #' @export # @@ -58,10 +83,9 @@ strategy_stc <- function(formula = #' #' The default formula is #' \deqn{ -#' y = X3 + X4 + trt*X1 + trt*X2 +#' y = X_3 + X_4 + \beta_{t}X_1 + \beta_{t}X_2 #' } #' -#' @param formula Linear regression formula object #' @param R The number of resamples used for the non-parametric bootstrap #' #' @return `gcomp_ml` class object @@ -82,10 +106,8 @@ strategy_gcomp_ml <- function(formula = #' #' The default formula is #' \deqn{ -#' y = X3 + X4 + trt*X1 + trt*X2 +#' y = X_3 + X_4 + \beta_{t}X_1 + \beta_{t}X_2 #' } -#' -#' @param formula Linear regression formula object #' #' @return `gcomp_stan` class object #' @export @@ -102,9 +124,10 @@ strategy_gcomp_stan <- function(formula = #' @title New strategy objects #' #' @description -#' Create class for each approach +#' Create a type of strategy class for each modelling approach. #' -#' @param strategy Class name +#' @param strategy Class name from `strategy_maic`, `strategy_stc`, `strategy_gcomp_ml`, `strategy_gcomp_stan` +#' @param formula Linear regression `formula` object #' @param ... Additional arguments #' #' @export @@ -117,7 +140,7 @@ new_strategy <- function(strategy, ...) { #' @title Calculate the difference between treatments using all evidence #' #' @description -#' This is the main wrapper for `hat_Delta_stats()`. +#' This is the main, top-level wrapper for `hat_Delta_stats()`. #' #' \insertCite{RemiroAzocar2022}{mimR} #' @@ -172,14 +195,18 @@ hat_Delta_stats <- function(AC.IPD, BC.ALD, strategy, CI = 0.95, ...) { #' @name IPD_stats -#' @title Individual level data statistics +#' @title Calculate individual-level patient data statistics +#' +#' @description +#' Separate methods for each approach +#' MAIC, STC, G-computation via MLE or Bayesian inference. #' #' @param strategy A list corresponding to different approaches #' @template args-ipd #' @template args-ald #' @param ... Additional arguments #' -#' @return Mean and variance +#' @return Mean and variance values #' @export #' IPD_stats <- function(strategy, ipd, ald, ...) @@ -194,15 +221,9 @@ IPD_stats.default <- function() { #' @rdname IPD_stats -#' @title Matching-adjusted indirect comparison statistics -#' -#' @description -#' Marginal A vs C treatment effect estimates -#' using bootstrapping -#' -#' @param strategy A list corresponding to different approaches -#' @template args-ipd -#' @template args-ald +#' @section Matching-adjusted indirect comparison statistics: +#' Marginal _A_ vs _C_ treatment effect estimates +#' using bootstrapping sampling. #' #' @export #' @@ -225,16 +246,11 @@ IPD_stats.maic <- function(strategy, #' @rdname IPD_stats -#' @title Simulated treatment comparison statistics -#' -#' @description -#' IPD from the AC trial are used to fit a regression model describing the -#' observed outcomes `y` in terms of the relevant baseline characteristics `x` and -#' the treatment variable `z`. +#' @section Simulated treatment comparison statistics: +#' IPD from the _AC_ trial are used to fit a regression model describing the +#' observed outcomes \eqn{y} in terms of the relevant baseline characteristics `x` and +#' the treatment variable \eqn{z}. #' -#' @param strategy A list corresponding to different approaches -#' @template args-ipd -#' @template args-ald #' @export #' IPD_stats.stc <- function(strategy, @@ -252,18 +268,14 @@ IPD_stats.stc <- function(strategy, #' @rdname IPD_stats -#' @title G-computation maximum likelihood statistics -#' -#' @param strategy A list corresponding to different approaches -#' @template args-ipd -#' @template args-ald +#' @section G-computation maximum likelihood statistics: +#' Compute a non-parametric bootstrap with \eqn{R=1000} resamples. #' #' @export #' IPD_stats.gcomp_ml <- function(strategy, ipd, ald) { - # non-parametric bootstrap with 1000 resamples AC_maic_boot <- boot::boot(data = ipd, statistic = gcomp_ml.boot, R = strategy$R, @@ -275,11 +287,9 @@ IPD_stats.gcomp_ml <- function(strategy, #' @rdname IPD_stats -#' @title G-computation Bayesian statistics -#' -#' @param strategy A list corresponding to different approaches -#' @template args-ipd -#' @template args-ald +#' @section G-computation Bayesian statistics: +#' Using Stan, compute marginal log-odds ratio for _A_ vs _C_ for each MCMC sample +#' by transforming from probability to linear predictor scale #' #' @export #' @@ -289,8 +299,6 @@ IPD_stats.gcomp_stan <- function(strategy, ppv <- gcomp_stan(formula = strategy$formula, ipd = ipd, ald = ald) - # compute marginal log-odds ratio for A vs C for each MCMC sample - # by transforming from probability to linear predictor scale hat.delta.AC <- qlogis(rowMeans(ppv$y.star.A)) - qlogis(rowMeans(ppv$y.star.C)) diff --git a/R/gcomp_ml.R b/R/gcomp_ml.R index 3f24095..9fa1dcb 100644 --- a/R/gcomp_ml.R +++ b/R/gcomp_ml.R @@ -1,9 +1,11 @@ #' G-computation maximum likelihood bootstrap #' -#' @param data Data -#' @param indices Indices -#' @param formula Linear regression formula +#' 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"} #' #' @return Mean difference in expected log-odds #' @export @@ -17,13 +19,15 @@ gcomp_ml.boot <- function(data, indices, #' G-computation Maximum Likelihood Log-Odds Ratio #' -#' Marginal A vs. C log-odds ratio (mean difference in expected log-odds) -#' estimated by transforming from probability to linear predictor scale +#' Marginal _A_ vs _C_ log-odds ratio (mean difference in expected log-odds) +#' estimated by transforming from probability to linear predictor scale. +#' +#' \eqn{\log(\hat{\mu}_A/(1 - \hat{\mu}_A)) - \log(\hat{\mu}_C/(1 - \hat{\mu}_C))} #' #' @param formula Linear regression formula -#' @param dat Data +#' @param dat Trial data #' -#' @return \eqn{log(hat.mu.A/(1-hat.mu.A)) - log(hat.mu.C/(1-hat.mu.C))} +#' @return Difference of log-odds #' @export #' gcomp_ml_log_odds_ratio <- function(formula, dat) { @@ -77,8 +81,8 @@ gcomp_ml_log_odds_ratio <- function(formula, dat) { data.trtA <- data.trtC <- x_star # intervene on treatment while keeping set covariates fixed - data.trtA[[treat_name]] <- 1 # dataset where everyone receives treatment A - data.trtC[[treat_name]] <- 0 # dataset where all observations receive C + data.trtA[[treat_name]] <- 1 # dataset where all receive A + data.trtC[[treat_name]] <- 0 # dataset where all receive C # predict counterfactual event probs, conditional on treatment/covariates hat.mu.A.i <- predict(fit, type="response", newdata=data.trtA) diff --git a/R/gcomp_stan.R b/R/gcomp_stan.R index 34d22d1..683f5f3 100644 --- a/R/gcomp_stan.R +++ b/R/gcomp_stan.R @@ -1,11 +1,14 @@ #' G-computation using Stan #' -#' @param formula Linear regression formula object +#' Calculate draws of binary responses from posterior predictive distribution +#' from the Bayesian G-computation method and Hamiltonian Monte-Carlo. +#' +#' @param formula Linear regression formula object; default \eqn{y = X_3 + X_4 + \beta_t X_1 + \beta_t X_2} #' @template args-ipd #' @template args-ald #' -#' @return A list of `y.star.A` and `y.star.C` posterior predictions +#' @return A list of \eqn{y^*_A} and \eqn{y^*_C} posterior predictions #' @export #' gcomp_stan <- function(formula = as.formula("y ~ X3 + X4 + trt*X1 + trt*X2"), diff --git a/man/IPD_stats.Rd b/man/IPD_stats.Rd index b74e5e2..56b8aec 100644 --- a/man/IPD_stats.Rd +++ b/man/IPD_stats.Rd @@ -7,7 +7,7 @@ \alias{IPD_stats.stc} \alias{IPD_stats.gcomp_ml} \alias{IPD_stats.gcomp_stan} -\title{Individual level data statistics} +\title{Calculate individual-level patient data statistics} \usage{ IPD_stats(strategy, ipd, ald, ...) @@ -31,13 +31,33 @@ IPD_stats(strategy, ipd, ald, ...) \item{...}{Additional arguments} } \value{ -Mean and variance +Mean and variance values } \description{ -Marginal A vs C treatment effect estimates -using bootstrapping +Separate methods for each approach +MAIC, STC, G-computation via MLE or Bayesian inference. +} +\section{Matching-adjusted indirect comparison statistics}{ + +Marginal \emph{A} vs \emph{C} treatment effect estimates +using bootstrapping sampling. +} -IPD from the AC trial are used to fit a regression model describing the -observed outcomes \code{y} in terms of the relevant baseline characteristics \code{x} and -the treatment variable \code{z}. +\section{Simulated treatment comparison statistics}{ + +IPD from the \emph{AC} trial are used to fit a regression model describing the +observed outcomes \eqn{y} in terms of the relevant baseline characteristics \code{x} and +the treatment variable \eqn{z}. } + +\section{G-computation maximum likelihood statistics}{ + +Compute a non-parametric bootstrap with \eqn{R=1000} resamples. +} + +\section{G-computation Bayesian statistics}{ + +Using Stan, compute marginal log-odds ratio for \emph{A} vs \emph{C} for each MCMC sample +by transforming from probability to linear predictor scale +} + diff --git a/man/gcomp_ml.boot.Rd b/man/gcomp_ml.boot.Rd index 015914a..643f30e 100644 --- a/man/gcomp_ml.boot.Rd +++ b/man/gcomp_ml.boot.Rd @@ -11,15 +11,15 @@ gcomp_ml.boot( ) } \arguments{ -\item{data}{Data} +\item{data}{Trial data} -\item{indices}{Indices} +\item{indices}{Indices sampled from rows of \code{data}} -\item{formula}{Linear regression formula} +\item{formula}{Linear regression formula; default \eqn{y = X_3 + X_4 + \beta_t X_1 + \beta_t X_2"}} } \value{ Mean difference in expected log-odds } \description{ -G-computation maximum likelihood bootstrap +Using bootstrap resampling, calculates the log odds ratio } diff --git a/man/gcomp_ml_log_odds_ratio.Rd b/man/gcomp_ml_log_odds_ratio.Rd index 9cffca8..a2381a1 100644 --- a/man/gcomp_ml_log_odds_ratio.Rd +++ b/man/gcomp_ml_log_odds_ratio.Rd @@ -9,12 +9,15 @@ gcomp_ml_log_odds_ratio(formula, dat) \arguments{ \item{formula}{Linear regression formula} -\item{dat}{Data} +\item{dat}{Trial data} } \value{ -\eqn{log(hat.mu.A/(1-hat.mu.A)) - log(hat.mu.C/(1-hat.mu.C))} +Difference of log-odds } \description{ -Marginal A vs. C log-odds ratio (mean difference in expected log-odds) -estimated by transforming from probability to linear predictor scale +Marginal \emph{A} vs \emph{C} log-odds ratio (mean difference in expected log-odds) +estimated by transforming from probability to linear predictor scale. +} +\details{ +\eqn{\log(\hat{\mu}_A/(1 - \hat{\mu}_A)) - \log(\hat{\mu}_C/(1 - \hat{\mu}_C))} } diff --git a/man/gcomp_stan.Rd b/man/gcomp_stan.Rd index 578dad7..1c06292 100644 --- a/man/gcomp_stan.Rd +++ b/man/gcomp_stan.Rd @@ -7,15 +7,16 @@ gcomp_stan(formula = as.formula("y ~ X3 + X4 + trt*X1 + trt*X2"), ipd, ald) } \arguments{ -\item{formula}{Linear regression formula object} +\item{formula}{Linear regression formula object; default \eqn{y = X_3 + X_4 + \beta_t X_1 + \beta_t X_2}} \item{ipd}{Individual-level data} \item{ald}{Aggregate-level data} } \value{ -A list of \code{y.star.A} and \code{y.star.C} posterior predictions +A list of \eqn{y^*_A} and \eqn{y^*_C} posterior predictions } \description{ -G-computation using Stan +Calculate draws of binary responses from posterior predictive distribution +from the Bayesian G-computation method and Hamiltonian Monte-Carlo. } diff --git a/man/hat_Delta_stats.Rd b/man/hat_Delta_stats.Rd index c5956be..f4ed0bc 100644 --- a/man/hat_Delta_stats.Rd +++ b/man/hat_Delta_stats.Rd @@ -4,7 +4,7 @@ \alias{hat_Delta_stats} \title{Calculate the difference between treatments using all evidence} \usage{ -hat_Delta_stats(AC.IPD, BC.ALD, strategy, ...) +hat_Delta_stats(AC.IPD, BC.ALD, strategy, CI = 0.95, ...) } \arguments{ \item{AC.IPD}{Individual-level patient data. Suppose between studies A and C.} @@ -14,13 +14,18 @@ hat_Delta_stats(AC.IPD, BC.ALD, strategy, ...) \item{strategy}{Computation strategy function. These can be \code{strategy_maic()}, \code{strategy_stc()}, \code{strategy_gcomp_ml()} and \code{strategy_gcomp_stan()}} +\item{CI}{Confidence interval; between 0,1} + \item{...}{Additional arguments} } \value{ -List of statistics as a \code{mimR} class object +List of length 3 of statistics as a \code{mimR} class object. +Containing statistics between each pair of treatments. +These are the mean contrasts, variances and confidence intervals, +respectively. } \description{ -This is the main wrapper for \code{hat_Delta_stats()}. +This is the main, top-level wrapper for \code{hat_Delta_stats()}. \insertCite{RemiroAzocar2022}{mimR} } diff --git a/man/strategy.Rd b/man/strategy.Rd index a8b0480..e9f8708 100644 --- a/man/strategy.Rd +++ b/man/strategy.Rd @@ -29,15 +29,15 @@ strategy_gcomp_stan(formula = as.formula("y ~ X3 + X4 + trt*X1 + trt*X2")) new_strategy(strategy, ...) } \arguments{ -\item{formula}{Linear regression formula object} +\item{formula}{Linear regression \code{formula} object} \item{R}{The number of resamples used for the non-parametric bootstrap} -\item{strategy}{Class name} +\item{dat_ALD}{Aggregate-level data} -\item{...}{Additional arguments} +\item{strategy}{Class name from \code{strategy_maic}, \code{strategy_stc}, \code{strategy_gcomp_ml}, \code{strategy_gcomp_stan}} -\item{ald}{Aggregate-level data} +\item{...}{Additional arguments} } \value{ \code{maic} class object @@ -49,27 +49,54 @@ new_strategy(strategy, ...) \code{gcomp_stan} class object } \description{ -Create class for each approach +Create a type of strategy class for each modelling approach. } \section{Matching-adjusted indirect comparison (MAIC)}{ + +MAIC is a form of non-parametric likelihood reweighting method +which allows the propensity score logistic +regression model to be estimated without IPD in the \emph{AC} population. +The mean outcomes \eqn{\mu_{t(AC)}} on treatment \eqn{t = A,B} in the \emph{AC} +target population are estimated by taking a weighted average of the +outcomes \eqn{Y} of the \eqn{N} individuals in arm \eqn{t} of the \emph{AB} population + Used to compare marginal treatment effects where there are cross-trial differences in effect modifiers and limited patient-level data. +\deqn{ +\hat{Y}_{} = \frac{\sum_{i=1}^{N} Y_{it(AB)} w_{it}}{\sum _{i=1}^{N} w_{it}} +} +where the weight \eqn{w_{it}} assigned to the \eqn{i}-th individual receiving treatment +\eqn{t} is equal to the odds of being enrolled in the \emph{AC} trial vs the \emph{AB} trial. + The default formula is \deqn{ - y = X3 + X4 + trt*X1 + trt*X2 + y = X_3 + X_4 + \beta_{t}X_1 + \beta_{t}X_2 } } \section{Simulated treatment comparison (STC)}{ Outcome regression-based method which targets a conditional treatment effect. +STC is a modification of the covariate adjustment method. +An outcome model is fitted using IPD in the \emph{AB} trial + +\deqn{ +g(\mu_{t(AB)}(X)) = \beta_0 + \beta_1^T X + (\beta_B + \beta_2^T X^{EM}) I(t=B) +} +where \eqn{\beta_0} is an intercept term, \eqn{\beta_1} is a vector of coefficients for +prognostic variables, \eqn{\beta_B} is the relative effect of treatment \emph{B} compared +to \emph{A} at \eqn{X=0}, \eqn{\beta_2} is a vector of coefficients for effect +modifiers \eqn{X^{EM}} subvector of the full covariate vector \eqn{X}), and +\eqn{\mu_{t(AB)}(X)} is the expected outcome of an individual assigned +treatment \eqn{t} with covariate values \eqn{X} which is transformed onto a +chosen linear predictor scale with link function \eqn{g(\cdot)}. The default formula is \deqn{ - y = X3 + X4 + trt*(X1 - mean(X1)) + trt*(X2 - mean(X2)) + y = X_3 + X_4 + \beta_t(X_1 - \bar{X_1}) + \beta_t(X_2 - \bar{X2}) } } @@ -78,7 +105,7 @@ The default formula is The default formula is \deqn{ - y = X3 + X4 + trt*X1 + trt*X2 + y = X_3 + X_4 + \beta_{t}X_1 + \beta_{t}X_2 } } @@ -87,7 +114,7 @@ The default formula is The default formula is \deqn{ - y = X3 + X4 + trt*X1 + trt*X2 + y = X_3 + X_4 + \beta_{t}X_1 + \beta_{t}X_2 } }