stremr: Estimate Survival with Interventions on Exposure and...

Description Usage Arguments Value Details Additional parameters Specifying the counterfactual intervention function (f_gstar1 and optPars$f_gstar2) IPTW estimator See Also Examples

View source: R/stremr.R

Description

Estimate the causal survival curve for a particular stochastic, dynamic or static intervention on the treatment/exposure and monitoring process. Implements the IPW (Inverse Probability-Weighted or Horvitz-Thompson) estimator of the discrete survival hazard function which is mapped into survival function.

Usage

1
2
3
4
5
6
stremr(data, ID = "Subj_ID", t.name = "time_period", covars, CENS = "C",
  TRT = "A", MONITOR = "N", OUTCOME = "Y", gform_CENS, gform_TRT,
  gform_MONITOR, stratify_CENS = NULL, stratify_TRT = NULL,
  stratify_MONITOR = NULL, intervened_TRT = NULL,
  intervened_MONITOR = NULL, noCENScat = 0L,
  verbose = getOption("stremr.verbose"), optPars = list())

Arguments

data

Input data in long format. Can be a data.frame or a data.table with named columns, containing the time-varying covariates (covars), the right-censoring event indicator(s) (CENS), the exposure variable(s) (TRT), the monitoring process variable(s) (MONITOR) and the survival OUTCOME variable (OUTCOME).

ID

Unique subject identifier column name in data.

t.name

The name of the time/period variable in data.

covars

Vector of names with time varying and baseline covariates in data. This argument does not need to be specified, by default all variables that are not in ID, t, CENS, TRT, MONITOR and OUTCOME will be considered as covariates.

CENS

Column name of the censoring variable(s) in data. Each separate variable specified in CENS can be either binary (0/1 valued integer) or categorical (integer). For binary indicators of CENSoring, the value of 1 indicates the CENSoring or end of follow-up event (this cannot be changed). For categorical CENSoring variables, by default the value of 0 indicates no CENSoring / continuation of follow-up and other values indicate different reasons for CENSoring. Use the argument noCENScat to change the reference (continuation of follow-up) category from default 0 to any other value. (NOTE: Changing noCENScat has zero effect on coding of the binary CENSoring variables, those have to always use 1 to code the CENSoring event). Note that factors are not allowed in CENS.

TRT

A column name in data for the exposure/treatment variable(s).

MONITOR

A column name in data for the indicator(s) of monitoring events.

OUTCOME

A column name in data for the survival OUTCOME variable name, code as 1 for the outcome event.

gform_CENS

Regression formula(s) for estimating the propensity score for the censoring mechanism: P(C(t) | W). See Details.

gform_TRT

Regression formula(s) for propensity score for the exposure/treatment(s): P(A(t) | W). See Details.

gform_MONITOR

Regression formula(s) for estimating the propensity score for the MONITORing process: P(N(t) | W). See Details. (the observed exposure mechanism), When omitted the regression is defined by sA~sW, where sA

stratify_CENS

A named list with one item per variable in CENS. Each list item is a character vector of stratification subsets for the corresponding variable in CENS.

stratify_TRT

A named list with one item per variable in TRT. Each list item is a character vector of stratification subsets for the corresponding variable in TRT.

stratify_MONITOR

A named list with one item per variable in MONITOR. Each list item is a character vector of stratification subsets for the corresponding variable in MONITOR.

intervened_TRT

Column name in data containing the counterfactual probabilities of following a specific treatment regimen.

intervened_MONITOR

Column name in data containing the counterfactual probabilities of following a specific monitoring regimen.

noCENScat

The level (integer) that indicates CONTINUATION OF FOLLOW-UP for ALL censoring variables. Defaults is 0. Use this to modify the default reference category (no CENSoring / continuation of follow-up) for variables specifed in CENS.

verbose

Set to TRUE to print messages on status and information to the console. Turn this on by default using options(stremr.verbose=TRUE).

optPars

A named list of additional optional parameters to be passed to stremr, such as alpha, lbound, family, YnodeDET, h_g0_GenericModel and h_gstar_GenericModel. See Details below for the description of each parameter.

Value

...

Details

The regression formalas in Qform, hform.g0 and hform.gstar can include any summary measures names defined in sW and sA, referenced by their individual variable names or by their aggregate summary measure names. For example, hform.g0 = "netA ~ netW" is equivalent to hform.g0 = "A + A_netF1 + A_netF2 ~ W + W_netF1 + W_netF2" for sW,sA summary measures defined by def_sW(netW=W[[0:2]]) and def_sA(netA=A[[0:2]]).

Additional parameters

Some of the parameters that control the estimation in stremr can be set by calling the function set_all_stremr_options.

Additional parameters can be also specified as a named list optPars argument of the stremr function. The items that can be specified in optPars are:

Specifying the counterfactual intervention function (f_gstar1 and optPars$f_gstar2)

The functions f_gstar1 and f_gstar2 can only depend on variables specified by the combined matrix of summary measures (sW,sA), which is passed using the argument data. The functions should return a vector of length nrow(data) of counterfactual treatments for observations in the input data.

IPTW estimator

**********************************************************************

See Also

stremr-package for the general overview of the package,

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
#-------------------------------------------------------------------
# EXAMPLE WITH CATEGORICAL CENSORING (3 levels)
#-------------------------------------------------------------------
require("data.table")
require("magrittr")
data(OdataCatCENS)
OdataDT <- as.data.table(OdataCatCENS, key=c(ID, t))
# Indicator that the person has never been treated in the past:
OdataDT[, "barTIm1eq0" := as.integer(c(0, cumsum(TI)[-.N]) %in% 0), by = ID]
# Define lagged N, first value is always 1 (always monitored at the first time point):
OdataDT[, ("N.tminus1") := shift(get("N"), n = 1L, type = "lag", fill = 1L), by = ID]

#-------------------------------------------------------------------
# Regressions for modeling the exposure (TRT)
#-------------------------------------------------------------------
gform_TRT <- "TI ~ CVD + highA1c + N.tminus1"
# Fit a separate model for TRT (stratify) for each of the following subsets:
stratify_TRT <- list(
  TI=c(
       # MODEL TI AT t=0
       "t == 0L",
       # MODEL TRT INITATION WHEN MONITORED
       "(t > 0L) & (N.tminus1 == 1L) & (barTIm1eq0 == 1L)",
       # MODEL TRT INITATION WHEN NOT MONITORED
       "(t > 0L) & (N.tminus1 == 0L) & (barTIm1eq0 == 1L)",
       # MODEL TRT CONTINUATION (BOTH MONITORED AND NOT MONITORED)
       "(t > 0L) & (barTIm1eq0 == 1L)"
      ))

#-------------------------------------------------------------------
# Regressions for modeling the categorical censoring (CENS)
#-------------------------------------------------------------------
gform_CENS <- c("CatC ~ highA1c")
# stratify by time-points (separate model for all t<16 and t=16)
stratify_CENS <- list(CatC=c("t < 16", "t == 16"))

#-------------------------------------------------------------------
# Regressions for modeling the monitoring regimen (MONITOR)
#-------------------------------------------------------------------
# Intercept only model, pooling across all time points t
gform_MONITOR <- "N ~ 1"

#-------------------------------------------------------------------
# Define the counterfactual monitoring regimen of interest
#-------------------------------------------------------------------
# probability of being monitored at each t is 0.1
OdataDT[, "gstar.N" := 0.1]

# Define two dynamic rules: dlow & dhigh
OdataDT <- defineIntervedTRT(OdataDT, theta = c(0,1), ID = "ID", t = "t", I = "highA1c",
                            CENS = "C", TRT = "TI", MONITOR = "N", tsinceNis1 = "lastNat1",
                            new.TRT.names = c("dlow", "dhigh"), return.allcolumns = TRUE)

# Estimate IPW-based hazard and survival (KM) for a rule "dhigh":
IPW_KM_res <- stremr(OdataDT, intervened_TRT = "dhigh", intervened_MONITOR = "gstar.N",
              ID = "ID", t = "t", covars = c("highA1c", "lastNat1"),
              CENS = "CatC", gform_CENS = gform_CENS, stratify_CENS = stratify_CENS,
              TRT = "TI", gform_TRT = gform_TRT, stratify_TRT = stratify_TRT,
              MONITOR = "N", gform_MONITOR = gform_MONITOR, OUTCOME = "Y.tplus1")

# Survival estimates by time:
IPW_KM_res$IPW_estimates
# Input data:
IPW_KM_res$dataDT

Example output

sh: 1: cannot create /dev/null: Permission denied
Loading required package: data.table
Loading required package: magrittr
    t   sum_Y_IPAW sum_all_IPAW           ht   St.IPTW       ht.KM     St.KM
1   0  9.910890351   926.170738 1.070093e-02 0.9892991 0.011709602 0.9882904
2   1 17.900833629   785.151317 2.279921e-02 0.9667438 0.020057307 0.9684680
3   2 20.383396016   585.466138 3.481567e-02 0.9330860 0.018115942 0.9509232
4   3 16.881335081   408.872517 4.128753e-02 0.8945612 0.034482759 0.9181328
5   4  6.501491023   344.984446 1.884575e-02 0.8777025 0.032934132 0.8878949
6   5 40.579472710   322.247044 1.259266e-01 0.7671764 0.031914894 0.8595578
7   6  3.567748829   280.130093 1.273604e-02 0.7574056 0.021739130 0.8408718
8   7  0.013952040   219.561998 6.354488e-05 0.7573575 0.005235602 0.8364693
9   8 23.610654177   141.907185 1.663810e-01 0.6313476 0.046242775 0.7977886
10  9  0.083891244   107.142640 7.829865e-04 0.6308533 0.020689655 0.7812827
11 10  0.626547293   137.742399 4.548689e-03 0.6279837 0.022900763 0.7633907
12 11  0.060272827    69.471855 8.675863e-04 0.6274389 0.042735043 0.7307672
13 12  0.070962423    60.410513 1.174670e-03 0.6267019 0.019417476 0.7165775
14 13  2.719183158    93.420087 2.910705e-02 0.6084604 0.021739130 0.7009997
15 14  4.171085606    98.812185 4.221226e-02 0.5827759 0.037500000 0.6747122
16 15  0.006068597    22.005535 2.757759e-04 0.5826152 0.027027027 0.6564768
17 16  0.000000000     5.495776 0.000000e+00 0.5826152 0.000000000 0.6564768
      rule.name
1  dhighgstar.N
2  dhighgstar.N
3  dhighgstar.N
4  dhighgstar.N
5  dhighgstar.N
6  dhighgstar.N
7  dhighgstar.N
8  dhighgstar.N
9  dhighgstar.N
10 dhighgstar.N
11 dhighgstar.N
12 dhighgstar.N
13 dhighgstar.N
14 dhighgstar.N
15 dhighgstar.N
16 dhighgstar.N
17 dhighgstar.N
        ID CVD t lastNat1 highA1c TI CatC C  N Y.tplus1 barTIm1eq0 N.tminus1
   1:    1   0 0        0       0  0    0 0  1        0          1         1
   2:    1   0 1        0       0  1    0 0  0        0          1         1
   3:    1   0 2        1       0  1    1 1 NA       NA          0         0
   4:    2   0 0        0       0  0    0 0  1        0          1         1
   5:    2   0 1        0       1  0    0 0  1        0          1         1
  ---                                                                       
8126: 1000   0 1        1       0  0    0 0  0        0          1         0
8127: 1000   0 2        2       0  0    0 0  1        0          1         0
8128: 1000   0 3        0       0  0    0 0  1        0          1         1
8129: 1000   0 4        0       1  0    0 0  1        0          1         1
8130: 1000   0 5        0       1  0    0 0  0        1          1         1
      gstar.N dlow dhigh       g0.A       g0.C      g0.N      g0.CAN
   1:     0.1    1     0 0.89631162 0.91897388 0.4939082 0.406825707
   2:     0.1    1     0 0.01160565 0.91897388 0.5060918 0.005397615
   3:     0.1    1     0 1.00000000 0.04113875 1.0000000 0.041138746
   4:     0.1    1     0 0.89631162 0.91897388 0.4939082 0.406825707
   5:     0.1    1     1 0.23588241 0.91535060 0.4939082 0.106642229
  ---                                                               
8126:     0.1    1     0 1.00000000 0.91897388 0.5060918 0.465085186
8127:     0.1    1     0 1.00000000 0.91897388 0.4939082 0.453888691
8128:     0.1    1     0 0.79614663 0.91897388 0.4939082 0.361361951
8129:     0.1    1     1 0.23588241 0.91535060 0.4939082 0.106642229
8130:     0.1    1     1 0.23588241 0.91535060 0.5060918 0.109272872

stremr documentation built on May 30, 2017, 6:35 a.m.