Package 'messi' reference manual

Title:	Mediation with External Summary Statistic Information
Description:	Fits the MESSI, hard constraint, and unconstrained models in Boss et al. (2023) <doi:10.48550/arXiv.2306.17347> for mediation analyses with external summary-level information on the total effect.
Authors:	Jonathan Boss [aut], Bhramar Mukherjee [aut], Michael Kleinsasser [cre]
Maintainer:	Michael Kleinsasser <[email protected]>
License:	GPL-2
Version:	0.1.2
Built:	2025-01-06 15:36:29 UTC
Source:	https://github.com/umich-cphds/messi

Estimate hard constraint model parameters using cyclical coordinate descent.

Description

Estimate hard constraint model parameters using cyclical coordinate descent.

Usage

constrained.unpenalized(
  Y,
  M,
  A,
  C = NULL,
  T.hat.external,
  err.tol.out = 1e-08,
  err.tol.med = 1e-08,
  max.itr = 10000
)
constrained.unpenalized(
  Y,
  M,
  A,
  C = NULL,
  T.hat.external,
  err.tol.out = 1e-08,
  err.tol.med = 1e-08,
  max.itr = 10000
)

Arguments

`Y`	A (n x 1) continuous outcome vector.
`M`	A (n x p_m) matrix of mediators.
`A`	A (n x 1) vector of exposures.
`C`	A (n x p_c) matrix of confounders and adjustment covariates. If there are no confounders or adjustment covariates set C = NULL.
`T.hat.external`	External estimate of the total effect.
`err.tol.out`	Termination condition for cyclical coordinate descent algorithm with respect to the outcome model parameters.
`err.tol.med`	Termination condition for cyclical coordinate descent algorithm with respect to the mediator model parameters.
`max.itr`	Maximum number of iterations for cyclical coordinate descent algorithm.

Value

A list containing point estimates of the hard constraint model parameters and an indicator of whether the algorithm converges.

Simulated data with real mediation effect

Description

Simulated data with real mediation effect

Usage

Med
Med

Format

An object of class list of length 8.

Examples

data(Med)
data(Med)

Implementation of Mediation with External Summary Statistic Information (MESSI) from Boss et al. (2024).

Description

Implementation of Mediation with External Summary Statistic Information (MESSI) from Boss et al. (2024).

Usage

messi(
  Y,
  M,
  A,
  C = NULL,
  method = "MESSI EB",
  T.hat.external,
  var.T.hat.external,
  n.boot = 200,
  s2.fixed = NULL
)
messi(
  Y,
  M,
  A,
  C = NULL,
  method = "MESSI EB",
  T.hat.external,
  var.T.hat.external,
  n.boot = 200,
  s2.fixed = NULL
)

Arguments

`Y`	A (n x 1) continuous outcome vector.
`M`	A (n x p_m) matrix of mediators.
`A`	A (n x 1) vector of exposures.
`C`	A (n x p_c) matrix of confounders and adjustment covariates. If there are no confounders or adjustment covariates set C = NULL.
`method`	A string specifying which method to use. Options include 'Unconstrained', 'Hard', 'MESSI EB', and 'MESSI Fixed'. Default is 'MESSI EB'.
`T.hat.external`	External estimate of the total effect. Set to NULL if method = 'Unconstrained'.
`var.T.hat.external`	Estimated variance of the external estimator of the total effect. Set to NULL if method = 'Unconstrained' or method = 'Hard'.
`n.boot`	Number of parametric bootstrap draws for obtaining quantile-based confidence intervals for the TE and NDE. Relevant for method = 'MESSI EB' and method = 'MESSI Fixed'. Can set to NULL for method = 'Unconstrained' and method = 'Hard'.
`s2.fixed`	Option to specify the tuning parameter s^2 in the MESSI model. Only use if method = 'MESSI Fixed'.

Details

The MESSI EB method should be the default method if the user is not sure which method to use.

Value

A list containing the (1) point estimates and confidence intervals for the natural direct effect, the natural indirect effect, and the total effect (2) point estimates for all mediation model parameters (3) the asymptotic variance covariance matrix corresponding to alpha_a and beta_m.

Examples

data(Med)

Y = Med$Y
M = Med$M
A = Med$A
C = Med$C
T.hat.external = Med$T.hat.external
var.T.hat.external = Med$var.T.hat.external

test <- messi(Y = Y, M = M, A = A, C = C, method = 'Unconstrained', T.hat.external = T.hat.external,
              var.T.hat.external = var.T.hat.external, s2.fixed = NULL)

n = Med$n
p = Med$p

plot_messi(n = n, alpha.a.hat = test$alpha.a.hat, beta.m.hat = test$beta.m.hat, 
           labels = paste0("M",1:p), asym.var.mat = test$asym.var.mat)
              
test <- messi(Y = Y, M = M, A = A, C = C, method = 'Hard', T.hat.external = T.hat.external,
              var.T.hat.external = var.T.hat.external, s2.fixed = NULL)

data(Med)

Y = Med$Y
M = Med$M
A = Med$A
C = Med$C
T.hat.external = Med$T.hat.external
var.T.hat.external = Med$var.T.hat.external

test <- messi(Y = Y, M = M, A = A, C = C, method = 'Unconstrained', T.hat.external = T.hat.external,
              var.T.hat.external = var.T.hat.external, s2.fixed = NULL)

n = Med$n
p = Med$p

plot_messi(n = n, alpha.a.hat = test$alpha.a.hat, beta.m.hat = test$beta.m.hat, 
           labels = paste0("M",1:p), asym.var.mat = test$asym.var.mat)
              
test <- messi(Y = Y, M = M, A = A, C = C, method = 'Hard', T.hat.external = T.hat.external,
              var.T.hat.external = var.T.hat.external, s2.fixed = NULL)

Simulated data with null mediation effect

Description

Simulated data with null mediation effect

Usage

nullMed
nullMed

Format

An object of class list of length 4.

Examples

data(nullMed)
data(nullMed)

Forestplot to Summarize Estimation and Inference on alpha_a and beta_m.

Description

Forestplot to Summarize Estimation and Inference on alpha_a and beta_m.

Usage

plot_messi(n, alpha.a.hat, beta.m.hat, labels, asym.var.mat)
plot_messi(n, alpha.a.hat, beta.m.hat, labels, asym.var.mat)

Arguments

`n`	Sample size of the analysis
`alpha.a.hat`	Estimate of alpha_a, a (p_m x 1) vector.
`beta.m.hat`	Estimate of beta_m, a (p_m x 1) vector.
`labels`	A (p_m x 1) vector of mediator names. Make sure that the labels are in the same order as the mediators appear in the design matrix.
`asym.var.mat`	Joint asymptotic variance-covariance matrix of alpha_a and beta_m, a (2p_m x 2p_m) matrix.

Value

Data frames and forestplots summarizing alpha_a and beta_m estimation.

Examples

data(Med)

Y = Med$Y
M = Med$M
A = Med$A
C = Med$C
T.hat.external = Med$T.hat.external
var.T.hat.external = Med$var.T.hat.external

test <- messi(Y = Y, M = M, A = A, C = C, method = 'Unconstrained', T.hat.external = T.hat.external,
              var.T.hat.external = var.T.hat.external, s2.fixed = NULL)

n = Med$n
p = Med$p

plot_messi(n = n, alpha.a.hat = test$alpha.a.hat, beta.m.hat = test$beta.m.hat, 
           labels = paste0("M",1:p), asym.var.mat = test$asym.var.mat)


data(Med)

Y = Med$Y
M = Med$M
A = Med$A
C = Med$C
T.hat.external = Med$T.hat.external
var.T.hat.external = Med$var.T.hat.external

test <- messi(Y = Y, M = M, A = A, C = C, method = 'Unconstrained', T.hat.external = T.hat.external,
              var.T.hat.external = var.T.hat.external, s2.fixed = NULL)

n = Med$n
p = Med$p

plot_messi(n = n, alpha.a.hat = test$alpha.a.hat, beta.m.hat = test$beta.m.hat, 
           labels = paste0("M",1:p), asym.var.mat = test$asym.var.mat)

Cyclical coordinate descent algorithm for the M-step in the EM Algorithm for the maximizing the soft constraint model likelihood.

Description

Cyclical coordinate descent algorithm for the M-step in the EM Algorithm for the maximizing the soft constraint model likelihood.

Usage

rand.eff.coord.desc.unpenalized(
  Y,
  M,
  A,
  C = NULL,
  first.moment,
  second.moment,
  err.tol.out = 1e-08,
  err.tol.med = 1e-08,
  max.itr = 10000
)
rand.eff.coord.desc.unpenalized(
  Y,
  M,
  A,
  C = NULL,
  first.moment,
  second.moment,
  err.tol.out = 1e-08,
  err.tol.med = 1e-08,
  max.itr = 10000
)

Arguments

`Y`	A (n x 1) continuous outcome vector.
`M`	A (n x p_m) matrix of mediators.
`A`	A (n x 1) vector of exposures.
`C`	A (n x p_c) matrix of confounders and adjustment covariates. If there are no confounders or adjustment covariates set C = NULL.
`first.moment`	Posterior expectation of the total effect parameter.
`second.moment`	Posterior expection of the squared total effect parameter.
`err.tol.out`	Termination condition for cyclical coordinate descent algorithm with respect to the outcome model parameters.
`err.tol.med`	Termination condition for cyclical coordinate descent algorithm with respect to the mediator model parameters.
`max.itr`	Maximum number of iterations for cyclical coordinate descent algorithm.

Value

A list containing point estimates of the soft constraint model parameters and an indicator of whether the algorithm converges.

Estimate soft constraint model parameters using the EM algorithm.

Description

Estimate soft constraint model parameters using the EM algorithm.

Usage

rand.eff.unpenalized(
  Y,
  M,
  A,
  C = NULL,
  rand.eff.mean,
  rand.eff.var,
  T.hat.external = T.hat.external,
  var.T.hat.external = var.T.hat.external,
  err.tol.out = 1e-08,
  err.tol.med = 1e-08,
  max.itr = 10000
)
rand.eff.unpenalized(
  Y,
  M,
  A,
  C = NULL,
  rand.eff.mean,
  rand.eff.var,
  T.hat.external = T.hat.external,
  var.T.hat.external = var.T.hat.external,
  err.tol.out = 1e-08,
  err.tol.med = 1e-08,
  max.itr = 10000
)

Arguments

`Y`	A (n x 1) continuous outcome vector.
`M`	A (n x p_m) matrix of mediators.
`A`	A (n x 1) vector of exposures.
`C`	A (n x p_c) matrix of confounders and adjustment covariates. If there are no confounders or adjustment covariates set C = NULL.
`rand.eff.mean`	Mean of the random effects distribution for the internal total effect parameter.
`rand.eff.var`	Variance of the random effects distribution for the internal total effect parameter.
`T.hat.external`	External estimate of the total effect.
`var.T.hat.external`	Estimated variance of the external total effect estimator.
`err.tol.out`	Termination condition for cyclical coordinate descent algorithm with respect to the outcome model parameters.
`err.tol.med`	Termination condition for cyclical coordinate descent algorithm with respect to the mediator model parameters.
`max.itr`	Maximum number of iterations for cyclical coordinate descent algorithm.

Value

A list containing point estimates of the soft constraint model parameters and an indicator of whether the algorithm converges.

Estimate unconstrained model parameters.

Description

Estimate unconstrained model parameters.

Usage

unconstrained.unpenalized(Y, M, A, C = NULL)
unconstrained.unpenalized(Y, M, A, C = NULL)

Arguments

`Y`	A (n x 1) continuous outcome vector.
`M`	A (n x p_m) matrix of mediators.
`A`	A (n x 1) vector of exposures.
`C`	A (n x p_c) matrix of confounders and adjustment covariates. If there are no confounders or adjustment covariates set C = NULL.

Value

A list containing point estimates of the unconstrained model parameters.

Package 'messi'

Help Index

Estimate hard constraint model parameters using cyclical coordinate descent.

Description

Usage

Arguments

Value

Simulated data with real mediation effect

Description

Usage

Format

Examples

Implementation of Mediation with External Summary Statistic Information (MESSI) from Boss et al. (2024).

Description

Usage

Arguments

Details

Value

Examples

Simulated data with null mediation effect

Description

Usage

Format

Examples

Forestplot to Summarize Estimation and Inference on alpha_a and beta_m.

Description

Usage

Arguments

Value

Examples

Cyclical coordinate descent algorithm for the M-step in the EM Algorithm for the maximizing the soft constraint model likelihood.

Description

Usage

Arguments

Value

Estimate soft constraint model parameters using the EM algorithm.

Description

Usage

Arguments

Value

Estimate unconstrained model parameters.

Description

Usage

Arguments

Value