TMLE for G-Computation of Cumulative Incidence

This function estimates the marginal cumulative incidence for failures of specified types using targeted minimum loss-based estimation based on the G-computation representation of cumulative incidence. The function is called by survtmle whenever method="mean" is specified. However, power users could, in theory, make calls directly to this function.

mean_tmle(
  ftime,
  ftype,
  trt,
  t0 = max(ftime[ftype > 0]),
  adjustVars = NULL,
  SL.ftime = NULL,
  SL.ctime = NULL,
  SL.trt = NULL,
  glm.ftime = NULL,
  glm.ctime = NULL,
  glm.trt = "1",
  glm.family = "binomial",
  returnIC = TRUE,
  returnModels = FALSE,
  ftypeOfInterest = unique(ftype[ftype != 0]),
  trtOfInterest = unique(trt),
  cvControl,
  bounds = NULL,
  verbose = FALSE,
  Gcomp = FALSE,
  gtol = 0.001,
  ...
)

Arguments

ftime	A numeric vector of failure times. Right-censored observations should have corresponding `ftype` set to 0.
ftype	A numeric vector indicating the type of failure. Observations with `ftype=0` are treated as having been right-censored. Each unique value besides zero is treated as a separate type of failure.
trt	A numeric vector indicating observed treatment assignment. Each unique value will be treated as a different type of treatment. Currently, only two unique values are supported.
t0	The time at which to return cumulative incidence estimates. By default this is set to `max(ftime[ftype > 0])`.
adjustVars	A `data.frame` of adjustment variables that will be used in estimating the conditional treatment, censoring, and failure (hazard or conditional mean) probabilities.
SL.ftime	A character vector or list specification to be passed to the `SL.library` option of `SuperLearner` for the outcome regression (either cause-specific hazards or iterated mean). See the documentation of `SuperLearner` for more information on how to specify valid `SuperLearner` libraries. It is expected that the wrappers used in the library will play nicely with the input variables, which will be called `"trt"`, `names(adjustVars)`, and `"t"` (if `method = "hazard"`).
SL.ctime	A character vector or list specification to be passed to the `SL.library` option of `SuperLearner` for the estimate of the conditional hazard for censoring. It is expected that the wrappers used in the library will play nicely with the input variables, which will be called `"trt"` and `names(adjustVars)`.
SL.trt	A character vector or list specification to be passed to the `SL.library` option of `SuperLearner` for the estimate of the conditional probability of treatment. It is expected that the wrappers used in the library will play nicely with the input variables, which will be `names(adjustVars)`.
glm.ftime	A character specification of the right-hand side of the equation passed to the `formula` option of a call to `glm` for the outcome regression. Ignored if `SL.ftime` is not equal to `NULL`. Use `"trt"` to specify the treatment in this formula (see examples). The formula can additionally include any variables found in `names(adjustVars)`.
glm.ctime	A character specification of the right-hand side of the equation passed to the `formula` option of a call to `glm` for the estimate of the conditional hazard for censoring. Ignored if `SL.ctime` is not equal to `NULL`. Use `"trt"` to specify the treatment in this formula (see examples). The formula can additionally include any variables found in `names(adjustVars)`.
glm.trt	A character specification of the right-hand side of the equation passed to the `formula` option of a call to `glm` for the estimate of the conditional probability of treatment. Ignored if `SL.trt` is not equal to `NULL`. The formula can include any variables found in `names(adjustVars)`.
glm.family	The type of regression to be performed if fitting GLMs in the estimation and fluctuation procedures. The default is "binomial" for logistic regression. Only change this from the default if there are justifications that are well understood. This is passed directly to `estimateCensoring`.
returnIC	A `logical` indicating whether to return vectors of influence curve estimates. These are needed for some post-hoc comparisons, so it is recommended to leave as `TRUE` (the default) unless the user is sure these estimates will not be needed later.
returnModels	A `logical` indicating whether to return the `glm` or `SuperLearner` objects used to estimate the nuisance parameters. Must be set to `TRUE` if the user plans to use `timepoints` to obtain estimates of incidence at times other than `t0`. See the documentation of `timepoints` for more information.
ftypeOfInterest	An input specifying what failure types to compute estimates of incidence for. The default value computes estimates for values `unique(ftype)`. Can alternatively be set to a vector of values found in `ftype`.
trtOfInterest	An input specifying which levels of `trt` are of interest. The default value computes estimates for all values in `unique(trt)`. Can alternatively be set to a vector of values found in `trt`.
cvControl	A `list` providing control options to be fed directly into calls to `SuperLearner`. This should match the contents of `SuperLearner.CV.control` exactly. For details, consult the documentation of the SuperLearner package. This is usually passed in through the `survtmle` wrapper function.
bounds	A `data.frame` of bounds on the conditional hazard function (if `method = "hazard"`) or on the iterated conditional means (if `method = "mean"`). The `data.frame` should have a column named `"t"` that includes values `1:t0`. The other columns should be names `paste0("l",j)` and `paste0("u",j)` for each unique failure type label j, denoting lower and upper bounds, respectively. See examples.
verbose	A `logical` indicating whether the function should print messages to indicate progress. If `SuperLearner` is called internally, this option will be passed to `SuperLearner`.
Gcomp	A `logical` indicating whether to compute the G-computation estimator (i.e., a substitution estimator with no targeting step). Theory does not support inference for the G-computation estimator if Super Learner is used to estimate failure and censoring distributions. The G-computation is only implemented if `method = "mean"`.
gtol	The truncation level of predicted censoring survival. Setting to larger values can help performance in data sets with practical positivity violations.
...	Other options. Not currently used.

Value

An object of class survtmle.

call

The call to survtmle.

est

A numeric vector of point estimates -- one for each combination of ftypeOfInterest and trtOfInterest.

var

A covariance matrix for the point estimates.

meanIC

The empirical mean of the efficient influence function at the estimated, targeted nuisance parameters. Each value should be small or the user will be warned that excessive finite-sample bias may exist in the point estimates.

The efficient influence function at the estimated, fluctuated nuisance parameters, evaluated on each of the observations. These are used to construct confidence intervals for post-hoc comparisons.

ftimeMod

If returnModels=TRUE the fit object(s) for the call to SuperLearner or glm for the outcome regression models. If method="mean" this will be a list of length length(ftypeOfInterest) each of length t0 (one regression for each failure type and for each timepoint). If method="hazard" this will be a list of length length(ftypeOfInterest) with one fit corresponding to the hazard for each cause of failure. If returnModels = FALSE, this entry will be NULL.

ctimeMod

If returnModels = TRUE the fit object for the call to SuperLearner or glm or for the pooled hazard regression model for the censoring mechanism. If returnModels = FALSE, this entry will be NULL.

trtMod

If returnModels = TRUE the fit object for the call to SuperLearner or glm for the conditional probability of the trt regression model. If returnModels = FALSE, this entry will be NULL.

The timepoint at which the function was evaluated.

ftime

The numeric vector of failure times used in the fit.

ftype

The numeric vector of failure types used in the fit.

trt

The numeric vector of treatment assignments used in the fit.

adjustVars

The data.frame of failure times used in the fit.

Examples

## Single failure type examples
# simulate data
set.seed(1234)
n <- 100
trt <- rbinom(n, 1, 0.5)
adjustVars <- data.frame(W1 = round(runif(n)), W2 = round(runif(n, 0, 2)))

ftime <- round(1 + runif(n, 1, 4) - trt + adjustVars$W1 + adjustVars$W2)
ftype <- round(runif(n, 0, 1))

# Fit 1 - fit mean_tmle object with GLMs for treatment, censoring, failure
fit1 <- mean_tmle(
  ftime = ftime, ftype = ftype,
  trt = trt, adjustVars = adjustVars,
  glm.trt = "W1 + W2",
  glm.ftime = "trt + W1 + W2",
  glm.ctime = "trt + W1 + W2"
)
#> 'speedglm' ran into an error in withCallingHandlers.'glm' will be used instead.