Treatment Response Analysis

Usage

waterfall(
  data,
  patientID,
  responseVar,
  timeVar = NULL,
  groupVar = NULL,
  inputType = "percentage",
  sortBy = "response",
  showThresholds = TRUE,
  labelOutliers = FALSE,
  showMedian = FALSE,
  showCI = FALSE,
  minResponseForLabel = 50,
  colorBy = "recist",
  colorScheme = "jamovi",
  barAlpha = 1,
  barWidth = 0.7,
  showWaterfallPlot = TRUE,
  showSpiderPlot = TRUE,
  spiderColorBy = "response",
  spiderColorScheme = "classic",
  timeUnitLabel = "generic",
  generateCopyReadyReport = FALSE,
  showClinicalSignificance = FALSE,
  showConfidenceIntervals = TRUE,
  enableGuidedMode = FALSE
)

Arguments

data

The data as a data frame.

patientID

Variable containing patient identifiers (e.g., PT001, Patient_1, Study_ID). Each patient should have a unique identifier for proper analysis.

responseVar

Response variable: either raw tumor measurements (mm, cm, sum of diameters) or pre-calculated percentage changes from baseline. For raw measurements: requires time variable with baseline at time = 0. For percentages: negative values = tumor shrinkage (good response), positive values = tumor growth (poor response). Example: -30 means 30\

timeVarTime point of measurement (e.g., months from baseline, days from treatment start). Required for spider plot and raw measurement processing. Baseline should be time = 0.

groupVarOptional grouping variable for coloring bars by patient groups (e.g., treatment arms, disease subtypes). When specified, overrides RECIST category coloring to show group-based colors.

inputTypeSpecify data format: 'raw' for actual tumor measurements (requires time variable) or 'percentage' for pre-calculated percentage changes from baseline

sortBySort the waterfall plot by best response or patient ID.

showThresholdsShow +20\ lines. Helps identify Progressive Disease (PD) and Partial Response (PR) cutoffs.

labelOutliersLabel responses exceeding the specified threshold.

showMedianShow median response as a horizontal line.

showCIShow confidence interval around median response.

minResponseForLabelMinimum response value for labels to be displayed.

colorByColoring method: RECIST categories or patient groups (requires Group Variable).

colorSchemeColor scheme for waterfall plot. 'Colorful' provides distinct colors for group-based coloring.

barAlphaTransparency of bars in waterfall plot.

barWidthWidth of bars in waterfall plot.

showWaterfallPlotDisplay the waterfall plot showing best response for each patient.

showSpiderPlotDisplay spider plot showing response trajectories over time (requires time variable).

spiderColorByColoring method for spider plot: Response status or patient groups. For backward compatibility, defaults to response status coloring.

spiderColorSchemeColor scheme for spider plot lines and points.

timeUnitLabelLabel to use for the spider plot time axis. Does not rescale data; only affects axis labeling.

generateCopyReadyReportGenerate publication-ready result sentences with statistical details

showClinicalSignificanceDisplay clinical significance interpretations for ORR and DCR

showConfidenceIntervalsCalculate and display exact binomial confidence intervals for ORR and DCR

enableGuidedModeEnable step-by-step guidance for new users

A results object containing:

results$guidedAnalysis					a html
results$todo					a html
results$todo2					a html
results$clinicalSummary					a html
results$aboutAnalysis					a html
results$summaryTable					a table
results$personTimeTable					a table
results$clinicalMetrics					a table
results$waterfallplot					an image
results$spiderplot					an image
results$copyReadyReport					a html
results$clinicalSignificance					a html
results$clinicalGlossary					a html
results$enhancedClinicalMetrics					a table
results$groupComparisonTable					a table
results$groupComparisonTest					a table
results$addResponseCategory					an output

Tables can be converted to data frames with asDF or as.data.frame. For example:results$summaryTable$asDFas.data.frame(results$summaryTable) Creates waterfall and spider plots to analyze tumor response data following RECIST criteria. Supports both raw tumor measurements and pre-calculated percentage changes. Provides comprehensive response analysis including ORR, DCR, and person-time metrics.