Creates comprehensive swimmer plots using the ggswim package to visualize patient timelines, clinical events, milestones, and treatment responses. Features enhanced data validation and complete ggswim integration for professional clinical visualization.
Usage
swimmerplot(
data,
patientID,
startTime,
endTime,
responseVar,
timeType = "raw",
dateFormat = "ymd",
timeUnit = "months",
timeDisplay = "relative",
maxMilestones = 5,
milestone1Name = "Surgery",
milestone1Date = NULL,
milestone2Name = "Treatment Start",
milestone2Date = NULL,
milestone3Name = "Response Assessment",
milestone3Date = NULL,
milestone4Name = "Progression",
milestone4Date = NULL,
milestone5Name = "Death/Last Follow-up",
milestone5Date = NULL,
showEventMarkers = FALSE,
eventVar = NULL,
eventTimeVar = NULL,
laneWidth = 3,
markerSize = 5,
plotTheme = "ggswim",
showLegend = TRUE,
referenceLines = "none",
customReferenceTime = 12,
sortVariable = NULL,
sortOrder = "duration_desc",
showInterpretation = TRUE,
personTimeAnalysis = TRUE,
responseAnalysis = TRUE,
exportTimeline = FALSE,
exportSummary = FALSE
)Arguments
- data
The data as a data frame containing patient timeline information.
- patientID
Variable containing unique patient identifiers.
- startTime
Time/date when observation/treatment started.
- endTime
Time/date when observation/treatment ended.
- responseVar
Optional variable for response types (e.g., CR, PR, SD, PD) to color lanes.
- timeType
Select whether time values are raw numbers or dates/times.
- dateFormat
Select the date/time format in your data (only used when Time Input Type is Date/Time).
- timeUnit
Time unit to use for display and calculations.
- timeDisplay
Choose whether to align all start times to 0 or use absolute start times.
- maxMilestones
Maximum number of milestone events to support.
- milestone1Name
Name for the first milestone event (e.g., Surgery, Treatment Start).
- milestone1Date
Date/time variable when milestone 1 occurred.
- milestone2Name
Name for the second milestone event.
- milestone2Date
Date/time variable when milestone 2 occurred.
- milestone3Name
Name for the third milestone event.
- milestone3Date
Date/time variable when milestone 3 occurred.
- milestone4Name
Name for the fourth milestone event.
- milestone4Date
Date/time variable when milestone 4 occurred.
- milestone5Name
Name for the fifth milestone event.
- milestone5Date
Date/time variable when milestone 5 occurred.
- showEventMarkers
Whether to display event markers along patient timelines.
- eventVar
Variable containing event type labels for markers.
- eventTimeVar
Variable containing event times (defaults to start time if not specified).
- laneWidth
Width/thickness of patient timeline lanes.
- markerSize
Size of event markers and milestone markers.
- plotTheme
Visual theme for the swimmer plot.
- showLegend
Whether to display the plot legend.
- referenceLines
Add reference time lines to the plot for clinical context.
- customReferenceTime
Custom time point to mark with a reference line (only used when Reference Lines is set to Custom).
- sortVariable
Optional variable to sort patient timelines (defaults to duration-based sorting).
- sortOrder
How to order patients in the visualization.
- showInterpretation
Whether to display automated clinical interpretation of the timeline data.
- personTimeAnalysis
Whether to include epidemiological person-time metrics in the analysis.
- responseAnalysis
Whether to analyze response patterns when response variable is provided.
- exportTimeline
Export processed timeline data for external analysis.
- exportSummary
Export comprehensive summary statistics and clinical metrics.
Value
A results object containing:
results$instructions | a html | ||||
results$plot | an image | ||||
results$summary | a table | ||||
results$interpretation | a html | ||||
results$personTimeTable | a table | ||||
results$milestoneTable | a table | ||||
results$eventMarkerTable | a table | ||||
results$timelineData | an output | ||||
results$summaryData | an output | ||||
results$exportInfo | a html | ||||
results$validationReport | a html | ||||
results$advancedMetrics | a table |
Tables can be converted to data frames with asDF or as.data.frame. For example:
results$summary$asDF
as.data.frame(results$summary)
Examples
# \donttest{
# Clinical trial swimmer plot example
data <- data.frame(
PatientID = paste0("PT", formatC(1:20, width = 3, flag = "0")),
StartTime = rep(0, 20),
EndTime = sample(6:24, 20, replace = TRUE),
Response = sample(c("CR", "PR", "SD", "PD"), 20, replace = TRUE),
Surgery = sample(c(1, 2, 3, NA), 20, replace = TRUE),
Progression = sample(c(8, 12, 16, NA), 20, replace = TRUE)
)
swimmerplot(
data = data,
patientID = "PatientID",
startTime = "StartTime",
endTime = "EndTime",
responseVar = "Response",
milestone1Name = "Surgery",
milestone1Date = "Surgery",
milestone2Name = "Progression",
milestone2Date = "Progression",
showEventMarkers = TRUE,
showInterpretation = TRUE
)
#>
#> SWIMMER PLOT
#>
#> character(0)
#>
#> Timeline Summary Statistics
#> ───────────────────────────────────
#> Metric Value
#> ───────────────────────────────────
#> Number of Patients 20.00000
#> Total Observations 20.00000
#> Median Duration 14.50000
#> Mean Duration 14.45000
#> Total Person-Time 289.00000
#> Mean Follow-up 14.45000
#> CR Rate (%) 30.00000
#> PD Rate (%) 20.00000
#> PR Rate (%) 30.00000
#> SD Rate (%) 20.00000
#> ───────────────────────────────────
#>
#>
#> <div style='background-color: #e8f5e8; padding: 15px; border-radius:
#> 5px; margin: 10px 0;'>
#>
#> Clinical Interpretation
#>
#> <div style='margin: 10px 0;'><h5 style='color: #2e7d32;'>Timeline
#> Analysis:
#>
#> Study included 20 patients with 20 timeline observations. Median
#> follow-up was 14.5 months (range: 8.0 to 22.0 months).
#>
#> <div style='margin: 10px 0;'><h5 style='color: #2e7d32;'>Person-Time
#> Analysis:
#>
#> Total person-time: 289.0 months. Average follow-up per patient: 14.4
#> months.
#>
#> <div style='margin: 10px 0;'><h5 style='color: #2e7d32;'>Response
#> Pattern Analysis:
#>
#> Most common response was CR (30.0% of observations). Response
#> distribution shows clinical patterns suitable for efficacy analysis.
#>
#> Person-Time Analysis
#> ──────────────────────────────────────────────────────────────────────────
#> Response Type Patients Total Time Mean Time Incidence Rate
#> ──────────────────────────────────────────────────────────────────────────
#> ──────────────────────────────────────────────────────────────────────────
#>
#>
#> Milestone Event Summary
#> ────────────────────────────────────────────────────
#> Milestone Events Median Time Time Range
#> ────────────────────────────────────────────────────
#> ────────────────────────────────────────────────────
#>
#>
#> Event Marker Summary
#> ────────────────────────────────────────────────────
#> Event Type Count Percentage Median Time
#> ────────────────────────────────────────────────────
#> ────────────────────────────────────────────────────
#>
#>
#> Advanced Clinical Metrics
#> ──────────────────────────────────────────────────────
#> Metric Value Unit Clinical Interpretation
#> ──────────────────────────────────────────────────────
#> ──────────────────────────────────────────────────────
#>
# }