ltmle: Longitudinal Targeted Maximum Likelihood Estimation

In joshuaschwab/ltmle: Longitudinal Targeted Maximum Likelihood Estimation

Longitudinal Targeted Maximum Likelihood Estimation

Description

ltmle is Targeted Maximum Likelihood Estimation (TMLE) of treatment/censoring specific mean outcome for point-treatment and longitudinal data. ltmleMSM adds Marginal Structural Models. Both always provide Inverse Probability of Treatment/Censoring Weighted estimate (IPTW) as well. Maximum likelihood based G-computation estimate (G-comp) can be obtained instead of TMLE. ltmle can be used to calculate additive treatment effect, risk ratio, and odds ratio.

Usage

ltmle(
  data,
  Anodes,
  Cnodes = NULL,
  Lnodes = NULL,
  Ynodes,
  survivalOutcome = NULL,
  Qform = NULL,
  gform = NULL,
  abar,
  rule = NULL,
  gbounds = c(0.01, 1),
  Yrange = NULL,
  deterministic.g.function = NULL,
  stratify = FALSE,
  SL.library = "glm",
  SL.cvControl = list(),
  estimate.time = TRUE,
  gcomp = FALSE,
  iptw.only = FALSE,
  deterministic.Q.function = NULL,
  variance.method = "tmle",
  observation.weights = NULL,
  id = NULL
)

ltmleMSM(
  data,
  Anodes,
  Cnodes = NULL,
  Lnodes = NULL,
  Ynodes,
  survivalOutcome = NULL,
  Qform = NULL,
  gform = NULL,
  gbounds = c(0.01, 1),
  Yrange = NULL,
  deterministic.g.function = NULL,
  SL.library = "glm",
  SL.cvControl = list(),
  regimes,
  working.msm,
  summary.measures,
  final.Ynodes = NULL,
  stratify = FALSE,
  msm.weights = "empirical",
  estimate.time = TRUE,
  gcomp = FALSE,
  iptw.only = FALSE,
  deterministic.Q.function = NULL,
  variance.method = "tmle",
  observation.weights = NULL,
  id = NULL
)

Arguments

data	data frame following the time-ordering of the nodes. See 'Details'.
Anodes	column names or indicies in data of treatment nodes
Cnodes	column names or indicies in data of censoring nodes
Lnodes	column names or indicies in data of time-dependent covariate nodes
Ynodes	column names or indicies in data of outcome nodes
survivalOutcome	If TRUE, then Y nodes are indicators of an event, and if Y at some time point is 1, then all following should be 1. Required to be TRUE or FALSE if outcomes are binary and there are multiple Ynodes.
Qform	character vector of regression formulas for Q. See 'Details'.
gform	character vector of regression formulas for g or a matrix/array of prob(A=1). See 'Details'.
abar	binary vector (numAnodes x 1) or matrix (n x numAnodes) of counterfactual treatment or a list of length 2. See 'Details'.
rule	a function to be applied to each row (a named vector) of data that returns a numeric vector of length numAnodes. See 'Details'.
gbounds	lower and upper bounds on estimated cumulative probabilities for g-factors. Vector of length 2, order unimportant.
Yrange	NULL or a numerical vector where the min and max of Yrange specify the range of all Y nodes. See 'Details'.
deterministic.g.function	optional information on A and C nodes that are given deterministically. See 'Details'. Default NULL indicates no deterministic links.
stratify	if TRUE stratify on following abar when estimating Q and g. If FALSE, pool over abar.
SL.library	optional character vector of libraries to pass to SuperLearner. NULL indicates glm should be called instead of SuperLearner. 'default' indicates a standard set of libraries. May be separately specified for Q and g. See 'Details'.
SL.cvControl	optional list to be passed as cvControl to SuperLearner
estimate.time	if TRUE, run an initial estimate using only 50 observations and use this to print a very rough estimate of the total time to completion. No action if there are fewer than 50 observations.
gcomp	if TRUE, run the maximum likelihood based G-computation estimate instead of TMLE
iptw.only	by default (iptw.only = FALSE), both TMLE and IPTW are run in ltmle and ltmleMSM. If iptw.only = TRUE, only IPTW is run, which is faster.
deterministic.Q.function	optional information on Q given deterministically. See 'Details'. Default NULL indicates no deterministic links.
variance.method	Method for estimating variance of TMLE. One of "ic", "tmle", "iptw". If "tmle", compute both the robust variance estimate using TMLE and the influence curve based variance estimate (use the larger of the two). If "iptw", compute both the robust variance estimate using IPTW and the influence curve based variance estimate (use the larger of the two). If "ic", only compute the influence curve based variance estimate. "ic" is fastest, but may be substantially anti-conservative if there are positivity violations or rare outcomes. "tmle" is slowest but most robust if there are positivity violations or rare outcomes. "iptw" is a compromise between speed and robustness. variance.method="tmle" or "iptw" are not yet available with non-binary outcomes, gcomp=TRUE, stratify=TRUE, or deterministic.Q.function.
observation.weights	observation (sampling) weights. Vector of length n. If NULL, assumed to be all 1.
id	Household or subject identifiers. Vector of length n or NULL. Integer, factor, or character recommended, but any type that can be coerced to factor will work. NULL means all distinct ids.
regimes	binary array: n x numAnodes x numRegimes of counterfactual treatment or a list of 'rule' functions
working.msm	character formula for the working marginal structural model
summary.measures	array: num.regimes x num.summary.measures x num.final.Ynodes - measures summarizing the regimes that will be used on the right hand side of working.msm (baseline covariates may also be used in the right hand side of working.msm and do not need to be included in summary.measures)
final.Ynodes	vector subset of Ynodes - used in MSM to pool over a set of outcome nodes
msm.weights	projection weights for the working MSM. If "empirical", weight by empirical proportions of rows matching each regime for each final.Ynode, with duplicate regimes given zero weight. If NULL, no weights. Or an array of user-supplied weights with dimensions c(n, num.regimes, num.final.Ynodes) or c(num.regimes, num.final.Ynodes).

Details

The estimates returned by ltmle are of a treatment specific mean, E[Y_{\bar{a}}], the mean of the final treatment node, where all treatment nodes, A, are set to \bar{a} (abar) and all censoring nodes C are set to 1 (uncensored). The estimates returned by ltmleMSM are similar but are the parameters in a working marginal structural model.

data should be a data frame where the order of the columns corresponds to the time-ordering of the model.

• in censoring columns (Cnodes): factor with two levels: "censored" and "uncensored". The helper function BinaryToCensoring can be used to create these factors.

• in treatment columns (Anodes): 1 = treated, 0 = untreated (must be binary)

• in event columns (Ynodes): If survivalOutcome is TRUE, then Y nodes are treated as indicators of a one-time event. See details for survivalOutocme. If survivalOutcome is FALSE, Y nodes are treated as binary if all values are 0 or 1, and are treated as continuous otherwise. If Y nodes are continuous, they may be automatically scaled. See details for Yrange.

• time-dependent covariate columns (Lnodes): can be any numeric data

• Data in Cnodes, Anodes, Lnodes and Ynodes are not used after (to the right of) censoring (or an event when survivalOutcome==TRUE) and may be coded as NA or any other value.

• Columns in data that are before (to the left of) the first of Cnodes or Anodes are treated as baseline variables, even if they are specified as Lnodes.

• After the first of Cnodes, Anodes, Ynodes, or Lnodes, every column must be in one of Cnodes, Anodes, Ynodes, or Lnodes.

If survivalOutcome is TRUE, all Y values are indicators of an event (e.g. death) at or before the current time, where 1 = event and 0 = no event. The events in Ynodes must be of the form where once Y jumps to 1, Y remains 1 at subsequent nodes.

For continuous outcomes, (survivalOutcome==FALSE and some Y nodes are not 0 or 1,) Y values are truncated at the minimum and maximum of Yrange if specified, and then transformed and scaled to be in [0,1]. That is, transformed to (Y-min(Yrange))/(max(Yrange)-min(Yrange)). If Yrange is NULL, it is set to the range of all Y nodes. In that case, Y nodes are only scaled if any values fall outside of [0,1]. For intervention specific means (ltmle), parameter estimates are transformed back based Yrange.

Qform should be NULL, in which case all parent nodes of each L and Y node will be used as regressors, or a named character vector that can be coerced to class "formula". The length of Qform must be equal to length(Lnodes) + length(Ynodes)** and the names and order of the formulas must be the same as the names and order of the L and Y nodes in data. The left hand side of each formula should be "Q.kplus1". If SL.library is NULL, glm will be called using the elements of Qform. If SL.library is specified, SuperLearner will be called after a design matrix is created using Qform.

** If there is a "block" of L and Y nodes not separated by A or C nodes, only one regression is required at the first L/Y node in a block. You can pass regression formulas for the other L/Y nodes, but they will be ignored (with a message). See example 5.

gform should be NULL, in which case all parent nodes of each L and Y node will be used as regressors, or a character vector that can be coerced to class "formula", or a matrix/array of Prob(A=1). If gform is a character vector, the length of gform must be equal to length(Anodes) + length(Cnodes) and the order of the formulas must be the same as the order the A and C nodes appear in data. The left hand side of each formula should be the name of the Anode or Cnode. If SL.library is NULL, glm will be called using the elements of gform. If SL.library is specified, SuperLearner will be called after a design matrix is created using gform.

In ltmle, gform can also be a n x numACnodes matrix where entry (i, j) is the probability that the ith observation of the jth A/C node is 1 (if an Anode) or uncensored (if a Cnode), conditional on following abar up to that node. In ltmleMSM, gform can similarly be a n x numACnodes x numRegimes array, where entry (i, j, k) is the probability that the ith observation of the jth A/C node is 1 (if an Anode) or uncensored (if a Cnode), conditional on following regime k up to that node. If gform is a matrix/array, deterministic.g.function will not be used and should be NULL.

abar specifies the counterfactual values of the Anodes, using the order they appear in data and should have the same length (if abar is a vector) or number of columns (if abar is a matrix) as Anodes.

rule can be used to specify a dynamic treatment rule. rule is a function applied to each row of data which returns a numeric vector of the same length as Anodes.

abar and rule cannot both be specified. If one of them if a list of length 2, additive treatment effect, risk ratio, and odds ratio can be computed using summary.ltmleEffectMeasures.

regimes can be a binary array: n x numAnodes x numRegimes of counterfactual treatment or a list of 'rule' functions as described above for the rule argument for the ltmle function

deterministic.g.function can be a function used to specify model knowledge about value of Anodes and/or Cnodes that are set deterministically. For example, it may be the case that once a patient starts treatment, they always stay on treatment. For details on the form of the function and examples, see deterministic.g.function_template

deterministic.Q.function can be a function used to specify model knowledge about the final event state. For example, it may be the case that a patient can complete the study at some intermediate time point, in which case the probability of death is 0 (assuming they have not died already). For details on the form of the function and examples, see deterministic.Q.function_template

SL.library may be a character vector of libraries (or 'glm' or 'default'), in which case these libraries are used to estimate both Q and g OR a list with two components, Q and g, where each is a character vector of libraries (or 'glm' or 'default'). 'glm' indicates glm should be called instead of SuperLearner If SL.library is the string 'default', SL.library is set to list("SL.glm", "SL.stepAIC", "SL.bayesglm", c("SL.glm", "screen.corP"), c("SL.step", "screen.corP"), c("SL.step.forward", "screen.corP"), c("SL.stepAIC", "screen.corP"), c("SL.step.interaction", "screen.corP"), c("SL.bayesglm", "screen.corP"). Note that the default set of libraries consists of main terms models. It may be advisable to include squared terms, interaction terms, etc in gform and Qform or include libraries that consider non-linear terms.

If attr(SL.library, "return.fit") == TRUE, then fit$g and fit$Q will return full SuperLearner or glm objects. If not, only a summary matrix will be returned to save memory.

The print method for ltmle objects only prints the tmle estimates.

Value

ltmle returns an object of class "ltmle" (unless abar or rule is a list, in which case it returns an object of class ltmleSummaryMeasures, which has the same components as ltmleMSM.) The function summary (i.e. summary.ltmle) can be used to obtain or print a summary of the results. An object of class "ltmle" is a list containing the following components:

estimates	a named vector of length 4 with elements, each an estimate of E[Y_{bar{a}}]: tmle - Targeted Maximum Likelihood Estimate [NULL if gcomp is TRUE] iptw - Inverse Probability of Treatment/Censoring Weighted estimate gcomp - maximum likelihood based G-computation estimate [NULL if gcomp is FALSE]
IC	a list with the following components of Influence Curve values

• tmle - vector of influence curve values for Targeted Maximum Likelihood Estimate [NULL if gcomp is TRUE]

• iptw - vector of influence curve values for Inverse Probability of Treatment/Censoring Weighted estimate

• gcomp - vector of influence curve values for Targeted Maximum Likelihood Estimate without updating [NULL if gcomp is FALSE]

cum.g	cumulative g, after bounding: for ltmle, n x numACnodes, for ltmleMSM, n x numACnodes x num.regimes
cum.g.unbounded	cumulative g, before bounding: for ltmle, n x numACnodes, for ltmleMSM, n x numACnodes x num.regimes
cum.g.used	binary - TRUE if an entry of cum.g was used in the updating step (note: even if cum.g.used is FALSE, a small value of cum.g.unbounded may still indicate a positivity problem): for ltmle, n x numACnodes, for ltmleMSM, n x numACnodes x num.regimes
call	the matched call
gcomp	the gcomp input
formulas	a list with elements Qform and gform
fit	a list with the following components

• g - list of length numACnodes - glm or SuperLearner (see Details) return objects from fitting g regressions

• Q - list of length numLYnodes - glm or SuperLearner (see Details) return objects from fitting Q regressions

• Qstar - list of length numLYnodes - glm (or numerical optimization if glm fails to solve the score equation) return objects from updating the Q fit

ltmleMSM returns an object of class "ltmleMSM" The function summary (i.e. summary.ltmleMSM) can be used to obtain or print a summary of the results. An object of class "ltmleMSM" is a list containing the following components:

beta	parameter estimates for working.msm using TMLE (GCOMP if gcomp input is TRUE)
beta.iptw	parameter estimates for working.msm using IPTW
IC	matrix, n x numBetas - influence curve values for TMLE (without updating if gcomp input is TRUE)
IC.iptw	matrix, n x numBetas - influence curve values for IPTW
msm	object of class glm - the result of fitting the working.msm
cum.g	array, n x numACnodes x numRegimes - cumulative g, after bounding
cum.g.unbounded	array, n x numACnodes x numRegimes - cumulative g, before bounding
call	the matched call
gcomp	the gcomp input
formulas	a list with elements Qform and gform
fit	a list with the following components

• g - list of length numRegimes of list of length numACnodes - glm or SuperLearner (see Details) return objects from fitting g regressions

• Q - list of length numLYnodes - glm or SuperLearner (see Details) return objects from fitting Q regressions

• Qstar - list of length numLYnodes - glm (or numerical optimization if glm fails to solve the score equation) return objects from updating the Q fit

Functions

• ltmleMSM(): Longitudinal Targeted Maximum Likelihood Estimation for a Marginal Structural Model

Author(s)

Joshua Schwab [e-mail], Samuel Lendle, Maya Petersen, and Mark van der Laan

See Also

summary.ltmle, summary.ltmleMSM, SuperLearner, deterministic.g.function_template, deterministic.Q.function_template

Examples

# See \url{http://joshuaschwab.github.io/ltmle/} for more examples.

rexpit <- function(x) rbinom(n=length(x), size=1, prob=plogis(x))

# Single time point Example
n <- 1000
W <- rnorm(n)
A <- rexpit(-1 + 2 * W)
Y <- rexpit(W + A)
data <- data.frame(W, A, Y)

result1 <- ltmle(data, Anodes="A", Ynodes="Y", abar=1)
summary(result1)
summary(result1, estimator="iptw")
# MSM Example
# Given data over 3 time points where A switches to 1 once and then stays 1. We want to know
# how death varies as a function of gender, time and an indicator of whether a patient's
# intended regime was to switch before time.
# Note that working.msm includes time and switch.time, which are columns of
# summary.measures; working.msm also includes male, which is ok because it is a baseline
# covariate (it comes before any A/C/L/Y nodes).
data(sampleDataForLtmleMSM)
Anodes <- grep("^A", names(sampleDataForLtmleMSM$data))
Lnodes <- c("CD4_1", "CD4_2")
Ynodes <- grep("^Y", names(sampleDataForLtmleMSM$data))
msm.weights <- matrix(1:12, nrow=4, ncol=3) #just an example (can also use a 200x3x4 array),
                                            #or NULL (for no weights), or "empirical" (the default)

result2 <- ltmleMSM(sampleDataForLtmleMSM$data, Anodes=Anodes, Lnodes=Lnodes, Ynodes=Ynodes,
                   survivalOutcome=TRUE,
                   regimes=sampleDataForLtmleMSM$regimes,
                   summary.measures=sampleDataForLtmleMSM$summary.measures, final.Ynodes=Ynodes,
                   working.msm="Y ~ male + time + I(pmax(time - switch.time, 0))",
                   msm.weights=msm.weights, estimate.time=FALSE)
print(summary(result2))

joshuaschwab/ltmle documentation built on April 20, 2023, 12:05 p.m.