TMLE for Cause-Specific Hazard Functions — hazard

This function estimates the marginal cumulative incidence for failures of specified types using targeted minimum loss-based estimation based on the initial estimates of the cause-specific hazard functions for failures of each type. The function is called by survtmle whenever method = "hazard" is specified. However, power users could, in theory, make calls directly to this function.

hazard_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,
  tol = 1/(length(ftime)),
  maxIter = 100,
  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 cause-specific hazards. 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` and `estimateHazards`.
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. The `data.frame` should have a column named `"t"` that includes values `seq_len(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 additionally be passed to `SuperLearner`.
tol	The stopping criteria. The TMLE algorithm performs updates to the initial estimators until the empirical mean of the efficient influence function is smaller than `tol` or until `maxIter` iterations have been completed. The default (`1 / length(ftime)`) is a sensible value. Larger values can be used in situations where convergence of the algorithm is an issue; however, this may result in large finite-sample bias.
maxIter	The maximum number of iterations for the algorithm. The algorithm will iterate until either the empirical mean of the efficient influence function is smaller than `tol` or until `maxIter` iterations have been completed.
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 calls 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 glm or SuperLearner for the pooled hazard regression model for the censoring distribution. If returnModels = FALSE, this entry will be NULL.

trtMod

If returnModels = TRUE the fit object for the call to glm or SuperLearner for the conditional probability of 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 hazard_tmle object with GLMs for treatment, censoring, failure
fit1 <- hazard_tmle(
  ftime = ftime, ftype = ftype,
  trt = trt, adjustVars = adjustVars,
  glm.trt = "W1 + W2",
  glm.ftime = "trt + W1 + W2",
  glm.ctime = "trt + W1 + W2",
  returnModels = TRUE
)