---
title: "Inverse Probability of Censoring Weights"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Inverse Probability of Censoring Weights}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(trtswitch)
library(dplyr, warn.conflicts = FALSE)
library(ggplot2)
```

# Introduction
The inverse probability of censoring weights (IPCW) method is a powerful tool for adjusting survival analysis in the presence of treatment switching. In scenarios where patients switch treatments, survival data are artificially censored, leading to biased estimates if not properly addressed. This bias arises because the decision to switch treatments may depend on prognostic factors that also influence survival outcomes.

To mitigate this bias, researchers gather data on prognostic covariates at baseline and at regular intervals until one of the following occurs: a treatment switch, death, drop-out, or the end of the follow-up period. A "switching model" is then developed to estimate weights for each patient at each time point. These weights represent the inverse probability of remaining unswitched over time. Each patient retains a weight greater than 1, which accounts for both their own data and that of switchers with similar prognostic profiles.

Finally, an "outcome" model utilizing IPCW-weighted survival times is employed to estimate the treatment effect, adjusted for switching.

# Estimation of weights
The switching model can be implemented using either pooled logistic regression or proportional hazards regression with time-dependent covariates.

## Pooled Logistic Regression Model
When using pooled logistic regression for the switching model, the following specifications can be made:

- **Visit-Specific Intercepts**: These can be modeled using a natural cubic spline with specified degrees of freedom, denoted as $\nu$ (corresponding to the `ns_df` parameter of the `ipcw` function). The boundary and internal knots can be based on the range and percentiles of observed treatment switching times, respectively. Here, $\nu$ equals the number of internal knots plus one; a value of $\nu=0$ indicates a common intercept, while $\nu=1$ leads to a linear effect of visit. By default, $\nu=3$, which implies two internal knots for the cubic spline. The parameter `relative_time` is set to `TRUE` by default, which indicates that visit time is relative to the secondary baseline defined by the `swtrt_time_lower` parameter. Setting `relative_time = FALSE` makes visit time relative to randomization.

- **Stratification Factors**: If more more than one stratification factor exists, they can be included in the logistic model either as main effects only (`strata_main_effect_only = TRUE`) or as all possible combinations of the  levels of the stratification factors (`strata_main_effect_only = FALSE`). 

- **Handling Nonconvergence**: If the pooled logistic regression model encounters issues such as complete or quasi-complete separation, Firth's bias-reducing penalized likelihood method (`firth = TRUE`) can be applied alongside intercept correction (`flic = TRUE`) to yield more accurate predicted probabilities. 

## Proportional Hazards Model
When using a Cox model with time-dependent covariates as the switching model, adjacent observations within a subject may be combined as long as the values of time-dependent covariates do not change over each combined interval. This approach saves data storage but observations across subjects will not be aligned at regular intervals. In this case, unique event times across treatment arms should be replicated within each subject, enabling the availability of weights at each event time.

## Stabilized Weights
To address the high variability in "unstabilized" weights, researchers often opt for "stabilized" weights. The switching model for stabilized weights involves a model for the numerator of the weight in addition to the model for the denominator. Typically, the numerator model mirrors the denominator model but includes only prognostic baseline variables. Any prognostic baseline variables included in the numerator must also be part of the weighted outcome model. 

## Truncation of Weights
You can specify weight truncation using the `trunc` and `trunc_upper_only` parameters of the `ipcw` function. The `trunc` parameter is a number between 0 and 0.5 that represents the fraction of the weight distribution to truncate. The `trunc_upper_only` parameter is a flag that indicates whether to truncate weights only from the upper end of the weight distribution.

# Estimation of Hazard Ratio
Once weights have been obtained for each event time in the data set, we fit a (potentially stratified) Cox proportional hazards model to this weighted data set to obtain an estimate of the hazard ratio. The confidence interval for the hazard ratio can be derived by bootstrapping the weight estimation and the  subsequent model-fitting process.

## Example for Pooled Logistic Regression Switching Model
First we prepare the data.
```{r data example 1}
sim1 <- tsegestsim(
  n = 500, allocation1 = 2, allocation2 = 1, pbprog = 0.5, 
  trtlghr = -0.5, bprogsl = 0.3, shape1 = 1.8, 
  scale1 = 0.000025, shape2 = 1.7, scale2 = 0.000015, 
  pmix = 0.5, admin = 5000, pcatnotrtbprog = 0.5, 
  pcattrtbprog = 0.25, pcatnotrt = 0.2, pcattrt = 0.1, 
  catmult = 0.5, tdxo = 1, ppoor = 0.1, pgood = 0.04, 
  ppoormet = 0.4, pgoodmet = 0.2, xomult = 1.4188308, 
  milestone = 546, swtrt_control_only = TRUE,
  outputRawDataset = 1, seed = 2000)
```

Given that the observations are collected at regular intervals, we can use a pooled logistic regression switching model. In this model, the prognostic baseline variable is represented by `bprog`, while `catlag` and the interaction between `bprog` and `catlag` serve as time-dependent covariates. Additionally, `s1`, `s2`, and `s3` are the three terms for the natural cubic spline with $\nu=3$ degrees of freedom for visit-specific intercepts.  
```{r analysis example 1}
fit1 <- ipcw(
  sim1$paneldata, id = "id", tstart = "tstart", 
  tstop = "tstop", event = "died", treat = "trtrand", 
  swtrt = "xo", swtrt_time = "xotime", 
  swtrt_time_lower = "timePFSobs",
  swtrt_time_upper = "xotime_upper", base_cov = "bprog", 
  numerator = "bprog", denominator = "bprog*catlag", 
  logistic_switching_model = TRUE, ns_df = 3,
  relative_time = TRUE, swtrt_control_only = TRUE, 
  boot = FALSE)
```

The fits for the denominator and numerator switching models are as follows, utilizing robust sandwich variance estimates to account for correlations among  observations within the same subject. 
```{r switching models example 1}
# denominator switching model fit
fit1$fit_switch[[1]]$fit_den$parest[, c("param", "beta", "sebeta", "z")]

# numerator switching model fit
fit1$fit_switch[[1]]$fit_num$parest[, c("param", "beta", "sebeta", "z")]
```

Since treatment switching is not allowed in the experimental arm, the weights are identical to 1 for subjects in the experimental group. The unstabilized and stablized weights for the control group are plotted below.
````{verbatim}
```{r weights example 1}
# unstabilized weights
ggplot(fit1$data_outcome %>% filter(trtrand == 0), 
       aes(x = unstabilized_weight)) + 
  geom_density(fill="#77bd89", color="#1f6e34", alpha=0.8) +
  scale_x_continuous("unstabilized weights")

# stabilized weights
ggplot(fit1$data_outcome %>% filter(trtrand == 0), 
       aes(x = stabilized_weight)) + 
  geom_density(fill="#77bd89", color="#1f6e34", alpha=0.8) +
  scale_x_continuous("stabilized weights")
```
````

Now we fit a weighted outcome Cox model and compare the treatemnt hazard ratio estimate with the reported. 
```{r cox example 1}
fit1$fit_outcome$parest[, c("param", "beta", "sebeta", "z")]
    
exp(fit1$fit_outcome$parest[1, c("beta", "lower", "upper")])
```


## Example for Time-Dependent Covariates Cox Switching Model
Now we apply the IPCW method using a Cox proportional hazards model with time-dependent covariates as the switching model. 
```{r example 2}
fit2 <- ipcw(
  shilong, id = "id", tstart = "tstart", tstop = "tstop", 
  event = "event", treat = "bras.f", swtrt = "co", 
  swtrt_time = "dco", 
  base_cov = c("agerand", "sex.f", "tt_Lnum", "rmh_alea.c", 
               "pathway.f"),
  numerator = c("agerand", "sex.f", "tt_Lnum", "rmh_alea.c", 
                "pathway.f"),
  denominator = c("agerand", "sex.f", "tt_Lnum", "rmh_alea.c",
                  "pathway.f", "ps", "ttc", "tran"),
  swtrt_control_only = FALSE, boot = FALSE)
```

The fits for the denominator and numerator switching models for the control arm are as follows, utilizing robust sandwich variance estimates to account for correlations among  observations within the same subject.  
```{r switching models for control example 2}
# denominator switching model for the control group
fit2$fit_switch[[1]]$fit_den$parest[, c("param", "beta", "sebeta", "z")]

# numerator switching model for the control group
fit2$fit_switch[[1]]$fit_num$parest[, c("param", "beta", "sebeta", "z")]
```

The fits for the denominator and numerator switching models for the experimental arm are as follows:
```{r switching models for experimental example 2}
# denominator switching model for the experimental group
fit2$fit_switch[[2]]$fit_den$parest[, c("param", "beta", "sebeta", "z")]

# numerator switching model for the experimental group
fit2$fit_switch[[2]]$fit_num$parest[, c("param", "beta", "sebeta", "z")]
```


Below, the unstabilized and stabilized weights are plotted by treatment group: the left panel displays data for the control group, while the right panel shows data for the experimental group.
````{verbatim}
```{r weights example 2}
# unstabilized weights
ggplot(fit2$data_outcome, aes(x = unstabilized_weight)) + 
  geom_density(fill="#77bd89", color="#1f6e34", alpha=0.8) + 
  scale_x_continuous("unstabilized weights") + 
  facet_wrap(~treated) 

# stabilized weights
ggplot(fit2$data_outcome, aes(x = stabilized_weight)) + 
  geom_density(fill="#77bd89", color="#1f6e34", alpha=0.8) + 
  scale_x_continuous("stabilized weights") + 
  facet_wrap(~treated)
```
````

Finally, we fit the weighted outcome Cox model and compare the treatment hazard ratio estimate with the reported. 
```{r cox example 2}
fit2$fit_outcome$parest[, c("param", "beta", "sebeta", "z")]

c(fit2$hr, fit2$hr_CI)
```