Repository Mirror for your Cloud Server and Webhosting

Title:

Parametric Survival Model Selection for Decision-Analytic Models

Version:

0.1.2

Description:

Provides a standardized framework to support the selection and evaluation of parametric survival models for time-to-event data. Includes tools for visualizing survival data, checking proportional hazards assumptions (Grambsch and Therneau, 1994, <doi:10.1093/biomet/81.3.515>), comparing parametric (Ishak and colleagues, 2013, <doi:10.1007/s40273-013-0064-3>), spline (Royston and Parmar, 2002, <doi:10.1002/sim.1203>) and cure models, examining hazard functions, and evaluating model extrapolation. Methods are consistent with recommendations in the NICE Decision Support Unit Technical Support Documents (14 and 21 https://sheffield.ac.uk/nice-dsu/tsds/survival-analysis). Results are structured to facilitate integration into decision-analytic models, and reports can be generated with 'rmarkdown'. The package builds on existing tools including 'flexsurv' (Jackson, 2016, <doi:10.18637/jss.v070.i08>)) and 'flexsurvcure' for estimating cure models.

License:

GPL (≥ 3)

URL:

https://github.com/Bram-R/PERSUADE

BugReports:

https://github.com/Bram-R/PERSUADE/issues

Depends:

R (≥ 4.1.0)

Imports:

data.table, flexsurv, flexsurvcure, ggplot2, muhaz, rmarkdown, rms, sft, stats, survival, survminer

Suggests:

kableExtra, knitr, testthat (≥ 3.1.2), utils

VignetteBuilder:

knitr

Config/testthat/edition:

Encoding:

UTF-8

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2025-10-06 09:47:00 UTC; G10028783

Author:

Bram Ramaekers

[aut, cre, ths], Xavier Pouwels

[ctb], Sabine Grimm

[ths], Manuela Joore

[ths]

Maintainer:

Bram Ramaekers <bram.ramaekers@mumc.nl>

Repository:

CRAN

Date/Publication:

2025-10-09 08:10:03 UTC

Main PERSUADE Function

Description

Executes the PERSUADE workflow for parametric survival analysis, including Kaplan-Meier, parametric, spline, and cure models. Produces outputs for visualization, prediction, and Excel export.

Usage

f_PERSUADE(
  name = "no_name",
  years,
  status,
  group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  cure_link = "logistic",
  time_unit,
  time_horizon,
  time_pred_surv_table
)

Arguments

name

Character. Name identifier for the analysis (default: "no_name").

years

Numeric vector of time-to-event data.

status

Numeric vector indicating event occurrence (1 = event, 0 = censoring).

group

Factor indicating group membership.

strata

Logical. Whether to stratify models by group.

spline_mod

Logical. Whether spline models should be fitted.

cure_mod

Logical. Whether cure models should be fitted.

cure_link

Character string specifying the link function for cure models ("logistic", "loglog", "identity", "probit"; default = "logistic").

time_unit

Numeric. The unit of time for annualization.

time_horizon

Numeric. The maximum prediction time horizon.

time_pred_surv_table

Numeric vector of time points for survival table predictions.

Details

The workflow proceeds in three main stages:

Observed data (Kaplan-Meier, hazards, Cox regression).
Parametric, spline, and cure model fitting.
Prediction and export of results.

Value

A list of class "PERSUADE" containing:

input: Input arguments used in the analysis.
surv_obs: Observed survival results (Kaplan-Meier, hazards, Cox model).
surv_model: Fitted parametric/spline/cure models.
surv_pred: Model predictions.
surv_model_excel: Excel-ready parameter table.
misc: Auxiliary results (labels, number of groups, etc.).

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)

Calculate Cumulative Hazard Estimates

Description

Computes cumulative hazard estimates for up to three groups along with variance and confidence intervals, using the estimateNAH package.

Usage

f_cum_hazard(years, status, group, ngroups, time_pred, time_unit)

Arguments

years

Numeric vector of time-to-event data.

status

Numeric vector indicating event occurrence (1 = event, 0 = censoring).

group

Factor indicating group membership.

ngroups

Integer. Number of groups (1-3).

time_pred

Numeric vector of prediction times.

time_unit

Numeric. Time unit length for scaling.

Value

A data frame with columns:

group: Group identifier.
time: Prediction times.
H: Cumulative hazard values.
var: Variance estimates.
H_upper, H_lower: 95% confidence interval bounds.
H_delta, H_upper_delta, H_lower_delta: Differences between time steps.

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
f_cum_hazard(
  years = years,
  status = status,
  group = group,
  ngroups = nlevels(group),
  time_pred = seq(0, 5000, 365.25),
  time_unit = 30
)

Generate PDF Report for a PERSUADE Analysis

Description

Save the PERSUADE object and render a PDF report using the bundled PERSUADE_output.Rmd template, or a user-specified template.

Usage

f_generate_report(
  PERSUADE,
  output_dir = NULL,
  template_dir = NULL,
  open = FALSE
)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

output_dir

Character string giving the directory to copy the function output to. If NULL (the default), the function uses: file.path(tempdir(), paste0(PERSUADE$name, "_output")). Change tempdir() into getwd() for copying to working directory.

template_dir

Optional character string giving the full path to an Rmd template. If NULL (the default), the function looks for PERSUADE_output.Rmd within the package installation directory.

open

Logical. Whether to browse the generated file.

Details

The default R markdown file PERSUADE_output.Rmd is stored within the package under ⁠inst/rmd/⁠. Figures are written to a subdirectory ⁠Images/⁠ inside the output folder, and the knit environment is initialised with the supplied PERSUADE object. Supplying a custom template_dir allows alternative report formats to be used, and simplifies testing. This function requires the following suggested packages: knitr, kableExtra, and rmarkdown. If not installed, the function will throw an error.

Value

A length-1 character string giving the absolute path to the generated PDF, returned invisibly.

Examples

## Not run:  # Requires LaTeX to be installed
years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
# Copy output to temporary directory
# (change `tempdir()` into `getwd()`
# for copying to working directory)
f_generate_report(
  PERSUADE,
  output_dir = file.path(
  tempdir(), paste0(PERSUADE$name, "_output")
  ),
  template_dir = NULL
)

## End(Not run)

Copy Excel Template for Model Parameters

Description

Copy the bundled Excel template PERSUADE_Excel_template.xltx to a user-specified directory. This template provides a convenient structure for transferring survival model outputs from PERSUADE into health economic models.

Usage

f_get_excel_template(output_dir = NULL)

Arguments

output_dir

Character string giving the directory to copy the template to. If NULL (the default), the function uses: tempdir(). Change tempdir() into getwd() for copying to working directory.

Details

The default Excel file PERSUADE_Excel_template.xltx is stored within the package under ⁠inst/excel_template/⁠. This function locates the installed file via system.file() and copies it into the requested directory. If a file with the same name already exists at the destination, it will be overwritten.

The Excel template provides a standardized format for entering parametric survival model parameters, making it easier to use PERSUADE outputs in downstream decision-analytic models. Users may adapt the template as needed for their specific workflows.

Value

A length-1 character string giving the absolute path to the copied template file, returned invisibly.

Examples


# Copy output to temporary directory
# (change `tempdir()` into `getwd()` for
# copying to working directory)
f_get_excel_template(
output_dir = file.path(tempdir(), paste0("BC_OS", "_output"))
)

Calculate Smoothed Hazard Estimates

Description

Computes smoothed hazard estimates for up to three groups using the muhaz package.

Usage

f_hazard(years, status, group, ngroups)

Arguments

years

Numeric vector of time-to-event data.

status

Numeric vector indicating event occurrence (1 = event, 0 = censoring).

group

Factor indicating group membership.

ngroups

Integer. Number of groups (1-3).

Value

A list with elements:

hazards: List of hazard objects (one per group).
names: Vector of group identifiers for hazard values.
max: Data frame with maximum time and hazard values.

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
f_hazard(
  years = years,
  status = status,
  group = group,
  ngroups = nlevels(group)
)

Plot Extrapolated Cure Survival Models per Group

Description

Plot Kaplan-Meier curves per group with shaded confidence bands and overlay fitted cure survival models (Weibull, log-normal, log-logistic; mixture and non-mixture forms) extrapolated to the analysis time horizon. Runs only when PERSUADE$input$cure_mod is TRUE.

Usage

f_plot_cure_surv_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = TRUE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_cure_surv_extrap(PERSUADE)

Cure Survival Model Overlay

Description

Overlays a fitted cure survival model on KM curves, including shaded KM confidence bands per group.

Usage

f_plot_cure_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

model_index

Integer. Index of the cure model in PERSUADE$surv_pred$model$cure.

Value

A base R plot of KM curves with cure model overlays.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = TRUE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_cure_surv_model(PERSUADE, model_index = 1)

Diagnostic Plot for Cure Survival Models

Description

Produces diagnostic plots for mixture and non-mixture cure survival models, using transformations depending on the underlying distribution (Weibull, log-normal, log-logistic).

Usage

f_plot_diag_cure_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

model_index

Integer. Index of the cure model in PERSUADE$surv_pred$model$cure.

Value

A base R diagnostic plot for the selected cure survival model.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = TRUE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_diag_cure_surv_model(PERSUADE, model_index = 1)

Diagnostic Plot for Parametric Survival Models

Description

Produces diagnostic plots for standard parametric survival models, using appropriate transformations depending on the model family (exponential, Weibull, Gompertz, log-normal, log-logistic, gamma, generalized gamma).

Usage

f_plot_diag_param_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

model_index

Integer. Index of the parametric model in PERSUADE$surv_pred$model.

Value

A base R diagnostic plot for the selected parametric survival model.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_diag_param_surv_model(PERSUADE, model_index = 1)

Diagnostic Plot for Spline Survival Models

Description

Produces diagnostic plots for spline-based survival models, using log-time transformations adapted to hazard, odds, or normal scales depending on the spline model type.

Usage

f_plot_diag_spline_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

model_index

Integer. Index of the spline model in PERSUADE$surv_pred$model$spline.

Value

A base R diagnostic plot for the selected spline-based survival model.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_diag_spline_surv_model(PERSUADE, model_index = 1)

Plot Extrapolated Hazard Functions (Cure Models)

Description

Plot observed smoothed hazard rates per group and overlay extrapolated hazard functions from all fitted cure survival models (mixture and non-mixture). Runs only when PERSUADE$input$cure_mod is TRUE.

Usage

f_plot_hazard_cure_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = TRUE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_hazard_cure_extrap(PERSUADE)

Plot Extrapolated Hazard Functions (Parametric Models)

Description

Plot observed smoothed hazard rates per group and overlay extrapolated hazard functions from all fitted parametric survival models.

Usage

f_plot_hazard_parametric_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_hazard_parametric_extrap(PERSUADE)

Plot Extrapolated Hazard Functions (Spline Models)

Description

Plot observed smoothed hazard rates per group and overlay extrapolated hazard functions from all fitted spline survival models. Runs only when PERSUADE$input$spline_mod is TRUE.

Usage

f_plot_hazard_spline_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_hazard_spline_extrap(PERSUADE)

Hazard Plot with Model Overlays

Description

Plots observed smoothed hazard estimates together with hazard predictions from parametric, spline, and cure survival models (if fitted).

Usage

f_plot_hazard_with_models(PERSUADE)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

Value

A series of base R plots, one per group, with hazard overlays by model family.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_hazard_with_models(PERSUADE)

Plot Kaplan-Meier Survival Curves (ggsurvplot)

Description

Generates Kaplan-Meier survival plots from a PERSUADE object using survminer::ggsurvplot(), automatically adapting to the number of groups.

Usage

f_plot_km_survival(PERSUADE)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

Value

A ggsurvplot object with KM curves, risk table, CI bands, and optional censor marks.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_km_survival(PERSUADE)

Plot Kaplan-Meier Survival Curves (Base R)

Description

Generates Kaplan-Meier survival plots from a PERSUADE object using base R graphics, with shaded confidence intervals and group-specific legends.

Usage

f_plot_km_survival_base(PERSUADE)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

Value

A base R plot.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_km_survival_base(PERSUADE)

Log-Log Survival Diagnostic Plot

Description

Creates a log(-log(S(t))) vs log(time) plot to visually assess proportional hazards.

Usage

f_plot_log_cumhaz(PERSUADE)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

Value

A base R plot showing ln(-ln(S(t))) against ln(time).

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_log_cumhaz(PERSUADE)

Plot Extrapolated Parametric Survival Models per Group

Description

Plot Kaplan-Meier curves per group with shaded confidence bands and overlay fitted parametric survival models (Exponential, Weibull, Gompertz, log-normal, log-logistic, Gamma, generalized Gamma) extrapolated to the analysis time horizon.

Usage

f_plot_param_surv_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_param_surv_extrap(PERSUADE)

Parametric Survival Model Overlay

Description

Overlays a fitted parametric survival model on top of KM curves, including shaded KM confidence bands per group.

Usage

f_plot_param_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

model_index

Integer. Index of the parametric model in PERSUADE$surv_pred$model.

Value

A base R plot of KM curves with parametric model overlays.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_param_surv_model(PERSUADE, model_index = 1)

Schoenfeld Residuals Plot

Description

Produces scaled Schoenfeld residual plots with fitted regression lines to evaluate Cox proportional hazards assumptions.

Usage

f_plot_schoenfeld_residuals(PERSUADE)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

Value

One or more base R plots, one per group comparison.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_schoenfeld_residuals(PERSUADE)

Smoothed Hazard Function Plot

Description

Plots smoothed hazard estimates for each group in the PERSUADE object.

Usage

f_plot_smoothed_hazard(PERSUADE)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

Value

A base R plot of smoothed hazards by group.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_smoothed_hazard(PERSUADE)

Plot Extrapolated Spline Survival Models per Group

Description

Plot Kaplan-Meier curves per group with shaded confidence bands and overlay fitted spline survival models (hazard, odds, normal scales) extrapolated to the analysis time horizon. Runs only when PERSUADE$input$spline_mod is TRUE.

Usage

f_plot_spline_surv_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_spline_surv_extrap(PERSUADE)

Spline Survival Model Overlay

Description

Overlays a spline-based survival model on KM curves, including shaded KM confidence bands and vertical lines for knot positions.

Usage

f_plot_spline_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object created by f_PERSUADE().

model_index

Integer. Index of the spline model in PERSUADE$surv_pred$model$spline.

Value

A base R plot of KM curves with spline model overlays and knots.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_spline_surv_model(PERSUADE, model_index = 1)

Plot Extrapolated Annual Transition Probabilities (Cure Models)

Description

Plot smoothed observed annual transition probabilities with shaded confidence intervals and overlay predictions from all fitted cure survival models. Runs only when PERSUADE$input$cure_mod is TRUE.

Usage

f_plot_tp_cure_surv_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = TRUE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_tp_cure_surv_extrap(PERSUADE)

Plot Annual Transition Probabilities for Cure Survival Models

Description

Plot smoothed observed annual transition probabilities with shaded confidence intervals, overlaid with predictions from a selected cure survival model (mixture or non-mixture; Weibull, log-normal, or log-logistic).

Usage

f_plot_tp_cure_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

model_index

Integer index selecting the cure model within PERSUADE$surv_model$cure_models (1-based). Defaults to 1.

Value

Invisibly returns NULL. The function draws a base R plot as a side effect.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = TRUE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_tp_cure_surv_model(PERSUADE, model_index = 1)

Plot Extrapolated Annual Transition Probabilities (Parametric Models)

Description

Plot smoothed observed annual transition probabilities with shaded confidence intervals and overlay predictions from all fitted parametric survival models.

Usage

f_plot_tp_param_surv_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_tp_param_surv_extrap(PERSUADE)

Plot Annual Transition Probabilities for Parametric Survival Models

Description

Plot smoothed observed annual transition probabilities alongside model-predicted probabilities for a selected parametric model, with shaded confidence intervals per group.

Usage

f_plot_tp_param_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

model_index

Integer index selecting the parametric model within PERSUADE$surv_model$param_models (1-based). Defaults to 1.

Value

Invisibly returns NULL. The function draws a base R plot as a side effect.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_tp_param_surv_model(PERSUADE, model_index = 1)

Plot Extrapolated Annual Transition Probabilities (Spline Models)

Description

Plot smoothed observed annual transition probabilities with shaded confidence intervals and overlay predictions from all fitted spline survival models. Runs only when PERSUADE$input$spline_mod is TRUE.

Usage

f_plot_tp_spline_surv_extrap(PERSUADE)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

Value

Invisibly returns NULL. The function draws one or more base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_tp_spline_surv_extrap(PERSUADE)

Plot Annual Transition Probabilities for Spline Survival Models

Description

Plot smoothed observed annual transition probabilities together with predictions from a selected spline survival model (hazard/odds/normal scale), including shaded confidence intervals and vertical lines for spline knots.

Usage

f_plot_tp_spline_surv_model(PERSUADE, model_index = 1)

Arguments

PERSUADE

A PERSUADE object returned by f_PERSUADE().

model_index

Integer index selecting the spline model within PERSUADE$surv_model$spline_models (1-based). Defaults to 1.

Value

Invisibly returns NULL. The function draws a base R plot as a side effect.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = TRUE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
f_plot_tp_spline_surv_model(PERSUADE, model_index = 1)

Compute Summary Statistics for Numeric Variables

Description

Compute descriptive statistics for each numeric variable in a data frame: mean, standard deviation, minimum, first quartile (Q1), median, third quartile (Q3), maximum, and interquartile range (IQR). Results are rounded to three decimals.

Usage

f_summary(df)

Arguments

df

A data frame; numeric columns are summarized.

Value

A data frame (one row per variable) with columns: Mean, Std.Dev, Min, Q1, Median, Q3, Max, IQR.

Examples

f_summary(mtcars)

Fit Parametric Survival Models

Description

Fits standard parametric models, spline models, and cure models using the flexsurv package.

Usage

f_surv_model(
  years,
  status,
  group,
  strata,
  ngroups,
  form,
  spline_mod,
  cure_mod,
  cure_link,
  group_names
)

Arguments

years

Numeric vector of time-to-event data.

status

Numeric vector indicating event occurrence (1 = event, 0 = censoring).

group

Factor indicating group membership.

strata

Logical. Whether to stratify models by group.

ngroups

Integer. Number of groups.

form

A survival model formula (e.g., Surv(years, status) ~ group).

spline_mod

Logical. Whether spline models should be fitted.

cure_mod

Logical. Whether cure models should be fitted.

cure_link

Character string specifying the link function for cure models ("logistic", "loglog", "identity", "probit"; default = "logistic").

group_names

Character vector of group labels (for cure fractions).

Details

Models fitted include Exponential, Weibull, Gompertz, Log-normal, Log-logistic, Gamma, Generalised Gamma. Optional spline models (1-3 knots, scales: hazard, odds, normal) and cure models (Weibull, Log-normal, Log-logistic with logistic/probit/etc. link).

Value

A list containing:

param_models, param_ic: Parametric models and information criteria.
spline_models, spline_ic: Spline models and IC (if fitted).
cure_models, cure_ic: Cure models and IC (if fitted).

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
form <- stats::as.formula(survival::Surv(years, status) ~ group)
f_surv_model(
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  ngroups = nlevels(group),
  form = form,
  spline_mod = FALSE,
  cure_mod = FALSE,
  cure_link = "logistic",
  group_names = levels(group)
)

Prepare Excel-Ready Survival Model Output

Description

Formats model parameters (including spline knots) into a table suitable for export to Excel.

Usage

f_surv_model_excel(ngroups, strata, surv_model, spline_mod, cure_mod)

Arguments

ngroups

Integer. Number of groups.

strata

Logical. Whether stratified models were used.

surv_model

List of fitted models from f_surv_model().

spline_mod

Logical. Whether spline models were included.

cure_mod

Logical. Whether cure models were included.

Value

A transposed data frame containing:

Distribution names
Parameter names
Estimates, SE, CI
Knot values (if splines fitted)
Covariance matrix

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
form <- stats::as.formula(survival::Surv(years, status) ~ group)
surv_model <- f_surv_model(
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  ngroups = nlevels(group),
  form = form,
  spline_mod = FALSE,
  cure_mod = FALSE,
  cure_link = "logistic",
  group_names = levels(group)
)
f_surv_model_excel(
  ngroups = nlevels(group),
  strata = FALSE,
  surv_model = surv_model,
  spline_mod = FALSE,
  cure_mod = FALSE
)

Predict from Survival Models

Description

Generates predicted survival and hazard values from fitted parametric, spline, and cure models.

Usage

f_surv_model_pred(
  ngroups,
  time_pred,
  surv_model,
  spline_mod,
  cure_mod,
  group_names
)

Arguments

ngroups

Integer. Number of groups.

time_pred

Numeric vector of prediction times.

surv_model

List of fitted survival models from f_surv_model().

spline_mod

Logical. Whether spline models were fitted.

cure_mod

Logical. Whether cure models were fitted.

group_names

Character vector of group labels.

Value

A list of predictions containing:

param_models: Survival & hazard predictions for standard models.
spline: Predictions for spline models (if fitted).
cure: Predictions for cure models (if fitted).

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
form <- stats::as.formula(survival::Surv(years, status) ~ group)
surv_model <- f_surv_model(
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  ngroups = nlevels(group),
  form = form,
  spline_mod = FALSE,
  cure_mod = FALSE,
  cure_link = "logistic",
  group_names = levels(group)
)
f_surv_model_pred(
  ngroups = nlevels(group),
  time_pred = seq(0, 5000, 365.25),
  surv_model = surv_model,
  spline_mod = FALSE,
  cure_mod = FALSE,
  group_names = levels(group)
)

Group Predictions by Survival Model

Description

Consolidates predictions from f_surv_model_pred() into group-specific data frames.

Usage

f_surv_model_pred_gr(
  ngroups,
  surv_model,
  surv_model_pred,
  spline_mod,
  cure_mod
)

Arguments

ngroups

Integer. Number of groups.

surv_model

List of survival models from f_surv_model().

surv_model_pred

List of predictions from f_surv_model_pred().

spline_mod

Logical. Whether spline models were fitted.

cure_mod

Logical. Whether cure models were fitted.

Value

A list of length ngroups, each a data frame with columns:

time
survival predictions for all models (parametric, spline, cure).

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
form <- stats::as.formula(survival::Surv(years, status) ~ group)
surv_model <- f_surv_model(
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  ngroups = nlevels(group),
  form = form,
  spline_mod = FALSE,
  cure_mod = FALSE,
  cure_link = "logistic",
  group_names = levels(group)
)
surv_model_pred <- f_surv_model_pred(
  ngroups = nlevels(group),
  time_pred = seq(0, 5000, 365.25),
  surv_model = surv_model,
  spline_mod = FALSE,
  cure_mod = FALSE,
  group_names = levels(group)
)
f_surv_model_pred_gr(
  ngroups = nlevels(group),
  surv_model = surv_model,
  surv_model_pred = surv_model_pred,
  spline_mod = FALSE,
  cure_mod = FALSE
)

Compute Transition Probabilities for Survival Model Predictions

Description

Compute Transition Probabilities for Survival Model Predictions

Usage

f_surv_model_pred_tp_gr(
  ngroups,
  time_pred,
  time_unit,
  surv_model_pred_gr,
  cols_tp
)

Arguments

ngroups

Integer, number of groups.

time_pred

Numeric vector of prediction times (currently unused).

time_unit

Numeric, time unit for transition probability calculation.

surv_model_pred_gr

List of group predictions. Each group's table should have a time column in column 1 and survival-related columns from 2:cols_tp.

cols_tp

Integer, index of the last survival-related column (i.e., use columns 2:cols_tp).

Value

Named list of data.frames with transition probabilities (truncated after threshold).

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
form <- stats::as.formula(survival::Surv(years, status) ~ group)
surv_model <- f_surv_model(
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  ngroups = nlevels(group),
  form = form,
  spline_mod = FALSE,
  cure_mod = FALSE,
  cure_link = "logistic",
  group_names = levels(group)
)
surv_model_pred <- f_surv_model_pred(
  ngroups = nlevels(group),
  time_pred = seq(0, 5000, 365.25),
  surv_model = surv_model,
  spline_mod = FALSE,
  cure_mod = FALSE,
  group_names = levels(group)
)
surv_model_pred_gr <- f_surv_model_pred_gr(
  ngroups = nlevels(group),
  surv_model = surv_model,
  surv_model_pred = surv_model_pred,
  spline_mod = FALSE,
  cure_mod = FALSE
)
f_surv_model_pred_tp_gr(
  ngroups = nlevels(group),
  time_pred = seq(0, 5000, 365.25),
  time_unit = 365.25/12,
  surv_model_pred_gr = surv_model_pred_gr,
  cols_tp = 8
)

Calculate Transition Probabilities

Description

Derives annualized transition probabilities (and confidence bounds) from cumulative hazard estimates, smoothed with LOESS.

Usage

f_tp(ngroups, cum_haz, time_unit)

Arguments

ngroups

Integer. Number of groups (1-3).

cum_haz

Data frame from f_cum_hazard() with columns group, time, H_delta, H_upper_delta, H_lower_delta.

time_unit

Numeric. Time unit for annualization.

Value

A list with:

gr_1, gr_2, gr_3: Data frames of smoothed probabilities per group.
max: Maximum upper bound across all groups.

Examples

years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
cum_haz <- f_cum_hazard(
  years = years,
  status = status,
  group = group,
  ngroups = nlevels(group),
  time_pred = seq(0, 5000, 365.25),
  time_unit = 30
)
f_tp(ngroups = nlevels(group), cum_haz = cum_haz, time_unit = 30)

Plot Method for PERSUADE Objects

Description

Generates diagnostic and model fit plots for PERSUADE survival analysis objects. The type argument controls which plot(s) are produced:

"km": Kaplan-Meier survival curves.
"ph": Proportional hazards diagnostics.
"hr": Hazard function with fitted models.
"param_models": Fitted parametric survival models with diagnostics and transition probability plots.
"spline_models": Fitted spline-based survival models with diagnostics and transition probability plots.
"cure_models": Fitted cure survival models with diagnostics and transition probability plots.

Usage

## S3 method for class 'PERSUADE'
plot(x, type = "km", ...)

Arguments

x

A PERSUADE object from f_PERSUADE().

type

Character. The type of plot to produce.

...

Additional arguments (currently unused).

Value

Invisibly returns a list of results from the plotting functions. Also produces base R plots as side effects.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
plot(PERSUADE, "km")

Print Method for PERSUADE Objects

Description

Displays a brief summary of the PERSUADE object in the console.

Usage

## S3 method for class 'PERSUADE'
print(x, ...)

Arguments

x

A PERSUADE object from f_PERSUADE().

...

Additional arguments (currently unused).

Value

Invisibly returns the PERSUADE object.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
print(PERSUADE)

Summary Method for PERSUADE Objects

Description

The type argument controls which summary is produced:

"km": Kaplan-Meier estimates (default).
"surv_probs": Survival probabilities at specified prediction times for each group.
"gof": Goodness-of-fit statistics for standard parametric models.
"gof_spline": Goodness-of-fit statistics for spline models.
"gof_cure": Goodness-of-fit statistics for cure models (including cure fraction).

Usage

## S3 method for class 'PERSUADE'
summary(object, ..., type = "km")

Arguments

object

A PERSUADE object from f_PERSUADE().

...

Additional arguments. Currently only type is used.

type

Character string, one of "km", "surv_probs", "gof", "gof_spline", "gof_cure". Controls the type of summary output.

Value

A data frame or list of data frames depending on type.

Examples


years <- survival::lung$time
status <-  survival::lung$status
group <- factor(survival::lung$sex)
PERSUADE <- f_PERSUADE(
  name = "Example",
  years = years,
  status = status,
  group = group,
  strata = FALSE,
  spline_mod = FALSE,
  cure_mod = FALSE,
  time_unit = 365.25/12,
  time_horizon = 2000,
  time_pred_surv_table = seq(0, 2000, 365.25)
)
summary(PERSUADE, type = "surv_probs")

Main PERSUADE Function

Description

Usage

Arguments

Details

Value

See Also

Examples

Calculate Cumulative Hazard Estimates

Description

Usage

Arguments

Value

Examples

Generate PDF Report for a PERSUADE Analysis

Description

Usage

Arguments

Details

Value

See Also

Examples

Copy Excel Template for Model Parameters

Description

Usage

Arguments

Details

Value

See Also

Examples

Calculate Smoothed Hazard Estimates

Description

Usage

Arguments

Value

Examples

Plot Extrapolated Cure Survival Models per Group

Description

Usage

Arguments

Value

See Also

Examples

Cure Survival Model Overlay

Description

Usage

Arguments

Value

See Also

Examples

Diagnostic Plot for Cure Survival Models

Description

Usage

Arguments

Value

See Also

Examples

Diagnostic Plot for Parametric Survival Models

Description

Usage

Arguments

Value

See Also

Examples

Diagnostic Plot for Spline Survival Models

Description

Usage

Arguments

Value

See Also

Examples

Plot Extrapolated Hazard Functions (Cure Models)

Description

Usage

Arguments

Value

See Also

Examples

Plot Extrapolated Hazard Functions (Parametric Models)

Description