exactmed {ExactMed}R Documentation

Exact Mediation Effects Computation (Binary Mediator)

Description

Relying on a regression-based approach, the exactmed() function calculates standard causal mediation effects when the outcome and the mediator are binary. More precisely, exactmed() uses a logistic regression specification for both the outcome and the mediator in order to compute exact conditional natural direct and indirect effects (see details in Samoilenko and Lefebvre, 2021). The function returns point and interval estimates for the conditional natural effects without making any assumption regarding the rareness or commonness of the outcome (hence the term exact). For completeness, exactmed() also calculates the conditional controlled direct effects at both values of the mediator. Natural and controlled effects estimates are reported using three different scales: odds ratio (OR), risk ratio (RR) and risk difference (RD). The interval estimates can be obtained either by the delta method or the bootstrap.

Usage

exactmed(
  data,
  a,
  m,
  y,
  a1,
  a0,
  m_cov = NULL,
  y_cov = NULL,
  m_cov_cond = NULL,
  y_cov_cond = NULL,
  adjusted = TRUE,
  interaction = TRUE,
  Firth = FALSE,
  boot = FALSE,
  nboot = 1000,
  bootseed = 1991,
  confcoef = 0.95,
  hvalue_m = NULL,
  hvalue_y = NULL,
  yprevalence = NULL
)

Arguments

data

A named data frame that includes the exposure, mediator and outcome variables as well as the covariates to be adjusted for in the models. The exposure can be either binary or continuous. If a covariate is categorical, it has to be included in the data frame as a factor, character or logical variable.

a

The name of the binary or continuous exposure variable.

m

The name of the binary mediator variable.

y

The name of the binary outcome variable.

a1

A value corresponding to the high level of the exposure.

a0

A value corresponding to the low level of the exposure.

m_cov

A vector containing the names of the adjustment variables (covariates) in the mediator model.

y_cov

A vector containing the names of the adjustment variables (covariates) in the outcome model.

m_cov_cond

A named vector (atomic vector or list) containing specific values for some or all of the adjustment covariates m_cov in the mediator model. Please consult the package vignette for details.

y_cov_cond

A named vector (atomic vector or list) containing specific values for some or all of the adjustment covariates y_cov in the outcome model. Please consult the package vignette for details.

adjusted

A logical variable specifying whether to obtain adjusted or unadjusted estimates. If adjusted = FALSE, vectors m_cov and y_cov are ignored by the procedure.

interaction

A logical variable specifying whether there is an exposure-mediator interaction term in the outcome model.

Firth

A logical variable specifying whether to compute conventional or penalized maximum likelihood estimates for the logistic regression models (see details).

boot

A logical value specifying whether the confidence intervals are obtained by the delta method or by percentile bootstrap.

nboot

The number of bootstrap replications used to obtain the confidence intervals if boot = TRUE. By default nboot = 1000.

bootseed

The value of the initial seed (positive integer) for random number generation if boot = TRUE.

confcoef

A number between 0 and 1 for the confidence coefficient (ex.: 0.95) of the interval estimates.

hvalue_m

The value corresponding to the high level of the mediator. If the mediator is already coded as a numerical binary variable taking 0 or 1 values, then by default hvalue_m = 1.

hvalue_y

The value corresponding to the high level of the outcome. If the outcome is already coded as a numerical binary variable taking 0 or 1 values, then by default hvalue_y = 1.

yprevalence

The prevalence of the outcome in the population (a number between 0 and 1). Option used when case-control data are used. The low level of the outcome is treated as the control level.

Details

By default, exactmed() reports mediation effects evaluated at the sample-specific mean values of the numerical covariates (including the dummy variables created internally by the function to represent the non-reference levels of the categorical covariates). In order to estimate mediation effects at specific values of some covariates (that is, stratum-specific effects), the user needs to provide named vectors m_cov_cond and/or y_cov_cond containing those values or levels. The adjustment covariates appearing in both m_cov and y_cov (common adjustment covariates) must have the same values; otherwise, exactmed()'s execution is aborted and an error message is displayed in the R console.

The Firth parameter allows to reduce the bias of the regression coefficients estimators when facing a problem of separation or quasi-separation. The bias reduction is achieved by the brglmFit fitting method of the brglm2 package. More precisely, estimates are obtained via penalized maximum likelihood with a Jeffreys prior penalty, which is equivalent to the mean bias-reducing adjusted score equation approach in Firth (1993).

When the data come from a case-control study, the yprevalence parameter should be used and its value ideally correspond to the true outcome prevalence. exactmed() accounts for the ascertainment in the sample by employing weighted regression techniques that use inverse probability weighting (IPW) with robust standard errors. These errors are obtained via the vcovHC function of the R package sandwich. Specifically, we use the HC3 type covariance matrix estimator (default type of the vcovHC function).

For the mediation effects expressed on the multiplicative scales (odds ratio, OR; risk ratio, RR), the exactmed() function returns delta method confidence intervals by exponentiating the lower and upper limits of the normal confidence intervals obtained for the logarithmic transformations of the effects. The exactmed() function also provides the estimated standard errors of natural and controlled direct effects estimators that are not log-transformed, where those are derived using a first order Taylor expansion (e.g., \hat{SE}(\hat{OR})=\hat{OR} \times \hat{SE}(\log(\hat{OR}))). The function performs Z-tests (null hypothesis: there is no effect) computing the corresponding two-tailed p-values. Note that for the multiplicative scales, the standard scores (test statistics) are obtained by dividing the logarithm of an effect estimator by the estimator of the corresponding standard error (e.g., \log(\hat{OR}) / \hat{SE}(\log(\hat{OR}))). No log-transformation is applied when working on the risk difference scale.

Value

An object of class results is returned:

ne.or

Natural effects estimates on OR scale.

ne.rr

Natural effects estimates on RR scale.

ne.rd

Natural effects estimates on RD scale.

cdem0

Controlled direct effect (m=0) estimates.

cdem1

Controlled direct effect (m=1) estimates.

med.reg

Summary of the mediator regression.

out.reg

Summary of the outcome regression.

If boot==TRUE, the returned object also contains:

boot.ne.or

Bootstrap replications of natural effects on OR scale.

boot.ne.rr

Bootstrap replications of natural effects on RR scale.

boot.ne.rd

Bootstrap replications of natural effects on RD scale.

boot.cdem0.or

Bootstrap replications of controlled direct effect (m=0) on OR scale.

boot.cdem0.rr

Bootstrap replications of controlled direct effect (m=0) on RR scale.

boot.cdem0.rd

Bootstrap replications of controlled direct effect (m=0) on RD scale.

boot.cdem1.or

Bootstrap replications of controlled direct effect (m=1) on OR scale.

boot.cdem1.rr

Bootstrap replications of controlled direct effect (m=1) on RR scale.

boot.cdem1.rd

Bootstrap replications of controlled direct effect (m=1) on RD scale.

boot.ind

Indices of the observations sampled in each bootstrap replication (one replication per column).

Note

The exactmed() function only works for complete data. Users can apply multiple imputation techniques (e.g., R package mice) or remove observations of variables used in mediation analysis that have missing values (NA).

References

Samoilenko M, Blais L, Lefebvre G. Comparing logistic and log-binomial models for causal mediation analyses of binary mediators and rare binary outcomes: evidence to support cross-checking of mediation results in practice. Observational Studies.2018;4(1):193-216. doi:10.1353/obs.2018.0013.

Samoilenko M, Lefebvre G. Parametric-regression-based causal mediation analysis of binary outcomes and binary mediators: moving beyond the rareness or commonness of the outcome. American Journal of Epidemiology.2021;190(9):1846-1858. doi:10.1093/aje/kwab055.

Samoilenko M, Lefebvre G. An exact regression-based approach for the estimation of the natural direct and indirect effects with a binary outcome and a continuous mediator. Statistics in Medicine.2023; 42(3): 353–387. doi:10.1002/sim.9621.

Firth D. Bias reduction of maximum likelihood estimates. Biometrika.1993;80:27-38. doi:10.2307/2336755.

Examples

exactmed(
  data = datamed, a = "X", m = "M", y = "Y", a1 = 1, a0 = 0,
  m_cov = c("C1", "C2"), y_cov = c("C1", "C2")
)

exactmed(
  data = datamed, a = "X", m = "M", y = "Y", a1 = 1, a0 = 0,
  m_cov = c("C1", "C2"), y_cov = c("C1", "C2"), yprevalence = 0.1
)

m_cov_cond <- c(C1 = 0.1, C2 = 0.4)
y_cov_cond <- c(C1 = 0.1, C2 = 0.4)

exactmed(
  data = datamed, a = "X", m = "M", y = "Y", a1 = 1, a0 = 0,
  m_cov = c("C1", "C2"), y_cov = c("C1", "C2"),
  m_cov_cond = m_cov_cond, y_cov_cond = y_cov_cond
)

C1b <- factor(sample(c("a", "b", "c"), nrow(datamed), replace = TRUE))
datamed$C1 <- C1b

m_cov_cond <- list(C1 = "c", C2 = 0.4)
y_cov_cond <- list(C1 = "c", C2 = 0.4)

exactmed(
  data = datamed, a = "X", m = "M", y = "Y", a1 = 1, a0 = 0,
  m_cov = c("C1", "C2"), y_cov = c("C1", "C2"),
  m_cov_cond = m_cov_cond, y_cov_cond = y_cov_cond
)

[Package ExactMed version 0.3.0 Index]