Type:	Package
Title:	Simplify Survival Data Analysis and Model Fitting
Version:	2.0.1
Description:	Inspect survival data, plot Kaplan-Meier curves, assess the proportional hazards assumption, fit parametric survival models, predict and plot survival and hazards, and export the outputs to Excel. A simple interface for fitting survival models using 'flexsurv::flexsurvreg()', 'flexsurv::flexsurvspline()', 'flexsurvcure::flexsurvcure()', and 'survival::survreg()'.
License:	MIT + file LICENSE
URL:	https://github.com/Maple-Health-Group/easysurv, https://maple-health-group.github.io/easysurv/
BugReports:	https://github.com/Maple-Health-Group/easysurv/issues
Depends:	R (≥ 4.1.0)
Imports:	bshazard, censored, cli, data.table, dplyr, flexsurv, flexsurvcure, ggplot2, ggsurvfit, openxlsx, parsnip, plotly, purrr, rlang, scales, stats, survival, tibble, tidyr, usethis, utils
Suggests:	knitr, rmarkdown, spelling, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/Needs/website:	r-lib/asciicast
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.1
NeedsCompilation:	no
Packaged:	2024-06-20 19:26:29 UTC; NiallDavison
Author:	Niall Davison [aut, cre], Brad Kievit [aut], Maple Health Group, LLC [cph, fnd]
Maintainer:	Niall Davison <niall.davison@maplehealthgroup.com>
Repository:	CRAN
Date/Publication:	2024-06-21 10:30:06 UTC

easysurv: Simplify Survival Data Analysis and Model Fitting

Description

Inspect survival data, plot Kaplan-Meier curves, assess the proportional hazards assumption, fit parametric survival models, predict and plot survival and hazards, and export the outputs to Excel. A simple interface for fitting survival models using 'flexsurv::flexsurvreg()', 'flexsurv::flexsurvspline()', 'flexsurvcure::flexsurvcure()', and 'survival::survreg()'.

Author(s)

Maintainer: Niall Davison niall.davison@maplehealthgroup.com (ORCID)

Authors:

• Brad Kievit brad.kievit@maplehealthgroup.com

Other contributors:

• Maple Health Group, LLC [copyright holder, funder]

See Also

Useful links:

• https://github.com/Maple-Health-Group/easysurv

• https://maple-health-group.github.io/easysurv/

• Report bugs at https://github.com/Maple-Health-Group/easysurv/issues

Formatted Copy of ggsurvfit::adtte

Description

Background The example simulated data set is based on large phase III clinical trials in breast cancer such as the ALTTO trial doi:10.1200/JCO.2015.62.1797. The example trial aims to determine if a combination of two therapies tablemab (T) plus vismab (V) improves outcomes for metastatic human epidermal growth factor 2-positive breast cancer and increases the pathologic complete response in the neoadjuvant setting (i.e. treatment given as a first step to shrink a tumor before the main treatment or surgery).

The trial has four treatment arms, patients with centrally confirmed human epidermal growth factor 2-positive early breast cancer were randomly assigned to 1 year of adjuvant therapy with V, T, their sequence (T to V), or their combination (T+V) for 52 weeks.

The primary end point was progression-free survival (PFS) as defined by Cancer.gov: '"the length of time during and after the treatment of a disease, such as cancer, that a patient lives with the disease but it does not get worse. In a clinical trial, measuring the progression-free survival is one way to see how well a new treatment works"'.

A number of baseline measurements (taken at randomization) are also included such as age, hormone receptor status and prior radiotherapy treatment.

Additional details on reasons for study discontinuation and censoring event description are also included.

The data set adopts an abridged version of the CDISC ADaM ADTTE time to event data model. See here for more info on CDISC ADaM data standards https://www.cdisc.org/standards/foundational/adam and specifically the ADTTE time to event data model here https://www.cdisc.org/standards/foundational/adam/adam-basic-data-structure-bds-time-event-tte-analyses-v1-0.

Usage

easy_adtte

Format

The data set contains the following variables:

STUDYID

The study identifier. A code unique to the clinical trial

SUBJID

subject identifier. Numeric ID unique to each patient

USUBJID

unique subject identifier. Text ID combining study and patient IDs

AGE

age at randomisation (years)

STR01

Hormone receptor status at randomisation

STR01N

Hormone receptor positive (Numeric)

STR01L

Hormone receptor positive (Long format)

STR02

Prior Radiotherapy at randomisation

STR02N

Prior Radiotherapy at randomisation (Numeric)

STR02L

Prior Radiotherapy at randomisation (Long format)

TRT01P

Planned treatment assigned at randomisation

TRT01PN

Planned treatment assigned at randomisation (Numeric)

PARAM

Analysis parameter: Progression free survival

PARAMCD

Analysis parameter code

AVAL

Analysis value (time to event (years)

CNSR

Censoring (0 = Event, 1 = Censored)

EVNTDESC

Event description

CNSDTDSC

Censoring description

DCTREAS

Discontinuation from study reason

Source

ggsurvfit::adtte

Formatted Copy of flexsurv::bc

Description

This is a copy of the bc data set exported by the flexsurv package. This data set, however, has column labels assigned.

Usage

easy_bc

Format

The data set contains the following variables:

censrec

0 = Censored, 1 = Dead

rectime

Time of censoring or death in days

group

Prognostic group: Good, Medium, or Poor

recyrs

Time of censoring or death in years

Source

flexsurv::bc

Formatted Copy of survival::lung

Description

This is a copy of the lung data set exported by the survival package. This data set, however, has column labels assigned and time in months.

Usage

easy_lung

Format

The data set contains the following variables:

inst

Institution code

time

Survival time, months

status

Censoring status, 1 = censored, 2 = dead

age

Age

sex

Sex, 1 = Male, 2 = Female

ph.ecog

ECOG Performance Status (Physician)

ph.karno

Karnofsky performance score (Physician)

pat.karno

Karnofsky performance score (Patient)

meal.cal

Calories consumed

wt.loss

Weight loss, lbs

Source

survival::lung

Fit Survival Models

Description

Fits survival models to the provided data using the specified engine and returns various outputs including model parameters, goodness of fit, and estimates of median survival.

Usage

fit_models(
  data,
  time,
  event,
  predict_by = NULL,
  covariates = NULL,
  dists = c("exp", "gamma", "gengamma", "gompertz", "llogis", "lnorm", "weibull"),
  engine = "flexsurv",
  k = c(1, 2, 3),
  scale = "hazard",
  add_time_0 = TRUE,
  ...
)

Arguments

Value

A list containing information about the fit_models() call, the distributions attempted, goodness of fit, fit averages, and cure fractions (if applicable).

Examples

models <- fit_models(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  predict_by = "group",
  covariates = "group"
)

models

Generate Kaplan-Meier estimates

Description

Calculates Kaplan-Meier estimates for survival data and returns summary statistics, plots, and additional outputs.

Usage

get_km(
  data,
  time,
  event,
  group = NULL,
  group_labels = NULL,
  just_km = FALSE,
  ...
)

Arguments

Value

A list containing Kaplan-Meier estimates, summary statistics, and plots.

Examples

km_results <- get_km(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  group = "group",
  risktable_symbols = FALSE
)

km_results

Extract Schoenfeld Residuals

Description

This function extracts Schoenfeld residuals from a fitted cox.zph object and formats them into a tidy data frame.

Usage

get_schoenfeld(fit_zph)

Arguments

Value

A tibble with the Schoenfeld residuals in long format, containing the columns:

Examples

library(survival)
test_fit <- survival::coxph(survival::Surv(time, status) ~ sex, data = lung)
test_fit_zph <- survival::cox.zph(test_fit)
get_schoenfeld(test_fit_zph)

Inspect Survival Data

Description

Quickly inspect the survival data to ensure it is in the correct format.

Usage

inspect_surv_data(data, time, event, group = NULL)

Arguments

Value

A list containing tibbles that summarise the first few rows of the survival data, the sample sizes, the events, and median survival.

Examples

inspect_surv_data(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  group = "group"
)

Plot method for fit_models

Description

Plot method for fit_models

Usage

## S3 method for class 'fit_models'
plot(
  x,
  eval_time = NULL,
  km_include = TRUE,
  subtitle_include = TRUE,
  add_plotly = FALSE,
  ...
)

Arguments

Value

A list containing predictions and plots for the survival and hazards of models in a fit_models object.

Examples

models <- fit_models(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  predict_by = "group",
  covariates = "group"
)

plot(models)

Cumulative Log Log Plot

Description

Generates a Cumulative Log Log survival curve plot using ggsurvfit::ggsurvfit() with customizable options.

Usage

plot_cloglog(
  fit,
  median_line = FALSE,
  legend_position = "top",
  plot_theme = theme_easysurv()
)

Arguments

Value

A ggplot object representing the cumulative log log plot.

Examples

library(ggsurvfit)
fit <- survfit2(Surv(time, status) ~ surg, data = df_colon)
plot_cloglog(fit)

Plot Kaplan-Meier Data

Description

Generates a Kaplan-Meier survival curve plot using ggsurvfit::ggsurvfit() with customizable options. This function provides sensible defaults while allowing for customization.

Usage

plot_km(
  fit,
  risktable = TRUE,
  risktable_symbols = TRUE,
  median_line = TRUE,
  legend_position = "top",
  plot_theme = theme_easysurv(),
  risktable_theme = theme_risktable_easysurv()
)

Arguments

Value

A ggplot object representing the Kaplan-Meier survival curve plot.

Examples

library(ggsurvfit)
fit <- survfit2(Surv(time, status) ~ surg, data = df_colon)
plot_km(fit, risktable_symbols = FALSE)

Plot Schoenfeld Residuals

Description

Plot the residuals generated by the get_schoenfeld function. This function creates a visual representation of Schoenfeld residuals from a Cox proportional hazards model. It allows for customization of the plot, including the addition of horizontal and smoothed lines, and styling of points and plot elements.

Usage

plot_schoenfeld(
  residuals,
  hline = TRUE,
  sline = TRUE,
  sline_se = TRUE,
  hline_col = "#F8766D",
  hline_size = 1,
  hline_alpha = 1,
  hline_yintercept = 0,
  hline_lty = "dashed",
  sline_col = "#00BFC4",
  sline_size = 1,
  sline_alpha = 0.2,
  sline_lty = "dashed",
  point_col = "black",
  point_size = 1,
  point_shape = 19,
  point_alpha = 1,
  plot_theme = ggplot2::theme_bw()
)

Arguments

Value

A ggplot object representing the plot of Schoenfeld residuals.

Examples

library(survival)
test_fit <- survival::coxph(survival::Surv(time, status) ~ sex, data = lung)
test_fit_zph <- survival::cox.zph(test_fit)
plot_schoenfeld(get_schoenfeld(test_fit_zph))

Predict method for fit_models

Description

Predict method for fit_models

Usage

## S3 method for class 'fit_models'
predict(object, eval_time = NULL, type = c("survival", "hazard"), ...)

Arguments

Value

A list of predictions for each model in the fit_models object.

Examples

models <- fit_models(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  predict_by = "group",
  covariates = "group"
)

predict(models)

Predict and Plot Fitted Models

Description

This function generates survival and hazard predictions and plots for each model in a fit_models object. Optionally, interactive plotly outputs can be added for each plot.

Usage

predict_and_plot(
  fit_models,
  eval_time = NULL,
  km_include = TRUE,
  subtitle_include = TRUE,
  add_plotly = FALSE
)

Arguments

Value

A list of predictions and plots for each model in the fit_models object.

Examples

models <- fit_models(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  predict_by = "group"
)

predict_and_plot(models)

Print methods for fit_models()

Description

Print methods for fit_models()

Usage

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

Arguments

Value

A print summary of the fit_models object.

Examples

models <- fit_models(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  predict_by = "group",
  covariates = "group"
)

models

Print methods for get_km()

Description

Print methods for get_km()

Usage

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

Arguments

Value

The summary of the Kaplan-Meier estimates, printed via the console.

Examples

km_results <- get_km(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  group = "group",
  risktable_symbols = FALSE
)

print(km_results)

Print methods for inspect_surv_data()

Description

Print methods for inspect_surv_data()

Usage

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

Arguments

Value

A print summary of the inspect_surv_data object.

Print methods for predict_and_plot()

Description

Print methods for predict_and_plot()

Usage

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

Arguments

Value

A print summary of the predict_and_plot object.

Examples

models <- fit_models(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  predict_by = "group"
)

predict_and_plot(models)

Print methods for test_ph()

Description

Print methods for test_ph()

Usage

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

Arguments

Value

A print summary of the test_ph object.

Examples

ph_results <- test_ph(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  group = "group"
)

ph_results

Launch Example Survival Analysis Script using the easy_lung Data Set

Description

This function launches an example script for starting survival analysis using the easysurv package. The script uses a modified version of the lung data set exported from the survival package. The code is inspired by usethis::use_template() but modified to work outside the context of an .RProj or package.

Usage

quick_start(output_file_name = NULL)

Arguments

Value

A new R script file with example code.

Examples

quick_start()

Launch Example Survival Analysis Script using the easy_bc Data Set

Description

This function launches an example script for starting survival analysis using the easysurv package. The script uses a modified version of the bc data set exported from the flexsurv package. The code is inspired by usethis::use_template() but modified to work outside the context of an .RProj or package.

Usage

quick_start2(output_file_name = NULL)

Arguments

Value

A new R script file with example code.

Examples

quick_start2()

Launch Example Survival Analysis Script using the easy_adtte Data Set

Description

This function launches an example script for starting survival analysis using the easysurv package. The script uses simulated phase III breast cancer trial data available from the ggsurvfit package. The code is inspired by usethis::use_template() but modified to work outside the context of an .RProj or package.

Usage

quick_start3(output_file_name = NULL)

Arguments

Value

A new R script file with example code.

Examples

quick_start3()

Test Proportional Hazards Assumption

Description

Assesses the proportional hazards assumption for survival data using a Cox proportional hazards model and related tests.

Usage

test_ph(data, time, event, group, plot_theme = theme_easysurv())

Arguments

Value

A list containing plots and test results related to the assessment of the proportional hazards assumption.

Examples

ph_results <- test_ph(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  group = "group"
)

ph_results

Plot Theme for easysurv Survival and Hazard Plots

Description

Plot Theme for easysurv Survival and Hazard Plots

Usage

theme_easysurv()

Value

A ggplot2 theme object.

Examples

library(ggsurvfit)
fit <- survfit2(Surv(time, status) ~ surg, data = df_colon)
fit |> ggsurvfit() + theme_easysurv()

Plot Theme for easysurv Risk Tables

Description

To be used with ggsurvfit::add_risktable().

Usage

theme_risktable_easysurv()

Value

A list containing a ggplot2 theme object.

Examples

library(ggsurvfit)
fit <- survfit2(Surv(time, status) ~ surg, data = df_colon)
fit <- fit |> ggsurvfit() +
  theme_easysurv() +
  add_risktable(theme = theme_risktable_easysurv())
fit

Export easysurv output to Excel via openxlsx

Description

Export easysurv output to Excel via openxlsx

Usage

write_to_xl(wb, object)

Arguments

Value

An Excel workbook with the easysurv output.

Examples

km_results <- get_km(
  data = easysurv::easy_bc,
  time = "recyrs",
  event = "censrec",
  group = "group",
  risktable_symbols = FALSE
)

wb <- openxlsx::createWorkbook()

## Not run: 
write_to_xl(wb, km_results)
openxlsx::saveWorkbook(wb, "km_results.xlsx", overwrite = TRUE)
openxlsx::openXL("km_results.xlsx")

## End(Not run)