ClinicoPathJamoviModule: Analysis for Clinicopathological Research

Documented in powersurvival

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

powersurvivalOptions <- if (requireNamespace("jmvcore", quietly=TRUE)) R6::R6Class(
    "powersurvivalOptions",
    inherit = jmvcore::Options,
    public = list(
        initialize = function(
            calc_type = "sample_size",
            study_design = "simple",
            hazard_ratio = 0.7,
            power = 0.8,
            alpha = 0.05,
            sample_size = 200,
            allocation_ratio = 1,
            prob_event = 0.5,
            accrual_time = 1,
            follow_up_time = 3,
            median_survival = 5,
            loss_followup = 0.05, ...) {

            super$initialize(
                package="ClinicoPath",
                name="powersurvival",
                requiresData=TRUE,
                ...)

            private$..calc_type <- jmvcore::OptionList$new(
                "calc_type",
                calc_type,
                options=list(
                    "power",
                    "sample_size",
                    "hazard_ratio"),
                default="sample_size")
            private$..study_design <- jmvcore::OptionList$new(
                "study_design",
                study_design,
                options=list(
                    "simple",
                    "complex"),
                default="simple")
            private$..hazard_ratio <- jmvcore::OptionNumber$new(
                "hazard_ratio",
                hazard_ratio,
                min=0.01,
                max=10,
                default=0.7)
            private$..power <- jmvcore::OptionNumber$new(
                "power",
                power,
                min=0.01,
                max=0.99,
                default=0.8)
            private$..alpha <- jmvcore::OptionNumber$new(
                "alpha",
                alpha,
                min=0.001,
                max=0.5,
                default=0.05)
            private$..sample_size <- jmvcore::OptionInteger$new(
                "sample_size",
                sample_size,
                min=10,
                default=200)
            private$..allocation_ratio <- jmvcore::OptionNumber$new(
                "allocation_ratio",
                allocation_ratio,
                min=0.1,
                max=10,
                default=1)
            private$..prob_event <- jmvcore::OptionNumber$new(
                "prob_event",
                prob_event,
                min=0.01,
                max=0.99,
                default=0.5)
            private$..accrual_time <- jmvcore::OptionNumber$new(
                "accrual_time",
                accrual_time,
                min=0,
                default=1)
            private$..follow_up_time <- jmvcore::OptionNumber$new(
                "follow_up_time",
                follow_up_time,
                min=0,
                default=3)
            private$..median_survival <- jmvcore::OptionNumber$new(
                "median_survival",
                median_survival,
                min=0.1,
                default=5)
            private$..loss_followup <- jmvcore::OptionNumber$new(
                "loss_followup",
                loss_followup,
                min=0,
                max=0.5,
                default=0.05)

            self$.addOption(private$..calc_type)
            self$.addOption(private$..study_design)
            self$.addOption(private$..hazard_ratio)
            self$.addOption(private$..power)
            self$.addOption(private$..alpha)
            self$.addOption(private$..sample_size)
            self$.addOption(private$..allocation_ratio)
            self$.addOption(private$..prob_event)
            self$.addOption(private$..accrual_time)
            self$.addOption(private$..follow_up_time)
            self$.addOption(private$..median_survival)
            self$.addOption(private$..loss_followup)
        }),
    active = list(
        calc_type = function() private$..calc_type$value,
        study_design = function() private$..study_design$value,
        hazard_ratio = function() private$..hazard_ratio$value,
        power = function() private$..power$value,
        alpha = function() private$..alpha$value,
        sample_size = function() private$..sample_size$value,
        allocation_ratio = function() private$..allocation_ratio$value,
        prob_event = function() private$..prob_event$value,
        accrual_time = function() private$..accrual_time$value,
        follow_up_time = function() private$..follow_up_time$value,
        median_survival = function() private$..median_survival$value,
        loss_followup = function() private$..loss_followup$value),
    private = list(
        ..calc_type = NA,
        ..study_design = NA,
        ..hazard_ratio = NA,
        ..power = NA,
        ..alpha = NA,
        ..sample_size = NA,
        ..allocation_ratio = NA,
        ..prob_event = NA,
        ..accrual_time = NA,
        ..follow_up_time = NA,
        ..median_survival = NA,
        ..loss_followup = NA)
)

powersurvivalResults <- if (requireNamespace("jmvcore", quietly=TRUE)) R6::R6Class(
    "powersurvivalResults",
    inherit = jmvcore::Group,
    active = list(
        message = function() private$.items[["message"]],
        power_result = function() private$.items[["power_result"]],
        sample_size_result = function() private$.items[["sample_size_result"]],
        hazard_ratio_result = function() private$.items[["hazard_ratio_result"]],
        power_plot = function() private$.items[["power_plot"]]),
    private = list(),
    public=list(
        initialize=function(options) {
            super$initialize(
                options=options,
                name="",
                title="Power Analysis for Survival Studies",
                refs=list(
                    "powerSurvEpi",
                    "powerSurvival",
                    "survivalStats",
                    "Schoenfeld1983",
                    "FreedmanAndSchoenfeld1982",
                    "LachinAndFoulkes1986"))
            self$add(jmvcore::Html$new(
                options=options,
                name="message",
                title="Package Installation Required"))
            self$add(jmvcore::Html$new(
                options=options,
                name="power_result",
                title="Power Calculation Results",
                visible="(calc_type:power)"))
            self$add(jmvcore::Html$new(
                options=options,
                name="sample_size_result",
                title="Sample Size Calculation Results",
                visible="(calc_type:sample_size)"))
            self$add(jmvcore::Html$new(
                options=options,
                name="hazard_ratio_result",
                title="Hazard Ratio Calculation Results",
                visible="(calc_type:hazard_ratio)"))
            self$add(jmvcore::Image$new(
                options=options,
                name="power_plot",
                title="Power Analysis Plot",
                width=600,
                height=400,
                renderFun=".power_plot",
                visible=TRUE))}))

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

#' Power Analysis for Survival Studies
#'
#' Calculates power, sample size, or minimum detectable hazard ratio for 
#' survival studies. This helps researchers design adequately powered studies 
#' to detect meaningful differences in survival between groups.
#'
#' @examples
#' \donttest{
#' # Example power calculation for a survival study
#' # powersurvival(
#' #   calc_type = "sample_size",
#' #   hazard_ratio = 0.7,
#' #   power = 0.8,
#' #   alpha = 0.05,
#' #   prob_event = 0.5,
#' #   allocation_ratio = 1
#' # )
#'}
#' @param data The data as a data frame. Note that power analysis typically
#'   doesn't require actual data - it's used for study planning.
#' @param calc_type Select what to calculate. 'Power' calculates statistical
#'   power given sample size and hazard ratio. 'Sample Size' determines required
#'   sample size for desired power and hazard ratio. 'Hazard Ratio' calculates
#'   the minimum detectable effect size given sample size and power.
#' @param study_design Select the study design complexity. 'Simple' assumes a
#'   fixed follow-up period for all subjects. 'Complex' allows for accrual
#'   period and variable follow-up times.
#' @param hazard_ratio The hazard ratio to detect. Values < 1 indicate
#'   protective effects (treatment better than control); values > 1 indicate
#'   harmful effects (control better than treatment).
#' @param power The probability of detecting an effect if one exists (1 minus
#'   the Type II error rate). Conventional values are 0.8 or 0.9.
#' @param alpha The Type I error rate (probability of falsely rejecting the
#'   null hypothesis). Conventional value is 0.05.
#' @param sample_size The total number of subjects across all groups. For
#'   sample size calculation, this is a starting value for the search algorithm.
#' @param allocation_ratio The ratio of control group size to treatment group
#'   size. 1 indicates equal allocation. Values > 1 mean more subjects in the
#'   control group; values < 1 mean more in the treatment group.
#' @param prob_event The overall probability of observing the event (e.g.,
#'   death) during the study period. This affects the number of events observed,
#'   which is crucial for power.
#' @param accrual_time The period over which participants are recruited, in
#'   years. Only used for complex designs.
#' @param follow_up_time The additional follow-up period after accrual ends,
#'   in years. Only used for complex designs.
#' @param median_survival The median survival time in the control group, in
#'   years. Used to estimate the baseline hazard rate. Only used for complex
#'   designs.
#' @param loss_followup The annual rate of loss to follow-up (attrition). Only
#'   used for complex designs.
#' @return A results object containing:
#' \tabular{llllll}{
#'   \code{results$message} \tab \tab \tab \tab \tab a html \cr
#'   \code{results$power_result} \tab \tab \tab \tab \tab a html \cr
#'   \code{results$sample_size_result} \tab \tab \tab \tab \tab a html \cr
#'   \code{results$hazard_ratio_result} \tab \tab \tab \tab \tab a html \cr
#'   \code{results$power_plot} \tab \tab \tab \tab \tab an image \cr
#' }
#'
#' @export
powersurvival <- function(
    data,
    calc_type = "sample_size",
    study_design = "simple",
    hazard_ratio = 0.7,
    power = 0.8,
    alpha = 0.05,
    sample_size = 200,
    allocation_ratio = 1,
    prob_event = 0.5,
    accrual_time = 1,
    follow_up_time = 3,
    median_survival = 5,
    loss_followup = 0.05) {

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

    if (missing(data))
        data <- jmvcore::marshalData(
            parent.frame())


    options <- powersurvivalOptions$new(
        calc_type = calc_type,
        study_design = study_design,
        hazard_ratio = hazard_ratio,
        power = power,
        alpha = alpha,
        sample_size = sample_size,
        allocation_ratio = allocation_ratio,
        prob_event = prob_event,
        accrual_time = accrual_time,
        follow_up_time = follow_up_time,
        median_survival = median_survival,
        loss_followup = loss_followup)

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

    analysis$run()

    analysis$results
}