Advanced TNM Stage Migration Analysis 1 — stagemigration1 • ClinicoPath

Usage

stagemigration1(
  data,
  oldStage = NULL,
  newStage = NULL,
  survivalTime = NULL,
  event = NULL,
  eventLevel,
  confidenceLevel = 0.95,
  calculateNRI = TRUE,
  nriTimePoints = "12, 24, 60",
  calculateIDI = TRUE,
  performROCAnalysis = TRUE,
  rocTimePoints = "12, 24, 36, 60",
  performDCA = FALSE,
  performCalibration = FALSE,
  institutionVariable = NULL,
  clinicalSignificanceThreshold = 0.02,
  nriClinicalThreshold = 0.2,
  performHomogeneityTests = FALSE,
  performTrendTests = FALSE,
  performLikelihoodTests = FALSE,
  calculatePseudoR2 = FALSE,
  showMigrationOverview = TRUE,
  showMigrationSummary = FALSE,
  showStageDistribution = FALSE,
  showMigrationMatrix = TRUE,
  showStatisticalComparison = TRUE,
  showConcordanceComparison = FALSE,
  showMigrationHeatmap = TRUE,
  showSankeyDiagram = FALSE,
  showROCComparison = TRUE,
  showCalibrationPlots = FALSE,
  showDecisionCurves = FALSE,
  showForestPlot = FALSE,
  showWillRogersAnalysis = FALSE,
  showWillRogersVisualization = FALSE,
  showMigrationSurvivalComparison = FALSE,
  showSurvivalCurves = TRUE,
  survivalPlotType = "separate",
  showConfidenceIntervals = FALSE,
  showRiskTables = FALSE,
  plotTimeRange = "auto",
  showClinicalInterpretation = FALSE,
  showStatisticalSummary = FALSE,
  showMethodologyNotes = FALSE,
  includeEffectSizes = FALSE,
  advancedMigrationAnalysis = FALSE,
  generateExecutiveSummary = FALSE,
  enableMultifactorialAnalysis = TRUE,
  showExplanations = FALSE
)

Arguments

data

The dataset containing staging and survival information for TNM validation analysis.

oldStage

📋 CLINICAL EXAMPLE: Select your current staging variable such as 'TNM7_Stage' containing values like: Stage I, Stage IIA, Stage IIB, Stage IIIA, Stage IIIB, Stage IV. 🔍 TECHNICAL DETAILS: The original staging variable (e.g., TNM 7th edition, AJCC 7th edition). Should be coded as ordered factor with appropriate stage levels for meaningful comparison.

newStage

📋 CLINICAL EXAMPLE: Select your new staging variable such as 'TNM8_Stage' containing the same patients but potentially different stage assignments based on revised criteria (e.g., T descriptor changes, nodal assessment updates). 🔍 TECHNICAL DETAILS: The proposed new staging variable (e.g., TNM 8th edition, revised staging). Should use the same coding structure as the original staging system for valid comparison.

survivalTime

📋 CLINICAL EXAMPLE: Select your follow-up time variable such as 'OS_months' containing values like: 12.5, 24.8, 36.2, 45.0 (months from diagnosis to death or last contact). 🔍 TECHNICAL DETAILS: Time to event or censoring in consistent units (months recommended). For overall survival analysis, use time from diagnosis to death or last follow-up. For disease-free survival, use time from treatment to recurrence or last follow-up.

event

📋 CLINICAL EXAMPLE: Select your event variable such as 'Death_Status' containing values like: 0 (alive/censored), 1 (dead/event occurred) OR "Alive", "Dead" OR "No Event", "Death", "Disease Progression". 🔍 TECHNICAL DETAILS: Event indicator (1 = event occurred, 0 = censored) or factor with event levels. For overall survival, event = death from any cause. For disease-specific survival, event = death from the specific disease being studied.

eventLevel

The level indicating event occurrence when using factor variables.

confidenceLevel

Confidence level for all confidence intervals and hypothesis tests.

calculateNRI

Calculate Net Reclassification Improvement to quantify improvement in risk classification between staging systems. Essential for staging validation.

nriTimePoints

Comma-separated time points for NRI calculation (e.g., "12, 24, 60" for 1, 2, and 5-year survival). Use clinically relevant time points.

calculateIDI

Calculate Integrated Discrimination Improvement to measure improvement in risk prediction accuracy between staging systems.

performROCAnalysis

Perform time-dependent ROC analysis to compare discriminative ability of staging systems over time.

rocTimePoints

Time points for ROC analysis. Should include clinically important survival milestones for the specific cancer type.

performDCA

Perform Decision Curve Analysis to assess clinical utility and net benefit of the new staging system for clinical decision making.

performCalibration

Assess calibration of risk predictions from both staging systems. Important for validating accuracy of survival predictions.

institutionVariable

Optional variable indicating institution or study center for multi-institutional validation. When provided, performs internal-external cross-validation using k-1 centers for development and remaining center for validation. Essential for multi-center staging validation studies.

clinicalSignificanceThreshold

Minimum improvement in C-index considered clinically significant. Default 0.02 based on oncology literature recommendations.

nriClinicalThreshold

Minimum NRI improvement considered clinically meaningful. Default 0.20 (20\

performHomogeneityTestsTest homogeneity within stages and monotonic trend across stages. Essential for validating stage ordering and grouping.

performTrendTestsTest for monotonic trend in survival across stage levels. Validates that higher stages consistently have worse prognosis.

performLikelihoodTestsPerform formal likelihood ratio tests comparing nested staging models. Provides statistical significance testing for staging improvement.

calculatePseudoR2Calculate multiple pseudo R-squared measures for model comparison (Nagelkerke, McFadden, Cox-Snell).

showMigrationOverviewDisplay overview table showing the fundamental migration statistics including: total number of patients, number and percentage of patients who migrated stages, direction of migration (upstaged vs downstaged), and net migration effect. This is the essential first table for understanding the overall impact of the new staging system.

showMigrationSummaryDisplay statistical summary of migration patterns including overall migration rate and formal statistical tests. Shows Chi-square test results for independence and Fisher's exact test p-values to determine if the migration patterns are statistically significant. Essential for validating whether observed changes are due to genuine staging improvements or random variation.

showStageDistributionDisplay side-by-side comparison of how patients are distributed across stages in both the original and new staging systems. Shows the count and percentage of patients in each stage, along with the net change. This helps identify which stages are gaining or losing patients and whether the new system creates better separation between prognostic groups.

showMigrationMatrixDisplay detailed cross-tabulation matrix showing exactly how patients moved between stages. Rows represent the original staging system and columns represent the new staging system. Diagonal values indicate patients who remained in the same stage, while off-diagonal values show stage migrations. This is essential for understanding the specific migration patterns and identifying which stages are most affected by the new criteria.

showStatisticalComparisonDisplay table with C-index comparisons and other statistical metrics.

showConcordanceComparisonDisplay detailed concordance comparison between staging systems.

showMigrationHeatmapDisplay a color-coded heatmap visualization of the migration matrix. Darker colors indicate more patients, with the diagonal showing patients who remained in the same stage. This visual representation makes it easy to identify migration patterns at a glance - upstaging appears above the diagonal, downstaging below. Essential for presentations and publications.

showSankeyDiagramDisplay a Sankey flow diagram showing patient migration patterns between original and new staging systems. Flow thickness represents the number of patients moving between stages, making it easy to visualize dominant migration patterns. Excellent for presentations and understanding the overall reclassification impact.

showROCComparisonDisplay time-dependent ROC curves comparing staging systems.

showCalibrationPlotsDisplay calibration plots for both staging systems.

showDecisionCurvesDisplay decision curves showing net benefit of staging systems.

showForestPlotDisplay forest plot with stage-specific hazard ratios and confidence intervals.

showWillRogersAnalysisDetailed analysis of Will Rogers phenomenon with survival comparisons between migrated and non-migrated patients within stages.

showWillRogersVisualizationDisplay visualization showing how stage migration affects survival within each stage. Shows before/after survival curves demonstrating the Will Rogers paradox where both stages appear to improve.

showMigrationSurvivalComparisonDisplay Kaplan-Meier survival curves comparing the same stages before and after patient migration. Shows how survival curves change when patients are reclassified between staging systems, providing visual evidence of the Will Rogers phenomenon and staging system improvements.

showSurvivalCurvesDisplay survival curves comparing the staging systems.

survivalPlotTypeControls display of survival curves for staging system comparison.

showConfidenceIntervalsDisplay confidence intervals around survival curves and other estimates.

showRiskTablesDisplay at-risk tables below survival curves.

plotTimeRangeMaximum time for survival plots. Use "auto" for automatic range or specify maximum months (e.g., "60" for 5-year follow-up).

showClinicalInterpretationDisplay comprehensive clinical interpretation of all statistical results with guidance for staging system adoption decisions.

showStatisticalSummaryDisplay comprehensive table summarizing all statistical comparisons.

showMethodologyNotesDisplay detailed notes on statistical methods used and their interpretation.

includeEffectSizesCalculate and display effect sizes for all comparisons to assess practical significance beyond statistical significance.

advancedMigrationAnalysisPerform comprehensive stage migration analysis including monotonicity checks, Will Rogers phenomenon detection, stage-specific validation, and enhanced discrimination metrics. Provides detailed assessment of staging system quality and migration patterns.

generateExecutiveSummaryGenerate executive summary with key findings and recommendations for clinical and research stakeholders.

enableMultifactorialAnalysis.

showExplanationsInclude detailed explanations for results.

A results object containing:

`results$welcomeMessage`					a html
`results$copyReadyReport`					a html
`results$guidedModeProgress`					a html
`results$mydataview`					a preformatted
`results$mydataview2`					a preformatted
`results$migrationOverviewExplanation`					a html
`results$migrationOverview`					a table
`results$migrationMatrixExplanation`					a html
`results$migrationMatrix`					a table
`results$stageDistributionExplanation`					a html
`results$stageDistribution`					a table
`results$migrationSummaryExplanation`					a html
`results$migrationSummary`					a table
`results$statisticalComparisonExplanation`					a html
`results$statisticalComparison`					a table
`results$concordanceComparisonExplanation`					a html
`results$concordanceComparison`					a table
`results$nriResultsExplanation`					a html
`results$nriResults`					a table
`results$idiResultsExplanation`					a html
`results$idiResults`					a table
`results$multifactorialAnalysisExplanation`					a html
`results$multifactorialResults`					a table
`results$multifactorialResultsExplanation`					a html
`results$adjustedCIndexComparison`					a table
`results$adjustedCIndexComparisonExplanation`					a html
`results$nestedModelTests`					a table
`results$nestedModelTestsExplanation`					a html
`results$stepwiseResults`					a table
`results$stepwiseResultsExplanation`					a html
`results$interactionTests`					a table
`results$interactionTestsExplanation`					a html
`results$stratifiedAnalysis`					a table
`results$stratifiedAnalysisExplanation`					a html
`results$rocAnalysis`					a table
`results$integratedAUCAnalysis`					a table
`results$dcaResultsExplanation`					a html
`results$dcaResults`					a table
`results$pseudoR2ResultsExplanation`					a html
`results$pseudoR2Results`					a table
`results$decisionCurvesExplanation`					a html
`results$decisionCurves`					an image
`results$bootstrapResults`					a table
`results$bootstrapValidationExplanation`					a html
`results$willRogersAnalysisExplanation`					a html
`results$willRogersBasicAnalysis`					a table
`results$likelihoodTestsExplanation`					a html
`results$likelihoodTests`					a table
`results$linearTrendTestExplanation`					a html
`results$linearTrendTest`					a table
`results$homogeneityTestsExplanation`					a html
`results$homogeneityTests`					a table
`results$trendTestsExplanation`					a html
`results$trendTests`					a table
`results$clinicalInterpretationExplanation`					a html
`results$clinicalInterpretation`					a table
`results$executiveSummaryExplanation`					a html
`results$executiveSummary`					a table
`results$statisticalSummaryExplanation`					a html
`results$statisticalSummary`					a table
`results$effectSizesExplanation`					a html
`results$effectSizes`					a table
`results$methodologyNotes`					a html
`results$migrationHeatmapExplanation`					a html
`results$migrationHeatmap`					an image
`results$sankeyDiagram`					an image
`results$rocComparisonExplanation`					a html
`results$rocComparisonPlot`					an image
`results$forestPlotExplanation`					a html
`results$forestPlot`					an image
`results$calibrationAnalysisExplanation`					a html
`results$calibrationAnalysis`					a table
`results$calibrationPlotsExplanation`					a html
`results$calibrationPlots`					an image
`results$advancedMigrationExplanation`					a html
`results$monotonicityCheck`					a table
`results$willRogersAnalysis`					a table
`results$willRogersVisualization`					an image
`results$migrationSurvivalComparison`					an image
`results$willRogersEnhancedAnalysis`					a table
`results$willRogersStageDetail`					a table
`results$stageSpecificCIndex`					a table
`results$enhancedPseudoR2`					a table
`results$enhancedReclassificationMetrics`					a table
`results$proportionalHazardsTest`					a table
`results$decisionCurveAnalysis`					a table
`results$survivalCurvesExplanation`					a html
`results$survivalCurves`					an image
`results$dashboardExplanation`					a html
`results$comparativeAnalysisDashboard`					a table
`results$willRogersEvidenceSummaryExplanation`					a html
`results$willRogersEvidenceSummary`					a table
`results$willRogersClinicalRecommendation`					a table
`results$enhancedMigrationPatternAnalysis`					a table
`results$landmarkAnalysisResults`					a table
`results$advancedMigrationHeatmapStats`					a table
`results$abbreviationGlossary`					a html
`results$crossValidationExplanation`					a html
`results$crossValidationResults`					a table
`results$crossValidationPlot`					an image
`results$enhancedLRComparison`					a table

Tables can be converted to data frames with asDF or as.data.frame. For example:results$migrationOverview$asDFas.data.frame(results$migrationOverview) Comprehensive analysis for validating TNM staging system improvements using state-of-the-art statistical methods. This analysis provides pathologists with robust tools to evaluate whether a new staging system provides superior prognostic discrimination compared to existing systems. Includes advanced metrics: Net Reclassification Improvement (NRI), Integrated Discrimination Improvement (IDI), time-dependent ROC analysis, decision curve analysis, bootstrap validation, and comprehensive clinical interpretation guidance.