Performs univariate survival analysis comparing survival between groups. This analysis calculates person-time follow-up for each group and uses this to derive accurate survival estimates and incidence rates that account for varying follow-up durations across groups. The Cox proportional hazards model incorporates person-time by modeling the hazard function, which represents the instantaneous event rate per unit of person-time.
Usage
survival(
data,
elapsedtime,
tint = FALSE,
dxdate,
fudate,
explanatory,
outcome,
outcomeLevel,
dod,
dooc,
awd,
awod,
analysistype = "overall",
cutp = "12, 36, 60",
timetypedata = "ymd",
timetypeoutput = "months",
uselandmark = FALSE,
landmark = 3,
pw = FALSE,
padjustmethod = "holm",
ph_cox = FALSE,
sc = FALSE,
kmunicate = FALSE,
ce = FALSE,
ch = FALSE,
endplot = 60,
ybegin_plot = 0,
yend_plot = 1,
byplot = 12,
multievent = FALSE,
ci95 = FALSE,
risktable = FALSE,
censored = FALSE,
pplot = FALSE,
medianline = "none",
person_time = FALSE,
time_intervals = "12, 36, 60",
rate_multiplier = 100,
rmst_analysis = FALSE,
rmst_tau = 0,
stratified_cox = FALSE,
strata_variable,
residual_diagnostics = FALSE,
loglog = FALSE,
showExplanations = FALSE,
showSummaries = FALSE,
use_parametric = FALSE,
parametric_distribution = "weibull",
parametric_covariates = TRUE,
spline_knots = 3,
spline_scale = "hazard",
parametric_extrapolation = FALSE,
extrapolation_time = 0,
parametric_diagnostics = TRUE,
compare_distributions = FALSE,
parametric_survival_plots = FALSE,
hazard_plots = FALSE
)Arguments
- data
The data as a data frame.
- elapsedtime
The time elapsed from the start of the study to the event or censoring.
- tint
If the time is in date format, select this option to calculate the survival time. The time will be calculated as the difference between the event date and the diagnosis date. If the follow-up date is available, the time will be calculated as the difference between the event date and the follow-up date.
- dxdate
The date of diagnosis. Accepts: (1) Date/datetime text formats (e.g., "2024-01-15"), (2) Numeric Unix epoch seconds (from DateTime Converter's corrected_datetime_numeric output), (3) Numeric datetime values from R. Time intervals will be automatically calculated as the difference between follow-up/event date and diagnosis date.
- fudate
The date of follow-up or event. Accepts: (1) Date/datetime text formats (e.g., "2024-01-15"), (2) Numeric Unix epoch seconds (from DateTime Converter's corrected_datetime_numeric output), (3) Numeric datetime values from R. Must be in the same format as diagnosis date. Time intervals calculated as difference from diagnosis date.
- explanatory
The explanatory variable that will be used to compare the survival times of different groups.
- outcome
The outcome variable that will be used to compare the survival times of different groups.
- outcomeLevel
The level of the outcome variable that will be used as the event level.
- dod
.
- dooc
.
- awd
.
- awod
.
- analysistype
.
- cutp
.
- timetypedata
select the time type in data
- timetypeoutput
select the time type in output
- uselandmark
.
- landmark
.
- pw
.
- padjustmethod
.
- ph_cox
.
- sc
.
- kmunicate
.
- ce
.
- ch
.
- endplot
.
- ybegin_plot
.
- yend_plot
.
- byplot
.
- multievent
.
- ci95
.
- risktable
.
- censored
.
- pplot
.
- medianline
If true, displays a line indicating the median survival time on the survival plot.
- person_time
Enable this option to calculate and display person-time metrics, including total follow-up time and incidence rates. These metrics help quantify the rate of events per unit of time in your study population.
- time_intervals
Specify time intervals for stratified person-time analysis. Enter a comma-separated list of time points to create intervals. For example, "12, 36, 60" will create intervals 0-12, 12-36, 36-60, and 60+.
- rate_multiplier
Specify the multiplier for incidence rates (e.g., 100 for rates per 100 person-years, 1000 for rates per 1000 person-years).
- rmst_analysis
Calculate Restricted Mean Survival Time, which represents the average survival time up to a specified time horizon. Useful when median survival cannot be estimated or for comparing survival over a specific time period.
- rmst_tau
Time horizon for RMST calculation. If 0 or not specified, uses the 75th percentile of follow-up time. Should be specified in the same units as the survival time.
- stratified_cox
Perform stratified Cox regression to account for non-proportional hazards or unmeasured confounders that affect baseline hazard.
- strata_variable
Variable to use for stratification in Cox regression. This variable should represent groups with different baseline hazards.
- residual_diagnostics
Calculate and display Cox model residuals for diagnostic purposes, including Martingale, deviance, score, and Schoenfeld residuals.
- loglog
Display log-log survival plot for visual assessment of proportional hazards assumption. Parallel lines suggest proportional hazards.
- showExplanations
Display detailed explanations for each analysis component to help interpret the statistical methods and results.
- showSummaries
Display natural language summaries alongside tables and plots. These summaries provide plain-language interpretations of the statistical results. Turn off to reduce visual clutter when summaries are not needed.
- use_parametric
Enable parametric survival modeling using flexsurv package. Provides alternative to Cox regression with explicit hazard functions and extrapolation capabilities beyond observed follow-up.
- parametric_distribution
Choose parametric distribution for survival modeling. Weibull is most common, while splines provide flexible hazard shapes. Different distributions make different assumptions about hazard function shape.
- parametric_covariates
Include explanatory variables as covariates in parametric models, similar to Cox regression but with parametric baseline hazard.
- spline_knots
Number of knots for spline-based models. More knots allow more flexible hazard shapes but may lead to overfitting. Used only for Royston-Parmar splines.
- spline_scale
Scale for spline-based models. Hazard scale models log hazard function, odds scale models log cumulative odds, normal scale models normal scores.
- parametric_extrapolation
Perform survival extrapolation beyond observed follow-up time using fitted parametric models. Useful for health economic modeling and long-term prognosis assessment.
- extrapolation_time
Maximum time for survival extrapolation (in same units as survival time). If 0, uses 2x maximum observed time. Use with caution as extrapolation relies on distributional assumptions.
- parametric_diagnostics
Display model diagnostics including AIC/BIC for model comparison, residual plots, and goodness-of-fit statistics for parametric models.
- compare_distributions
Fit and compare multiple parametric distributions using AIC/BIC criteria. Helps select the best-fitting distribution for your data.
- parametric_survival_plots
Generate survival curves from fitted parametric models with confidence intervals. Compare with Kaplan-Meier estimates for model validation.
- hazard_plots
Plot estimated hazard functions from parametric models. Shows how instantaneous risk changes over time for different distributions.
Value
A results object containing:
results$subtitle | a preformatted | ||||
results$todo | a html | ||||
results$medianSurvivalHeading | a preformatted | ||||
results$medianSummary | a preformatted | ||||
results$medianTable | a table | ||||
results$medianSurvivalHeading3 | a preformatted | ||||
results$medianSurvivalExplanation | a html | ||||
results$coxRegressionHeading | a preformatted | ||||
results$coxSummary | a preformatted | ||||
results$coxTable | a table | ||||
results$tCoxtext2 | a html | ||||
results$coxRegressionHeading3 | a preformatted | ||||
results$coxRegressionExplanation | a html | ||||
results$cox_ph | a preformatted | ||||
results$plot8 | an image | ||||
results$survivalTablesHeading | a preformatted | ||||
results$survTableSummary | a preformatted | ||||
results$survTable | a table | ||||
results$survivalTablesHeading3 | a preformatted | ||||
results$survivalTablesExplanation | a html | ||||
results$personTimeHeading | a preformatted | ||||
results$personTimeTable | a table | ||||
results$personTimeSummary | a html | ||||
results$personTimeExplanation | a html | ||||
results$rmstHeading | a preformatted | ||||
results$rmstTable | a table | ||||
results$rmstSummary | a preformatted | ||||
results$rmstExplanation | a html | ||||
results$residualDiagnosticsExplanation | a html | ||||
results$residualsTable | a table | ||||
results$survivalExport | an output | ||||
results$survivalExportSummary | a html | ||||
results$pairwiseComparisonHeading | a preformatted | ||||
results$pairwiseTable | a table | ||||
results$pairwiseSummary | a preformatted | ||||
results$plot | an image | ||||
results$plot2 | an image | ||||
results$plot3 | an image | ||||
results$plot6 | an image | ||||
results$survivalPlotsHeading3 | a preformatted | ||||
results$survivalPlotsExplanation | a html | ||||
results$plot7 | an image | ||||
results$residualsPlot | an image | ||||
results$calculatedtime | an output | ||||
results$outcomeredefined | an output | ||||
results$parametricModelComparison | a table | ||||
results$parametricModelSummary | a table | ||||
results$parametricDiagnostics | a html | ||||
results$parametricSurvivalPlot | an image | ||||
results$hazardFunctionPlot | an image | ||||
results$extrapolationPlot | an image | ||||
results$extrapolationTable | a table | ||||
results$parametricModelsExplanation | a html | ||||
results$clinicalGlossaryExplanation | a html | ||||
results$clinicalInterpretationExplanation | a html | ||||
results$copyReadySentencesExplanation | a html |
Tables can be converted to data frames with asDF or as.data.frame. For example:
results$medianTable$asDF
as.data.frame(results$medianTable)