---
title: "An Introduction to StratifiedMedicine"
output: rmarkdown::html_vignette
author: "Thomas Jemielita"
vignette: >
  %\VignetteIndexEntry{An Introduction to StratifiedMedicine}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width=10, fig.height=8.5
)
```

# Introduction
Welcome to the StratifiedMedicine R package. The overall goal of this package is to develop analytic and visualization tools to aid in stratified and personalized medicine. Stratified medicine aims to find subsets or subgroups of patients with similar treatment effects, for example responders vs non-responders, while personalized medicine aims to understand treatment effects at the individual level (does a specific individual respond to treatment A?). 

Currently, the main tools in this package area: (1) Filter Models (identify important variables and reduce input covariate space), (2) Patient-Level Estimate Models (using regression models, estimate counterfactual quantities, such as the conditional average treatment effect or CATE), (3) Subgroup Models (identify groups of patients using tree-based approaches),
and (4) Parameter Estimation (across the identified subgroups), and (5) PRISM (Patient Response Identifiers for Stratified Medicine; combines tools 1-4). Development of this package is ongoing. 

As a running example, consider a continuous outcome (ex: % change in tumor size) with a binary treatment (study treatment vs control). The estimand of interest is the average treatment effect, $\theta_0 = E(Y|A=1)-E(Y|A=0)$. First, we simulate continuous data where roughly 30\% of the patients receive no treatment-benefit for using $A=1$ vs $A=0$. Responders (should receive study treatment) vs non-responders (should receive control) are defined by the continuous predictive covariates $X_1$ and $X_2$ for a total of four subgroups. Subgroup treatment effects are: $\theta_{1} = 0$ ($X_1 \leq 0, X_2 \leq 0$), $\theta_{2} = 0.25 (X_1 > 0, X_2 \leq 0)$, $\theta_{3} = 0.45 (X_1 \leq 0, X2 > 0$), $\theta_{4} = 0.65 (X_1>0, X_2>0)$.

```{r sim_ctns, warning=FALSE, message=FALSE}
library(ggplot2)
library(dplyr)
library(partykit)
library(StratifiedMedicine)
library(survival)
dat_ctns = generate_subgrp_data(family="gaussian")
Y = dat_ctns$Y
X = dat_ctns$X # 50 covariates, 46 are noise variables, X1 and X2 are truly predictive
A = dat_ctns$A # binary treatment, 1:1 randomized 
length(Y)
table(A)
dim(X)
```


# Filter Models

The aim of filter models is to potentially reduce the covariate space such that subsequent analyses focus on the "important" variables. For example, we may want to identify variables that are prognostic and/or predictive of the outcome across treatment levels. Filter models can be run using the "filter_train" function. The default is search for prognostic variables using elastic net (Y~ENET(X); Hou and Hastie 2005). Random forest based importance (filter="ranger") is also available. See below for an example. Note that the object "filter.vars" contains the variables that pass the filter, while "plot_importance" shows us the relative importance of the input variables. For glmnet, this corresponds to the standardized regression coefficients (variables with coefficients=0 are not shown).

```{r filter_glmnet, warning=FALSE, message=FALSE}
res_f <- filter_train(Y, A, X, filter="glmnet")
res_f$filter.vars
plot_importance(res_f)
```
An alternative approach is to search for variables that are potentially prognostic and/or predictive by forcing variable by treatment interactions, or Y~ENET(X,XA). Variables with estimated coefficients of 0 in both the main effects (X) and interaction effects (XA) are filtered. This can be implemented by tweaking the hyper-parameters: 
```{r filter_glmnet2, warning=FALSE, message=FALSE, include=FALSE}
res_f2 <- filter_train(Y, A, X, filter="glmnet", hyper=list(interaction=T))
res_f2$filter.vars
plot_importance(res_f2)
```
Here, note that both the main effects of X1 and X2, along with the interaction effects (labeled X1_trtA and X2_trtA), have relatively large estimated coefficients.

# Patient-level Estimate (PLE) Models

The aim of PLE models is to estimate counterfactual quantities, for example the CATE. This is implemented through the "ple_train" function. The "ple_train" follows the framework of Kunzel et al 2019, which utilizes base learners and meta learners to obtain estimates of interest. For family="gaussian", "binomial", this output estimates of \eqn{mu(a,x)=E(Y|x,a)} and treatment differences. For family="survival", either logHR or restricted mean survival time (RMST) estimates are obtained. Current base-leaner options include "linear" (lm/glm/or cox), "ranger" (random forest through ranger R package), "glmnet" (elastic net), and "bart" (Bayesian Additive Regression Trees through BART R package). Meta-learners include the "T-Leaner" (treatment specific models), "S-learner" (single regression model), and "X-learner" (2-stage approach, see Kunzel et al 2019). See below for an example. Note that the object "mu_train" contains the training set patient-level estimates (outcome-based and propensity scores), "plot_ple" shows a waterfall plot of the estimated CATEs, and "plot_dependence" shows the partial dependence plot for variable "X1" with respect to the estimated CATE. 

```{r ple_train, warning=FALSE, message=FALSE}
res_p1 <- ple_train(Y, A, X, ple="ranger", meta="T-learner")
summary(res_p1$mu_train)
plot_ple(res_p1)
plot_dependence(res_p1, X=X, vars="X1")
```
Next, let's illustrate how to change the meta-learner and the hyper-parameters. See below, along with a 2-dimension PDP example.
```{r ple_train2, warning=FALSE, message=FALSE}
res_p2 <- ple_train(Y, A, X, ple="ranger", meta="T-learner", hyper=list(mtry=5))
plot_dependence(res_p2, X=X, vars=c("X1", "X2"))
```

# Subgroup Models

Subgroup models are called using the "submod_train" function and currently only include
tree-based methods (ctree, lmtree, glmtree from partykit R package and rpart from rpart R package). First, let's run the default (for continuous, uses lmtree). This aims to find subgroups that are either prognostic and/or predictive. 

```{r submod_train1, warning=FALSE, message=FALSE}
res_s1 <- submod_train(Y, A, X, submod="lmtree")
summary(res_s1)
plot_tree(res_s1)
```

At each node, "naive" treatment estimates are provided. Without some type of resampling or penalization, subgroup-specific estimates tend to be overly positive or negative, as the same data that trains the subgroup model is used for parameter estimation. Resampling methods, such as bootstrapping, can help mitigate biased treatment estimates (more details in later Sections). See the "resample" argument for more details. 

Another generic approach is "rpart_cate", which corresponds to regressing CATE~rpart(X) where CATE corresponds to estimates of E(Y|A=1,X)-E(Y|A=0,X). For survival endpoints, the treatment difference would correspond to either logHR or RMST. For the example below, we set the clinically meaningful threshold to 0.1 (delta=">0.10"). 

```{r submod_train2, warning=FALSE, message=FALSE}
res_s2 <- submod_train(Y, A, X,  mu_train=res_p2$mu_train, submod="rpart_cate")
summary(res_s2)
```

# Treatment Effect Estimation

The "param" argument within "submod_train" and "PRISM" determines the method for treatment effect estimation across the identified subgroups. Options include param="lm", "dr", "gcomp", "cox", and "rmst" which correspond respectively to linear regression, the doubly robust estimator, average the patient-level estimates (G-computation), cox regresson, and RMST (as in survRM2 R package). Notably, if the subgroups are determined adaptively (for example through lmtree), without resampling corrections, point-estimates tend to be overly optimistic. Resampling-based methods are described later.

Given a candidate set of subgroups, a "naive" approach is to fit linear regression models within each subgroup to obtain treatment effect estimates (A=1 vs A=0). See below.

```{r param1, warning=FALSE, message=FALSE}
param.dat1 <- param_est(Y, A, X, Subgrps = res_s1$Subgrps.train, param="lm")
param.dat1
```

# PRISM: Patient Response Identifiers for Stratified Medicine

While the above tools individually can be useful, PRISM (Patient Response Identifiers for Stratified Medicine; Jemielita and Mehrotra (to appear), https://arxiv.org/abs/1912.03337) combines each component for a stream-lined analysis. Given a data-structure of $(Y, A, X)$ (outcome(s), treatments, covariates), PRISM is a five step procedure:

0. **Estimand**: Determine the question(s) or estimand(s) of interest. For example, $\theta_0 = E(Y|A=1)-E(Y|A=0)$, where A is a binary treatment variable. While this isn't an explicit step in the PRISM function, the question of interest guides how to set up PRISM.

1. **Filter (filter)**: Reduce covariate space by removing variables unrelated to outcome/treatment. 

2. **Patient-level estimate (ple)**: Estimate counterfactual patient-level quantities, for example the conditional average treatment effect (CATE), $\theta(x) = E(Y|X=x,A=1)-E(Y|X=x,A=0)$. These can be used in the subgroup model and/or parameter estimation.

3. **Subgroup model (submod)**: Identify subgroups of patients with potentially varying treatment response. Based on initial subgroups (ex: tree nodes), we may also pool patients into "benefitting" and "non-benefitting" (see "pool" argument). With or without pooling, subgroup-specific treatment estimates and variability metrics are also provided. 

4. **Resampling**: Repeat Steps 1-3 across $R$ resamples for improved statistical performance of subgroup-specific estimates.

Ultimately, PRISM provides information at the patient-level and the subgroup-level (if any). While there are defaults in place, the user can also input their own functions/model wrappers into the PRISM algorithm. We will demonstrate this later. PRISM can also be run without treatment assignment (A=NULL); in this setting, the focus is on finding subgroups based on prognostic effects. The below table describes default PRISM configurations for different family (gaussian, biomial, survival) and treatment (no treatment vs treatment) settings, including the associated estimands. Note that OLS refers to ordinary least squares (linear regression), GLM refers to generalized linear model, and MOB refers to model based partitioning (Zeileis, Hothorn, Hornik 2008; Seibold, Zeileis, Hothorn 2016). To summarise, default models include elastic net (Zou and Hastie 2005) for filtering, random forest ("ranger" R package) for patient-level /counterfactual estimation, and MOB (through "partykit" R package; lmtree, glmtree, and ctree (Hothorn, Hornik, Zeileis 2005)). When treatment assignment is provided, parameter estimation for continuous and binary outcomes uses the double-robust estimator (based on the patient-level estimates). For survival outcomes, the cox regression hazard ratio (HR) or RMST (from the survR2 package) is used.

```{r table_steps, echo=FALSE}
library(knitr)
summ.table = data.frame( `Step` = c("estimand(s)", "filter", "ple", "submod", "param"),
                        `gaussian` = c("E(Y|A=0)<br>E(Y|A=1)<br>E(Y|A=1)-E(Y|A=0)",
                                       "Elastic Net<br>(glmnet)", 
                                       "X-learner: Random Forest<br>(ranger)",
                                       "MOB(OLS)<br>(lmtree)", 
                                       "Double Robust<br>(dr)"),
                        `binomial` = c("E(Y|A=0)<br>E(Y|A=1)<br>E(Y|A=1)-E(Y|A=0)",
                                       "Elastic Net<br>(glmnet)", 
                                       "X-learner: Random Forest<br>(ranger)",
                                       "MOB(GLM)<br>(glmtree)", 
                                       "Doubly Robust<br>(dr)"),    
                        `survival` = c("HR(A=1 vs A=0)",
                                       "Elastic Net<br>(glmnet)", 
                                       "T-learner: Random Forest<br>(ranger)",
                                       "MOB(OLS)<br>(lmtree)", 
                                       "Hazard Ratios<br>(cox)") )                        
                      
kable( summ.table, caption = "Default PRISM Configurations (With Treatment)", full_width=T)

summ.table = data.frame(`Step` = c("estimand(s)", "filter", "ple", "submod", "param"),
                        `gaussian` = c("E(Y)",
                                       "Elastic Net<br>(glmnet)", 
                                       "Random Forest<br>(ranger)",
                                       "Conditional Inference Trees<br>(ctree)",
                                       "OLS<br>(lm)"),
                        `binomial` = c("Prob(Y)",
                                       "Elastic Net<br>(glmnet)", 
                                       "Random Forest<br>(ranger)",
                                       "Conditional Inference Trees<br>(ctree)", 
                                       "OLS<br>(lm)"),    
                        `survival` = c("RMST", "Elastic Net<br>(glmnet)", 
                                       "Random Forest<br>(ranger)",
                                       "Conditional Inference Trees<br>(ctree)",
                                       "RMST<br>(rmst)"))                        
                      
kable( summ.table, caption = "Default PRISM Configurations (Without Treatment, A=NULL)", full_width=T)
```

# Example: Continuous Outcome with Binary Treatment

For continuous outcome data (family="gaussian"), the default PRISM configuration is: (1) filter="glmnet" (elastic net), (2) ple="ranger" (X-learner with random forest models), (3) submod="lmtree" (model-based partitioning with OLS loss), and (4) param="dr" (doubly-robust estimator). To run PRISM, at a minimum, the outcome (Y), treatment (A), and covariates (X) must be provided. See below. The summary gives a high-level overview of the findings (number of subgroups, parameter estimates, variables that survived the filter). The default plot() function currently combines tree plots with parameter estimates using the "ggparty" package. 

```{r default_ctns, warning=FALSE}
# PRISM Default: filter_glmnet, ranger, lmtree, dr #
res0 = PRISM(Y=Y, A=A, X=X)
summary(res0)
plot(res0) # same as plot(res0, type="tree")
```
We can also directly look for prognostic effects by specifying omitting A (treatment) from PRISM (or submod_train):

```{r default_ctns_prog, warning=FALSE}
# PRISM Default: filter_glmnet, ranger, ctree, param_lm #
res_prog = PRISM(Y=Y, X=X)
# res_prog = PRISM(Y=Y, A=NULL, X=X) #also works
summary(res_prog)
```

Next, circling back to the first PRISM model with treatment included, let's review other core PRISM outputs. Results relating to the filter include "filter.mod" (model output) and "filter.vars" (variables that pass the filter). The "plot_importance" function can also be called:
```{r default_ctns_filter, include=FALSE}
# Elastic net model: loss by lambda #
plot(res0$filter.mod)
# Variables that remain after filtering #
res0$filter.vars
# All predictive variables (X1,X2) and prognostic variables (X3,X5, X7) remains.
plot_importance(res0)
```
Results relating to "ple_train" include "ple.fit" (fitted "ple_train"), "mu.train" (training predictions), and "mu.test" (test predictions). "plot_ple" and "plot_dependence" can also be used with PRISM objects. For example, 
```{r default_ctns_ple}
summary(res0$mu_train)
plot_ple(res0)
plot_dependence(res0, vars=c("X2"))
```
Next, the subgroup model (lmtree), identifies 4-subgroups based on varying treatment effects. By plotting the subgroup model object ("submod.fit\$mod")", we see that partitions are made through X1 (predictive) and X2 (predictive). At each node, parameter estimates for node (subgroup) specific OLS models, $Y\sim \beta_0+\beta_1*A$. For example, patients in nodes 4 and 6 have estimated treatment effects of 0.47 and 0.06 respectively. Subgroup predictions for the train/test set can be found in the "out.train" and "out.test" data-sets.
```{r default_ctns_submod}
plot(res0$submod.fit$mod, terminal_panel = NULL)
table(res0$out.train$Subgrps)
table(res0$out.test$Subgrps)
```
Lastly, the "param.dat" object contain point-estimates, standard errors, lower/upper confidence intervals and p-values. This output feeds directly into previously shown default ("tree") plot.
```{r default_ctns2}
## Overall/subgroup specific parameter estimates/inference
res0$param.dat
```

The hyper-parameters for the individual steps of PRISM can also be easily modified. For example, "glmnet" by default selects covariates based on "lambda.min", "ranger" requires nodes to contain at least 10% of the total observations, and "lmtree" requires nodes to contain at least 10% of the total observations. See below for a different set of hyper-parameters.

```{r default_hyper, eval=FALSE}
res_new_hyper = PRISM(Y=Y, A=A, X=X, filter.hyper = list(lambda="lambda.1se"),
                      ple.hyper = list(min.node.pct=0.05), 
                      submod.hyper = list(minsize=200, maxdepth=3), verbose=FALSE)
summary(res_new_hyper)
```
# Example: Binary Outcome with Binary Treatment

Consider a binary outcome (ex: % overall response rate) with a binary treatment (study drug vs standard of care). The estimand of interest is the risk difference, $\theta_0 = E(Y|A=1)-E(Y|A=0)$. Similar to the continous example, we simulate binomial data where roughly 30\% of the patients receive no treatment-benefit for using $A=1$ vs $A=0$. Responders vs non-responders are defined by the continuous predictive covariates $X_1$ and $X_2$ for a total of four subgroups. Subgroup treatment effects are: $\theta_{1} = 0$ ($X_1 \leq 0, X_2 \leq 0$), $\theta_{2} = 0.11 (X_1 > 0, X_2 \leq 0)$, $\theta_{3} = 0.21 (X_1 \leq 0, X2 > 0$), $\theta_{4} = 0.31 (X_1>0, X_2>0)$.

For binary outcomes (Y=0,1), the default settings are: filter="glmnet", ple="ranger", submod="glmtree"" (GLM MOB with identity link), and param="dr".

```{r default_binary}
dat_bin = generate_subgrp_data(family="binomial", seed = 5558)
Y = dat_bin$Y
X = dat_bin$X # 50 covariates, 46 are noise variables, X1 and X2 are truly predictive
A = dat_bin$A # binary treatment, 1:1 randomized 

res0 = PRISM(Y=Y, A=A, X=X)
summary(res0)
```

# Example: Survival Outcome with Binary Treatment

Survival outcomes are also allowed in PRISM. The default settings use glmnet to filter ("glmnet"), ranger patient-level estimates ("ranger"; for survival, the output is the restricted mean survival time treatment difference), "lmtree" (log-rank score transformation on outcome Y, then fit MOB OLS) for subgroup identification, and subgroup-specific cox regression models). Another subgroup option is to use "ctree"", which uses the conditional inference tree (ctree) algorithm to find subgroups; this looks for partitions irrespective of treatment assignment and thus corresponds to finding prognostic effects. 

```{r default_surv}
# Load TH.data (no treatment; generate treatment randomly to simulate null effect) ##
data("GBSG2", package = "TH.data")
surv.dat = GBSG2
# Design Matrices ###
Y = with(surv.dat, Surv(time, cens))
X = surv.dat[,!(colnames(surv.dat) %in% c("time", "cens")) ]
set.seed(6345)
A = rbinom(n = dim(X)[1], size=1, prob=0.5)

# Default: glmnet ==> ranger (estimates patient-level RMST(1 vs 0) ==> mob_weib (MOB with Weibull) ==> cox (Cox regression)
res_weib = PRISM(Y=Y, A=A, X=X)
summary(res_weib)
plot(res_weib)
```

# Resampling

Resampling methods are also a feature in PRISM and submod_train. Bootstrap (resample="Bootstrap"), permutation (resample="Permutation"), and cross-validation (resample="CV") based-resampling are included. Resampling can be used for obtaining de-biased or "honest" subgroup estimates, inference, and/or probability statements. For each resampling method, the sampling mechanism can be stratified by the discovered subgroups and/or treatment (default: stratify="trt"). To summarize:

**Bootstrap Resampling**

Given observed data $(Y, A, X)$, fit $PRISM(Y,A,X)$. Based on the identified $k=1,..,K$ subgroups, output subgroup assignment for each patient. For the overall population $k=0$ and each subgroup ($k=0,...,K$), store the associated parameter estimates ($\hat{\theta}_{k}$).
For $r=1,..,R$ resamples with replacement ($(Y_r, A_r, X_r)$), fit $PRISM(Y_r, A_r, X_r)$ and obtain new subgroup assignments $k_r=1,..,K_r$ with associated parameter estimates $\hat{\theta}_{k_r}$. For subjects $i$ within subgroup $k_r$, note that everyone has the same assumed point-estimate, i.e., $\hat{\theta}_{k_r}=\hat{\theta}_{ir}$. For resample $r$, the bootstrap estimates based for the original identified subgroups ($k=0,...,K$) are calculated respectively as:
$$ \hat{\theta}_{rk} =  \sum_{k_r} w_{k_r} \hat{\theta}_{k_r}$$
where $w_{k_r} = \frac{n(k \cap k_r)}{\sum_{k_r} n(k \cap k_r)}$, or the # of subjects that are in both the original subgroup $k$ and the resampled subgroup $k_r$ divided by the total #. The bootstrap mean estimate and standard error, as well as probability statements, are calculated as:
$$ \tilde{\theta}_{k} =  \frac{1}{R}  \sum_r \hat{\theta}_{rk}  $$
$$ SE(\hat{\theta}_{k})_B = \sqrt{ \frac{1}{R} \sum_r (\hat{\theta}_{rk}-\tilde{\theta}_{k})^2   } $$
$$ \hat{P}(\hat{\theta}_{k}>c) =  \frac{1}{R}  \sum_r I(\hat{\theta}_{rk}>c)  $$
If resample="Bootstrap", the default is to use the bootstrap smoothed estimates, $\tilde{\theta}_{k}$, along with percentile-based CIs (i.e. 2.5,97.5 quantiles of bootstrap distribution). Bootstrap bias is also calculated, which can be used to assess the bias of the initial subgroup estimates.

Returning to the survival example, see below for an example of PRISM with 50 bootstrap resamples (for increased accuracy, use >1000). The bootstrap mean estimates, bootstrap standard errors, bootstrap bias, and percentile CI correspond to "est_resamp", "SE_resamp", "bias.boot", and "LCL.pct"/"UCL.pct" respectively. A density plot of the bootstrap distributions can be viewed through the plot(...,type="resample") option.

```{r default_boot, warning=FALSE, message=FALSE, eval=FALSE}
res_boot = PRISM(Y=Y, A=A, X=X, resample = "Bootstrap", R=50, ple="None")
summary(res_boot)
# Plot of distributions #
plot(res_boot, type="resample", estimand = "HR(A=1 vs A=0)")+geom_vline(xintercept = 1)
```

**Cross-Validation**

Cross-validation resampling (resample="CV") also follows the same general procedure as bootstrap resampling. Given observed data $(Y, A, X)$, fit $PRISM(Y,A,X)$. Based on the identified $k=1,..,K$ subgroups, output subgroup assignment for each patient. Next, split the data into $R$ folds (ex: 5). For fold $r$ with sample size $n_r$, fit PRISM on $(Y[-r],A[-r], X[-r])$ and predict the patient-level estimates and subgroup assignments ($k_r=1,...,K_r$) for patients in fold $r$. The data in fold $r$ is then used to obtain parameter estimates for each subgroup, $\hat{\theta}_{k_r}$. For fold $r$, estimates and SEs for the original subgroups ($k=1,...,K$) are then obtained using the same formula as with bootstrap resampling, again, denoted as ($\hat{\theta}_{rk}$, $SE(\hat{\theta}_{rk})$). This is repeated for each fold and "CV" estimates and SEs are calculated for each identified subgroup. Let $w_r = n_r / \sum_r n_r$, then:

$$ \hat{\theta}_{k,CV} = \sum w_r * \hat{\theta}_{rk} $$
$$ SE(\hat{\theta}_k)_{CV} =  \sqrt{ \sum_{r} w_{r}^2 SE(\hat{\theta}_{rk})^2 }$$
CV-based confidence intervals can then be formed, $\left[\hat{\theta}_{k,CV} \pm  1.96*SE(\hat{\theta}_k)_{CV} \right]$. 

# Conclusion

Overall, the StratifiedMedicine package contains a variety of tools ("filter_train", "ple_train", "submod_train", and "PRISM") and plotting features ("plot_dependence", "plot_importance", "plot_ple", "plot_tree") for the exploration of heterogeneous treatment effects. Each tool is also customizable, allowing the user to plug-in specific models (for example, xgboost with built-in hyper-parameter tuning). More details on creating user-specific models can be found in the "User_Specific_Models_PRISM" vignette [User_Specific_Models](https://CRAN.R-project.org/package=StratifiedMedicine/vignettes/SM_User_Models.html). The StratifiedMedicine R package will be continually updated and improved.

