hazard_tmle: TMLE for Cause-Specific Hazard Functions

In benkeser/survtmle: Compute Targeted Minimum Loss-Based Estimates in Right-Censored Survival Settings

TMLE for Cause-Specific Hazard Functions

Description

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.

Usage

hazard_tmle(
  ftime,
  ftype,
  trt,
  t0 = max(ftime[ftype > 0]),
  adjustVars = NULL,
  SL.ftime = NULL,
  SL.ctime = NULL,
  SL.trt = NULL,
  SL.ftimeMissing = NULL,
  glm.ftime = NULL,
  glm.ctime = NULL,
  glm.trt = "1",
  glm.ftimeMissing = NULL,
  glm.family = "binomial",
  att = FALSE,
  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,
  stratify = FALSE,
  ...
)

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.
att	A boolean indicating whether to compute the ATT estimate, instead of treatment specific survival curves. This option only works with two levels of trt that are labeled with 0 and 1.
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.
stratify	If TRUE, then the hazard model is estimated using only the observations with trt == trtOfInterest. Only works if length(trtOfInterest) == 1. If stratify = TRUE then glm.ftime cannot include trt in the model formula and any learners in SL.ftime should not assume a variable named trt will be included in the candidate super learner estimators.
...	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.

ic

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.

t0

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
)

benkeser/survtmle documentation built on Nov. 23, 2023, 4:45 a.m.