README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
library(RefManageR)
bib <- ReadBib(system.file("Bib", "README-refs.bib", package = "stremr"), check = FALSE)
# bib2 <- ReadBib(system.file("Bib", "RJC.bib", package = "RefManageR"))[[seq_len(20)]]
BibOptions(check.entries = FALSE, style = "markdown", cite.style = "authoryear", bib.style = "numeric")
```

# R/`stremr`: Streamlined Causal Inference for Static, Dynamic and Stochastic Regimes in Longitudinal Data


[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/stremr)](https://CRAN.R-project.org/package=stremr)
[![](https://cranlogs.r-pkg.org/badges/stremr)](https://CRAN.R-project.org/package=stremr)
[![Travis-CI Build Status](https://travis-ci.org/osofr/stremr.svg?branch=master)](https://travis-ci.org/osofr/stremr)
[![codecov](https://codecov.io/gh/osofr/stremr/branch/master/graph/badge.svg)](https://codecov.io/gh/osofr/stremr)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)

> Analysis of longitudinal data, with continuous or time-to-event (binary) outcome 
> and time-varying confounding.
> Allows adjustment for all *measured* time-varying confounding and informative right-censoring.
> Estimate the expected counterfactual outcome under static, dynamic or stochastic interventions. 
> Includes doubly robust and semi-parametrically efficient Targeted Minimum Loss-Based Estimator (TMLE), 
> along with several other estimators.  
> Perform data-adaptive estimation of the outcome and treatment models with Super Learner [`sl3`](https://jeremyrcoyle.github.io/sl3/).

__Authors:__ [Oleg Sofrygin](https://divisionofresearch.kaiserpermanente.org/researchers/sofrygin-oleg), [Mark van der Laan](https://vanderlaan-group.github.io/), [Romain Neugebauer](https://divisionofresearch.kaiserpermanente.org/researchers/neugebauer-romain)

## Available estimators

Currently available estimators can be roughly categorized into 4 groups:

  * Propensity-score / Inverse Probability Weighted (IPW):
    - direct (bounded) IPW (`directIPW`)
    - [IPW-adjusted Kaplan-Meier](https://doi.org/10.1002/sim.2174) (`survNPMSM`)
    - [MSM-IPW for the survival hazard](https://doi.org/10.1016/j.jclinepi.2013.01.016) (`survMSM`)
  * Outcome regression:
    - longitudinal G-formula (`GCOMP`) `r AutoCite(bib, "Bang:Robins05")`
  * Doubly-robust (DR) approaches:
    - TMLE for longitudinal data (`TMLE`) `r AutoCite(bib, "vanderLaan:Gruber12a")`
    - iterative TMLE (`iterTMLE`)
    - cross-validated TMLE (`CVTMLE`)
  * Sequentially doubly-robust (SDR) approaches:
    - infinite-dimensional TMLE (`iTMLE`) `r AutoCite(bib, "luedtke2017")`
    - doubly robust unbiased transformations (`DR_transform`) ([Rubin and van der Laan, 2006](http://biostats.bepress.com/ucbbiostat/paper208), `r Citet(bib, "luedtke2017")``)

##Input data format 

The exposure, monitoring and censoring variables can be coded as either binary, categorical or continuous. Each can be multivariate (e.g., can use more than one column of dummy indicators for different censoring events). The input data needs to be in long format.

 - Possibly right-censored data has to be in long format.
 - Each row must contain a subject identifier (`ID`) and the integer indicator of the current time (`t`), e.g., day, week, month, year.
 - The package assumes that the temporal ordering of covariates in each row is **fixed** according to (`ID`, `t`, `L`,`C`,`A`,`N`,`Y`), where 
     * `L` -- Time-varying and baseline covariates.
     * `C` -- Indicators of right censoring events at time `t`; this can be either a single categorical or several binary columns.
     * `A` -- Exposure (treatment) at time `t`; this can be multivariate (more than one column) and each column can be binary, categorical or continuous.
     * `N` -- Indicator of being monitored at time point `t+1` (binary).
     * `Y` -- Outcome (binary 0/1 or continuous between 0 and 1).
 - Categorical censoring can be useful for representing all of the censoring events with a single column (variable).

##Estimation of the outcome and treatment models

 - Separate models are fit for the observed censoring, exposure and monitoring mechanisms. Jointly, these make up what is known as the *propensity score*.
 - Separate outcome regression models can be specified for each time-point.
 - Each propensity score model can be stratified (separate model is fit) by time or any other user-specified stratification criteria. Each strata is defined with by a single logical expression that selects specific observations/rows in the observed data (strata).
 -  By default, all models are fit with the logistic regression.
 -  Alternatively, model fitting can be performed via any machine learning (ML) algorithm available in [`sl3`](https://github.com/jeremyrcoyle/sl3) and [`gridisl`](https://github.com/osofr/gridisl) R packages. See [`xgboost`](https://github.com/dmlc/xgboost) and [`h2o`](https://github.com/h2oai/h2o-3) for a sample description of possible ML algorithms.
 -  One can select the best model from an ensemble of many learners via *model stacking* or *Super Learning* `r AutoCite(bib, c("breiman1996stacked","vdl2007super"))`, which finds the optimal convex combination of all models in the ensemble via cross-validation.

## Brief overview of `stremr`

* [Installing `stremr` and Documentation](#installation)
* [Issues](#issues)
* [Documentation](#docs)
* [Example with Simulated Data](#Example1)
* [Sequential G-Computation (GCOMP) and Targeted Maximum Likelihood Estimation (TMLE) for longitudinal survival data](#GCOMPTMLE)
* [Machine Learning](#ML)
* [Ensemble Learning with Discrete SuperLearner (based on `gridisl` R package)](#gridisl)
* [Details on some implemented estimators](#estimators)


### Installation<a name="installation"></a>

<!-- To install the CRAN release version of `stremr`: 
```R
install.packages('stremr')
```
 -->

To install the development version (requires the `devtools` package):

```{r, eval = FALSE}
devtools::install_github('osofr/stremr')
```

For ensemble-learning with Super Learner algorithm we recommend installing the latest development version of the `sl3` R package. It can be installed as follows:

```{r, eval = FALSE}
devtools::install_github('jeremyrcoyle/sl3')
```

For optimal performance, we also recommend installing the latest version of `data.table` package:

```{r, eval = FALSE}
remove.packages("data.table")                         # First remove the current version
install.packages("data.table", type = "source",
    repos = "http://Rdatatable.github.io/data.table") # Then install devel version
```

### Issues<a name="issues"></a>

If you encounter any bugs or have any specific feature requests, please [file an
issue](https://github.com/osofr/stremr/issues).


### Documentation<a name="docs"></a>
To obtain documentation for specific relevant functions in `stremr` package:

```{r, eval = FALSE}
?stremr
?importData
?fitPropensity
?getIPWeights
?directIPW
?survNPMSM
?survMSM
?fit_GCOMP
?fit_iTMLE
```

<!-- <a name="Reports"></a>
### Automated Reports:

The following is an example of a function call that produces an automated `html` report shown below. For a pdf report just set the argument `format = "pdf"`.
```R
  make_report_rmd(OData, NPMSM = list(surv1, surv2), 
                  MSM = MSM.IPAW, 
                  GCOMP = list(gcomp_est1, gcomp_est2), 
                  TMLE = list(tmle_est_par1, tmle_est_par2),
                  AddFUPtables = TRUE, RDtables = get_MSM_RDs(MSM.IPAW, t.periods.RDs = c(12, 15), getSEs = TRUE),
                  WTtables = get_wtsummary(MSM.IPAW$wts_data, cutoffs = c(0, 0.5, 1, 10, 20, 30, 40, 50, 100, 150), by.rule = TRUE),
                  file.name = "sim.data.example.fup", title = "Custom Report Title", author = "Author Name", y_legend = 0.99, x_legend = 9.5)
```

![gif](https://cloud.githubusercontent.com/assets/6721358/18609476/d9b4db74-7cb7-11e6-9ca6-aacf0b70ca4c.gif)

 -->

### Simulated data example<a name="Example1"></a>

Load the data:

```{r}
require("magrittr")
require("data.table")
require("stremr")

data(OdataNoCENS)
datDT <- as.data.table(OdataNoCENS, key=c("ID", "t"))
```

Define some summaries (lags):

```{r}
datDT[, ("N.tminus1") := shift(get("N"), n = 1L, type = "lag", fill = 1L), by = ID]
datDT[, ("TI.tminus1") := shift(get("TI"), n = 1L, type = "lag", fill = 1L), by = ID]
```

Define counterfactual exposures. In this example we define one intervention as always treated  and another as never treated. Such intervention can be defined conditionally on other variables (dynamic intervention). Similarly, one can define the intervention as a probability that the counterfactual exposure is 1 at each time-point `t` (for stochastic interventions).

```{r}
datDT[, ("TI.set1") := 1L]
datDT[, ("TI.set0") := 0L]
```

Import input data into `stremr` object `DataStorageClass` and define relevant covariates:

```{r}
OData <- importData(datDT, ID = "ID", t = "t", covars = c("highA1c", "lastNat1", "N.tminus1"), CENS = "C", TRT = "TI", OUTCOME = "Y.tplus1")
```

Once the data has been imported, it is still possible to inspect it and modify it, as shown in this example:

```{r}
get_data(OData)[, ("TI.set0") := 1L]
get_data(OData)[, ("TI.set0") := 0L]
```

Regressions for modeling the propensity scores for censoring (`CENS`) and exposure (`TRT`). By default, each of these propensity scores is fit with a common model that pools across all available time points (smoothing over all time-points).

```{r}
gform_CENS <- "C ~ highA1c + lastNat1"
gform_TRT <- "TI ~ CVD + highA1c + N.tminus1"
```

Stratification, that is, fitting separate models for different time-points, is enabled with logical expressions in arguments `stratify_...` (see `?fitPropensity`). For example, the logical expression below states that we want to fit the censoring mechanism with a separate model for time point 16, while pooling with a common model fit over time-points 0 to 15. Any logical expression can be used to define such stratified modeling. This can be similarly applied to modeling the exposure mechanism (`stratify_TRT`) and the monitoring mechanism (`stratify_MONITOR`).

```{r}
stratify_CENS <- list(C=c("t < 16", "t == 16"))
```

Fit the propensity scores for censoring, exposure and monitoring:

```{r}
OData <- fitPropensity(OData,
                       gform_CENS = gform_CENS,
                       gform_TRT = gform_TRT,
                       stratify_CENS = stratify_CENS)
```

<a name="survNPMSM"></a>Estimate survival based on non-parametric/saturated IPW-MSM (IPTW-ADJUSTED KM):

```{r}
AKME.St.1 <- getIPWeights(OData, intervened_TRT = "TI.set1") %>%
             survNPMSM(OData) %$%
             estimates
```

The result is a `data.table` that contains the estimates of the counterfactual survival for each time-point, for the treatment regimen `TI.set1`. In this particular case, the column `St.NPMSM` contains the survival estimates for IPW-NPMSM and the first row represents the estimated proportion alive at the end of the first cycle / time-point. Note that the column `St.KM` 
contains the unadjusted/crude estimates of survival (should be equivalent to 
standard Kaplan-Meier estimates for most cases).

```{r}
head(AKME.St.1[],2)
```

<a name="directIPW"></a>Estimate survival with bounded IPW:

```{r}
IPW.St.1 <- getIPWeights(OData, intervened_TRT = "TI.set1") %>%
            directIPW(OData) %$%
            estimates
```

As before, the result is a `data.table` with estimates of the counterfactual survival for each time-point, for the treatment regimen `TI.set1`, located in column `St.directIPW`.

```{r}
head(IPW.St.1[],2)
```


<a name="survMSM"></a>Estimate hazard with IPW-MSM then map into survival estimate. Using two regimens and smoothing over two intervals of time-points:

```{r}
wts.DT.1 <- getIPWeights(OData = OData, intervened_TRT = "TI.set1", rule_name = "TI1")
wts.DT.0 <- getIPWeights(OData = OData, intervened_TRT = "TI.set0", rule_name = "TI0")
survMSM_res <- survMSM(list(wts.DT.1, wts.DT.0), OData, tbreaks = c(1:8,12,16)-1,)
```

In this particular case the output is a little different, with separate survival tables for each regimen. The output of `survMSM` is hence a list, 
with one item for each counterfactual treatment regimen considered during the estimation. The actual estimates of survival are located in the column(s) `St.MSM`. Note that `survMSM` output also contains the standard error estimates of survival at each time-point in column(s) `SE.MSM`. Finally, the output table also contains the subject-specific estimates of the influence-curve (influence-function) in column(s) `IC.St`. These influence function estimates can be used for constructing the confidence intervals of the counterfactual risk-differences for two contrasting treatments (see help for `get_RDs` function for more information).

```{r}
head(survMSM_res[["TI0"]][["estimates"]],2)
head(survMSM_res[["TI1"]][["estimates"]],2)
```

### Longitudinal GCOMP (G-formula) and TMLE <a name="GCOMPTMLE"></a>

Define time-points of interest, regression formulas and software to be used for fitting the sequential outcome models:

```{r}
tvals <- c(0:10)
Qforms <- rep.int("Qkplus1 ~ CVD + highA1c + N + lastNat1 + TI + TI.tminus1", (max(tvals)+1))
```

To run iterative means substitution estimator (G-Computation), where all at risk observations are `pooled` for fitting each outcome regression (Q-regression):

```{r}
gcomp_est <- fit_GCOMP(OData, tvals = tvals, intervened_TRT = "TI.set1", Qforms = Qforms)
```

The output table of `fit_GCOMP` contains the following information, with the column `St.GCOMP` containing the survival estimates for each time period:

```{r}
head(gcomp_est$estimates[],2)
```

To run the longitudinal `long format` Targeted Minimum-Loss Estimation (TMLE), `stratified` by rule-followers for fitting each outcome regression (Q-regression):

```{r}
tmle_est <- fit_TMLE(OData, tvals = tvals, intervened_TRT = "TI.set1", Qforms = Qforms)
```

The output table of `fit_TMLE` contains the following information, with the column `St.TMLE` containing the survival estimates for each time period. In addition, the column `SE.TMLE` contains the standard error estimates and the column and the column `IC.St` contains the subject-specific estimates of the efficient influence curve. The letter estimates are useful for constructing the confidence intervals of risk differences for two contrasting treatments (see help for `get_RDs` function for more information).

```{r}
head(tmle_est$estimates[],2)
```

To parallelize estimation over several time-points (`tvals`) for either GCOMP or TMLE use argument `parallel = TRUE`:

```{r, eval = FALSE}
require("doParallel")
registerDoParallel(cores = parallel::detectCores())
tmle_est <- fit_TMLE(OData, tvals = tvals, intervened_TRT = "TI.set1", Qforms = Qforms, parallel = TRUE)
```

### Data-adaptive estimation, cross-validation and Super Learning <a name="ML"></a>

Nuisance parameters can be modeled with any machine learning algorithm supported by [`sl3`](https://jeremyrcoyle.github.io/sl3/) R package. For example, for GLMs use learner `Lrnr_glm_fast`, for `xgboost` use learner `Lrnr_xgboost`, for `h2o` GLM learner use `Lrnr_h2o_glm`, for any other ML algorithm implemented in `h2o` use `Lrnr_h2o_grid$new(algorithm = "algo_name")`, for `glmnet` use learner `Lrnr_glmnet`. All together, these learners provide access to a wide variety of ML algorithms. To name a few: *GLM*, *Regularized GLM*, *Distributed Random Forest (RF)*, *Extreme Gradient Boosting (GBM)* and *Deep Neural Nets*. <!-- The package provides simple syntax for specifying large grids of tuning parameters, including random grid search over parameter space.  -->

Model selection can be performed via V-fold cross-validation or random validation splits and model stacking and Super Learner combination can be accomplished by using the learner `Lrnr_sl` and specifying the meta-learner (e.g., `Lrnr_solnp`). In the example below we define a Super Learner ensemble consisting of several learning algorithms. 

First, we define `sl3` learners for for xgboost, two types of GLMs and glmnet. Then we will stack these learners into a single learner called `Stack`:

```{r}
library("sl3")
lrn_xgb <- Lrnr_xgboost$new(nrounds = 5)
lrn_glm <- Lrnr_glm_fast$new()
lrn_glm2 <- Lrnr_glm_fast$new(covariates = c("CVD"))
lrn_glmnet <- Lrnr_glmnet$new(nlambda = 5, family = "binomial")
## Stack the above candidates:
lrn_stack <- Stack$new(lrn_xgb, lrn_glm, lrn_glm2, lrn_glmnet)
```

Next, we will define a Super Learner on the above defined stack, by feeding the stack into the `Lrnr_sl` object and then specifying the meta-learner that will find the optimal convex combination of the learners in a stack (`Lrnr_solnp`): 

```{r}
lrn_sl <- Lrnr_sl$new(learners = lrn_stack, metalearner = Lrnr_solnp$new())
```

<!-- For less error-prone training with `h2o` (especially if using `sl3::Lrnr_h2o_grid$new(algorithm = "gbm")` or , please install this version of `h2o` R package: -->

We will now use `stremr` to estimate the exposure / treatment propensity model with the above defined Super Learner (`lrn_sl`):

```{r}
OData <- fitPropensity(OData,
                       gform_CENS = gform_CENS,
                       gform_TRT = gform_TRT,
                       models_TRT = lrn_sl,
                       stratify_CENS = stratify_CENS)
```

<!-- Other available algorithms are Gradient Boosting Machines (`estimator = "h2o__gbm"`) or Extreme Gradient Boosting (`estimator = "xgboost__gbm"`), distributed GLM (including LASSO and Ridge) (`estimator = "h2o__glm"` or `estimator = "xgboost__glm"`) and Deep Neural Nets (`estimator = "h2o__deeplearning"`). -->

<!-- Use arguments `params_...` in `fitPropensity()` and `models` in `fit_GCOMP()` and `fit_TMLE()` to pass various tuning parameters and select different algorithms for different models:
```R
params_TRT = list(fit.package = "h2o", fit.algorithm = "gbm", ntrees = 50, learn_rate = 0.05, sample_rate = 0.8, col_sample_rate = 0.8, balance_classes = TRUE)
params_CENS = list(fit.package = "speedglm", fit.algorithm = "glm")
params_MONITOR = list(fit.package = "speedglm", fit.algorithm = "glm")
OData <- fitPropensity(OData,
          gform_CENS = gform_CENS, stratify_CENS = stratify_CENS, params_CENS = params_CENS,
          gform_TRT = gform_TRT, params_TRT = params_TRT,
          gform_MONITOR = gform_MONITOR, params_MONITOR = params_MONITOR)
```
 -->
 
<!-- Running TMLE based on the previous fit of the propensity scores. Also applying Random Forest to estimate the sequential outcome model:
```R
models = list(fit.package = "h2o", fit.algorithm = "randomForest", ntrees = 100, learn_rate = 0.05, sample_rate = 0.8, col_sample_rate = 0.8, balance_classes = TRUE)

tmle_est <- fit_TMLE(OData, tvals = tvals, intervened_TRT = "TI.set1", Qforms = Qforms, models = models, stratifyQ_by_rule = TRUE)
```
 -->
<!-- <a name="SuperLearner"></a>
###Ensemble Learning with SuperLearner (based on `gridisl` R package)

```R
require('gridisl')
```


Easy specification of large ensembles with grid search:

1. Define a learning algorithm (e.g., `glm`)
2. Define the search criteria (e.g., 120 second maximum). Increase parameters `max_runtime_secs` or `max_models` to cover larger number of models from tuning parameter space.
3. Define the space of tuning parameters (hyper-parameters) by specifying their learner-specific names and values for grid search (e.g., `alpha` and `lambda` for glm).


When running the SuperLearner with grid search, `stremr` calls the following outside functions:

1. Runs `h2o.grid` in the background for each individual learner and saves cross-validated risks.
2. Calls `h2o.stack` from `h2oEnsemble` package to evaluate the final SuperLearner fit on a combination of all learners returned by different grid searches and individually specified learners.


Here is an example defining the grid search criteria and search space of tuning parameters for h2o glm (`h2o.glm`):
```R
GLM_hyper_params <- list(search_criteria = list(strategy = "RandomDiscrete", max_models = 5),
                         alpha = c(0,1,seq(0.1,0.9,0.1)),
                         lambda = c(0,1e-7,1e-5,1e-3,1e-1))
```

Another example with grid search for Random Forest (`h2o.randomForest`) (will be combined with above in a single SuperLearner ensemble):
```R
search_criteria <- list(strategy = "RandomDiscrete", max_models = 5, max_runtime_secs = 60*60)
RF_hyper_params <- list(search_criteria = search_criteria,
                        ntrees = c(100, 200, 300, 500),
                        mtries = 1:4,
                        max_depth = c(5, 10, 15, 20, 25),
                        sample_rate = c(0.7, 0.8, 0.9, 1.0),
                        col_sample_rate_per_tree = c(0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8),
                        balance_classes = c(TRUE, FALSE))
```

Final example with grid search for Gradient Boosting Machines (`h2o.gbm`) (will be also combined with above grid searches):
```R
GBM_hyper_params <- list(search_criteria = search_criteria,
                         ntrees = c(100, 200, 300, 500),
                         learn_rate = c(0.005, 0.01, 0.03, 0.06),
                         max_depth = c(3, 4, 5, 6, 9),
                         sample_rate = c(0.7, 0.8, 0.9, 1.0),
                         col_sample_rate = c(0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8),
                         balance_classes = c(TRUE, FALSE))
```

In addition, we can specify individual learners that we may want to include in the SuperLearner library:
```R
h2o.glm.1 <- function(..., alpha = 0.0) h2o.glm.wrapper(..., alpha = alpha)
h2o.glm.2 <- function(..., x = "highA1c", alpha = 0.0) h2o.glm.wrapper(..., x = x, alpha = alpha)
h2o.glm.3 <- function(..., alpha = 1.0) h2o.glm.wrapper(..., alpha = alpha)
```

The SuperLearner ensemble is now defined with a single list of parameters that includes the above models.  We also define additional SuperLearner-specific parameters here (such as, `nfolds` - number of folds for cross-validation, `metalearner` and `seed`):
```R
SLparams = list(fit.package = "h2o", fit.algorithm = "SuperLearner",
                 grid.algorithm = c("glm", "randomForest", "gbm"),
                 learner = c("h2o.glm.1", "h2o.glm.2", "h2o.glm.3"),
                 metalearner = "h2o.glm_nn",
                 nfolds = 10,
                 seed = 23,
                 glm = GLM_hyper_params,
                 randomForest = RF_hyper_params,
                 gbm = GBM_hyper_params)
```


We can also save the SuperLearner fits by adding parameters `save.ensemble` and `ensemble.dir.path`. This will save the entire ensemble of models that were used by the SuperLearner. Separate directories are required for different SuperLearner models (for example a separate directory for censoring model and a separate directory for treatment model). These pre-saved fits can be loaded at a later time to avoid the lengthy refitting process by using the argument `load.ensemble = TRUE`.

```R
params_TRT = c(SLparams, save.ensemble = TRUE, ensemble.dir.path = "./h2o-ensemble-model-TRT")
```

The following example fits the propensity score using above SuperLearner to model the exposure mechanism and using `speedglm` logistic regressions for censoring and monitoring:
```R
params_CENS = list(fit.package = "speedglm", fit.algorithm = "glm")
params_MONITOR = list(fit.package = "speedglm", fit.algorithm = "glm")

OData <- fitPropensity(OData,
            gform_CENS = gform_CENS, stratify_CENS = stratify_CENS, params_CENS = params_CENS,
            gform_TRT = gform_TRT, params_TRT = params_TRT,
            gform_MONITOR = gform_MONITOR, params_MONITOR = params_MONITOR)
```

The following example loads the previously saved fits of the SuperLearner for the exposure. The only models fit during this call to `fitPropensity` are for the monitoring and censoring.
```R
params_TRT = c(SLparams, load.ensemble = TRUE, ensemble.dir.path = "./h2o-ensemble-model-TRT")

OData <- fitPropensity(OData,
            gform_CENS = gform_CENS, stratify_CENS = stratify_CENS, params_CENS = params_CENS,
            gform_TRT = gform_TRT, params_TRT = params_TRT,
            gform_MONITOR = gform_MONITOR, params_MONITOR = params_MONITOR)
```

The SuperLearner for TMLE and GCOMP is specified in an identical fashion. One needs to specify the relevant parameters and the ensemble models as part of the `models` argument. However, its currently not possible to save the individual SuperLearner fits of the outcome (Q) model.
 -->

### Details on some implemented estimators<a name="estimator"></a>

Currently implemented **estimators** include:

 - *Kaplan-Meier* Estimator. No adjustment for time-varying confounding or informative right-censoring.
 - *Inverse Probability Weighted (IPW) Kaplan-Meier (`survNPMSM`)*. Also known as the Adjusted Kaplan Meier (AKME). Also known as the saturated (non-parametric) IPW-MSM estimator of the survival hazard. This estimator inverse weights each observation based on the exposure/censoring model fits (propensity scores).
 - *Bounded Inverse Probability Weighted (B-IPW) Estimator of Survival('directIPW')*. Estimates the survival directly (without hazard), also based on the exposure/censoring model fit (propensity scores).
 - *Inverse Probability Weighted Marginal Structural Model (`survMSM`)* for the hazard function, mapped into survival. Currently only logistic regression is allowed where covariates are time-points and regime/rule indicators. This estimator is also based on the exposure/censoring model fit (propensity scores), but allows additional smoothing over multiple time-points and includes optional weight stabilization.
 - *Longitudinal G-formula (`GCOMP`)*. Also known as the iterative G-Computation formula or Q-learning. Directly estimates the outcome model while adjusting for time-varying confounding. Estimation can be stratified by rule/regime followed or pooled across all rules/regimes.
 - *Longitudinal Targeted Minimum-Loss-based Estimator (`TMLE`)*. Also known as L-TMLE. Doubly robust and semi-parametrically efficient estimator that de-biases each outcome regression fit with a targeting step, using IPW.
 - *Iterative TMLE (`iterTMLE`)* for longitudinal data. Fits sequential G-Computation and then iteratively performs targeting for all pooled Q's until convergence. 
 - *Infinite-dimensional TMLE (`iTMLE`)* for longitudinal data. Fits sequential G-Computation and performs additional *infinite-dimensional* targeting to achieve sequential double robustness. 

### Citation

To cite `stremr` in publications, please use:

> Sofrygin O, van der Laan MJ, Neugebauer R (2017). *stremr: Streamlined Estimation for Static, Dynamic and Stochastic Treatment Regimes in Longitudinal Data.* R package version x.x.xx


### Funding

This work was partially supported through a Patient-Centered Outcomes Research Institute (PCORI) Award (ME-1403-12506). All statements in this work, including its findings and conclusions, are solely those of the authors and do not necessarily represent the views of the Patient-Centered Outcomes Research Institute (PCORI), its Board of Governors or Methodology Committee. This work was also supported through an NIH grant (R01 AI074345-07).

### Copyright
The contents of this repository are distributed under the MIT license.
```
The MIT License (MIT)

Copyright (c) 2015-2017 Oleg Sofrygin 

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
---

### References

```{r results = "asis", echo = FALSE}
PrintBibliography(bib, .opts = list(check.entries = FALSE, sorting = "ynt"))
```