Type:	Package
Title:	Causally Interpretable Meta-Analysis
Version:	0.1.3
Description:	Provides robust and efficient methods for estimating causal effects in a target population using a multi-source dataset, including those of Dahabreh et al. (2019) <doi:10.1111/biom.13716>, Robertson et al. (2021) <doi:10.48550/arXiv.2104.05905>, and Wang et al. (2024) <doi:10.48550/arXiv.2402.02684>. The multi-source data can be a collection of trials, observational studies, or a combination of both, which have the same data structure (outcome, treatment, and covariates). The target population can be based on an internal dataset or an external dataset where only covariate information is available. The causal estimands available are average treatment effects and subgroup treatment effects. See Wang et al. (2025) <doi:10.1017/rsm.2025.5> for a detailed guide on using the package.
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
Imports:	glmnet, metafor, nnet, progress, SuperLearner
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
RoxygenNote:	7.3.2
URL:	https://github.com/ly129/CausalMetaR, https://doi.org/10.1017/rsm.2025.5
BugReports:	https://github.com/ly129/CausalMetaR/issues
Depends:	R (≥ 2.10)
NeedsCompilation:	no
Packaged:	2025-04-11 01:12:19 UTC; Sean
Author:	Yi Lian [aut], Guanbo Wang [aut], Sean McGrath [aut, cre], Issa Dahabreh [aut]
Maintainer:	Sean McGrath <sean.mcgrath514@gmail.com>
Repository:	CRAN
Date/Publication:	2025-04-11 08:40:20 UTC

Estimating the Average Treatment Effect (ATE) in an external target population using multi-source data

Description

Doubly-robust and efficient estimator for the ATE in an external target population using multi-source data.

Usage

ATE_external(
  X,
  X_external,
  Y,
  S,
  A,
  cross_fitting = FALSE,
  replications = 10L,
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(),
  external_model_args = list(),
  outcome_model_args = list(),
  show_progress = TRUE
)

Arguments

Details

Data structure:

The multi-source dataset consists the outcome Y, source S, treatment A, and covariates X (n \times p) in the internal populations. The data sources can be trials, observational studies, or a combination of both.

The external dataset contains only covariates X_external (n_0 \times p).

Estimation of nuissance parameters:

The following models are fit:

• External model: q(X)=P(R=1|X), where R takes value 1 if the subject belongs to any of the internal dataset and 0 if the subject belongs to the external dataset

• Propensity score model: \eta_a(X)=P(A=a|X). We perform the decomposition P(A=a|X)=\sum_{s} P(A=a|X, S=s)P(S=s|X) and estimate P(A=1|X, S=s) (i.e., the treatment model) and P(S=s|X) (i.e., the source model).

• Outcome model: \mu_a(X)=E(Y|X, A=a)

The models are estimated by SuperLearner with the exception of the source model which is estimated by glmnet or nnet.

ATE estimation:

The ATE estimator is

\dfrac{\widehat \kappa}{N}\sum\limits_{i=1}^{N} \Bigg[ I(R_i = 0) \widehat \mu_a(X_i) +I(A_i = a, R_i=1) \dfrac{1-\widehat q(X_i)}{\widehat \eta_a(X_i)\widehat q(X_i)} \Big\{ Y_i - \widehat \mu_a(X_i) \Big\} \Bigg],

where N=n+n_0, and \widehat \kappa=\{N^{-1} \sum_{i=1}^N I(R_i=0)\}^{-1}.

This estimator is doubly robust and non-parametrically efficient. To achieve non-parametric efficiency and asymptotic normality, it requires that ||\widehat \mu_a(X) -\mu_a(X)||\big\{||\widehat \eta_a(X) -\eta_a(X)||+||\widehat q(X) -q(X)||\big\}=o_p(n^{-1/2}). In addition, sample splitting and cross-fitting can be performed to avoid the Donsker class assumption.

When a data source is a randomized trial, it is still recommended to estimate the propensity score for optimal efficiency.

Value

An object of class "ATE_external". This object is a list with the following elements:

References

Dahabreh, I.J., Robertson, S.E., Petito, L.C., Hernán, M.A. and Steingrimsson, J.A. (2019) Efficient and robust methods for causally interpretable meta‐analysis: Transporting inferences from multiple randomized trials to a target population, Biometrics.

Wang, G., McGrath, S., and Lian, Y. (In press) CausalMetaR: An R package for performing causally interpretable meta-analyses, Research Synthesis Methods.

Examples

ae <- ATE_external(
  X = dat_multisource[, 1:10],
  Y = dat_multisource$Y,
  S = dat_multisource$S,
  A = dat_multisource$A,
  X_external = dat_external[, 1:10],
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  external_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)

Estimating the Average Treatment Effect (ATE) in an internal target population using multi-source data

Description

Doubly-robust and efficient estimator for the ATE in each internal target population using multi-source data.

Usage

ATE_internal(
  X,
  Y,
  S,
  A,
  cross_fitting = FALSE,
  replications = 10L,
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(),
  outcome_model_args = list(),
  show_progress = TRUE
)

Arguments

Details

Data structure:

The multi-source dataset consists the outcome Y, source S, treatment A, and covariates X (n \times p) in the internal populations. The data sources can be trials, observational studies, or a combination of both.

Estimation of nuissance parameters:

The following models are fit:

• Propensity score model: \eta_a(X)=P(A=a|X). We perform the decomposition P(A=a|X)=\sum_{s} P(A=a|X, S=s)P(S=s|X) and estimate P(A=1|X, S=s) (i.e., the treatment model) and q_s(X)=P(S=s|X) (i.e., the source model).

• Outcome model: \mu_a(X)=E(Y|X, A=a)

The models are estimated by SuperLearner with the exception of the source model which is estimated by glmnet or nnet.

ATE estimation:

The ATE estimator is

\dfrac{\widehat \kappa}{n}\sum\limits_{i=1}^{n} \Bigg[ I(S_i = s) \widehat \mu_a(X_i) +I(A_i = a) \dfrac{\widehat q_{s}(X_i)}{\widehat \eta_a(X_i)} \Big\{ Y_i - \widehat \mu_a(X_i) \Big\} \Bigg],

where \widehat \kappa=\{n^{-1} \sum_{i=1}^n I(S_i=s)\}^{-1}. The estimator is doubly robust and non-parametrically efficient.

To achieve non-parametric efficiency and asymptotic normality, it requires that ||\widehat \mu_a(X) -\mu_a(X)||\big\{||\widehat \eta_a(X) -\eta_a(X)||+||\widehat q_s(X) -q_s(X)||\big\}=o_p(n^{-1/2}). In addition, sample splitting and cross-fitting can be performed to avoid the Donsker class assumption.

When a data source is a randomized trial, it is still recommended to estimate the propensity score for optimal efficiency.

Value

An object of class "ATE_internal". This object is a list with the following elements:

References

Robertson, S.E., Steingrimsson, J.A., Joyce, N.R., Stuart, E.A. and Dahabreh, I.J. (2021). Center-specific causal inference with multicenter trials: Reinterpreting trial evidence in the context of each participating center. arXiv preprint arXiv:2104.05905.

Wang, G., McGrath, S., and Lian, Y. (In press) CausalMetaR: An R package for performing causally interpretable meta-analyses, Research Synthesis Methods.

Examples

ai <- ATE_internal(
  X = dat_multisource[, 1:10],
  Y = dat_multisource$Y,
  S = dat_multisource$S,
  A = dat_multisource$A,
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)

Estimating the Subgroup Treatment Effect (STE) in an external target population using multi-source data

Description

Doubly-robust and efficient estimator for the STE in an external target population using multi-source data.

Usage

STE_external(
  X,
  X_external,
  EM,
  EM_external,
  Y,
  S,
  A,
  cross_fitting = FALSE,
  replications = 10L,
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(),
  external_model_args = list(),
  outcome_model_args = list(),
  show_progress = TRUE
)

Arguments

Details

Data structure:

The multi-source dataset consists the outcome Y, source S, treatment A, covariates X (n \times p), and effect modifier EM in the internal populations. The data sources can be trials, observational studies, or a combination of both.

The external dataset contains only covariates X_external (n_0 \times p) and the effect modifier EM_external.

Estimation of nuissance parameters:

The following models are fit:

• External model: q(X)=P(R=1|X), where R takes value 1 if the subject belongs to any of the internal dataset and 0 if the subject belongs to the external dataset

• Propensity score model: \eta_a(X)=P(A=a|X). We perform the decomposition P(A=a|X)=\sum_{s} P(A=a|X, S=s)P(S=s|X) and estimate P(A=1|X, S=s) (i.e., the treatment model) and P(S=s|X) (i.e., the source model).

• Outcome model: \mu_a(X)=E(Y|X, A=a)

The models are estimated by SuperLearner with the exception of the source model which is estimated by glmnet or nnet.

STE estimation:

The estimator is

\dfrac{\widehat \kappa}{N}\sum\limits_{i=1}^{N} \Bigg[ I(R_i = 0) \widehat \mu_a(X_i) +I(A_i = a, R_i=1) \dfrac{1-\widehat q(X_i)}{\widehat \eta_a(X_i)\widehat q(X_i)} \Big\{ Y_i - \widehat \mu_a(X_i) \Big\} \Bigg],

where N=n+n_0, \widehat \kappa=\{N^{-1} \sum_{i=1}^N I(R_i=0)\}^{-1}, and and \widetilde X denotes the effect modifier.

The estimator is doubly robust and non-parametrically efficient. To achieve non-parametric efficiency and asymptotic normality, it requires that ||\widehat \mu_a(X) -\mu_a(X)||\big\{||\widehat \eta_a(X) -\eta_a(X)||+||\widehat q(X) -q(X)||\big\}=o_p(n^{-1/2}). In addition, sample splitting and cross-fitting can be performed to avoid the Donsker class assumption.

When a data source is a randomized trial, it is still recommended to estimate the propensity score for optimal efficiency.

Value

An object of class "STE_external". This object is a list with the following elements:

References

Wang, G., Levis, A., Steingrimsson, J. and Dahabreh, I. (2024) Efficient estimation of subgroup treatment effects using multi-source data, arXiv preprint arXiv:2402.02684.

Wang, G., McGrath, S., and Lian, Y. (In press) CausalMetaR: An R package for performing causally interpretable meta-analyses, Research Synthesis Methods.

Examples

se <- STE_external(
  X = dat_multisource[, 2:10],
  Y = dat_multisource$Y,
  EM = dat_multisource$EM,
  S = dat_multisource$S,
  A = dat_multisource$A,
  X_external = dat_external[, 2:10],
  EM_external = dat_external$EM,
  cross_fitting = FALSE,
  source_model = "MN.nnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  external_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)

Estimating the Subgroup Treatment Effect (STE) in an internal target population using multi-source data

Description

Doubly-robust and efficient estimator for the STE in each internal target population using multi-source data.

Usage

STE_internal(
  X,
  Y,
  EM,
  S,
  A,
  cross_fitting = FALSE,
  replications = 10L,
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(),
  outcome_model_args = list(),
  show_progress = TRUE
)

Arguments

Details

Data structure:

The multi-source dataset consists the outcome Y, source S, treatment A, covariates X (n \times p), and effect modifier EM in the internal populations. The data sources can be trials, observational studies, or a combination of both.

Estimation of nuissance parameters:

The following models are fit:

• Propensity score model: \eta_a(X)=P(A=a|X). We perform the decomposition P(A=a|X)=\sum_{s} P(A=a|X, S=s)P(S=s|X) and estimate P(A=1|X, S=s) (i.e., the treatment model) and q_s(X)=P(S=s|X) (i.e., the source model).

• Outcome model: \mu_a(X)=E(Y|X, A=a)

The models are estimated by SuperLearner with the exception of the source model which is estimated by glmnet or nnet.

STE estimation:

The estimator is

\dfrac{\widehat \kappa}{n}\sum\limits_{i=1}^{n} \Bigg[ I(S_i = s, \widetilde X_i=\widetilde x) \widehat \mu_a(X_i) +I(A_i = a, \widetilde X_i=\widetilde x) \dfrac{\widehat q_{s}(X_i)}{\widehat \eta_a(X_i)} \Big\{ Y_i - \widehat \mu_a(X_i) \Big\} \Bigg],

where \widehat \kappa=\{n^{-1} \sum_{i=1}^n I(S_i=s, \widetilde X_i=\widetilde x)\}^{-1} and \widetilde X denotes the effect modifier.

The estimator is doubly robust and non-parametrically efficient. To achieve non-parametric efficiency and asymptotic normality, it requires that ||\widehat \mu_a(X) -\mu_a(X)||\big\{||\widehat \eta_a(X) -\eta_a(X)||+||\widehat q_s(X) -q_s(X)||\big\}=o_p(n^{-1/2}). In addition, sample splitting and cross-fitting can be performed to avoid the Donsker class assumption.

When a data source is a randomized trial, it is still recommended to estimate the propensity score for optimal efficiency.

Value

An object of class "STE_internal". This object is a list with the following elements:

References

Wang, G., Levis, A., Steingrimsson, J. and Dahabreh, I. (2024) Efficient estimation of subgroup treatment effects using multi-source data, arXiv preprint arXiv:2402.02684.

Wang, G., McGrath, S., and Lian, Y. (In press) CausalMetaR: An R package for performing causally interpretable meta-analyses, Research Synthesis Methods.

Examples

si <- STE_internal(
  X = dat_multisource[, 2:10],
  Y = dat_multisource$Y,
  EM = dat_multisource$EM,
  S = dat_multisource$S,
  A = dat_multisource$A,
  cross_fitting = FALSE,
  source_model = "MN.nnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)

External dataset

Description

Simulated external dataset.

Usage

dat_external

Format

A data frame with 10,083 rows and 13 columns. The columns are:

Multi-source dataset

Description

Simulated multi-source dataset consisting of 3 sources.

Usage

dat_multisource

Format

A data frame with 3,917 rows and 13 columns. The columns are:

Plot method for objects of class "ATE_internal"

Description

This function creates forest plots of objects of class "ATE_internal".

Usage

## S3 method for class 'ATE_internal'
plot(x, source_names, ...)

Arguments

Value

No value is returned.

See Also

ATE_internal

Examples

ai <- ATE_internal(
  X = dat_multisource[, 1:10],
  Y = dat_multisource$Y,
  S = dat_multisource$S,
  A = dat_multisource$A,
  source_model = "MN.glmnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)
plot(ai)

Plot method for objects of class "STE_internal"

Description

This function creates forest plots of objects of class "STE_internal".

Usage

## S3 method for class 'STE_internal'
plot(
  x,
  use_scb = FALSE,
  header = c("Source", "Subgroup", ifelse(use_scb, "Estimate [95% SCB]",
    "Estimate [95% CI]")),
  source_names,
  subgroup_names,
  ...
)

Arguments

Details

Note that users may need to custom set the argument ilab.xpos which specifies the position (along the x-axis) of the effect modifier header and subgroup labels. See forest.rma for further details.

Value

No value is returned.

See Also

STE_internal

Examples

si <- STE_internal(
  X = dat_multisource[, 2:10],
  Y = dat_multisource$Y,
  EM = dat_multisource$EM,
  S = dat_multisource$S,
  A = dat_multisource$A,
  cross_fitting = FALSE,
  source_model = "MN.nnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)
plot(si)

Print method for objects of class "ATE_internal", "ATE_external", "STE_internal", or "STE_external"

Description

Print method for objects of class "ATE_internal", "ATE_external", "STE_internal", or "STE_external"

Usage

## S3 method for class 'STE_internal'
print(x, digits = 4, ...)

## S3 method for class 'ATE_internal'
print(x, digits = 4, ...)

## S3 method for class 'STE_external'
print(x, digits = 4, ...)

## S3 method for class 'ATE_external'
print(x, digits = 4, ...)

Arguments

Value

No value is returned.

See Also

ATE_internal, ATE_external, STE_internal, STE_external

Examples

si <- STE_internal(
  X = dat_multisource[, 2:10],
  Y = dat_multisource$Y,
  EM = dat_multisource$EM,
  S = dat_multisource$S,
  A = dat_multisource$A,
  cross_fitting = FALSE,
  source_model = "MN.nnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)
print(si)

Summary method for objects of class "ATE_internal", "ATE_external", "STE_internal", or "STE_external"

Description

Summary method for objects of class "ATE_internal", "ATE_external", "STE_internal", or "STE_external"

Usage

## S3 method for class 'STE_internal'
summary(object, digits = 4, ...)

## S3 method for class 'STE_external'
summary(object, digits = 4, ...)

## S3 method for class 'ATE_external'
summary(object, digits = 4, ...)

## S3 method for class 'ATE_internal'
summary(object, digits = 4, ...)

Arguments

Value

No value is returned.

See Also

ATE_internal, ATE_external, STE_internal, STE_external

Examples

si <- STE_internal(
  X = dat_multisource[, 2:10],
  Y = dat_multisource$Y,
  EM = dat_multisource$EM,
  S = dat_multisource$S,
  A = dat_multisource$A,
  cross_fitting = FALSE,
  source_model = "MN.nnet",
  source_model_args = list(),
  treatment_model_type = "separate",
  treatment_model_args = list(
    family = binomial(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  ),
  outcome_model_args = list(
    family = gaussian(),
    SL.library = c("SL.glmnet", "SL.nnet", "SL.glm"),
    cvControl = list(V = 5L)
  )
)
summary(si)