unvs.med (version 1.1.0)

FormalEstmed: Formal Estimation for Causal Mediation Effects (The Main Function)

Description

This is the main function for causal mediation estimations. Users only need to call this function to estimate causal mediation effects, as it can automatically call other internal functions for the algorithm. This function provides estimates of various types of mediation effects on risk difference (RD), odds ratio (OR) and risk ratio (RR) scales in the returned object, in which a wide range of estimation details and model information are also included. This function is applicable to almost any type of mediator and outcome models and data structure, greatly increasing the efficiency of causal mediation analysis.

Usage

FormalEstmed (med_model, out_model, data, exposure, exp0=NULL, exp1=NULL,
mediator=NULL, outcome=NULL, med_type=NULL,out_type=NULL, cov_val=NULL,
boot_num=100, MT = TRUE, Cf_lv=0.95)

Value

This function returns a list object of class "unvs.med". The object encompasses the complete result of the estimates of various types of effects on risk difference (RD), odds ratio (OR) and risk ratio (RR) scales, the results of mom-parametric bootstrapping, model specifications and other detailed information. Users may conduct further analysis based on this object.

The function summary.unvs.med can be used to obtain the refined result of this returned object, The function plot.unvs.med can be used to obtain the visualized result of this returned object. The function um.test1 can be used to test the statistical difference of effects within one single estimation. The function um.test2 can be used to test the statistical difference of effects between two separate estimations.

Stat.RD, Stat.OR, Stat.RR

Statistics of the estimates of mediation effects on risk difference (RD), odds ratio (OR) and risk ratio (RR) scales.

Boot_result

results of the original non-parametric bootstrapping estimations of mediation effects risk difference (RD), odds ratio (OR) and risk ratio (RR) scales.

Function_call

user's code of calling function FormalEstmed().

Exposure

exposure in the analysis.

Mediator

mediator in the analysis.

Medaitor_type

mediator's type in the analysis.

Medaitor_model

mediator's model in the analysis. If involving moderated mediation, i.e., Covariates_cond is not NULL, then this returned mediator's model is different from the input one.

Outcome

outcome in the analysis.

Outcome_type

outcome's type in the analysis.

Outcome_model

outcome's model in the analysis. If involving moderated mediation, i.e., Covariates_cond is not NULL, then this returned outcome's model is different from the input one.

Covariates

covariates in the analysis.

Covariates_cond

conditions of the covariates in the analysis.

Data

dataframe used in the analysis. If involving moderated mediation, i.e., Covariates_cond is not NULL, then this returned dataframe is different from the input one.

Bootstrap_number

times of bootstrapping in the analysis.

Confidence_level

levels of confident interval in the analysis.

Arguments

med_model

a fitted model object for the mediator.

out_model

a fitted model object for the outcome.

data

a dataframe used in the analysis.

exposure

a character variable of the exposure's name. Must be specified by the user.

exp0

a numeric variable of the baseline level of the exposure.

exp1

a numeric variable of the new level of the exposure.

mediator

a character variable of the mediator's name. Identified automatically if not specified by the user.

outcome

a character variable of the outcome's name. Identified automatically if not specified by the user.

med_type

a character variable of the mediator's type. Identified automatically if not specified by the user.

out_type

a character variable of the outcome's type. Identified automatically if not specified by the user.

cov_val

a character variable of the conditions of the covariates. Each string (element) in the character variable is a logical statement, e.g., 'C1==5', 'C2>1', etc.

boot_num

the times of bootstrapping in the analysis. The default is 100.

MT

a logical value indicating whether the multi-threading process is activated. If TURE, activating max-1 cores. If FALSE, use the ordinary 'for' loop. The default is TRUE.

Cf_lv

a numeric variable of the confidence interval. The value is presented in decimal form, not percentage form. The default is 0.95.

Details

For continuous variables, mediator and outcome can be identified automatically by this function. However, when the mediator or outcome variable is not continuous, users should make sure the class of the variable is consistent both in the dataframe and in the models, otherwise, users should specify it manually, not automatically. For example, for a ordinal type of outcome variable, if users transfer it into a factor variable in the dataframe before building the model, outcome can be identified automatically. If users do not transfer it into a factor variable in advance, but only specify it as a factor within the model, e.g., polr(as.factor(outcome)~X1+X2+...), then outcome can not be identified automatically. Therefore we recommend users transfer the mediator and outcome variable properly in the dataframe before building models.

Examples

# \donttest{
############################################################
# Example 1.1: Continuous exposure and outcome; Binary mediator
############################################################
data(testdata)
med_model=glm(med~exp+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
out_model=lm(out~med*exp+C1+C2+C3, data=testdata) # Fitting outcome's model
r11 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp") # Running formal estimation via bootstrapping
summary(r11) # Viewing results in short form and on RD scales.

########
# the new level of the exposure at 3.5
# r11.1 and r11.2 are identical
r11.1 = FormalEstmed (med_model=med_model, out_model=out_model, data=testdata,
exposure = "exp", exp0 = 2.5)
summary(r11.1)
r11.2 = FormalEstmed (med_model=med_model, out_model=out_model, data=testdata,
exposure = "exp", exp0 = 2.5, exp1 = 3.5)
summary(r11.2)

# Setting the baseline level of the exposure at 5,
# the new level of the exposure at 7
r11.3 = FormalEstmed (med_model=med_model, out_model=out_model, data=testdata,
exposure = "exp", exp0 = 5, exp1 = 7)
summary(r11.3)

############################################################
# Example 1.2: Example 1.1 but considering moderated mediation
############################################################
data(testdata)
med_model=glm(med~exp*C1+C2+exp*C3, data=testdata, family=binomial) # Fitting mediator's model
out_model=lm(out~med*exp+exp*C1+C2+exp*C3, data=testdata) # Fitting outcome's model
r12 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp", cov_val=c("C1==1","C3>7")) # Conditional on C1 and C3.
summary(r12)

############################################################
# Example 1.3: Example 1.1 with more bootstrapping
############################################################
data(testdata)
med_model=glm(med~exp+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
out_model=lm(out~med*exp+C1+C2+C3, data=testdata) # Fitting outcome's model
r13 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp", boot=500) # Running formal estimation via bootstrapping
summary(r13) # Viewing results in short form and on RD scales.

############################################################
# Example 2.1: Continuous exposure; Binary mediator; Ordinal outcome
#############################################################'
library("MASS") # For ordinal logistic regression
data(testdata)
med_model=glm(med~exp+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
testdata$out2=as.factor(testdata$out2) # out2 is the outcome. Convert it into a factor.
out_model=polr(out2~med*exp+C1+C2+C3, data=testdata, method="logistic") # Fitting outcome's model.
r21 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp", boot=100) # Running formal estimation via bootstrapping.
summary(r21)

############################################################
# Example 2.2: Example 2.1 but considering moderated mediation
#############################################################'
library("MASS") # For ordinal logistic regression
data(testdata)
med_model=glm(med~exp+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
testdata$out2=as.factor(testdata$out2) # out2 is the outcome. Convert it into a factor.
out_model=polr(out2~med*exp+C1+C2+C3, data=testdata, method="logistic") # Fitting outcome's model.
r22 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp", boot=100, cov_val="C2>=50") # Solely conditioning on C2
summary(r22)

############################################################
# Example 3.1: Binary exposure (0 and 1); Binary mediator; continue outcome
#############################################################'
data(testdata)
med_model=glm(med~exp2+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
out_model=lm(out~med*exp2+C1+C2+C3, data=testdata) # Fitting outcome's model
r31 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp2") # Running formal estimation via bootstrapping
summary(r31) # Viewing results in short form and on RD scales.

############################################################
# Example 3.2: Binary exposure (male and female); Binary mediator; continue outcome
#############################################################'
data(testdata)
med_model=glm(med~exp3+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
out_model=lm(out~med*exp3+C1+C2+C3, data=testdata) # Fitting outcome's model
r32 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp3") # Running formal estimation via bootstrapping
summary(r32) # Viewing results in short form and on RD scales.

############################################################
# Example 3.3: Binary exposure (male and female); Binary mediator; continue outcome
#############################################################'
data(testdata)
testdata$exp3=as.factor(testdata$exp3) # The default level is c("female","male").
levels(testdata$exp3)=c("male","female") # Factor level: c("male","female").
med_model=glm(med~exp3+C1+C2+C3, data=testdata, family=binomial) # Fitting mediator's model
out_model=lm(out~med*exp3+C1+C2+C3, data=testdata) # Fitting outcome's model
r33 = FormalEstmed (med_model=med_model, out_model=out_model,
data=testdata, exposure = "exp3") # Running formal estimation via bootstrapping
summary(r33) # Viewing results in short form and on RD scales.
# }