gformula_binary_eof | R Documentation |
Based on an observed data set, this internal function estimates the outcome probability at end-of-follow-up under multiple user-specified interventions using the parametric g-formula. See McGrath et al. (2020) for further details concerning the application and implementation of the parametric g-formula.
gformula_binary_eof(
obs_data,
id,
time_name,
covnames,
covtypes,
covparams,
covfits_custom = NA,
covpredict_custom = NA,
histvars = NULL,
histories = NA,
basecovs = NA,
censor_name = NULL,
censor_model = NA,
outcome_name,
ymodel,
ymodel_fit_custom = NULL,
ymodel_predict_custom = NULL,
intvars = NULL,
interventions = NULL,
int_times = NULL,
int_descript = NULL,
ref_int = 0,
visitprocess = NA,
restrictions = NA,
yrestrictions = NA,
baselags = FALSE,
nsimul = NA,
sim_data_b = FALSE,
seed,
nsamples = 0,
parallel = FALSE,
ncores = NA,
ci_method = "percentile",
threads,
model_fits = FALSE,
boot_diag = FALSE,
show_progress = TRUE,
ipw_cutoff_quantile = NULL,
ipw_cutoff_value = NULL,
int_visit_type = NULL,
sim_trunc = TRUE,
...
)
obs_data |
Data table containing the observed data. |
id |
Character string specifying the name of the ID variable in |
time_name |
Character string specifying the name of the time variable in |
covnames |
Vector of character strings specifying the names of the time-varying covariates in |
covtypes |
Vector of character strings specifying the "type" of each time-varying covariate included in |
covparams |
List of vectors, where each vector contains information for
one parameter used in the modeling of the time-varying covariates (e.g.,
model statement, family, link function, etc.). Each vector
must be the same length as |
covfits_custom |
Vector containing custom fit functions for time-varying covariates that
do not fall within the pre-defined covariate types. It should be in
the same order |
covpredict_custom |
Vector containing custom prediction functions for time-varying
covariates that do not fall within the pre-defined covariate types.
It should be in the same order as |
histvars |
List of vectors. The kth vector specifies the names of the variables for which the kth history function
in |
histories |
Vector of history functions to apply to the variables specified in |
basecovs |
Vector of character strings specifying the names of baseline covariates in |
censor_name |
Character string specifying the name of the censoring variable in |
censor_model |
Model statement for the censoring variable. Only applicable when using inverse probability weights to estimate the natural course means / risk from the observed data. See "Details". |
outcome_name |
Character string specifying the name of the outcome variable in |
ymodel |
Model statement for the outcome variable. |
ymodel_fit_custom |
Function specifying a custom outcome model. See the vignette "Using Custom Outcome Models in gfoRmula" for details. The default is |
ymodel_predict_custom |
Function obtaining predictions from the custom outcome model specified in |
intvars |
(Deprecated. See the |
interventions |
(Deprecated. See the |
int_times |
(Deprecated. See the |
int_descript |
Vector of character strings, each describing an intervention. It must
be in same order as the specified interventions (see the |
ref_int |
Integer denoting the intervention to be used as the
reference for calculating the end-of-follow-up mean ratio and mean difference. 0 denotes the
natural course, while subsequent integers denote user-specified
interventions in the order that they are
named in |
visitprocess |
List of vectors. Each vector contains as its first entry
the covariate name of a visit process; its second entry
the name of a covariate whose modeling depends on the
visit process; and its third entry the maximum number
of consecutive visits that can be missed before an
individual is censored. The default is |
restrictions |
List of vectors. Each vector contains as its first entry a covariate for which
a priori knowledge of its distribution is available; its second entry a condition
under which no knowledge of its distribution is available and that must be |
yrestrictions |
List of vectors. Each vector contains as its first entry
a condition and its second entry an integer. When the
condition is |
baselags |
Logical scalar for specifying the convention used for lagi and lag_cumavgi terms in the model statements when pre-baseline times are not
included in |
nsimul |
Number of subjects for whom to simulate data. By default, this argument is set
equal to the number of subjects in |
sim_data_b |
Logical scalar indicating whether to return the simulated data set. If bootstrap samples are used (i.e., |
seed |
Starting seed for simulations and bootstrapping. |
nsamples |
Integer specifying the number of bootstrap samples to generate. The default is 0. |
parallel |
Logical scalar indicating whether to parallelize simulations of different interventions to multiple cores. |
ncores |
Integer specifying the number of CPU cores to use in parallel
simulation. This argument is required when parallel is set to |
ci_method |
Character string specifying the method for calculating the bootstrap 95% confidence intervals, if applicable. The options are |
threads |
Integer specifying the number of threads to be used in |
model_fits |
Logical scalar indicating whether to return the fitted models. Note that if this argument is set to |
boot_diag |
Logical scalar indicating whether to return the parametric g-formula estimates as well as the coefficients, standard errors, and variance-covariance matrices of the parameters of the fitted models in the bootstrap samples. The default is |
show_progress |
Logical scalar indicating whether to print a progress bar for the number of bootstrap samples completed in the R console. This argument is only applicable when |
ipw_cutoff_quantile |
Percentile by which to truncate inverse probability weights. The default is |
ipw_cutoff_value |
Cutoff value by which to truncate inverse probability weights. The default is |
int_visit_type |
Vector of logicals. The kth element is a logical specifying whether to carry forward the intervened value (rather than the natural value) of the treatment variables(s) when performing a carry forward restriction type for the kth intervention in |
sim_trunc |
Logical scalar indicating whether to truncate simulated covariates to their range in the observed data set. This argument is only applicable for covariates of type |
... |
Other arguments, including (a) those that specify the interventions and (b) those that are passed to the functions in
Each intervention argument takes as input a list with the following elements:
For example, an "always treat" intervention on |
To assess model misspecification in the parametric g-formula, users can obtain inverse probability (IP) weighted estimates of the natural course means of the time-varying covariates from the observed data. See Chiu et al. (2023) for details. In addition to the general requirements described in McGrath et al. (2020), the requirements for the input data set and the call to the gformula function for such analyses are described below.
Users need to include a column in obs_data
with a time-varying censoring variable.
Users need to indicate the name of the censoring variable and a model statement for the censoring variable with parameters censor_name
and censor_model
, respectively.
Finally, users can specify how to truncate IP weights with the ipw_cutoff_quantile
or ipw_cutoff_value
parameters.
In addition to the package output described in McGrath et al. (2020), the output will display estimates of the "cumulative percent intervened on" and the "average percent intervened on". When using a custom intervention function, users need to specify whether each individual at that time point is eligible to contribute person-time to the percent intervened on calculations. Specifically, this must be specified in the eligible_pt
column of newdf
. By default, eligible_pt
is set to TRUE
for each individual at each time point in custom interventions.
An object of class "gformula_binary_eof". The object is a list with the following components:
result |
Results table containing the estimated outcome probability for all interventions (inculding natural course) at the last time point as well as the "cumulative percent intervened on" and the "average percent intervened on". If bootstrapping was used, the results table includes the bootstrap end-of-follow-up mean ratio, standard error, and 95% confidence interval. |
coeffs |
A list of the coefficients of the fitted models. |
stderrs |
A list of the standard errors of the coefficients of the fitted models. |
vcovs |
A list of the variance-covariance matrices of the parameters of the fitted models. |
rmses |
A list of root mean square error (RMSE) values of the fitted models. |
fits |
A list of the fitted models for the time-varying covariates and outcome. If |
sim_data |
A list of data tables of the simulated data. Each element in the list corresponds to one of the interventions. If the argument |
IP_weights |
A numeric vector specifying the inverse probability weights. See "Details". |
bootests |
A data.table containing the bootstrap replicates of the parametric g-formula estimates. If |
bootcoeffs |
A list, where the kth element is a list containing the coefficients of the fitted models corresponding to the kth bootstrap sample. If |
bootstderrs |
A list, where the kth element is a list containing the standard errors of the coefficients of the fitted models corresponding to the kth bootstrap sample. If |
bootvcovs |
A list, where the kth element is a list containing the variance-covariance matrices of the parameters of the fitted models corresponding to the kth bootstrap sample. If |
... |
Some additional elements. |
The results for the g-formula simulation under various interventions for the last time point are printed with the print.gformula_binary_eof
function. To generate graphs comparing the mean estimated and observed covariate values over time, use the plot.gformula_binary_eof
function.
Chiu YH, Wen L, McGrath S, Logan R, Dahabreh IJ, Hernán MA. Evaluating model specification when using the parametric g-formula in the presence of censoring. American Journal of Epidemiology. 2023;192:1887–1895.
McGrath S, Lin V, Zhang Z, Petito LC, Logan RW, Hernán MA, and JG Young. gfoRmula: An R package for estimating the effects of sustained treatment strategies via the parametric g-formula. Patterns. 2020;1:100008.
Robins JM. A new approach to causal inference in mortality studies with a sustained exposure period: application to the healthy worker survivor effect. Mathematical Modelling. 1986;7:1393–1512. [Errata (1987) in Computers and Mathematics with Applications 14, 917.-921. Addendum (1987) in Computers and Mathematics with Applications 14, 923-.945. Errata (1987) to addendum in Computers and Mathematics with Applications 18, 477.].
gformula
## Estimating the effect of threshold interventions on the mean of a binary
## end of follow-up outcome
id <- 'id_num'
time_name <- 'time'
covnames <- c('cov1', 'cov2', 'treat')
outcome_name <- 'outcome'
histories <- c(lagged, cumavg)
histvars <- list(c('treat', 'cov1', 'cov2'), c('cov1', 'cov2'))
covtypes <- c('binary', 'zero-inflated normal', 'normal')
covparams <- list(covmodels = c(cov1 ~ lag1_treat + lag1_cov1 + lag1_cov2 + cov3 +
time,
cov2 ~ lag1_treat + cov1 + lag1_cov1 + lag1_cov2 +
cov3 + time,
treat ~ lag1_treat + cumavg_cov1 +
cumavg_cov2 + cov3 + time))
ymodel <- outcome ~ treat + cov1 + cov2 + lag1_cov1 + lag1_cov2 + cov3
intervention1.treat <- list(static, rep(0, 7))
intervention2.treat <- list(threshold, 1, Inf)
int_descript <- c('Never treat', 'Threshold - lower bound 1')
nsimul <- 10000
ncores <- 2
gform_bin_eof <- gformula_binary_eof(obs_data = binary_eofdata, id = id,
time_name = time_name,
covnames = covnames,
outcome_name = outcome_name,
covtypes = covtypes,
covparams = covparams,
ymodel = ymodel,
intervention1.treat = intervention1.treat,
intervention2.treat = intervention2.treat,
int_descript = int_descript,
histories = histories, histvars = histvars,
basecovs = c("cov3"), seed = 1234,
parallel = TRUE, nsamples = 5,
nsimul = nsimul, ncores = ncores)
gform_bin_eof
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.