Title:	Regression-Based Causal Mediation Analysis with Interaction and Effect Modification Terms
Version:	1.0.1
Description:	This is an extension of the regression-based causal mediation analysis first proposed by Valeri and VanderWeele (2013) <doi:10.1037/a0031034> and Valeri and VanderWeele (2015) <doi:10.1097/EDE.0000000000000253>). It supports including effect measure modification by covariates(treatment-covariate and mediator-covariate product terms in mediator and outcome regression models) as proposed by Li et al (2023) <doi:10.1097/EDE.0000000000001643>. It also accommodates the original 'SAS' macro and 'PROC CAUSALMED' procedure in 'SAS' when there is no effect measure modification. Linear and logistic models are supported for the mediator model. Linear, logistic, loglinear, Poisson, negative binomial, Cox, and accelerated failure time (exponential and Weibull) models are supported for the outcome model.
License:	GPL-2
Encoding:	UTF-8
LazyData:	true
Imports:	Deriv, MASS, Matrix, assertthat, sandwich, survival
Suggests:	boot, furrr, future, geepack, knitr, mice, mitools, modelr, purrr, rlang, rmarkdown, stringr, testthat, tidyverse, magic, formattable, kableExtra
RoxygenNote:	7.2.3
VignetteBuilder:	knitr
URL:	https://kaz-yos.github.io/regmedint/
BugReports:	https://github.com/kaz-yos/regmedint/issues
Depends:	R (≥ 2.10)
NeedsCompilation:	no
Packaged:	2024-01-06 20:53:58 UTC; kazuki
Author:	Kazuki Yoshida [ctb, aut], Yi Li [cre, aut], Maya Mathur [ctb]
Maintainer:	Yi Li <yi.li10@mail.mcgill.ca>
Repository:	CRAN
Date/Publication:	2024-01-13 00:50:02 UTC

Create a vector of coefficients from the mediator model (mreg)

Description

This function extracts coef from mreg_fit and pads with zeros appropriately to create a named vector consistently having the following elements: (Intercept), avar, cvar (this part is eliminated when cvar = NULL), emm_ac_mreg (this part is eliminated when emm_ac_mreg = NULL).

Usage

beta_hat(mreg, mreg_fit, avar, cvar, emm_ac_mreg = NULL)

Arguments

Value

A named numeric vector of coefficients.

Return mediation analysis functions given mediator and outcome models specifications.

Description

This function returns functions that can be used to calculate the causal effect measures, given the mediator model fit (mreg_fit) and the outcome model fit (yreg_fit).

Usage

calc_myreg(
  mreg,
  mreg_fit,
  yreg,
  yreg_fit,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  interaction
)

Arguments

Value

A list containing two functions. The first is for calculating point estimates. The second is for calculating the correspoding

Create calculators for effects and se (mreg linear / yreg linear)

Description

Construct functions for the conditional effect estimates and their standard errors in the mreg linear / yreg linear setting. Internally, this function deconstructs model objects and feeds parameter estiamtes to the internal worker functions calc_myreg_mreg_linear_yreg_linear_est and calc_myreg_mreg_linear_yreg_linear_se.

Usage

calc_myreg_mreg_linear_yreg_linear(
  mreg,
  mreg_fit,
  yreg,
  yreg_fit,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  interaction
)

Arguments

Value

A list containing a function for effect estimates and a function for corresponding standard errors.

Create calculators for effects and se (mreg linear / yreg logistic)

Description

Construct functions for the conditional effect estimates and their standard errors in the mreg linear / yreg logistic setting. Internally, this function deconstructs model objects and feeds parameter estimates to the internal worker functions calc_myreg_mreg_linear_yreg_logistic_est and calc_myreg_mreg_linear_yreg_logistic_se.

Usage

calc_myreg_mreg_linear_yreg_logistic(
  mreg,
  mreg_fit,
  yreg,
  yreg_fit,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  interaction
)

Arguments

Value

A list containing a function for effect estimates and a function for corresponding standard errors.

Create calculators for effects and se (mreg logistic / yreg linear)

Description

Construct functions for the conditional effect estimates and their standard errors in the mreg logistic / yreg linear setting. Internally, this function deconstructs model objects and feeds parameter estimates to the internal worker functions calc_myreg_mreg_logistic_yreg_linear_est and calc_myreg_mreg_logistic_yreg_linear_se.

Usage

calc_myreg_mreg_logistic_yreg_linear(
  mreg,
  mreg_fit,
  yreg,
  yreg_fit,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  interaction
)

Arguments

Value

A list containing a function for effect estimates and a function for corresponding standard errors.

Create calculators for effects and se (mreg logistic / yreg logistic)

Description

Construct functions for the conditional effect estimates and their standard errors in the mreg logistic / yreg logistic setting. Internally, this function deconstructs model objects and feeds parameter estimates to the internal worker functions calc_myreg_mreg_logistic_yreg_logistic_est and calc_myreg_mreg_logistic_yreg_logistic_se.

Usage

calc_myreg_mreg_logistic_yreg_logistic(
  mreg,
  mreg_fit,
  yreg,
  yreg_fit,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  interaction
)

Arguments

Value

A list containing a function for effect estimates and a function for corresponding standard errors.

Extract point estimates.

Description

Extract point estimates evaluated at a0, a1, m_cde, and c_cond.

Usage

## S3 method for class 'regmedint'
coef(object, a0 = NULL, a1 = NULL, m_cde = NULL, c_cond = NULL, ...)

Arguments

Value

A numeric vector of point estimates.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
coef(regmedint_obj)
## Evaluate at different values
coef(regmedint_obj, m_cde = 0, c_cond = 1)

Extract the result matrix from a summary_regmedint object.

Description

Extract the result matrix from a summary_regmedint object.

Usage

## S3 method for class 'summary_regmedint'
coef(object, ...)

Arguments

Value

A matrix populated with results.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
coef(summary(regmedint_obj))

Confidence intervals for mediation prameter estimates.

Description

Construct Wald approximate confidence intervals for the quantities of interest.

Usage

## S3 method for class 'regmedint'
confint(
  object,
  parm = NULL,
  level = 0.95,
  a0 = NULL,
  a1 = NULL,
  m_cde = NULL,
  c_cond = NULL,
  ...
)

Arguments

Value

A numeric matrix of the lower limit and upper limit.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
confint(regmedint_obj)
## Evaluate at different values
confint(regmedint_obj, m_cde = 0, c_cond = 1)
## Change confidence level
confint(regmedint_obj, m_cde = 0, c_cond = 1, level = 0.99)

Fit a model for the mediator given the treatment and covariates.

Description

lm is called if mreg = "linear". glm is called with family = binomial() if mreg = "logistic".

Usage

fit_mreg(mreg, data, avar, mvar, cvar, emm_ac_mreg = NULL)

Arguments

Value

A regression object of class lm (linear) or glm (logistic)

Fit a model for the outcome given the treatment, mediator, and covariates.

Description

The outcome model type yreg can be one of the following "linear", "logistic", "loglinear" (implemented as modified Poisson), "poisson", "negbin", "survCox", "survAFT_exp", or "survAFT_weibull".

Usage

fit_yreg(
  yreg,
  data,
  yvar,
  avar,
  mvar,
  cvar,
  emm_ac_yreg = NULL,
  emm_mc_yreg = NULL,
  eventvar,
  interaction
)

Arguments

Details

The outcome regression functions to be called are the following:

• "linear" lm

• "logistic" glm

• "loglinear" glm (modified Poisson)

• "poisson" glm

• "negbin" glm.nb

• "survCox" coxph

• "survAFT_exp" survreg

• "survAFT_weibull" survreg

Value

Model fit object from on of the above regression functions.

Calculate the gradient of the proportion mediated for yreg linear.

Description

Calculate the gradient of the proportion mediated for yreg linear case.

Usage

grad_prop_med_yreg_linear(pnde, tnie)

Arguments

Value

A numeric vector of length two. Gradient of the proportion mediated with respect to pnde and tnie.

Calculate the gradient of the proportion mediated for yreg logistic.

Description

Calculate the gradient of the proportion mediated for yreg logistic case.

Usage

grad_prop_med_yreg_logistic(pnde, tnie)

Arguments

Value

A numeric vector of length two. Gradient of the proportion mediated with respect to pnde and tnie.

Low level constructor for a regmedint S3 class object.

Description

This is not a user function and meant to be executed within the regmedint function after validatingthe arguments.

Usage

new_regmedint(
  data,
  yvar,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  eventvar,
  a0,
  a1,
  m_cde,
  c_cond,
  yreg,
  mreg,
  interaction,
  casecontrol
)

Arguments

Value

A regmedint object.

print method for regmedint object

Description

Print the mreg_fit, yreg_fit, and the mediation analysis effect estimates.

Usage

## S3 method for class 'regmedint'
print(
  x,
  a0 = NULL,
  a1 = NULL,
  m_cde = NULL,
  c_cond = NULL,
  args_mreg_fit = list(),
  args_yreg_fit = list(),
  ...
)

Arguments

Value

Invisibly return the regmedint class object as is.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
## Implicit printing
regmedint_obj
## Explicit printing
print(regmedint_obj)
## Evaluate at different values
print(regmedint_obj, m_cde = 0, c_cond = 1)

Print method for summary objects from summary.regmedint

Description

Print results contained in a summary_regmedint object with additional explanation regarding the evaluation settings.

Usage

## S3 method for class 'summary_regmedint'
print(x, ...)

Arguments

Value

Invisibly return the first argument.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
## Implicit printing
summary(regmedint_obj)
## Explicit printing
print(summary(regmedint_obj))

Calculate the proportion mediated for yreg linear.

Description

Calculate the proportion mediated on the mean difference scale.

Usage

prop_med_yreg_linear(pnde, tnie)

Arguments

Value

Proportion mediated value.

Calculate the proportion mediated for yreg logistic.

Description

Calculate the approximate proportion mediated on the risk difference scale.

Usage

prop_med_yreg_logistic(pnde, tnie)

Arguments

Value

Proportion mediated value.

regmedint: A package for regression-based causal mediation analysis

Description

The package is an R implementation of regression-based closed-form causal mediation as originally described in Valeri & VanderWeele 2013 and Valeri & VanderWeele 2015 https://www.hsph.harvard.edu/tyler-vanderweele/tools-and-tutorials/. The earlier version is a sister program of the SAS macro. The current extended version (version 1.0 and later) supports effect modification by covariates (treatment-covariate and mediator-covariate product terms) in mediator and outcome models.

This is a user-interface for regression-based causal mediation analysis as described in Valeri & VanderWeele 2013 and Valeri & VanderWeele 2015.

Usage

regmedint(
  data,
  yvar,
  avar,
  mvar,
  cvar,
  emm_ac_mreg = NULL,
  emm_ac_yreg = NULL,
  emm_mc_yreg = NULL,
  eventvar = NULL,
  a0,
  a1,
  m_cde,
  c_cond,
  mreg,
  yreg,
  interaction = TRUE,
  casecontrol = FALSE,
  na_omit = FALSE
)

Arguments

Value

regmedint object, which is a list containing the mediator regression object, the outcome regression object, and the regression-based mediation results.

Fitting models

Use the regmedint function to fit models and set up regression-based causal mediation analysis.

Examining results

Several methods are available to examine the regmedint object. print summary coef confint

Examples

library(regmedint)
data(vv2015)
regmedint_obj1 <- regmedint(data = vv2015,
                            ## Variables
                            yvar = "y",
                            avar = "x",
                            mvar = "m",
                            cvar = c("c"),
                            eventvar = "event",
                            ## Values at which effects are evaluated
                            a0 = 0,
                            a1 = 1,
                            m_cde = 1,
                            c_cond = 3,
                            ## Model types
                            mreg = "logistic",
                            yreg = "survAFT_weibull",
                            ## Additional specification
                            interaction = TRUE,
                            casecontrol = FALSE)
summary(regmedint_obj1)

regmedint_obj2 <- regmedint(data = vv2015,
                            ## Variables
                            yvar = "y",
                            avar = "x",
                            mvar = "m",
                            cvar = c("c"),
                            emm_ac_mreg = c("c"), 
                            emm_ac_yreg = c("c"), 
                            emm_mc_yreg = c("c"), 
                            eventvar = "event",
                            ## Values at which effects are evaluated
                            a0 = 0,
                            a1 = 1,
                            m_cde = 1,
                            c_cond = 3,
                            ## Model types
                            mreg = "logistic",
                            yreg = "survAFT_weibull",
                            ## Additional specification
                            interaction = TRUE,
                            casecontrol = FALSE)
summary(regmedint_obj2)

Report variables with missing data

Description

Report the number of missing observations for each variables of interest relevant for the analysis

Usage

report_missing(data, yvar, avar, mvar, cvar, eventvar)

Arguments

Value

No return value, called for side effects.

summary method for regmedint object

Description

Summarize the mreg_fit, yreg_fit, and the mediation analysis effect estimates.

Usage

## S3 method for class 'regmedint'
summary(
  object,
  a0 = NULL,
  a1 = NULL,
  m_cde = NULL,
  c_cond = NULL,
  args_mreg_fit = list(),
  args_yreg_fit = list(),
  exponentiate = FALSE,
  level = 0.95,
  ...
)

Arguments

Value

A summary_regmedint object, which is a list containing the summary objects of the mreg_fit and the yreg_fit as well as the mediation analysis results.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
## Detailed result with summary
summary(regmedint_obj)
## Add exponentiate results for non-linear outcome models
summary(regmedint_obj, exponentiate = TRUE)
## Evaluate at different values
summary(regmedint_obj, m_cde = 0, c_cond = 1)
## Change confidence level
summary(regmedint_obj, m_cde = 0, c_cond = 1, level = 0.99)

Summary with robust sandwich variance estimator for modified Poisson

Description

This is a version of summary.glm modified to use the robust variance estimator sandwich.

Usage

## S3 method for class 'regmedint_mod_poisson'
summary(object, ...)

Arguments

Value

An object of the class summary.glm

Create a vector of coefficients from the outcome model (yreg)

Description

This function extracts coef from yreg_fit and 3s with zeros appropriately to create a named vector consistently having the following elements: (Intercept) (a zero element is added for yreg = "survCox" for which no intercept is estimated (the baseline hazard is left unspecified)), avar, mvar, avar:mvar (a zero element is added when interaction = FALSE). cvar (this part is eliminated when cvar = NULL), emm_ac_yreg (this part is eliminated when emm_ac_yreg = NULL), emm_mc_yreg (this part is eliminated when emm_mc_yreg = NULL).

Usage

theta_hat(
  yreg,
  yreg_fit,
  avar,
  mvar,
  cvar,
  emm_ac_yreg = NULL,
  emm_mc_yreg = NULL,
  interaction
)

Arguments

Value

A named numeric vector of coefficients.

Validate arguments to regmedint before passing to other functions

Description

Internal functions (usually) do not validate arguments, thus, we need to make sure informative errors are raised when the arguments are not safe for subsequent computation.

Usage

validate_args(
  data,
  yvar,
  avar,
  mvar,
  cvar,
  emm_ac_mreg,
  emm_ac_yreg,
  emm_mc_yreg,
  eventvar,
  a0,
  a1,
  m_cde,
  c_cond,
  mreg,
  yreg,
  interaction,
  casecontrol
)

Arguments

Value

No return value, called for side effects.

Validate soundness of a regmedint object.

Description

Check the structure of a proposed regmedint object for soundness.

Usage

validate_regmedint(x)

Arguments

Value

No return value, called for side effects.

Extract variance estimates in the vcov form.

Description

Extract variance estimates evaluated at a0, a1, m_cde, and c_cond.

Usage

## S3 method for class 'regmedint'
vcov(object, a0 = NULL, a1 = NULL, m_cde = NULL, c_cond = NULL, ...)

Arguments

Value

A numeric matrix with the diagonals populated with variance estimates. Off-diagnonals are NA since these are not estimated.

Examples

library(regmedint)
data(vv2015)
regmedint_obj <- regmedint(data = vv2015,
                           ## Variables
                           yvar = "y",
                           avar = "x",
                           mvar = "m",
                           cvar = c("c"),
                           eventvar = "event",
                           ## Values at which effects are evaluated
                           a0 = 0,
                           a1 = 1,
                           m_cde = 1,
                           c_cond = 0.5,
                           ## Model types
                           mreg = "logistic",
                           yreg = "survAFT_weibull",
                           ## Additional specification
                           interaction = TRUE,
                           casecontrol = FALSE)
vcov(regmedint_obj)
## Evaluate at different values
vcov(regmedint_obj, m_cde = 0, c_cond = 1)

Robust sandwich variance estimator for modified Poisson

Description

Provide robust sandwich variance-covariance estimate using sandwich.

Usage

## S3 method for class 'regmedint_mod_poisson'
vcov(object, ...)

Arguments

Value

A variance-covariance matrix using the sandwich.

Example dataset from Valeri and VanderWeele 2015.

Description

An example dataset from Valeri and VanderWeele (2015) <doi:10.1097/EDE.0000000000000253>.

Usage

vv2015

Format

A tibble with 100 rows and 7 variables:

id

Positive integer id.

x

Binary treatment assignment variable.

m

Binary mediator variable.

y

Time to event outcome variable.

cens

Binary censoring indicator. Censored is 1.

c

Continuous confounder variable.

event

Binary event indicator. Event is 1.

Source

https://www.hsph.harvard.edu/tyler-vanderweele/tools-and-tutorials/