Author: Bram Ramaekers

# Introduction to PERSUADE

#### Bram Ramaekers

## 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

    # 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):

    # 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:

    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:

    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:

    print(PERSUADE)
    summary(PERSUADE, type = "km")
    summary(PERSUADE, type = "gof")

## Generate diagnostic and model plots:

    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’):

    f_generate_report(PERSUADE)

## Exporting model parameters

Change `tempdir()` into `getwd()` for copying to working directory.

    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.

    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")`.