gformula_survival: Estimation of Survival Outcome Under the Parametric G-Formula
In gfoRmula: Parametric G-Formula
gformula_survival R Documentation
Estimation of Survival Outcome Under the Parametric G-Formula
Description
Based on an observed data set, this internal function estimates the risk over time 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.
Usage
gformula_survival(
obs_data,
id,
time_points = NULL,
time_name,
covnames,
covtypes,
covparams,
covfits_custom = NA,
covpredict_custom = NA,
histvars = NULL,
histories = NA,
basecovs = NA,
outcome_name,
ymodel,
ymodel_fit_custom = NULL,
ymodel_predict_custom = NULL,
compevent_name = NULL,
compevent_model = NA,
compevent_cens = FALSE,
censor_name = NULL,
censor_model = NA,
intvars = NULL,
interventions = NULL,
int_times = NULL,
int_descript = NULL,
ref_int = 0,
intcomp = NA,
visitprocess = NA,
restrictions = NA,
yrestrictions = NA,
compevent_restrictions = 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,
...
)
Arguments
obs_data
Data table containing the observed data.
id
Character string specifying the name of the ID variable in obs_data.
time_points
Number of time points to simulate. By default, this argument is set equal to the maximum
number of records that obs_data contains for any individual.
time_name
Character string specifying the name of the time variable in obs_data.
covnames
Vector of character strings specifying the names of the time-varying covariates in obs_data.
covtypes
Vector of character strings specifying the "type" of each time-varying covariate included in covnames. The possible "types" are: "binary", "normal", "categorical", "bounded normal", "zero-inflated normal", "truncated normal", "absorbing", "categorical time", and "custom".
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 covnames and in the same order.
If a parameter is not required for a certain covariate, it
should be set to NA at that index.
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 covnames. If a custom fit function is not
required for a particular covariate (e.g., if the first
covariate is of type "binary" but the second is of type "custom"), then that
index should be set to NA. The default is NA.
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 covnames. If a custom
prediction function is not required for a particular
covariate, then that index should be set to NA. The default is NA.
histvars
List of vectors. The kth vector specifies the names of the variables for which the kth history function
in histories is to be applied.
histories
Vector of history functions to apply to the variables specified in histvars. The default is NA.
basecovs
Vector of character strings specifying the names of baseline covariates in obs_data. These covariates are not simulated using a model but rather carry their value over all time points from the first time point of obs_data. These covariates should not be included in covnames. The default is NA.
outcome_name
Character string specifying the name of the outcome variable in obs_data.
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 NULL.
ymodel_predict_custom
Function obtaining predictions from the custom outcome model specified in ymodel_fit_custom. See the vignette "Using Custom Outcome Models in gfoRmula" for details. The default is NULL.
compevent_name
Character string specifying the name of the competing event variable in obs_data.
compevent_model
Model statement for the competing event variable. The default is NA.
compevent_cens
Logical scalar indicating whether to treat competing events as censoring events.
This argument is only applicable for survival outcomes and when a competing even model is supplied (i.e., compevent_name and compevent_model are specified).
If this argument is set to TRUE, the competing event model will only be used to construct inverse probability weights to estimate the natural course means / risk from the observed data.
If this argument is set to FALSE, the competing event model will be used in the parametric g-formula estimates of the risk and will not be used to construct inverse probability weights.
See "Details". The default is FALSE.
censor_name
Character string specifying the name of the censoring variable in obs_data. Only applicable when using inverse probability weights to estimate the natural course means / risk from the observed data. See "Details".
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".
intvars
(Deprecated. See the ... argument) List, whose elements are vectors of character strings. The kth vector in intvars specifies the name(s) of the variable(s) to be intervened
on in each round of the simulation under the kth intervention in interventions.
interventions
(Deprecated. See the ... argument) List, whose elements are lists of vectors. Each list in interventions specifies a unique intervention on the relevant variable(s) in intvars. Each vector contains a function
implementing a particular intervention on a single variable, optionally
followed by one or more "intervention values" (i.e.,
integers used to specify the treatment regime).
int_times
(Deprecated. See the ... argument) List, whose elements are lists of vectors. The kth list in int_times corresponds to the kth intervention in interventions. Each vector specifies the time points in which the relevant intervention is applied on the corresponding variable in intvars.
When an intervention is not applied, the simulated natural course value is used. By default, this argument is set so that all interventions are applied in all time points.
int_descript
Vector of character strings, each describing an intervention. It must
be in same order as the specified interventions (see the ... argument).
ref_int
Integer denoting the intervention to be used as the
reference for calculating the risk ratio and risk difference. 0 denotes the
natural course, while subsequent integers denote user-specified
interventions in the order that they are
named in interventions. The default is 0.
intcomp
List of two numbers indicating a pair of interventions to be compared by a hazard ratio.
The default is NA, resulting in no hazard ratio calculation.
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 NA.
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 TRUE
for the distribution of that covariate given that condition to be estimated via a parametric
model or other fitting procedure; its third entry a function for estimating the distribution
of that covariate given the condition in the second entry is false such that a priori knowledge
of the covariate distribution is available; and its fourth entry a value used by the function in the
third entry. The default is NA.
yrestrictions
List of vectors. Each vector contains as its first entry
a condition and its second entry an integer. When the
condition is TRUE, the outcome variable is simulated
according to the fitted model; when the condition is FALSE,
the outcome variable takes on the value in the second entry.
The default is NA.
compevent_restrictions
List of vectors. Each vector contains as its first entry
a condition and its second entry an integer. When the
condition is TRUE, the competing event variable is simulated
according to the fitted model; when the condition is FALSE,
the competing event variable takes on the value in the
second entry. The default is NA.
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 obs_data and when the current time index, t, is such that t < i. If this argument is set to FALSE, the value
of all lagi and lag_cumavgi terms in this context are set to 0 (for non-categorical covariates) or the reference
level (for categorical covariates). If this argument is set to TRUE, the value of lagi and lag_cumavgi terms
are set to their values at time 0. The default is FALSE.
nsimul
Number of subjects for whom to simulate data. By default, this argument is set
equal to the number of subjects in obs_data.
sim_data_b
Logical scalar indicating whether to return the simulated data set. If bootstrap samples are used (i.e., nsamples is set to a value greater than 0), this argument must be set to FALSE. The default is FALSE.
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 TRUE.
In many applications, users may wish to set this argument equal to parallel::detectCores() - 1.
ci_method
Character string specifying the method for calculating the bootstrap 95% confidence intervals, if applicable. The options are "percentile" and "normal".
threads
Integer specifying the number of threads to be used in data.table. See setDTthreads for further details.
model_fits
Logical scalar indicating whether to return the fitted models. Note that if this argument is set to TRUE, the output of this function may use a lot of memory. The default is FALSE.
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 FALSE.
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 parallel is set to FALSE and bootstrap samples are used (i.e., nsamples is set to a value greater than 0). The default is TRUE.
ipw_cutoff_quantile
Percentile by which to truncate inverse probability weights. The default is NULL (i.e., no truncation). See "Details".
ipw_cutoff_value
Cutoff value by which to truncate inverse probability weights. The default is NULL (i.e., no truncation). See "Details".
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 interventions.
When the kth element is set to FALSE, the natural value of the treatment variable(s) in the kth intervention in interventions will be carried forward.
By default, this argument is set so that the intervened value of the treatment variable(s) is carried forward for all interventions.
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 "normal", "bounded normal", "truncated normal", and "zero-inflated normal". The default is TRUE.
...
Other arguments, including (a) those that specify the interventions and (b) those that are passed to the functions in covpredict_custom. To specify interventions, users can supply arguments with the following naming requirements
Each intervention argument begins with a prefix of intervention.
After the prefix, the intervention number is specified and followed by a period.
After the period, the treatment variable name is specified.
Each intervention argument takes as input a list with the following elements:
The first element specifies the intervention function.
The subsequent elements specify any intervention values.
(Optional) The named element int_times specifies the time points to apply the intervention. By default, all interventions are applied at all time points.
For example, an "always treat" intervention on A is given by
intervention1.A = list(static, rep(1, time_points))
See the vignette "A Simplified Approach for Specifying Interventions in gfoRmula" and "Examples" section for more examples.
Details
To assess model misspecification in the parametric g-formula, users can obtain inverse probability (IP) weighted estimates of the natural course risk and/or 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.
When competing events are present, users need to include a column in obs_data with a time-varying indicator of the competing event variable and need to indicate the name of the competing event variable and the corresponding model statement with parameters compevent_name and compevent_model, respectively.
Users need to indicate whether to treat competing events as censoring events with the compevent_cens parameter.
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.
Value
An object of class "gformula_survival". The object is a list with the following components:
result
Results table containing the estimated risk and risk ratio for all interventions (inculding the natural course) at each 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 mean risk 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.
hazardratio_val
Hazard ratio between two interventions (if applicable).
fits
A list of the fitted models for the time-varying covariates, outcome, and competing event (if applicable). If model_fits is set to FALSE, a value of NULL is given.
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 sim_data_b is set to FALSE, a value of NA is given.
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 boot_diag is set to FALSE, a value of NULL is given.
bootcoeffs
A list, where the kth element is a list containing the coefficients of the fitted models corresponding to the kth bootstrap sample. If boot_diag is set to FALSE, a value of NULL is given.
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 boot_diag is set to FALSE, a value of NULL is given.
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 boot_diag is set to FALSE, a value of NULL is given.
...
Some additional elements.
The results for the g-formula simulation under various interventions only for the first and last time points are printed with the print.gformula_survival function. To generate graphs comparing the mean estimated covariate values and risks over time and mean observed covariate values and risks over time, use the plot.gformula_survival function.
References
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.].
See Also
gformula
Examples
## Estimating the effect of static treatment strategies on risk of a
## failure event
id <- 'id'
time_points <- 7
time_name <- 't0'
covnames <- c('L1', 'L2', 'A')
outcome_name <- 'Y'
covtypes <- c('binary', 'bounded normal', 'binary')
histories <- c(lagged, lagavg)
histvars <- list(c('A', 'L1', 'L2'), c('L1', 'L2'))
covparams <- list(covmodels = c(L1 ~ lag1_A + lag_cumavg1_L1 + lag_cumavg1_L2 +
L3 + t0,
L2 ~ lag1_A + L1 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + t0,
A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + t0))
ymodel <- Y ~ A + L1 + L2 + L3 + lag1_A + lag1_L1 + lag1_L2 + t0
intervention1.A <- list(static, rep(0, time_points))
intervention2.A <- list(static, rep(1, time_points))
int_descript <- c('Never treat', 'Always treat')
nsimul <- 10000
gform_basic <- gformula_survival(obs_data = basicdata_nocomp, id = id,
time_points = time_points,
time_name = time_name, covnames = covnames,
outcome_name = outcome_name,
covtypes = covtypes,
covparams = covparams, ymodel = ymodel,
intervention1.A = intervention1.A,
intervention2.A = intervention2.A,
int_descript = int_descript,
histories = histories, histvars = histvars,
basecovs = c('L3'), nsimul = nsimul,
seed = 1234)
gform_basic
## Estimating the effect of treatment strategies on risk of a failure event
## when competing events exist
id <- 'id'
time_points <- 7
time_name <- 't0'
covnames <- c('L1', 'L2', 'A')
outcome_name <- 'Y'
compevent_name <- 'D'
covtypes <- c('binary', 'bounded normal', 'binary')
histories <- c(lagged, lagavg)
histvars <- list(c('A', 'L1', 'L2'), c('L1', 'L2'))
covparams <- list(covlink = c('logit', 'identity', 'logit'),
covmodels = c(L1 ~ lag1_A + lag_cumavg1_L1 + lag_cumavg1_L2 +
L3 + as.factor(t0),
L2 ~ lag1_A + L1 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + as.factor(t0),
A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + as.factor(t0)))
ymodel <- Y ~ A + L1 + L2 + lag1_A + lag1_L1 + lag1_L2 + L3 + as.factor(t0)
compevent_model <- D ~ A + L1 + L2 + lag1_A + lag1_L1 + lag1_L2 + L3 + as.factor(t0)
intervention1.A <- list(static, rep(0, time_points))
intervention2.A <- list(static, rep(1, time_points))
int_descript <- c('Never treat', 'Always treat')
nsimul <- 10000
gform_basic <- gformula_survival(obs_data = basicdata, id = id,
time_points = time_points,
time_name = time_name, covnames = covnames,
outcome_name = outcome_name,
compevent_name = compevent_name,
covtypes = covtypes,
covparams = covparams, ymodel = ymodel,
compevent_model = compevent_model,
intervention1.A = intervention1.A,
intervention2.A = intervention2.A,
int_descript = int_descript,
histories = histories, histvars = histvars,
basecovs = c('L3'), nsimul = nsimul,
seed = 1234)
gform_basic
## Using IP weighting to estimate natural course risk
## Only the natural course intervention is included for simplicity
covnames <- c('L', 'A')
histories <- c(lagged)
histvars <- list(c('A', 'L'))
ymodel <- Y ~ L + A
covtypes <- c('binary', 'normal')
covparams <- list(covmodels = c(L ~ lag1_L + lag1_A,
A ~ lag1_L + L + lag1_A))
censor_name <- 'C'
censor_model <- C ~ L
res_censor <- gformula(obs_data = censor_data, id = 'id',
time_name = 't0', covnames = covnames,
outcome_name = 'Y', outcome_type = 'survival',
censor_name = censor_name, censor_model = censor_model,
covtypes = covtypes,
covparams = covparams, ymodel = ymodel,
intvars = NULL, interventions = NULL, int_descript = NULL,
histories = histories, histvars = histvars,
seed = 1234)
plot(res_censor)
gfoRmula documentation built on Oct. 1, 2024, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| gformula_survival | R Documentation |
Estimation of Survival Outcome Under the Parametric G-Formula
Description
Based on an observed data set, this internal function estimates the risk over time 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.
Usage
gformula_survival(
obs_data,
id,
time_points = NULL,
time_name,
covnames,
covtypes,
covparams,
covfits_custom = NA,
covpredict_custom = NA,
histvars = NULL,
histories = NA,
basecovs = NA,
outcome_name,
ymodel,
ymodel_fit_custom = NULL,
ymodel_predict_custom = NULL,
compevent_name = NULL,
compevent_model = NA,
compevent_cens = FALSE,
censor_name = NULL,
censor_model = NA,
intvars = NULL,
interventions = NULL,
int_times = NULL,
int_descript = NULL,
ref_int = 0,
intcomp = NA,
visitprocess = NA,
restrictions = NA,
yrestrictions = NA,
compevent_restrictions = 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,
...
)
Arguments
obs_data |
Data table containing the observed data. |
id |
Character string specifying the name of the ID variable in |
time_points |
Number of time points to simulate. By default, this argument is set equal to the maximum
number of records that |
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 |
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 |
compevent_name |
Character string specifying the name of the competing event variable in |
compevent_model |
Model statement for the competing event variable. The default is |
compevent_cens |
Logical scalar indicating whether to treat competing events as censoring events.
This argument is only applicable for survival outcomes and when a competing even model is supplied (i.e., |
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". |
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 risk ratio and risk difference. 0 denotes the
natural course, while subsequent integers denote user-specified
interventions in the order that they are
named in |
intcomp |
List of two numbers indicating a pair of interventions to be compared by a hazard ratio.
The default is |
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 |
compevent_restrictions |
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 |
Details
To assess model misspecification in the parametric g-formula, users can obtain inverse probability (IP) weighted estimates of the natural course risk and/or 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.
When competing events are present, users need to include a column in obs_data with a time-varying indicator of the competing event variable and need to indicate the name of the competing event variable and the corresponding model statement with parameters compevent_name and compevent_model, respectively.
Users need to indicate whether to treat competing events as censoring events with the compevent_cens parameter.
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.
Value
An object of class "gformula_survival". The object is a list with the following components:
result |
Results table containing the estimated risk and risk ratio for all interventions (inculding the natural course) at each 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 mean risk 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. |
hazardratio_val |
Hazard ratio between two interventions (if applicable). |
fits |
A list of the fitted models for the time-varying covariates, outcome, and competing event (if applicable). 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 only for the first and last time points are printed with the print.gformula_survival function. To generate graphs comparing the mean estimated covariate values and risks over time and mean observed covariate values and risks over time, use the plot.gformula_survival function.
References
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.].
See Also
gformula
Examples
## Estimating the effect of static treatment strategies on risk of a
## failure event
id <- 'id'
time_points <- 7
time_name <- 't0'
covnames <- c('L1', 'L2', 'A')
outcome_name <- 'Y'
covtypes <- c('binary', 'bounded normal', 'binary')
histories <- c(lagged, lagavg)
histvars <- list(c('A', 'L1', 'L2'), c('L1', 'L2'))
covparams <- list(covmodels = c(L1 ~ lag1_A + lag_cumavg1_L1 + lag_cumavg1_L2 +
L3 + t0,
L2 ~ lag1_A + L1 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + t0,
A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + t0))
ymodel <- Y ~ A + L1 + L2 + L3 + lag1_A + lag1_L1 + lag1_L2 + t0
intervention1.A <- list(static, rep(0, time_points))
intervention2.A <- list(static, rep(1, time_points))
int_descript <- c('Never treat', 'Always treat')
nsimul <- 10000
gform_basic <- gformula_survival(obs_data = basicdata_nocomp, id = id,
time_points = time_points,
time_name = time_name, covnames = covnames,
outcome_name = outcome_name,
covtypes = covtypes,
covparams = covparams, ymodel = ymodel,
intervention1.A = intervention1.A,
intervention2.A = intervention2.A,
int_descript = int_descript,
histories = histories, histvars = histvars,
basecovs = c('L3'), nsimul = nsimul,
seed = 1234)
gform_basic
## Estimating the effect of treatment strategies on risk of a failure event
## when competing events exist
id <- 'id'
time_points <- 7
time_name <- 't0'
covnames <- c('L1', 'L2', 'A')
outcome_name <- 'Y'
compevent_name <- 'D'
covtypes <- c('binary', 'bounded normal', 'binary')
histories <- c(lagged, lagavg)
histvars <- list(c('A', 'L1', 'L2'), c('L1', 'L2'))
covparams <- list(covlink = c('logit', 'identity', 'logit'),
covmodels = c(L1 ~ lag1_A + lag_cumavg1_L1 + lag_cumavg1_L2 +
L3 + as.factor(t0),
L2 ~ lag1_A + L1 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + as.factor(t0),
A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 +
lag_cumavg1_L2 + L3 + as.factor(t0)))
ymodel <- Y ~ A + L1 + L2 + lag1_A + lag1_L1 + lag1_L2 + L3 + as.factor(t0)
compevent_model <- D ~ A + L1 + L2 + lag1_A + lag1_L1 + lag1_L2 + L3 + as.factor(t0)
intervention1.A <- list(static, rep(0, time_points))
intervention2.A <- list(static, rep(1, time_points))
int_descript <- c('Never treat', 'Always treat')
nsimul <- 10000
gform_basic <- gformula_survival(obs_data = basicdata, id = id,
time_points = time_points,
time_name = time_name, covnames = covnames,
outcome_name = outcome_name,
compevent_name = compevent_name,
covtypes = covtypes,
covparams = covparams, ymodel = ymodel,
compevent_model = compevent_model,
intervention1.A = intervention1.A,
intervention2.A = intervention2.A,
int_descript = int_descript,
histories = histories, histvars = histvars,
basecovs = c('L3'), nsimul = nsimul,
seed = 1234)
gform_basic
## Using IP weighting to estimate natural course risk
## Only the natural course intervention is included for simplicity
covnames <- c('L', 'A')
histories <- c(lagged)
histvars <- list(c('A', 'L'))
ymodel <- Y ~ L + A
covtypes <- c('binary', 'normal')
covparams <- list(covmodels = c(L ~ lag1_L + lag1_A,
A ~ lag1_L + L + lag1_A))
censor_name <- 'C'
censor_model <- C ~ L
res_censor <- gformula(obs_data = censor_data, id = 'id',
time_name = 't0', covnames = covnames,
outcome_name = 'Y', outcome_type = 'survival',
censor_name = censor_name, censor_model = censor_model,
covtypes = covtypes,
covparams = covparams, ymodel = ymodel,
intvars = NULL, interventions = NULL, int_descript = NULL,
histories = histories, histvars = histvars,
seed = 1234)
plot(res_censor)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.