ClinicoPathJamoviModule: Analysis for Clinicopathological Research

Documented in swimmerplot

# 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,
            milestoneVariable = NULL,
            milestoneTime = NULL,
            referenceLines = "none",
            customReferenceTime = 12,
            timetype = "raw",
            timetypedata = "ymd",
            timetypeoutput = "months",
            startType = "relative",
            sortVariable = NULL,
            barHeight = 3, ...) {

            super$initialize(
                package="ClinicoPath",
                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$..milestoneVariable <- jmvcore::OptionVariable$new(
                "milestoneVariable",
                milestoneVariable,
                suggested=list(
                    "ordinal",
                    "nominal"),
                permitted=list(
                    "factor"),
                required=FALSE)
            private$..milestoneTime <- jmvcore::OptionVariable$new(
                "milestoneTime",
                milestoneTime,
                required=FALSE)
            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$..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)
            private$..barHeight <- jmvcore::OptionNumber$new(
                "barHeight",
                barHeight,
                min=0.1,
                max=10,
                default=3)

            self$.addOption(private$..patientID)
            self$.addOption(private$..start)
            self$.addOption(private$..end)
            self$.addOption(private$..event)
            self$.addOption(private$..milestoneVariable)
            self$.addOption(private$..milestoneTime)
            self$.addOption(private$..referenceLines)
            self$.addOption(private$..customReferenceTime)
            self$.addOption(private$..timetype)
            self$.addOption(private$..timetypedata)
            self$.addOption(private$..timetypeoutput)
            self$.addOption(private$..startType)
            self$.addOption(private$..sortVariable)
            self$.addOption(private$..barHeight)
        }),
    active = list(
        patientID = function() private$..patientID$value,
        start = function() private$..start$value,
        end = function() private$..end$value,
        event = function() private$..event$value,
        milestoneVariable = function() private$..milestoneVariable$value,
        milestoneTime = function() private$..milestoneTime$value,
        referenceLines = function() private$..referenceLines$value,
        customReferenceTime = function() private$..customReferenceTime$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),
    private = list(
        ..patientID = NA,
        ..start = NA,
        ..end = NA,
        ..event = NA,
        ..milestoneVariable = NA,
        ..milestoneTime = NA,
        ..referenceLines = NA,
        ..customReferenceTime = NA,
        ..timetype = NA,
        ..timetypedata = NA,
        ..timetypeoutput = NA,
        ..startType = NA,
        ..sortVariable = NA,
        ..barHeight = 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"))
            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")),
                clearWith=list(
                    "patientID",
                    "start",
                    "end",
                    "event",
                    "sortVariable",
                    "timetype",
                    "timetypedata",
                    "timetypeoutput",
                    "barHeight",
                    "startType")))
            self$add(jmvcore::Image$new(
                options=options,
                name="plot",
                title="Swimmer Plot",
                width=800,
                height=600,
                renderFun=".plot",
                requiresData=TRUE,
                clearWith=list(
                    "patientID",
                    "start",
                    "end",
                    "event",
                    "sortVariable",
                    "timetype",
                    "timetypedata",
                    "timetypeoutput",
                    "barHeight",
                    "startType")))}))

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 = "ClinicoPath",
                name = "swimmerplot",
                version = c(1,0,0),
                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 
#' 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")
#' )
#' swimmerplot(
#'     data = data,
#'     patientID = "PatientID",
#'     start = "StartTime",
#'     end = "EndTime",
#'     event = "Event"
#' )
#'}
#' @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 milestoneVariable Variable containing milestone events to mark on
#'   timeline
#' @param milestoneTime Times when milestones occurred
#' @param referenceLines .
#' @param customReferenceTime .
#' @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 .
#' @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,
    milestoneVariable,
    milestoneTime,
    referenceLines = "none",
    customReferenceTime = 12,
    timetype = "raw",
    timetypedata = "ymd",
    timetypeoutput = "months",
    startType = "relative",
    sortVariable,
    barHeight = 3) {

    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(milestoneVariable)) milestoneVariable <- jmvcore::resolveQuo(jmvcore::enquo(milestoneVariable))
    if ( ! missing(milestoneTime)) milestoneTime <- jmvcore::resolveQuo(jmvcore::enquo(milestoneTime))
    if ( ! missing(sortVariable)) sortVariable <- jmvcore::resolveQuo(jmvcore::enquo(sortVariable))
    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(milestoneVariable), milestoneVariable, NULL),
            `if`( ! missing(milestoneTime), milestoneTime, NULL),
            `if`( ! missing(sortVariable), sortVariable, NULL))

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

    options <- swimmerplotOptions$new(
        patientID = patientID,
        start = start,
        end = end,
        event = event,
        milestoneVariable = milestoneVariable,
        milestoneTime = milestoneTime,
        referenceLines = referenceLines,
        customReferenceTime = customReferenceTime,
        timetype = timetype,
        timetypedata = timetypedata,
        timetypeoutput = timetypeoutput,
        startType = startType,
        sortVariable = sortVariable,
        barHeight = barHeight)

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

    analysis$run()

    analysis$results
}