mean_tmle: TMLE for G-Computation of Cumulative Incidence

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

TMLE for G-Computation of Cumulative Incidence

Description

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.

Usage

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.

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 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.

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 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"
)

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