---
title: "Introduction to PERSUADE"
author: "Bram Ramaekers"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to PERSUADE}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

PERSUADE (ParamEtRic SUrvivAl moDel sElection) is a standardized tool in R to support the selection and communication of parametric survival models in health economic and decision-analytic modelling.

It provides:

- Kaplan–Meier visualizations and diagnostics
- Assessment of proportional hazards (PH) assumption
- Observed and predicted hazard function plots
- Fit comparisons of standard, spline-based, and cure models
- Goodness-of-fit statistics (AIC/BIC)
- Explore model extrapolation beyond observed data
- Automated PDF reports for communication
- Export the parametric survival model parameters for use in decision-analytic models

This vignette shows how to use PERSUADE with a step-by-step workflow.

## Install and load the PERSUADE package
```{r setup}
# Install and load PERSUADE
# devtools::install_github("Bram-R/PERSUADE", quiet = TRUE) # To install the development version of PERSUADE
# install.packages("PERSUADE") # To install CRAN version of PERSUADE
library(PERSUADE)
```

## Example workflow
The following example reproduces the workflow in `PERSUADE_example_workflow.R` (can be obtained through: `file.edit(system.file("example_workflow", "PERSUADE_example_workflow.R", package = "PERSUADE"))`). We will use the `flexsurv::bc` dataset (time to recurrence for breast cancer patients):
```{r data}
# Example dataset
years  <- flexsurv::bc$recyrs   # time to event
status <- flexsurv::bc$censrec  # event indicator
group  <- flexsurv::bc$group    # grouping variable
```

## Define analysis settings
Define the analysis settings to run PERSUADE:
```{r settings}
name <- "BC_OS"        # project name
time_pred_surv_table <- c(0, 1, 2, 3, 4, 5, 10, 15, 20, 25, 30, 35)  # survival table times
time_unit    <- 1/12   # monthly data in years
time_horizon <- 40     # analysis horizon (years)
```

## Running PERSUADE
The main function is `f_PERSUADE()`, which generates the S3 object PERSUADE:
```{r f_PERSUADE, eval=FALSE}
PERSUADE <- f_PERSUADE(
  name = name,
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = TRUE,
  cure_link = "logistic", # options: "logistic", "loglog", "identity", "probit"
  time_unit = time_unit,
  time_horizon = time_horizon,
  time_pred_surv_table = time_pred_surv_table
)
```

## Inspecting results
The output is a PERSUADE object. You can inspect it using:
```{r PERSUADE_res, eval=FALSE}
print(PERSUADE)
summary(PERSUADE, type = "km")
summary(PERSUADE, type = "gof")
```

## Generate diagnostic and model plots:
```{r PERSUADE_plot, eval=FALSE}
palette(rainbow(n = 9, s = 1, v = 1, start = 0, end = max(1, 9 - 1)/9, alpha = 1)) # Set colour palette for Figures
plot(PERSUADE, type = "km")            # Kaplan-Meier
plot(PERSUADE, type = "ph")            # Proportional hazards
plot(PERSUADE, type = "hr")            # Hazard functions
plot(PERSUADE, type = "param_models")  # Standard parametric fits
plot(PERSUADE, type = "spline_models") # Spline-based fits
plot(PERSUADE, type = "cure_models")   # Cure models
palette("default") # Set colour palette to default
```

## Reporting
To automatically generate a PDF report ('rmarkdown'):
```{r PERSUADE_report, eval=FALSE}
f_generate_report(PERSUADE)
```

## Exporting model parameters
Change `tempdir()` into `getwd()` for copying to working directory.
```{r PERSUADE_export, eval=FALSE}
write.csv(PERSUADE$surv_model_excel, 
          file.path(tempdir(), paste0(name, "_output"), 
                    "PERSUADE_Time-to-event_models_parameters_comma.csv"))
write.csv2(PERSUADE$surv_model_excel, 
           file.path(tempdir(), paste0(name, "_output"), 
                     "PERSUADE_Time-to-event_models_parameters_semicolon.csv"))
```

## Obtain Excel template 
The next step will copy the Excel template `PERSUADE_Excel_template.xltx` to a user specified directory (default = `tempdir()`). This template provides a convenient structure for transferring survival model parameters into health economic models. 
```{r, eval=FALSE}
f_get_excel_template()
```

## Next steps

- For a full reproducible example, check: `PERSUADE_example_workflow.R` (`file.edit(system.file("example_workflow", "PERSUADE_example_workflow.R", package = "PERSUADE"))`).
- To adapt PERSUADE to your data, replace the example inputs with your own time-to-event dataset.
- For technical details of each function, see the help pages, e.g. `?f_PERSUADE`.
- To list all objects in the PERSUADE package: `ls("package:PERSUADE")`.