Deterministic g/Q functions - examples and templates — deterministic.g.function

Template for the deterministic.g.function argument to ltmle or ltmleMSM.

Usage

deterministic.g.function_template(data, current.node, nodes)

deterministic.Q.function_template(
  data,
  current.node,
  nodes,
  called.from.estimate.g
)

Arguments

data

the 'data' data.frame passed to ltmle or ltmleMSM

current.node

the column index of data corresponding to the A or C node (for g) or L or Y node (for Q)

nodes

list of column indicies, components:

A Anodes (treatment)
C Cnodes (censoring)
L Lnodes (time-varying covariates)
Y Ynodes (events)
AC Anodes and Cnodes combined and sorted
LY Lnodes and Ynodes combined, sorted, "blocks" removed - see ltmle

called.from.estimate.g

TRUE or FALSE - your function will be called with called.from.estimate.g=TRUE during estimation of g and called.from.estimate.g=FALSE during estimation of Q.

Value

A deterministic.g.function should return a list with components:

is.deterministic: vector of logicals, length=nrow(data)
prob1: the probability that data[is.deterministic, current.node] == 1, vector of length 1 or length(which(is.deterministic))

A deterministic.Q.function should return a list with components:

is.deterministic: vector of logicals, length=nrow(data)
Q.value: the iterated expectation of the final Y, vector of length 1 or length(which(is.deterministic))

NOTE: The Q.value component is not used or required when called.from.estimate.g is TRUE

Details

MaintainTreatment and MaintainControl are two commonly used deterministic.g.functions.

The intended use of the templates is for the user to copy and paste the function arguments and body and then fill in the required sections. They will not run as-is. Note that there are no comments in the functions as saved. Versions with comments may be found in Examples section below.

MaintainTreatment and MaintainControl may be passed as-is for the deterministic.g.function argument to ltmle or ltmleMSM

Note that censoring nodes in data may be passed as binaries but they are converted to the preferred format of factors with levels "censored" and "uncensored" before deterministic functions are called. Also note that nodes may be passed to ltmle as either the names of nodes or numerical column indicies, but they are all converted to numerical indicies before deterministic functions are called. If the survivalFunction argument to ltmle or ltmleMSM is TRUE, the package automatically assumes that once Y jumps to 1, all future Y nodes stay 1 and treatment does not change. It is not necessary to specify this in deterministic functions.

Functions

deterministic.Q.function_template(): Template for the deterministic.Q.function argument to ltmle or ltmleMSM.

Author

Joshua Schwab jschwab77@berkeley.edu

Examples


# Show template for a deterministic.g.function (comments will not be
# shown, see below for comments)
deterministic.g.function_template
#> function (data, current.node, nodes) 
#> {
#>     is.deterministic <- stop("replace me!")
#>     prob1 <- stop("replace me!")
#>     return(list(is.deterministic = is.deterministic, prob1 = prob1))
#> }
#> <bytecode: 0x55963ec972d8>
#> <environment: namespace:ltmle>

# Show template for a deterministic.Q.function (comments will not be
# shown, see below for comments)
deterministic.Q.function_template
#> function (data, current.node, nodes, called.from.estimate.g) 
#> {
#>     is.deterministic <- stop("replace me!")
#>     Q.value <- stop("replace me!")
#>     return(list(is.deterministic = is.deterministic, Q.value = Q.value))
#> }
#> <bytecode: 0x55963df355f8>
#> <environment: namespace:ltmle>

# Use MaintainTreatment
set.seed(1)
rexpit <- function(x) rbinom(n = length(x), size = 1, prob = plogis(x))
n <- 100
W <- rnorm(n)
A1 <- rexpit(W)
A2 <- as.numeric(rexpit(W) | A1)  #treatment at time 1 implies treatment at time 2
Y <- rexpit(W + A1 + A2 + rnorm(n))
data <- data.frame(W, A1, A2, Y)

result <- ltmle(data, Anodes = c("A1", "A2"), Ynodes = "Y", abar = c(1, 1), 
    deterministic.g.function = MaintainTreatment)
#> Qform not specified, using defaults:
#> formula for Y:
#> Q.kplus1 ~ W + A1 + A2
#> 
#> gform not specified, using defaults:
#> formula for A1:
#> A1 ~ W
#> formula for A2:
#> A2 ~ W + A1
#> 
#> Estimate of time to completion: < 1 minute

# deterministic.g.function_template with comments:

deterministic.g.function_template <- function(data, current.node, nodes) {
    # data: the 'data' data.frame passed to ltmle/ltmleMSM current.node: the
    # column index of data corresponding to the A or C node (see
    # is.deterministic below) nodes: list of column indicies, components: A,
    # C, L, Y, AC (Anodes and Cnodes combined and sorted), LY (Lnodes and
    # Ynodes combined, sorted, 'blocks' removed - see ?ltmle) Note that nodes
    # may be passed to ltmle as either the names of nodes or numerical column
    # indicies, but they are all converted to numerical indicies before
    # deterministic.g.function is called
    
    # deterministic.g.function will be called at all Anodes and Cnodes
    # return(NULL) is equivalent to return(list(is.deterministic=rep(FALSE,
    # nrow(data)), prob1=numeric(0)))
    
    # define is.deterministic here: vector of logicals, length=nrow(data)
    # define prob1 here: the probability that data[is.deterministic,
    # current.node] == 1, vector of length 1 or
    # length(which(is.deterministic))
    is.deterministic <- stop("replace me!")
    prob1 <- stop("replace me!")
    return(list(is.deterministic = is.deterministic, prob1 = prob1))
}

# deterministic.Q.function_template with comments:

deterministic.Q.function_template <- function(data, current.node, nodes, 
    called.from.estimate.g) {
    # data: the 'data' data.frame passed to ltmle/ltmleMSM current.node: the
    # column index of data corresponding to the A or C node (see
    # is.deterministic below) nodes: list of column indicies, components: A,
    # C, L, Y, AC (Anodes and Cnodes combined and sorted), LY (Lnodes and
    # Ynodes combined, sorted, 'blocks' removed - see ?ltmle)
    # called.from.estimate.g: TRUE or FALSE - your function will be called
    # with called.from.estimate.g=TRUE during estimation of g and
    # called.from.estimate.g=FALSE during estimation of Q. During estimation
    # of g, only the is.deterministic element of the return list will be
    # used.  Note that nodes may be passed to ltmle as either the names of
    # nodes or numerical column indicies, but they are all converted to
    # numerical indicies before deterministic.Q.function is called
    
    # It is not necessary to specify that deterministic Y events (Y==1)
    # indicate a deterministic Q value of 1; this is automatic 
    # if the survivalFunction input to ltmle/ltmleMSM is TRUE.
    # deterministic.Q.function will be called at all Lnodes and Ynodes (after
    # removing 'blocks') and Anodes and Cnodes (see called.from.estimate.g
    # above) return(NULL) is equivalent to
    # return(list(is.deterministic=rep(FALSE, nrow(data)),
    # Q.value=numeric(0)))
    
    # define is.deterministic here: vector of logicals, length=nrow(data)
    # define Q.value here: the iterated expectation of the final Y, vector of
    # length 1 or length(which(is.deterministic))
    is.deterministic <- stop("replace me!")
    Q.value <- stop("replace me!")
    return(list(is.deterministic = is.deterministic, Q.value = Q.value))
}

Deterministic g/Q functions - examples and templates