R/swimmerplot.h.R

In sbalci/ClinicoPathDescriptives: Descriptive Analysis Tools for Clinicopathological Research

# This file is automatically generated, you probably don't want to edit this

swimmerplotOptions <- if (requireNamespace("jmvcore", quietly=TRUE)) R6::R6Class(
    "swimmerplotOptions",
    inherit = jmvcore::Options,
    public = list(
        initialize = function(
            patientID = NULL,
            start = NULL,
            end = NULL,
            event = NULL,
            timetype = "raw",
            timetypedata = "ymd",
            timetypeoutput = "months",
            startType = "relative",
            sortVariable = NULL,
            barHeight = 3,
            referenceLines = "none",
            customReferenceTime = 12,
            useggswim = FALSE,
            markerSize = 5,
            milestone1Name = "Surgery",
            milestone1Date = NULL,
            milestone2Name = "Treatment",
            milestone2Date = NULL,
            milestone3Name = "Recurrence",
            milestone3Date = NULL,
            milestone4Name = "Remission",
            milestone4Date = NULL,
            milestone5Name = "Death",
            milestone5Date = NULL, ...) {

            super$initialize(
                package="ClinicoPathDescriptives",
                name="swimmerplot",
                requiresData=TRUE,
                ...)

            private$..patientID <- jmvcore::OptionVariable$new(
                "patientID",
                patientID,
                suggested=list(
                    "nominal"),
                permitted=list(
                    "numeric",
                    "factor",
                    "id"))
            private$..start <- jmvcore::OptionVariable$new(
                "start",
                start)
            private$..end <- jmvcore::OptionVariable$new(
                "end",
                end)
            private$..event <- jmvcore::OptionVariable$new(
                "event",
                event,
                suggested=list(
                    "nominal",
                    "ordinal"),
                permitted=list(
                    "factor"),
                required=FALSE)
            private$..timetype <- jmvcore::OptionList$new(
                "timetype",
                timetype,
                options=list(
                    "raw",
                    "datetime"),
                default="raw")
            private$..timetypedata <- jmvcore::OptionList$new(
                "timetypedata",
                timetypedata,
                options=list(
                    "ymdhms",
                    "ymd",
                    "ydm",
                    "mdy",
                    "myd",
                    "dmy",
                    "dym"),
                default="ymd")
            private$..timetypeoutput <- jmvcore::OptionList$new(
                "timetypeoutput",
                timetypeoutput,
                options=list(
                    "days",
                    "weeks",
                    "months",
                    "years"),
                default="months")
            private$..startType <- jmvcore::OptionList$new(
                "startType",
                startType,
                options=list(
                    "relative",
                    "absolute"),
                default="relative")
            private$..sortVariable <- jmvcore::OptionVariable$new(
                "sortVariable",
                sortVariable,
                required=FALSE)
            private$..barHeight <- jmvcore::OptionNumber$new(
                "barHeight",
                barHeight,
                min=0.1,
                max=10,
                default=3)
            private$..referenceLines <- jmvcore::OptionList$new(
                "referenceLines",
                referenceLines,
                options=list(
                    "none",
                    "median",
                    "protocol",
                    "custom"),
                default="none")
            private$..customReferenceTime <- jmvcore::OptionNumber$new(
                "customReferenceTime",
                customReferenceTime,
                default=12)
            private$..useggswim <- jmvcore::OptionBool$new(
                "useggswim",
                useggswim,
                default=FALSE)
            private$..markerSize <- jmvcore::OptionNumber$new(
                "markerSize",
                markerSize,
                min=1,
                max=10,
                default=5)
            private$..milestone1Name <- jmvcore::OptionString$new(
                "milestone1Name",
                milestone1Name,
                default="Surgery")
            private$..milestone1Date <- jmvcore::OptionVariable$new(
                "milestone1Date",
                milestone1Date,
                suggested=list(
                    "continuous",
                    "ordinal",
                    "nominal"),
                required=FALSE)
            private$..milestone2Name <- jmvcore::OptionString$new(
                "milestone2Name",
                milestone2Name,
                default="Treatment")
            private$..milestone2Date <- jmvcore::OptionVariable$new(
                "milestone2Date",
                milestone2Date,
                suggested=list(
                    "continuous",
                    "ordinal",
                    "nominal"),
                required=FALSE)
            private$..milestone3Name <- jmvcore::OptionString$new(
                "milestone3Name",
                milestone3Name,
                default="Recurrence")
            private$..milestone3Date <- jmvcore::OptionVariable$new(
                "milestone3Date",
                milestone3Date,
                suggested=list(
                    "continuous",
                    "ordinal",
                    "nominal"),
                required=FALSE)
            private$..milestone4Name <- jmvcore::OptionString$new(
                "milestone4Name",
                milestone4Name,
                default="Remission")
            private$..milestone4Date <- jmvcore::OptionVariable$new(
                "milestone4Date",
                milestone4Date,
                suggested=list(
                    "continuous",
                    "ordinal",
                    "nominal"),
                required=FALSE)
            private$..milestone5Name <- jmvcore::OptionString$new(
                "milestone5Name",
                milestone5Name,
                default="Death")
            private$..milestone5Date <- jmvcore::OptionVariable$new(
                "milestone5Date",
                milestone5Date,
                suggested=list(
                    "continuous",
                    "ordinal",
                    "nominal"),
                required=FALSE)

            self$.addOption(private$..patientID)
            self$.addOption(private$..start)
            self$.addOption(private$..end)
            self$.addOption(private$..event)
            self$.addOption(private$..timetype)
            self$.addOption(private$..timetypedata)
            self$.addOption(private$..timetypeoutput)
            self$.addOption(private$..startType)
            self$.addOption(private$..sortVariable)
            self$.addOption(private$..barHeight)
            self$.addOption(private$..referenceLines)
            self$.addOption(private$..customReferenceTime)
            self$.addOption(private$..useggswim)
            self$.addOption(private$..markerSize)
            self$.addOption(private$..milestone1Name)
            self$.addOption(private$..milestone1Date)
            self$.addOption(private$..milestone2Name)
            self$.addOption(private$..milestone2Date)
            self$.addOption(private$..milestone3Name)
            self$.addOption(private$..milestone3Date)
            self$.addOption(private$..milestone4Name)
            self$.addOption(private$..milestone4Date)
            self$.addOption(private$..milestone5Name)
            self$.addOption(private$..milestone5Date)
        }),
    active = list(
        patientID = function() private$..patientID$value,
        start = function() private$..start$value,
        end = function() private$..end$value,
        event = function() private$..event$value,
        timetype = function() private$..timetype$value,
        timetypedata = function() private$..timetypedata$value,
        timetypeoutput = function() private$..timetypeoutput$value,
        startType = function() private$..startType$value,
        sortVariable = function() private$..sortVariable$value,
        barHeight = function() private$..barHeight$value,
        referenceLines = function() private$..referenceLines$value,
        customReferenceTime = function() private$..customReferenceTime$value,
        useggswim = function() private$..useggswim$value,
        markerSize = function() private$..markerSize$value,
        milestone1Name = function() private$..milestone1Name$value,
        milestone1Date = function() private$..milestone1Date$value,
        milestone2Name = function() private$..milestone2Name$value,
        milestone2Date = function() private$..milestone2Date$value,
        milestone3Name = function() private$..milestone3Name$value,
        milestone3Date = function() private$..milestone3Date$value,
        milestone4Name = function() private$..milestone4Name$value,
        milestone4Date = function() private$..milestone4Date$value,
        milestone5Name = function() private$..milestone5Name$value,
        milestone5Date = function() private$..milestone5Date$value),
    private = list(
        ..patientID = NA,
        ..start = NA,
        ..end = NA,
        ..event = NA,
        ..timetype = NA,
        ..timetypedata = NA,
        ..timetypeoutput = NA,
        ..startType = NA,
        ..sortVariable = NA,
        ..barHeight = NA,
        ..referenceLines = NA,
        ..customReferenceTime = NA,
        ..useggswim = NA,
        ..markerSize = NA,
        ..milestone1Name = NA,
        ..milestone1Date = NA,
        ..milestone2Name = NA,
        ..milestone2Date = NA,
        ..milestone3Name = NA,
        ..milestone3Date = NA,
        ..milestone4Name = NA,
        ..milestone4Date = NA,
        ..milestone5Name = NA,
        ..milestone5Date = NA)
)

swimmerplotResults <- if (requireNamespace("jmvcore", quietly=TRUE)) R6::R6Class(
    "swimmerplotResults",
    inherit = jmvcore::Group,
    active = list(
        todo = function() private$.items[["todo"]],
        summary = function() private$.items[["summary"]],
        plot = function() private$.items[["plot"]]),
    private = list(),
    public=list(
        initialize=function(options) {
            super$initialize(
                options=options,
                name="",
                title="Patient Timeline Analysis",
                refs=list(
                    "ClinicoPathJamoviModule",
                    "ggswim"),
                clearWith=list(
                    "patientID",
                    "start",
                    "end",
                    "event",
                    "sortVariable",
                    "timetype",
                    "timetypedata",
                    "timetypeoutput",
                    "barHeight",
                    "startType",
                    "milestone1Name",
                    "milestone1Date",
                    "milestone2Name",
                    "milestone2Date",
                    "milestone3Name",
                    "milestone3Date",
                    "milestone4Name",
                    "milestone4Date",
                    "milestone5Name",
                    "milestone5Date",
                    "referenceLines",
                    "customReferenceTime",
                    "useggswim",
                    "markerSize"))
            self$add(jmvcore::Html$new(
                options=options,
                name="todo",
                title="To Do"))
            self$add(jmvcore::Table$new(
                options=options,
                name="summary",
                title="Timeline Summary",
                rows=0,
                columns=list(
                    list(
                        `name`="metric", 
                        `title`="Metric", 
                        `type`="text"),
                    list(
                        `name`="value", 
                        `title`="Value", 
                        `type`="number", 
                        `format`=".1f"))))
            self$add(jmvcore::Image$new(
                options=options,
                name="plot",
                title="Swimmer Plot",
                width=800,
                height=600,
                renderFun=".plot",
                requiresData=TRUE))}))

swimmerplotBase <- if (requireNamespace("jmvcore", quietly=TRUE)) R6::R6Class(
    "swimmerplotBase",
    inherit = jmvcore::Analysis,
    public = list(
        initialize = function(options, data=NULL, datasetId="", analysisId="", revision=0) {
            super$initialize(
                package = "ClinicoPathDescriptives",
                name = "swimmerplot",
                version = c(0,0,3),
                options = options,
                results = swimmerplotResults$new(options=options),
                data = data,
                datasetId = datasetId,
                analysisId = analysisId,
                revision = revision,
                pause = NULL,
                completeWhenFilled = FALSE,
                requiresMissings = FALSE,
                weightsSupport = 'auto')
        }))

#' Swimmer Plot
#'
#' Creates a swimmer plot to visualize individual patient timelines and 
#' clinical events.
#'
#' @examples
#' \donttest{
#' # Example will show patient timelines
#' data <- data.frame(
#'     PatientID = paste0("PT", 1:10),
#'     StartTime = c(0, 0, 0, 0, 0, 0, 0, 0, 0, 0),
#'     EndTime = c(12, 8, 15, 6, 9, 11, 7, 14, 10, 5),
#'     Event = c("CR", "PD", "PR", "SD", "CR", "PD", "PR", "SD", "CR", "PD"),
#'     Surgery = c(1, 2, 3, 1, 2, 3, 1, 2, 3, 1)
#' )
#' swimmerplot(
#'     data = data,
#'     patientID = "PatientID",
#'     start = "StartTime",
#'     end = "EndTime",
#'     event = "Event",
#'     milestone1Name = "Surgery",
#'     milestone1Date = "Surgery"
#' )
#'}
#' @param data The data as a data frame.
#' @param patientID Variable containing patient identifiers.
#' @param start Time/date when observation/treatment started.
#' @param end Time/date when observation/treatment ended.
#' @param event Optional variable for event types (e.g., CR, PR, PD).
#' @param timetype Select whether time values are raw numbers or dates
#' @param timetypedata Select the time format in your data
#' @param timetypeoutput Select the time unit for display
#' @param startType Choose whether to align all start times to 0 or use
#'   absolute start times
#' @param sortVariable Variable to sort the patient timelines.
#' @param barHeight Thickness of timeline bars
#' @param referenceLines Add reference time lines to the plot
#' @param customReferenceTime Custom time point to mark with a reference line
#' @param useggswim .
#' @param markerSize Size of event markers on the plot
#' @param milestone1Name Name for the first milestone event (e.g., Surgery)
#' @param milestone1Date Date/time when milestone 1 occurred
#' @param milestone2Name Name for the second milestone event (e.g., Treatment)
#' @param milestone2Date Date/time when milestone 2 occurred
#' @param milestone3Name Name for the third milestone event (e.g., Recurrence)
#' @param milestone3Date Date/time when milestone 3 occurred
#' @param milestone4Name Name for the fourth milestone event (e.g., Remission)
#' @param milestone4Date Date/time when milestone 4 occurred
#' @param milestone5Name Name for the fifth milestone event (e.g., Death)
#' @param milestone5Date Date/time when milestone 5 occurred
#' @return A results object containing:
#' \tabular{llllll}{
#'   \code{results$todo} \tab \tab \tab \tab \tab a html \cr
#'   \code{results$summary} \tab \tab \tab \tab \tab a table \cr
#'   \code{results$plot} \tab \tab \tab \tab \tab an image \cr
#' }
#'
#' Tables can be converted to data frames with \code{asDF} or \code{\link{as.data.frame}}. For example:
#'
#' \code{results$summary$asDF}
#'
#' \code{as.data.frame(results$summary)}
#'
#' @export
swimmerplot <- function(
    data,
    patientID,
    start,
    end,
    event,
    timetype = "raw",
    timetypedata = "ymd",
    timetypeoutput = "months",
    startType = "relative",
    sortVariable,
    barHeight = 3,
    referenceLines = "none",
    customReferenceTime = 12,
    useggswim = FALSE,
    markerSize = 5,
    milestone1Name = "Surgery",
    milestone1Date,
    milestone2Name = "Treatment",
    milestone2Date,
    milestone3Name = "Recurrence",
    milestone3Date,
    milestone4Name = "Remission",
    milestone4Date,
    milestone5Name = "Death",
    milestone5Date) {

    if ( ! requireNamespace("jmvcore", quietly=TRUE))
        stop("swimmerplot requires jmvcore to be installed (restart may be required)")

    if ( ! missing(patientID)) patientID <- jmvcore::resolveQuo(jmvcore::enquo(patientID))
    if ( ! missing(start)) start <- jmvcore::resolveQuo(jmvcore::enquo(start))
    if ( ! missing(end)) end <- jmvcore::resolveQuo(jmvcore::enquo(end))
    if ( ! missing(event)) event <- jmvcore::resolveQuo(jmvcore::enquo(event))
    if ( ! missing(sortVariable)) sortVariable <- jmvcore::resolveQuo(jmvcore::enquo(sortVariable))
    if ( ! missing(milestone1Date)) milestone1Date <- jmvcore::resolveQuo(jmvcore::enquo(milestone1Date))
    if ( ! missing(milestone2Date)) milestone2Date <- jmvcore::resolveQuo(jmvcore::enquo(milestone2Date))
    if ( ! missing(milestone3Date)) milestone3Date <- jmvcore::resolveQuo(jmvcore::enquo(milestone3Date))
    if ( ! missing(milestone4Date)) milestone4Date <- jmvcore::resolveQuo(jmvcore::enquo(milestone4Date))
    if ( ! missing(milestone5Date)) milestone5Date <- jmvcore::resolveQuo(jmvcore::enquo(milestone5Date))
    if (missing(data))
        data <- jmvcore::marshalData(
            parent.frame(),
            `if`( ! missing(patientID), patientID, NULL),
            `if`( ! missing(start), start, NULL),
            `if`( ! missing(end), end, NULL),
            `if`( ! missing(event), event, NULL),
            `if`( ! missing(sortVariable), sortVariable, NULL),
            `if`( ! missing(milestone1Date), milestone1Date, NULL),
            `if`( ! missing(milestone2Date), milestone2Date, NULL),
            `if`( ! missing(milestone3Date), milestone3Date, NULL),
            `if`( ! missing(milestone4Date), milestone4Date, NULL),
            `if`( ! missing(milestone5Date), milestone5Date, NULL))

    for (v in event) if (v %in% names(data)) data[[v]] <- as.factor(data[[v]])

    options <- swimmerplotOptions$new(
        patientID = patientID,
        start = start,
        end = end,
        event = event,
        timetype = timetype,
        timetypedata = timetypedata,
        timetypeoutput = timetypeoutput,
        startType = startType,
        sortVariable = sortVariable,
        barHeight = barHeight,
        referenceLines = referenceLines,
        customReferenceTime = customReferenceTime,
        useggswim = useggswim,
        markerSize = markerSize,
        milestone1Name = milestone1Name,
        milestone1Date = milestone1Date,
        milestone2Name = milestone2Name,
        milestone2Date = milestone2Date,
        milestone3Name = milestone3Name,
        milestone3Date = milestone3Date,
        milestone4Name = milestone4Name,
        milestone4Date = milestone4Date,
        milestone5Name = milestone5Name,
        milestone5Date = milestone5Date)

    analysis <- swimmerplotClass$new(
        options = options,
        data = data)

    analysis$run()

    analysis$results
}