Help for package multimediate

Title:

Causal Mediation Analysis in Presence of Multiple Mediators Uncausally Related

Version:

0.1.4

Description:

Estimates key quantities in causal mediation analysis - including average causal mediation effects (indirect effects), average direct effects, total effects, and proportions mediated - in the presence of multiple uncausally related mediators. Methods are described by Jérolon et al., (2021) <doi:10.1515/ijb-2019-0088> and extended to accommodate survival outcomes as described by Domingo-Relloso et al., (2024) <doi:10.1101/2024.02.16.24302923>.

License:

GPL-3

Encoding:

UTF-8

LazyData:

true

URL:

https://samarafk.github.io/multimediate/

Imports:

rmutil, MASS, mvtnorm, stats, graphics, timereg

Suggests:

knitr, rmarkdown

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-07-09 18:59:16 UTC; samara

Author:

Allan Jerolon [aut], Arce Domingo-Relloso [aut], Samara Kiihl [cre, aut], Maria Tellez-Plaza [aut]

Maintainer:

Samara Kiihl <samarak@unicamp.br>

Repository:

CRAN

Date/Publication:

2025-07-14 17:20:02 UTC

Toy dataset 1

Description

A toy dataset for causal mediation analysis with 3 uncausally related mediators.

Usage

data("data1")

Format

A data frame with 1000 observations on the following 8 variables.

Treatment: a factor with levels 0 1
C1: a factor with levels 0 1
C2: a factor with levels 0 1
C3: a factor with levels 0 1
M1: a numeric vector
M2: a numeric vector
M3: a numeric vector
Outcome: a numeric vector

Examples

#data(data1)
#data1$Treatment=as.factor(data1$Treatment)
#data1$C1=as.factor(data1$C1)
#data1$C2=as.factor(data1$C2)
#data1$C3=as.factor(data1$C3)
#data1$M1=as.numeric(data1$M1)
#data1$M2=as.numeric(data1$M2)
#data1$M3=as.numeric(data1$M3)
#data1$Outcome=as.numeric(data1$Outcome)
#summary(data1)

#M1reg=lm(M1~ Treatment + C1 + C2, data=data1)
#M2reg=lm(M2~ Treatment + C1 + C3, data=data1)
#M3reg=lm(M3~ Treatment + C1     , data=data1)

#Yreg=lm(Outcome~ Treatment + M1 + M2 + M3 + C1 + C2 + C3, data=data1)

#med.analysis=multimediate(lmodel.m=list(M1reg,M2reg,M3reg),
#correlated=TRUE,model.y=Yreg,treat="Treatment",
#treat.value=1,control.value=0,J=1000,conf.level=0.95)

#summary(med.analysis,opt="avg")

Toy dataset 2

Description

A toy dataset for causal mediation analysis with 3 uncausally related mediators.

Usage

data("data2")

Format

A data frame with 1000 observations on the following 8 variables.

Treatment: a factor with levels 0 1
C1: a factor with levels 0 1
C2: a factor with levels 0 1
C3: a factor with levels 0 1
M1: a numeric vector
M2: a numeric vector
M3: a numeric vector
Outcome: a factor with levels FALSE TRUE

Examples

#data(data2)
#data2$Treatment=as.factor(data2$Treatment)
#data2$C1=as.factor(data2$C1)
#data2$C2=as.factor(data2$C2)
#data2$C3=as.factor(data2$C3)
#data2$M1=as.numeric(data2$M1)
#data2$M2=as.numeric(data2$M2)
#data2$M3=as.numeric(data2$M3)
#data2$Outcome=as.factor(data2$Outcome)
#summary(data2)

#M1reg=lm(M1~ Treatment + C1, data=data2)
#M2reg=lm(M2~ Treatment + C2, data=data2)
#M3reg=lm(M3~ Treatment + C3, data=data2)

#Yreg=glm(Outcome~ Treatment + M1 + M2 + M3 + C1 + C2 + C3, data=data2, family = binomial("logit"))

#med.analysis=multimediate(lmodel.m=list(M1reg,M2reg,M3reg),
#correlated=TRUE,model.y=Yreg,treat="Treatment",
#treat.value=1,control.value=0,J=1000,conf.level=0.95)

# summary(med.analysis,opt="avg",logit="effects")
# summary(med.analysis,opt="avg",logit="OR")
# summary(med.analysis,opt="avg",logit="logOR")
# summary(med.analysis,opt="avg",logit="all")

Toy dataset 3

Description

A toy dataset for causal mediation analysis with 3 uncausally related mediators.

Usage

data("data3")

Format

A data frame with 1000 observations on the following 8 variables.

Treatment: a factor with levels 0 1
C1: a factor with levels 0 1
C2: a factor with levels 0 1
C3: a factor with levels 0 1
M1: a numeric vector
M2: a numeric vector
M3: a numeric vector
Outcome: a factor with levels 0 1 2 3

Examples

#data(data3)
#data3$Treatment=as.factor(data3$Treatment)
#data3$C1=as.factor(data3$C1)
#data3$C2=as.factor(data3$C2)
#data3$C3=as.factor(data3$C3)
#data3$M1=as.numeric(data3$M1)
#data3$M2=as.numeric(data3$M2)
#data3$M3=as.numeric(data3$M3)
#data3$Outcome=as.factor(data3$Outcome)

#summary(data3)

#M1reg=lm(M1~ Treatment + C1 + C3, data=data3)
#M2reg=lm(M2~ Treatment + C1 + C2, data=data3)
#M3reg=lm(M3~ Treatment + C2 + C3, data=data3)

#library(MASS)
#Yreg=polr(Outcome ~ Treatment + M1 + M2 + M3 + C1 + C2 + C3 , data = data3, method = "probit")

#med.analysis=multimediate(lmodel.m=list(M1reg,M2reg,M3reg),
#correlated=TRUE,model.y=Yreg,treat="Treatment",
#treat.value=1,control.value=0,J=100,conf.level=0.95)

#summary(med.analysis,opt="avg")

Toy dataset 4

Description

A toy dataset for causal mediation analysis with 3 uncausally related mediators.

Usage

data("data4")

Format

A data frame with 1000 observations on the following 8 variables.

Treatment: a numeric vector
C1: a factor with levels 0 1
C2: a factor with levels 0 1
C3: a factor with levels 0 1
M1: a numeric vector
M2: a factor with levels 0 1
M3: a factor with levels 0 1 2 3
Outcome: a numeric vector

Examples

#data(data4)
#data4$Treatment=as.factor(data4$Treatment)
#data4$C1=as.factor(data4$C1)
#data4$C2=as.factor(data4$C2)
#data4$C3=as.factor(data4$C3)
#data4$M1=as.numeric(data4$M1)
#data4$M3=as.factor(data4$M3)
#data4$M2=as.factor(data4$M2)
#data4$Outcome=as.numeric(data4$Outcome)
#summary(data4)

#M1reg=lm(M1~  Treatment + C1 + C2 + C3, data = data4)
#M2reg=glm(M2~ Treatment + C1 + C3, data = data4, family = binomial("probit"))
#M3reg=polr(M3~Treatment + C2 + C3     , data = data4, method = "probit")

#Yreg=lm(Outcome~ Treatment + M1 + M2 + M3 + C1 + C2 + C3, data=data4)

#med.analysis=multimediate(lmodel.m=list(M1reg,M2reg,M3reg),
#correlated=TRUE,model.y=Yreg,treat="Treatment",
#treat.value=1,control.value=0,J=1000,conf.level=0.95)

#summary(med.analysis,opt="avg")

Toy dataset 5

Description

A toy dataset for causal mediation analysis with 3 uncausally related mediators and survival outcome.

Usage

data("data4")

Format

A data frame with 3000 observations on the following 8 variables.

Exposure: a numeric vector
M1: a numeric vector
M2: a numeric vector
M3: a numeric vector
event: event
surv_time: time before event

Examples

#data(data5)
#modM1=lm(M1 ~ Exposure, data = data5)
#modM2=lm(M2 ~ Exposure, data = data5)
#modM3=lm(M3 ~ Exposure, data = data5)
#lmodel.m=list(modM1,modM2, modM3)
#model.y=aalen(Surv(surv_time, event) ~ const(Exposure) + const(M1) + const(M2)
#+ const(M3), data = data5, robust=T)
#multi.media=multimediate(lmodel.m,correlated=TRUE,model.y,treat='Exposure',
#treat.value=1,control.value=0,J=1000,conf.level=0.95,data=data5)
#summary(multi.media, opt='avg')

multimediate

Description

multimediate estimates several quantities in causal mediation analysis, including the average causal mediation effect (indirect effect), average direct effect, proportion mediated, and total effect, in the presence of multiple uncausally related mediators.

Usage

multimediate(
  lmodel.m,
  correlated = FALSE,
  model.y,
  treat,
  treat.value = 1,
  control.value = 0,
  J = 1000,
  conf.level = 0.95,
  fun = mean,
  data = NULL,
  peryr = 1e+05,
  verbose = TRUE
)

Arguments

lmodel.m

list of fitted models object for mediators. Can be of class 'lm', 'polr','glm'.

correlated

a logical value. if 'FALSE' a identity matrix is used for the matrix of correlation of mediators; if 'TRUE' matrix of correlation is estimated. Default is 'FALSE'.

model.y

a fitted model object for the outcome. Can be of class 'lm', 'polr','glm' or 'aalen'.

treat

a character string indicating the name of the treatment variable used in the models. The treatment can be either binary (integer or a two-valued factor) or continuous (numeric).

treat.value

value of the treatment variable used as the treatment condition. Default is 1.

control.value

value of the treatment variable used as the control condition. Default is 0.

J

number of Monte Carlo draws for quasi-Bayesian approximation.

conf.level

level of the returned two-sided confidence intervals. Default is to return the 2.5 and 97.5 percentiles of the simulated quantities.

fun

the function used to compute the point estimate of the effects of interest from its empirical distribution. The function mean or median can be used. Default is the function mean.

data

dataset with all variables used in the mediator and outcome models

peryr

the number of person-years to multiply the additive estimator to obtain results in scale of cases per person-years (only applicable to the survival outcome)

verbose

Logical. If 'TRUE' (default), messages and a progress bar are displayed during execution.

Details

For binary outcomes, it also estimates average causal mediation effects on the odds ratio (OR) and log-odds (logOR) scales.

For survival outcomes, multimediate additionally estimates average causal mediation effects on cases per person-year scale.

Value

multimediate returns an object of class mm, a list that contains at least the components listed below. The function summary (i.e., summary.mm) can be used to obtain a table of the results.

model.y: the fitted outcome model.
model.m: a list of fitted mediator models, one for each mediator.
treatment: a character string indicating the name of the treatment variable used in the models.
treat.value: value of the treatment variable used as the treatment condition.
control.value: value of the treatment variable used as the control condition.
sims: the number of Monte Carlo draws for quasi-Bayesian approximation.

References

Jérolon, A., Baglietto, L., Birmelé, E., Alarcon, F., & Perduca, V. (2021). Causal mediation analysis in presence of multiple mediators uncausally related. The International Journal of Biostatistics, 17(2), 191–221. doi:10.1515/ijb-2019-0088

Domingo-Relloso A, Jerolon A, Tellez-Plaza M, Bermudez JD. Causal mediation for uncausally related mediators in the context of survival analysis. medRxiv [Preprint]. 2024 Feb 18:2024.02.16.24302923. doi: 10.1101/2024.02.16.24302923

Examples

# Load example data
data(data1)
summary(data1)

# Fit mediator models
M1reg <- lm(M1 ~ Treatment + C1 + C2, data = data1)
M2reg <- lm(M2 ~ Treatment + C1 + C3, data = data1)
M3reg <- lm(M3 ~ Treatment + C1, data = data1)

# Fit outcome model
Yreg <- lm(Outcome ~ Treatment + M1 + M2 + M3 + C1 + C2 + C3, data = data1)

# Perform multiple mediation analysis (may take some time)

med.analysis <- multimediate(
  lmodel.m = list(M1reg, M2reg, M3reg),
  correlated = TRUE,
  model.y = Yreg,
  treat = "Treatment",
  treat.value = 1,
  control.value = 0,
  J = 250,
  conf.level = 0.95,
  verbose = FALSE
)

summary(med.analysis, opt = "avg")

multimediate_survival - internal function

Description

multimediate_survival - internal function

Usage

multimediate_survival(
  lmodel.m,
  correlated = FALSE,
  model.y,
  treat,
  treat.value = 1,
  control.value = 0,
  J = 1000,
  conf.level = 0.95,
  fun = mean,
  data = NULL,
  peryr = 1e+05,
  verbose = TRUE
)

Arguments

lmodel.m

A list of fitted mediator models ('lm', 'glm', or 'polr' objects).

correlated

a logical value. if 'FALSE' a identity matrix is used for the matrix of correlation of mediators; if 'TRUE' matrix of correlation is estimated. Default is 'FALSE'.

model.y

A fitted outcome model ('lm', 'glm', 'polr', or 'aalen' object).

treat

The name of the treatment variable (character).

treat.value

The value representing the treatment condition (default: 1).

control.value

The value representing the control condition (default: 0).

J

Number of Monte Carlo simulations for effect estimation (default: 1000).

conf.level

Confidence level for confidence intervals (default: 0.95).

fun

A summary function applied to the simulated effects (default: 'mean').

data

A data frame containing the variables used in the models.

peryr

Scaling factor for incidence rates per person-year (default: 100,000).

verbose

Logical. If 'TRUE' (default), messages and a progress bar are displayed during execution.

Value

A list containing estimated direct, indirect (mediated), and total effects, along with confidence intervals and p-values for each.

plot.mm

Description

plot.mm is used to display the results of the mediation analyzes done with multimediate.

Usage

## S3 method for class 'mm'
plot(
  x,
  treatment = NULL,
  logit = "logOR",
  labels = NULL,
  effect.type = c("indirect", "direct", "total"),
  xlim = NULL,
  ylim = NULL,
  xlab = "",
  ylab = "",
  main = "Estimates and confidence intervals",
  is.legend = TRUE,
  lwd = 1.5,
  cex = 0.85,
  col = "black",
  ...
)

Arguments

x

element of the class "mm".

treatment

a character string indicating the baseline treatment value of the estimated causal mediation effect and direct effect to plot. Can be either "control", "treated", "average" or "three". If "NULL"(default), three sets of estimates are plotted.

logit

a character string indicating, when the outcome is binary, the scale of the average causal effects. "effects" for average causal effects, " OR" average causal effects on OR scale, "logOR" average causal effects on logOR scale.

labels

a vector of character strings indicating the labels for estimated effects. The default labels wiil be used if NULL.

effect.type

a vector indicating which quantities of interest to plot. Default is to plot all three quantities (indirects, direct and total effects).

xlim

range of the horizontal axis.

ylim

range of the vertical axis.

xlab

label of the horizontal axis.

ylab

label of the vertical axis.

main

main title.

is.legend

a logical value indicating the presence of the legend on top right. If the legend obscures some results, is.legend can be switched to "FALSE" or the x-axis can be changed manually with the parameters xlim.

lwd

width of the horizontal bars for confidence intervals.

cex

size of the dots for point estimates.

col

color of the dots and horizontal bars for the estimates.

...

additional parameters passed to 'plot'.

Value

plot summarizing the causal analysis

summary.mm

Description

summary.mm is used to display the results of the mediation analyzes done with multimediate.

Usage

## S3 method for class 'mm'
summary(object, opt = "navg", logit = "all", ...)

Arguments

object

element of the class mm.

opt

a character string indicating the details of the analysis "navg" for the average causal effects for t=0,1 and "avg" for the average causal effects.

logit

...

additional arguments affecting the summary produced

Value

table summarizing the causal analysis