---
title: "Condition System for Triggering Milestones in a Trial"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Condition System for Triggering Milestones in a Trial}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, message = FALSE, echo=FALSE}
library(TrialSimulator)
```

In clinical trial simulations, it is often necessary to specify when certain actions should be taken. For example, a trial may require interim data reviews when a predefined number of surrogate endpoint events occur to support dose selection. More complex triggers can be defined based on event numbers of one or multiple endpoints, calendar time, the number of enrolled patients, or a combination of multiple conditions. These triggers may govern critical analyses such as futility assessments, sample size re-assessment, interim analyses, and final evaluations, at various trial milestones. 

To facilitate this process, `TrialSimulator` provides an intuitive condition-based system for defining milestone triggers. It supports logical operations (`&` for AND and `|` for OR), allowing users to specify complex conditions seamlessly. The simulator is then automatically determines the appropriate time points and executes user-defined actions accordingly.

Currently, `TrialSimulator` provides three key functions to define the earliest possible time for triggering a milestone:

- `calendarTime(time)`: Specifies a minimum trial duration before a milestone can occur.

- `enrollment(n)`: Specifies a minimum number of patients that must be enrolled before a milestone can occur.

- `eventNumber(endpoint, n, arms)`: Specifies a minimum number of observed events for a given endpoint before triggering a milestone This condition can apply to specific arms or the entire trial.

The following sections illustrate various ways to define milestone triggers using these functions, which could be passed to the argument `when` of `milestone()`. 

#### A trial has been running for 6 months
```{r oiea}
## Note: the unit of time depends on the context of a trial
##       It is users responsibility to align it with trial's parameters
calendarTime(time = 6)
```

#### At least 520 patients are enrolled
```{r ioea}
enrollment(n = 520)
```

#### At least 340 PFS events are observed
```{r uuea}
## condition is based on number of event in the placebo arm
## Note: 'pfs' is the name of the endpoint, i.e., endpoints(name = 'pfs', ...)
## Note: 'pbo' is the name of the placebo arm, i.e., arm(name = 'pbo', ...)
eventNumber(endpoint = 'pfs', n = 340, arms = 'pbo')

## condition can be based on number of event in specific arms
eventNumber(endpoint = 'pfs', n = 340, arms = c('pbo', 'trt'))

## condition can be based on number of event in the trial
## Note: for example, a trial of more than two arms. 
##       Here the number of PFS events are counted on all arms in trial
eventNumber(endpoint = 'pfs', n = 340)
```

#### Other examples
```{r eaiggo}
## observe at least 200 OS events on at least 500 enrolled patients, or
## the trial has been running for at least 12 months
(enrollment(n = 500) & eventNumber(endpoint = 'os', n = 200)) | 
  calendarTime(time = 12)

## observe 320 OS or 480 PFS event when the trial has been running for 6 months
calendarTime(time = 6) & 
  (eventNumber('os', n = 320) | eventNumber('pfs', n = 480))
```