| 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 21https://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: | 3 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| NeedsCompilation: | no |
| 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.).
See Also
f_hazard(),f_cum_hazard(),f_surv_model()
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 withvariance and confidence intervals, using theestimateNAH 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$timestatus <- survival::lung$statusgroup <- 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 bundledPERSUADE_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 |
output_dir | Character string giving the directory to copy the functionoutput to. If |
template_dir | Optional character string giving the full path to an Rmdtemplate. If |
open | Logical. Whether to browse the generated file. |
Details
The default R markdown filePERSUADE_output.Rmd is stored withinthe package underinst/rmd/. Figures are written to a subdirectoryImages/ inside the output folder, and the knit environment isinitialised with the suppliedPERSUADE object. Supplying a customtemplate_dir allows alternative report formats to be used, andsimplifies testing. This function requires the following suggested packages:knitr,kableExtra, andrmarkdown.If not installed, the function will throw an error.
Value
A length-1 character string giving the absolute path to the generatedPDF, returned invisibly.
See Also
Examples
## Not run: # Requires LaTeX to be installedyears <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 templatePERSUADE_Excel_template.xltx to a user-specifieddirectory. This template provides a convenient structure for transferring survivalmodel outputs fromPERSUADE 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 |
Details
The default Excel filePERSUADE_Excel_template.xltx is stored withinthe package underinst/excel_template/. This function locates the installedfile viasystem.file() and copies it into the requested directory. If a filewith the same name already exists at the destination, it will be overwritten.
The Excel template provides a standardized format for entering parametricsurvival model parameters, making it easier to use PERSUADE outputs indownstream decision-analytic models. Users may adapt the template as neededfor their specific workflows.
Value
A length-1 character string giving the absolute path to the copiedtemplate file, returned invisibly.
See Also
f_generate_report(),system.file()
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 usingthemuhaz 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$timestatus <- survival::lung$statusgroup <- 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 overlayfitted cure survival models (Weibull, log-normal, log-logistic; mixture andnon-mixture forms) extrapolated to the analysis time horizon. Runs only whenPERSUADE$input$cure_mod isTRUE.
Usage
f_plot_cure_surv_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 KMconfidence bands per group.
Usage
f_plot_cure_surv_model(PERSUADE, model_index = 1)Arguments
PERSUADE | A PERSUADE object created by |
model_index | Integer. Index of the cure model in |
Value
A base R plot of KM curves with cure model overlays.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 |
model_index | Integer. Index of the cure model in |
Value
A base R diagnostic plot for the selected cure survival model.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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, usingappropriate 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 |
model_index | Integer. Index of the parametric model in |
Value
A base R diagnostic plot for the selected parametric survival model.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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-timetransformations adapted to hazard, odds, or normal scales depending on thespline model type.
Usage
f_plot_diag_spline_surv_model(PERSUADE, model_index = 1)Arguments
PERSUADE | A PERSUADE object created by |
model_index | Integer. Index of the spline model in |
Value
A base R diagnostic plot for the selected spline-based survival model.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 extrapolatedhazard functions from all fitted cure survival models (mixture and non-mixture).Runs only whenPERSUADE$input$cure_mod isTRUE.
Usage
f_plot_hazard_cure_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 extrapolatedhazard functions from all fitted parametric survival models.
Usage
f_plot_hazard_parametric_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 extrapolatedhazard functions from all fitted spline survival models. Runs only whenPERSUADE$input$spline_mod isTRUE.
Usage
f_plot_hazard_spline_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 predictionsfrom parametric, spline, and cure survival models (if fitted).
Usage
f_plot_hazard_with_models(PERSUADE)Arguments
PERSUADE | A PERSUADE object created by |
Value
A series of base R plots, one per group, with hazard overlays by model family.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 usingsurvminer::ggsurvplot(), automatically adapting to the number of groups.
Usage
f_plot_km_survival(PERSUADE)Arguments
PERSUADE | A PERSUADE object created by |
Value
Aggsurvplot object with KM curves, risk table, CI bands, and optional censor marks.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 |
Value
A base R plot.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 |
Value
A base R plot showing ln(-ln(S(t))) against ln(time).
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 overlayfitted 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 |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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, includingshaded KM confidence bands per group.
Usage
f_plot_param_surv_model(PERSUADE, model_index = 1)Arguments
PERSUADE | A PERSUADE object created by |
model_index | Integer. Index of the parametric model in |
Value
A base R plot of KM curves with parametric model overlays.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 linesto evaluate Cox proportional hazards assumptions.
Usage
f_plot_schoenfeld_residuals(PERSUADE)Arguments
PERSUADE | A PERSUADE object created by |
Value
One or more base R plots, one per group comparison.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 |
Value
A base R plot of smoothed hazards by group.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 overlayfitted spline survival models (hazard, odds, normal scales) extrapolated tothe analysis time horizon. Runs only whenPERSUADE$input$spline_mod isTRUE.
Usage
f_plot_spline_surv_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 KMconfidence bands and vertical lines for knot positions.
Usage
f_plot_spline_surv_model(PERSUADE, model_index = 1)Arguments
PERSUADE | A PERSUADE object created by |
model_index | Integer. Index of the spline model in |
Value
A base R plot of KM curves with spline model overlays and knots.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 confidenceintervals and overlay predictions from all fitted cure survival models.Runs only whenPERSUADE$input$cure_mod isTRUE.
Usage
f_plot_tp_cure_surv_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 confidenceintervals, 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 |
model_index | Integer index selecting the cure model within |
Value
Invisibly returnsNULL. The function draws a base R plot as a side effect.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 confidenceintervals and overlay predictions from all fitted parametric survival models.
Usage
f_plot_tp_param_surv_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 alongsidemodel-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 |
model_index | Integer index selecting the parametric model within |
Value
Invisibly returnsNULL. The function draws a base R plot as a side effect.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 confidenceintervals and overlay predictions from all fitted spline survival models.Runs only whenPERSUADE$input$spline_mod isTRUE.
Usage
f_plot_tp_spline_surv_extrap(PERSUADE)Arguments
PERSUADE | A PERSUADE object returned by |
Value
Invisibly returnsNULL. The function draws one or more base R plots as side effects.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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 withpredictions 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 |
model_index | Integer index selecting the spline model within |
Value
Invisibly returnsNULL. The function draws a base R plot as a side effect.
See Also
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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, thirdquartile (Q3), maximum, and interquartile range (IQR). Results are roundedto 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 modelsusing theflexsurv 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., |
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$timestatus <- survival::lung$statusgroup <- 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 atable 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 |
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$timestatus <- survival::lung$statusgroup <- 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 |
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$timestatus <- survival::lung$statusgroup <- 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 fromf_surv_model_pred() intogroup-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 |
surv_model_pred | List of predictions from |
spline_mod | Logical. Whether spline models were fitted. |
cure_mod | Logical. Whether cure models were fitted. |
Value
A list of lengthngroups, each a data frame with columns:
timesurvival predictions for all models (parametric, spline, cure).
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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$timestatus <- survival::lung$statusgroup <- 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 |
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$timestatus <- survival::lung$statusgroup <- 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.Thetype 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 |
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$timestatus <- survival::lung$statusgroup <- 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 |
... | Additional arguments (currently unused). |
Value
Invisibly returns the PERSUADE object.
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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
Thetype 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 |
... | Additional arguments. Currently only |
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 ontype.
Examples
years <- survival::lung$timestatus <- survival::lung$statusgroup <- 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")