Stage Migration Analysis

Analyzes staging system changes and the "Will Rogers Phenomenon" in disease staging. This analysis compares staging distributions before and after a staging system change, quantifies stage migration, and evaluates changes in prognostic performance.

Usage

stagemigration(
  data,
  oldStage,
  newStage,
  survivalTime,
  event,
  eventLevel,
  plotMigration = TRUE,
  survivalPlotType = "separate",
  showCI = FALSE,
  showWillRogers = TRUE
)

Arguments

data

The dataset containing staging and survival information.

oldStage

The original staging variable. This represents the staging system used before the revision or change (e.g., TNM 7th edition).

newStage

The new staging variable. This represents the revised or changed staging system (e.g., TNM 8th edition).

survivalTime

The survival or follow-up time variable. This should be a numeric variable representing time in consistent units (e.g., months).

event

The event indicator variable. This can be a factor or numeric variable indicating whether the event of interest (e.g., death) occurred.

eventLevel

The level of the event variable that indicates the event occurred. This is required if the event variable is a factor.

plotMigration

Enable to display an alluvial/Sankey plot visualizing stage migration patterns. This plot shows how patients move between stages in the old and new systems.

survivalPlotType

Controls how survival curves are displayed for comparing staging systems. "Separate" shows full KM plots for each system, while "Side by side" focuses on direct stage comparisons.

showCI

Enable to display 95\ curves.

showWillRogers

Enable to perform detailed analysis of the Will Rogers phenomenon. This will compare survival within stages between patients who migrated and those who didn't.

Value

A results object containing:

results$todo					a html
results$migrationSummary					a table
results$stageDistribution					a table
results$migrationTable					a table
results$survivalComparison					a table
results$stagingPerformance					a table
results$migrationPlot					an image
results$survivalPlot					an image
results$concordancePlot					an image

Tables can be converted to data frames with asDF or as.data.frame. For example:

results$migrationSummary$asDF

as.data.frame(results$migrationSummary)

Examples

# \donttest{
# Example analyzing migration between TNM staging editions:
# stagemigration(
#   data = patient_data,
#   oldStage = "tnm7_stage",
#   newStage = "tnm8_stage",
#   survivalTime = "follow_up_months",
#   event = "death_status",
#   eventLevel = "Dead"
# )
# }