Cross Table for Clinicopathological Comparisons — .escapeVariableNames • ClinicoPath

This function generates cross tables comparing a dependent variable (rows) with a grouping variable (columns) and automatically selects hypothesis tests appropriate for clinical research. The output tables are rendered in various styles (e.g., arsenal, finalfit, gtsummary, NEJM, Lancet, hmisc) and are intended for pathologists and oncologists. In addition to visualizing associations, this function now optionally provides an exportable CSV version of the cross table.

Performs comprehensive univariate and stratified 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.

Key Features:

Kaplan-Meier survival curves with multiple plot types
Cox proportional hazards regression (univariate and stratified)
Median survival time with confidence intervals
Restricted Mean Survival Time (RMST) analysis
Person-time analysis with incidence rates
Competing risks and cause-specific survival
Landmark analysis for conditional survival
Proportional hazards assumption testing
Model residual diagnostics
Pairwise group comparisons with multiple testing correction

Statistical Methods:

Kaplan-Meier estimator for survival probabilities
Log-rank test for group comparisons
Cox proportional hazards model for risk assessment
Competing risks analysis using cumulative incidence functions
RMST for robust survival comparisons

Visualization Options:

Standard survival curves
Cumulative events and hazard plots
KMunicate-style plots for publication
Log-log plots for proportional hazards assessment
Residual diagnostic plots

Generates a Venn Diagram and an Upset diagram from selected categorical variables. This function converts specified variables to logical values based on a chosen "true" level. Two visual outputs are produced: a Venn diagram (via ggvenn) and an Upset plot (via UpSetR or ComplexUpset). Additionally, a summary table of "true" counts for each variable is provided.

ComplexUpset features include advanced styling, statistical annotations, custom sorting, and enhanced theming options for publication-ready figures.

Usage

.escapeVariableNames(var_names)

.escapeVariableNames(var_names)

.escapeVariableNames(var_names)

.escapeVariableNames(var_names)

.escapeVariableNames(var_names)

Arguments

vars: A set of variables used as the dependent variables (rows).
group: A variable (factor) used as the grouping variable (columns).
sty: A string indicating the desired table style. Options include: "arsenal", "finalfit", "gtsummary", "nejm", "lancet", "hmisc".
excl: Logical. If TRUE, rows with missing values will be excluded.
cont: A string ("mean" or "median") to specify the central tendency metric.
pcat: A string ("chisq" or "fisher") to specify the primary test.
data: The data as a data frame
elapsedtime: Numeric variable containing survival time (time to event or censoring)
tint: Logical. Use dates to calculate survival time from diagnosis and follow-up dates
dxdate: Date variable for diagnosis date (when tint = TRUE)
fudate: Date variable for follow-up/event date (when tint = TRUE)
explanatory: Factor variable for group comparisons (e.g., treatment groups, risk categories)
outcome: Event indicator variable (binary: 0=censored, 1=event) or factor for multi-state outcomes
outcomeLevel: Event level when using factor outcome variable
dod: Dead of disease level (for competing risks analysis)
dooc: Dead of other causes level (for competing risks analysis)
awd: Alive with disease level (for competing risks analysis)
awod: Alive without disease level (for competing risks analysis)
analysistype: Type of survival analysis: "overall", "cause", or "compete"
cutp: Time points for survival probability estimation (comma-separated)
timetypedata: Date format in data: "ymd", "dmy", "mdy", etc.
timetypeoutput: Time unit for output: "days", "weeks", "months", "years"
uselandmark: Logical. Perform landmark analysis
landmark: Landmark time point for conditional survival analysis
pw: Logical. Perform pairwise group comparisons
padjustmethod: Multiple testing correction method for pairwise comparisons
ph_cox: Logical. Test proportional hazards assumption
stratified_cox: Logical. Use stratified Cox regression
strata_variable: Variable for Cox model stratification
rmst_analysis: Logical. Calculate Restricted Mean Survival Time
rmst_tau: Time horizon for RMST calculation (uses 75th percentile if NULL)
residual_diagnostics: Logical. Calculate and display model residuals
export_survival_data: Logical. Export survival estimates for external analysis
person_time: Logical. Calculate person-time metrics and incidence rates
time_intervals: Time intervals for stratified person-time analysis
rate_multiplier: Multiplier for incidence rates (e.g., 100 for per 100 person-years)
sc: Logical. Display survival curve plot
ce: Logical. Display cumulative events plot
ch: Logical. Display cumulative hazard plot
kmunicate: Logical. Display KMunicate-style plot
loglog: Logical. Display log-log plot for proportional hazards assessment
endplot: Maximum time for plot x-axis
ybegin_plot: Minimum value for plot y-axis
yend_plot: Maximum value for plot y-axis
byplot: Time interval for plot axis breaks
multievent: Logical. Use multiple event levels for competing risks
ci95: Logical. Display 95% confidence intervals on plots
risktable: Logical. Display risk table below survival curves
censored: Logical. Display censoring marks on survival curves
pplot: Logical. Display p-value on plots
medianline: Type of median survival line: "none", "h", "v", "hv"

Value

The function produces an HTML table output, and if requested, an additional downloadable CSV export.

A comprehensive results object containing survival analysis outputs

The function produces a Venn diagram and an Upset diagram.

Details

The function cleans variable names and applies original labels. It then builds a formula based on the cleaned data and performs the appropriate statistical test (e.g. chi-square or Fisher’s exact test). Detailed user guidance is provided via HTML to-do messages.

Analysis Types:

Overall Survival: Time from study entry to death from any cause
Cause-Specific Survival: Time to death from specific cause (censoring other deaths)
Competing Risks: Accounts for multiple types of events that prevent observation of the primary outcome

Person-Time Analysis: Calculates incidence rates accounting for varying follow-up times. Particularly useful for:

Studies with differential loss to follow-up
Comparison of event rates across populations
Assessment of time-varying risk

Restricted Mean Survival Time (RMST): Alternative to median survival when survival curves don't reach 50% or for comparing survival over a specific time horizon. Represents the area under the survival curve up to a specified time point.

Model Diagnostics:

Proportional hazards assumption testing using Schoenfeld residuals
Martingale and deviance residuals for outlier detection
Log-log plots for visual assessment of proportional hazards

References

Klein JP, Moeschberger ML (2003). Survival Analysis: Techniques for Censored and Truncated Data. Springer.

Therneau TM, Grambsch PM (2000). Modeling Survival Data: Extending the Cox Model. Springer.

Royston P, Parmar MK (2013). Restricted mean survival time: an alternative to the hazard ratio for the design and analysis of randomized trials with a time-to-event outcome. BMC Medical Research Methodology 13:152.

Examples

# \donttest{
# Basic survival analysis
data("histopathologySurvival", package = "ClinicoPathJamoviModule")

# Standard survival analysis with median and survival probabilities
survival_result <- survival(
  data = histopathologySurvival,
  elapsedtime = "OverallSurvival_indays",
  outcome = "Outcome",
  outcomeLevel = "Dead",
  explanatory = "Grade",
  timetypeoutput = "months",
  cutp = "12, 36, 60",
  sc = TRUE,
  pw = TRUE
)

# Survival analysis with person-time metrics
survival_with_pt <- survival(
  data = histopathologySurvival,
  elapsedtime = "OverallSurvival_indays", 
  outcome = "Outcome",
  outcomeLevel = "Dead",
  explanatory = "Stage",
  person_time = TRUE,
  time_intervals = "365, 1095, 1825",
  rate_multiplier = 1000
)

# RMST analysis for non-proportional hazards
rmst_analysis <- survival(
  data = histopathologySurvival,
  elapsedtime = "OverallSurvival_indays",
  outcome = "Outcome", 
  outcomeLevel = "Dead",
  explanatory = "Treatment",
  rmst_analysis = TRUE,
  rmst_tau = 1095  # 3 years
)

# Competing risks analysis
competing_risks <- survival(
  data = cancer_data,
  elapsedtime = "survival_days",
  outcome = "death_cause",
  multievent = TRUE,
  dod = "Cancer",
  dooc = "Other",
  awd = "Alive_Disease",
  awod = "Alive_Free",
  analysistype = "compete",
  explanatory = "risk_group"
)

# Landmark analysis for conditional survival
landmark_survival <- survival(
  data = histopathologySurvival,
  elapsedtime = "OverallSurvival_indays",
  outcome = "Outcome",
  outcomeLevel = "Dead", 
  explanatory = "Grade",
  uselandmark = TRUE,
  landmark = 365  # 1-year conditional survival
)

# Date-based survival calculation
date_survival <- survival(
  data = clinical_data,
  tint = TRUE,
  dxdate = "diagnosis_date",
  fudate = "last_contact_date",
  timetypedata = "ymd",
  timetypeoutput = "months",
  outcome = "vital_status",
  outcomeLevel = "Dead",
  explanatory = "treatment_arm"
)
# }