---
title: "Getting started with gsDesignTune"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with gsDesignTune}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dev = "svg",
  fig.ext = "svg",
  fig.width = 7.2916667,
  fig.asp = 0.618,
  fig.align = "center",
  out.width = "80%"
)
```

This vignette demonstrates dependency-aware grid search over group sequential
designs using gsDesignTune.

```{r}
library(gsDesign)
library(gsDesignTune)
```

## Basic designs with `gsDesignTune()`

`gsDesignTune()` wraps `gsDesign::gsDesign()` for tuning basic group sequential
designs.

```{r}
job <- gsDesignTune(
  k = 3,
  test.type = 2,
  alpha = 0.025,
  beta = 0.10,
  timing = tune_values(list(c(0.33, 0.67, 1), c(0.5, 0.75, 1))),
  upper = SpendingFamily$new(
    SpendingSpec$new(sfLDOF, par = tune_fixed(0)),
    SpendingSpec$new(sfHSD, par = tune_seq(-4, 4, length_out = 3))
  )
)

job$run(strategy = "grid", parallel = FALSE)
res <- job$results()
head(res)
```

### Ranking and filtering

```{r}
best <- job$best("final_n", direction = "min")
head(best, 10)
```

### Plot

```{r}
job$plot(metric = "final_n", x = "upper_par", color = "upper_fun")
```

## Survival designs with `gsSurvTune()`

`gsSurvTune()` wraps `gsDesign::gsSurv()` for tuning time-to-event designs.

```{r}
job_surv <- gsSurvTune(
  k = 3,
  test.type = 4,
  alpha = 0.025,
  beta = 0.10,
  timing = tune_values(list(c(0.33, 0.67, 1), c(0.5, 0.75, 1))),
  hr = tune_seq(0.60, 0.75, length_out = 3),
  upper = SpendingFamily$new(
    SpendingSpec$new(sfLDOF, par = tune_fixed(0)),
    SpendingSpec$new(sfHSD, par = tune_seq(-4, 4, length_out = 3))
  ),
  lower = SpendingSpec$new(sfLDOF, par = tune_fixed(0)),
  lambdaC = log(2) / 6,
  eta = 0.01,
  gamma = c(2.5, 5, 7.5, 10),
  R = c(2, 2, 2, 6),
  T = 18,
  minfup = 6,
  ratio = 1
)

job_surv$run(strategy = "grid", parallel = FALSE)
res_surv <- job_surv$results()
head(res_surv)
```

### Calendar-timed analyses with `gsSurvCalendarTune()`

`gsSurvCalendarTune()` is similar to `gsSurvTune()`, but you specify planned
calendar times of analyses via `calendarTime` instead of information timing.

```{r}
job_cal <- gsSurvCalendarTune(
  test.type = 4,
  alpha = 0.025,
  beta = 0.10,
  calendarTime = tune_values(list(c(12, 24, 36), c(9, 18, 27))),
  spending = tune_choice("information", "calendar"),
  hr = tune_seq(0.60, 0.75, length_out = 3),
  upper = SpendingFamily$new(
    SpendingSpec$new(sfLDOF, par = tune_fixed(0)),
    SpendingSpec$new(sfHSD, par = tune_seq(-4, 4, length_out = 3))
  ),
  lower = SpendingSpec$new(sfLDOF, par = tune_fixed(0)),
  lambdaC = log(2) / 6,
  eta = 0.01,
  gamma = c(2.5, 5, 7.5, 10),
  R = c(2, 2, 2, 6),
  minfup = 18,
  ratio = 1
)

job_cal$run(strategy = "grid", parallel = FALSE)
res_cal <- job_cal$results()
head(res_cal)
```

### Multi-scenario exploration

```{r}
best_surv <- job_surv$best("final_events", direction = "min")
head(best_surv, 10)
```

```{r}
job_surv$plot(metric = "final_events", x = "hr", color = "upper_fun")
```

## Export a report

```{r}
report_path <- tempfile(fileext = ".html")
job_surv$report(report_path)
report_path
```