---
title: "Define Time-to-Event Endpoints in Clinical Trials"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Define Time-to-Event Endpoints in Clinical Trials}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  cache = TRUE,
  cache.path = 'cache/defineTimeToEventEndpoints/',
  comment = '#>',
  dpi = 300,
  out.width = '100%'
)
```

```{r setup, message = FALSE, echo = FALSE}
library(dplyr)
library(survival)
library(survminer)
library(simdata)
library(TrialSimulator)
set.seed(12345)
```

The first step in simulating a randomized clinical trial using `TrialSimulator` is to define one or more endpoints for each treatment arm. This vignette demonstrates how to use the following key functions to define time-to-event endpoints. For non-time-to-event endpoints, please refer to the separate vignette [Define Non-Time-to-Event Endpoints in Clinical Trials](defineNonTimeToEventEndpoints.html).

- `endpoint`: Creates one or more endpoints
- `test_generator`: Generates an example dataset from an `Endpoints` object

Typically, endpoints follow the same distribution family across arms but with different parameters. Distribution parameters are specified through the `...` arguments in `endpoint`. However, please note that `endpoint` offers the flexibility to specify different distribution families across arms for endpoints. 

Note that the function `test_generator` is for helping users understanding how `TrialSimulator` works. In formal simulation, we do not need to call this function. 

For the sake of completeness, in this vignette, we also demonstrates how to define an arm with the created endpoints by using the following key functions: 

- `arm`: Creates one or more arms
- `add_endpoints`: Add one or more endpoints into an arm

## Define a univariate endpoint with random number generators from `stats`

To define a time-to-event endpoint such as progression-free survival (`PFS`) following an exponential distribution, we need to specify its `name` and `type.` This specification is crucial because `TrialSimulator` ensures all arms have the same set of endpoints and manages endpoint data based on `type`. For example, endpoints of type `"tte"` (time-to-event) automatically receive an additional column `(name)_event` to indicate censoring status.

```{r lkioie}
pfs_pbo <- endpoint(name = 'PFS', type = 'tte', 
                    generator = rexp, rate = log(2)/5.6)
```

Arguments for the generator function (in this case, `rate`) are passed through `...`. We can verify that the generator works as expected by requesting an example dataset:

```{r adfla, message=FALSE}
test_set <- pfs_pbo$test_generator(n = 1e5)
head(test_set)
median(test_set$PFS) ## should be close to 5.6
```

Note that data returned by `test_generator` is only for validation purposes. During actual trial simulation, `TrialSimulator` determines when to call `generator` from which how many samples to draw. To request access of a data locked at a milestone, we can use the member function `get_locked_data` of a `Trials` object which will be introduced in the vignette [An Example of Simulating a Trial with Adaptive Design](adaptiveDesign.html). 

We can get a summary report by printing an `endpoint` object
```{r ieaofdsaf, results='asis'}
pfs_pbo
```

Similarly, we can define a `PFS` endpoint for the treatment arm:

```{r aldj}
pfs_trt <- endpoint(name = 'PFS', type = 'tte', 
                    generator = rexp, rate = log(2)/6.4)
median(pfs_trt$test_generator(n = 1e5)$PFS) ## should be close to 6.4
```

Now we can define the placebo and treatment arms by adding the `PFS` endpoints: 

```{r alfjd}
pbo <- arm(name = 'placebo')
pbo$add_endpoints(pfs_pbo)
trt <- arm(name = 'treatment')
trt$add_endpoints(pfs_trt)
```

We will cover how to create a trial object based on arms `pbo` and `trt` in 
another vignette. 

## Define a univariate endpoint with custom random number generators

`endpoints` accepts custom random number generators for univariate random variables, as long as the generator's first argument is `n` (number of observations). Additional arguments can be passed through `...` in `endpoints`.

`TrialSimulator` provides a built-in custom generator, `PiecewiseConstantExponentialRNG`, to generate time-to-event endpoints from piecewise constant exponential distributions. This is particularly useful for simulating lagged or delayed treatment effects. The example below demonstrates a scenario where treatment effect begins at week 2:

```{r aldjfba}
risk_pbo <- data.frame(
  end_time = c(2, 8, 10), 
  piecewise_risk = c(1, 0.48, 0.25) * exp(-1)
)

pfs_pbo <- endpoint(name = 'PFS', type = 'tte', 
                    generator = PiecewiseConstantExponentialRNG, 
                    risk = risk_pbo, 
                    endpoint_name = 'PFS')
risk_trt <- risk_pbo %>% 
  mutate(hazard_ratio = c(1, .6, .7))

pfs_trt <- endpoint(name = 'PFS', type = 'tte', 
                    generator = PiecewiseConstantExponentialRNG, 
                    risk = risk_trt, 
                    endpoint_name = 'PFS')

test_set <- rbind(pfs_pbo$test_generator(n = 1e4) %>% mutate(arm = 'pbo'), 
                  pfs_trt$test_generator(n = 1e4) %>% mutate(arm = 'trt'))

sfit <- survfit(Surv(time = PFS, event = PFS_event) ~ arm, test_set)
ggsurvplot(sfit, data = test_set, palette = c("blue", "red"))
```

In this example, `PiecewiseConstantExponentialRNG` adds a column `PFS_event` because we specified `endpoint_name = 'PFS'`. Some patients have their `PFS` censored (`PFS_event = 0`). By default, when a custom generator is supplied and an event column is not provided for a time-to-event endpoint, `TrialSimulator` will add one and set all values to 1 (no censoring).

```{r ldao}
head(test_set %>% slice_sample(prop = 1))
```

To add endpoint to an arm, 
```{r eegj}
pbo <- arm(name = 'placebo')
pbo$add_endpoints(pfs_pbo)

trt <- arm(name = 'treatment')
trt$add_endpoints(pfs_trt)
```

## Define multiple endpoints

We can define more than one endpoint in a trial. Let's add overall survival (OS) as a second endpoint. We'll assume the median overall survival is 7.2 months in the placebo arm and 8.5 months in the treatment arm. 

```{r laiojb}
os_pbo <- endpoint(name = 'OS', type = 'tte', 
                   generator = rexp, rate = log(2)/7.2)
os_trt <- endpoint(name = 'OS', type = 'tte', 
                   generator = rexp, rate = log(2)/8.5)

median(os_pbo$test_generator(n = 1e5)$OS) ## should be close to 7.2
median(os_trt$test_generator(n = 1e5)$OS) ## should be close to 8.5

## add endpoint to existing arms
pbo$add_endpoints(os_pbo)
trt$add_endpoints(os_trt)
```

Note that by defining `PFS` and `OS` separately (i.e., calling `endpoints` for each endpoint), we are implicitly assuming that these endpoints are independent in the trial.

## An example of a custom random number generator for correlated endpoints

To define multiple correlated endpoints, we need to create a custom generator. In this example, we define one based on the R package `simdata`:

```{r albaiola}
custom_generator <- function(n, pfs_rate, os_rate, corr){
  
  dist <- list()
  dist[['PFS']] <- function(x) qexp(x, rate = pfs_rate)
  dist[['OS']] <- function(x) qexp(x, rate = os_rate)
  dsgn = simdata::simdesign_norta(cor_target_final = corr, 
                                dist = dist, 
                                transform_initial = data.frame,
                                names_final = names(dist), 
                                seed_initial = 1)
  
  simdata::simulate_data(dsgn, n_obs = n) %>% 
    mutate(PFS_event = 1, OS_event = 1) ## event indicators
}
```

Note that for custom generator, we need to add columns of event indicator for each of the time-to-event endpoints. 

```{r ojhonln}
corr <- matrix(c(1, .6, .6, 1), nrow = 2)
eps_pbo <- endpoint(name = c('PFS', 'OS'), type = c('tte', 'tte'), 
                    generator = custom_generator, 
                    pfs_rate = log(2)/5.6, os_rate = log(2)/7.2, 
                    corr = corr)

eps_trt <- endpoint(name = c('OS', 'PFS'), type = c('tte', 'tte'), 
                    generator = custom_generator, 
                    pfs_rate = log(2)/6.4, os_rate = log(2)/8.5, 
                    corr = corr)

test_set <- rbind(eps_pbo$test_generator(n = 1e5) %>% mutate(arm = 'pbo'), 
                  eps_trt$test_generator(n = 1e5) %>% mutate(arm = 'trt'))

with(test_set, cor(PFS, OS)) ## should be close to 0.6

## sample medians match to the parameters well
test_set %>% 
  group_by(arm) %>% 
  summarise(PFS = median(PFS), OS = median(OS))

```

Instead of use `test_generator`, a simpler way to summarize an endpoint object is to print it directly. For example, the two endpoints in the placebo arm

```{r daadidal, results='asis'}
eps_pbo
```

and the two endpoints in the treatment arm 

```{r ieaofafa, results='asis'}
eps_trt
```

To define arms with these correlated endpoints, simply do the following:

```{r lioe}
pbo <- arm(name = 'placebo')
pbo$add_endpoints(eps_pbo)

trt <- arm(name = 'treatment')
trt$add_endpoints(eps_trt)
```