Intuitive Survival Analysis with jiwillsurvive

Introduction

The jiwillsurvive() function in ClinicoPath provides an intuitive and comprehensive approach to survival analysis. This function combines ease of use with powerful features, making survival analysis accessible to clinicians while providing advanced options for researchers.

Key Features

Multiple Analysis Types: Survival models, Kaplan-Meier curves, follow-up visualization, and data preparation
Automatic Date Handling: Calculate follow-up times from start and end dates
Flexible Input: Multiple event variable formats (numeric, logical, factor)
Rich Visualizations: Customizable plots with multiple styles and color palettes
Clinical Interpretation: Automated interpretation of survival results
Statistical Tests: Built-in log-rank tests and survival comparisons

This vignette demonstrates all features of the jiwillsurvive function using comprehensive clinical datasets.

Loading Required Libraries and Data

library(ClinicoPath)

# Load the comprehensive test dataset
data("jiwillsurvive_test_data")

# Preview the data structure
str(jiwillsurvive_test_data)
head(jiwillsurvive_test_data)

Data Requirements

The jiwillsurvive function is designed to be flexible with various data formats:

Core Variables:

Time Variable: Numeric survival/follow-up time (required for survival analysis)
Event Variable: Event indicator (accepts numeric 0/1, logical TRUE/FALSE, or factor)
Grouping Variable: Optional categorical variable for group comparisons

Date-Based Variables (for automatic follow-up calculation):

Start Date Variable: Study start, enrollment, or treatment date
End Date Variable: Event date, last follow-up, or censoring date

Data Format Support:

Date variables can be Date objects or character strings
Event variables accept multiple formats automatically
No specific column naming requirements

Basic Survival Analysis

Simple Survival Model

# Basic survival analysis without grouping
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  show_risk_table = TRUE,
  show_statistics = TRUE,
  show_interpretation = TRUE
)

Survival Analysis with Group Comparison

# Survival analysis comparing treatment groups
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "treatment",
  show_risk_table = TRUE,
  show_median_survival = TRUE,
  show_statistics = TRUE
)

Kaplan-Meier Analysis

Classic Kaplan-Meier Curves

# Classic Kaplan-Meier analysis
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "kaplan_meier",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "treatment",
  confidence_level = 0.95,
  show_confidence_bands = TRUE,
  show_censoring_marks = TRUE
)

Multiple Grouping Variables

# Analysis by disease stage
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "kaplan_meier",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "stage",
  plot_title = "Survival by Disease Stage",
  x_label = "Time (months)",
  y_label = "Survival Probability"
)

Date-Based Follow-up Calculation

Data Preparation from Dates

# Prepare data by calculating follow-up from dates
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "data_prep",
  start_date_var = "enrollment_date",
  end_date_var = "last_contact_date",
  derive_followup = TRUE,
  followup_units = "months"
)

Different Time Units

# Calculate follow-up in different units
for(unit in c("days", "weeks", "months", "years")) {
  cat("\n=== Follow-up in", unit, "===\n")
  result <- jiwillsurvive(
    data = jiwillsurvive_test_data,
    analysis_type = "data_prep",
    start_date_var = "enrollment_date",
    end_date_var = "last_contact_date",
    derive_followup = TRUE,
    followup_units = unit
  )
}

Survival Analysis with Derived Follow-up

# Survival analysis using dates to derive follow-up time
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months", # This will be overridden by derived time
  event_var = "death_event",
  group_var = "treatment",
  start_date_var = "enrollment_date",
  end_date_var = "last_contact_date",
  derive_followup = TRUE,
  followup_units = "months",
  plot_title = "Survival Analysis Using Derived Follow-up Time"
)

Follow-up Visualization

Histogram of Follow-up Times

# Visualize distribution of follow-up times
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "followup_plot",
  time_var = "survival_months",
  followup_plot_type = "histogram",
  followup_units = "months"
)

Timeline Visualization

# Patient timeline visualization
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "followup_plot", 
  time_var = "survival_months",
  followup_plot_type = "timeline",
  followup_units = "months"
)

Summary Statistics Plot

# Summary statistics visualization
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "followup_plot",
  time_var = "survival_months", 
  followup_plot_type = "summary",
  followup_units = "months"
)

Advanced Customization Options

Plot Styles and Color Palettes

# Test different plot styles
plot_styles <- c("iwillsurvive", "classic", "modern", "minimal", "publication")

for(style in plot_styles) {
  cat("\n=== Plot Style:", style, "===\n")
  result <- jiwillsurvive(
    data = jiwillsurvive_test_data,
    analysis_type = "survival_model",
    time_var = "survival_months",
    event_var = "death_event",
    group_var = "treatment",
    plot_style = style,
    plot_title = paste("Survival Analysis -", tools::toTitleCase(style), "Style")
  )
}

Color Palette Options

# Test different color palettes
color_palettes <- c("default", "colorblind", "viridis", "set1", "dark2")

for(palette in color_palettes) {
  cat("\n=== Color Palette:", palette, "===\n")
  result <- jiwillsurvive(
    data = jiwillsurvive_test_data,
    analysis_type = "survival_model",
    time_var = "survival_months",
    event_var = "death_event",
    group_var = "treatment",
    color_palette = palette,
    plot_title = paste("Survival Analysis -", tools::toTitleCase(palette), "Palette")
  )
}

Custom Plot Labels and Breaks

# Customize plot appearance
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "treatment",
  plot_title = "Treatment Efficacy in Cancer Patients",
  x_label = "Time from Treatment Initiation (months)",
  y_label = "Overall Survival Probability",
  time_breaks = "0,6,12,18,24,30,36,42,48,54,60,66,72",
  legend_position = "bottom",
  show_median_survival = TRUE,
  show_confidence_bands = TRUE
)

Working with Different Event Variable Formats

Numeric Event Variables (0/1)

# Using numeric event variable
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event", # Numeric 0/1
  group_var = "treatment"
)

Logical Event Variables (TRUE/FALSE)

# Using logical event variable
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_logical", # Logical TRUE/FALSE
  group_var = "treatment"
)

Factor Event Variables

# Using factor event variable
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model", 
  time_var = "survival_months",
  event_var = "death_factor", # Factor with "Alive"/"Dead"
  group_var = "treatment"
)

Clinical Applications and Examples

Biomarker Analysis

# Survival analysis by biomarker status
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "biomarker_status",
  plot_title = "Survival by Biomarker Status",
  color_palette = "colorblind",
  show_statistics = TRUE,
  show_interpretation = TRUE
)

Risk Stratification

# Survival analysis by risk groups
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "risk_group",
  plot_title = "Survival by Risk Stratification",
  color_palette = "viridis",
  plot_style = "publication",
  show_median_survival = TRUE
)

Performance Status Analysis

# Create performance status groups for analysis
jiwillsurvive_test_data$ps_group <- factor(
  ifelse(jiwillsurvive_test_data$performance_status <= 1, "Good (0-1)", "Poor (2-3)"),
  levels = c("Good (0-1)", "Poor (2-3)")
)

jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "ps_group",
  plot_title = "Survival by Performance Status",
  x_label = "Time (months)",
  confidence_level = 0.90,
  show_confidence_bands = TRUE
)

Working with Edge Cases

Short Follow-up Data

# Load and analyze short follow-up dataset
data("jiwillsurvive_short_followup")

jiwillsurvive(
  data = jiwillsurvive_short_followup,
  analysis_type = "survival_model",
  time_var = "survival_days",
  event_var = "death_event",
  group_var = "treatment",
  followup_units = "days",
  plot_title = "Short-term Survival Analysis (Days)"
)

Long Follow-up Data

# Load and analyze long follow-up dataset
data("jiwillsurvive_long_followup")

jiwillsurvive(
  data = jiwillsurvive_long_followup,
  analysis_type = "survival_model",
  time_var = "survival_years",
  event_var = "death_event",
  group_var = "treatment",
  followup_units = "years",
  plot_title = "Long-term Survival Analysis (Years)"
)

Single Group Analysis

# Load and analyze single group dataset
data("jiwillsurvive_single_group")

jiwillsurvive(
  data = jiwillsurvive_single_group,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "event",
  plot_title = "Single Cohort Survival Analysis",
  show_median_survival = TRUE,
  show_interpretation = TRUE
)

Advanced Statistical Options

Custom Time Points for Summary

# Survival analysis with specific time points
jiwillsurvive(
  data = jiwillsurvive_test_data,
  analysis_type = "survival_model",
  time_var = "survival_months",
  event_var = "death_event",
  group_var = "treatment",
  time_points = "6,12,18,24,36,48,60",
  show_survival_table = TRUE,
  plot_title = "Survival with Custom Time Points"
)

Different Confidence Levels

# Test different confidence levels
confidence_levels <- c(0.80, 0.90, 0.95, 0.99)

for(conf in confidence_levels) {
  cat("\n=== Confidence Level:", conf*100, "% ===\n")
  result <- jiwillsurvive(
    data = jiwillsurvive_test_data,
    analysis_type = "survival_model",
    time_var = "survival_months",
    event_var = "death_event",
    group_var = "treatment",
    confidence_level = conf,
    show_confidence_bands = TRUE,
    plot_title = paste("Survival Analysis -", conf*100, "% CI")
  )
}

Working with Existing Package Datasets

Analysis with Colon Cancer Data

# Load and analyze colon cancer dataset
data("colon")

# Preview colon dataset
str(colon)

# Survival analysis of colon cancer data
jiwillsurvive(
  data = colon,
  analysis_type = "survival_model",
  time_var = "time",
  event_var = "status",
  group_var = "rx",
  plot_title = "Colon Cancer Survival by Treatment",
  x_label = "Time (days)",
  show_statistics = TRUE
)

Analysis with Melanoma Data

# Load and analyze melanoma dataset
data("melanoma")

# Preview melanoma dataset  
str(melanoma)

# Survival analysis of melanoma data
jiwillsurvive(
  data = melanoma,
  analysis_type = "survival_model",
  time_var = "time",
  event_var = "status", 
  group_var = "sex",
  plot_title = "Melanoma Survival by Sex",
  x_label = "Time (days)",
  color_palette = "set1"
)

Analysis with Basic Survival Data

# Load and analyze basic survival dataset
data("basic_survival_data")

# Preview dataset
str(basic_survival_data)

# Multiple analyses with different grouping variables
grouping_vars <- c("treatment", "stage", "sex")

for(var in grouping_vars) {
  cat("\n=== Analysis by", var, "===\n")
  result <- jiwillsurvive(
    data = basic_survival_data,
    analysis_type = "survival_model",
    time_var = "survival_months",
    event_var = "death_event",
    group_var = var,
    plot_title = paste("Survival by", tools::toTitleCase(var))
  )
}

Best Practices and Recommendations

Data Preparation Recommendations

Data Quality: Ensure no negative survival times
Missing Values: Handle missing data appropriately
Date Formats: Use consistent date formats
Event Coding: Use clear event coding (0/1, FALSE/TRUE, or descriptive factors)

Analysis Workflow

Start with Data Preparation: Use analysis_type = "data_prep" for date-based data
Explore Follow-up: Use analysis_type = "followup_plot" to understand data distribution
Main Analysis: Use analysis_type = "survival_model" or "kaplan_meier" for primary analysis
Interpretation: Enable show_interpretation = TRUE for clinical insights

Visualization Tips

Color Palettes: Use “colorblind” for presentations, “viridis” for publications
Plot Styles: Use “publication” for manuscripts, “modern” for presentations
Custom Labels: Always use descriptive titles and axis labels
Confidence Intervals: Show confidence bands for uncertainty visualization

Conclusion

The jiwillsurvive() function provides a comprehensive, user-friendly approach to survival analysis that accommodates various data formats and analytical needs. Its intuitive design makes survival analysis accessible while providing advanced features for sophisticated analyses.

Key Advantages:

Flexibility: Multiple input formats and analysis types
Automation: Automatic date handling and follow-up calculation
Visualization: Rich, customizable plots with clinical interpretation
Robustness: Handles edge cases and various data scenarios
Integration: Works seamlessly with existing ClinicoPath datasets

This function is particularly valuable for: - Clinical researchers conducting survival studies - Epidemiologists analyzing time-to-event data - Biostatisticians requiring flexible survival analysis tools - Clinicians seeking intuitive survival analysis capabilities

For additional resources and advanced examples, see the ClinicoPath documentation and other survival analysis vignettes in this package.

ClinicoPath Development Team

2025-07-13