#' Split function to configure risk difference column

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Wrapper function for [rtables::add_combo_levels()] which configures settings for the risk difference

#' column to be added to an `rtables` object. To add a risk difference column to a table, this function

#' should be used as `split_fun` in calls to [rtables::split_cols_by()], followed by setting argument

#' `riskdiff` to `TRUE` in all following analyze function calls.

#'

#' @param arm_x (`string`)\cr name of reference arm to use in risk difference calculations.

#' @param arm_y (`character`)\cr names of one or more arms to compare to reference arm in risk difference

#'   calculations. A new column will be added for each value of `arm_y`.

#' @param col_label (`character`)\cr labels to use when rendering the risk difference column within the table.

#'   If more than one comparison arm is specified in `arm_y`, default labels will specify which two arms are

#'   being compared (reference arm vs. comparison arm).

#' @param pct (`flag`)\cr whether output should be returned as percentages. Defaults to `TRUE`.

#'

#' @return A closure suitable for use as a split function (`split_fun`) within [rtables::split_cols_by()]

#'   when creating a table layout.

#'

#' @seealso [stat_propdiff_ci()] for details on risk difference calculation.

#'

#' @examples

#' adae <- tern_ex_adae

#' adae$AESEV <- factor(adae$AESEV)

#'

#' lyt <- basic_table() %>%

#'   split_cols_by("ARMCD", split_fun = add_riskdiff(arm_x = "ARM A", arm_y = c("ARM B", "ARM C"))) %>%

#'   count_occurrences_by_grade(

#'     var = "AESEV",

#'     riskdiff = TRUE

#'   )

#'

#' tbl <- build_table(lyt, df = adae)

#' tbl

#'

#' @export

add_riskdiff <- function(arm_x,

                         arm_y,

                         col_label = paste0(

                           "Risk Difference (%) (95% CI)", if (length(arm_y) > 1) paste0("\n", arm_x, " vs. ", arm_y)

                         ),

                         pct = TRUE) {

      )

    )

  }

}

#' Analysis function to calculate risk difference column values

#'

#' In the risk difference column, this function uses the statistics function associated with `afun` to

#' calculates risk difference values from arm X (reference group) and arm Y. These arms are specified

#' when configuring the risk difference column which is done using the [add_riskdiff()] split function in

#' the previous call to [rtables::split_cols_by()]. For all other columns, applies `afun` as usual. This

#' function utilizes the [stat_propdiff_ci()] function to perform risk difference calculations.

#'

#' @inheritParams argument_convention

#' @param afun (named `list`)\cr a named list containing one name-value pair where the name corresponds to

#'   the name of the statistics function that should be used in calculations and the value is the corresponding

#'   analysis function.

#' @param s_args (named `list`)\cr additional arguments to be passed to the statistics function and analysis

#'   function supplied in `afun`.

#'

#' @return A list of formatted [rtables::CellValue()].

#'

#' @seealso

#' * [stat_propdiff_ci()] for details on risk difference calculation.

#' * Split function [add_riskdiff()] which, when used as `split_fun` within [rtables::split_cols_by()] with

#'   `riskdiff` argument set to `TRUE` in subsequent analyze functions calls, adds a risk difference column

#'   to a table layout.

#'

#' @keywords internal

afun_riskdiff <- function(df,

                          labelstr = "",

                          .var,

                          .N_col, # nolint

                          .N_row, # nolint

                          .df_row,

                          .spl_context,

                          .all_col_counts,

                          .stats,

                          .formats = NULL,

                          .labels = NULL,

                          .indent_mods = NULL,

                          na_str = default_na_str(),

                          afun,

                          s_args = list()) {

    )

  }

  )

    # Apply basic afun (no risk difference) in all other columns

  } else {

    } else {

    }

    # Apply statistics function to arm X and arm Y data

    # Get statistic name and row names

    } else {

    }

    # Calculate risk difference for each row, repeated if multiple statistics in table

  }

}

#' Control function for risk difference column

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Sets a list of parameters to use when generating a risk (proportion) difference column. Used as input to the

#' `riskdiff` parameter of [tabulate_rsp_subgroups()] and [tabulate_survival_subgroups()].

#'

#' @inheritParams add_riskdiff

#' @param format (`string` or `function`)\cr the format label (string) or formatting function to apply to the risk

#'   difference statistic. See the `3d` string options in [formatters::list_valid_format_labels()] for possible format

#'   strings. Defaults to `"xx.x (xx.x - xx.x)"`.

#'

#' @return A `list` of items with names corresponding to the arguments.

#'

#' @seealso [add_riskdiff()], [tabulate_rsp_subgroups()], and [tabulate_survival_subgroups()].

#'

#' @examples

#' control_riskdiff()

#' control_riskdiff(arm_x = "ARM A", arm_y = "ARM B")

#'

#' @export

control_riskdiff <- function(arm_x = NULL,

                             arm_y = NULL,

                             format = "xx.x (xx.x - xx.x)",

                             col_label = "Risk Difference (%) (95% CI)",

                             pct = TRUE) {

}

#' Odds ratio estimation

#'

#' @description `r lifecycle::badge("stable")`

#'

#' The analyze function [estimate_odds_ratio()] creates a layout element to compare bivariate responses between

#' two groups by estimating an odds ratio and its confidence interval.

#'

#' The primary analysis variable specified by `vars` is the group variable. Additional variables can be included in the

#' analysis via the `variables` argument, which accepts `arm`, an arm variable, and `strata`, a stratification variable.

#' If more than two arm levels are present, they can be combined into two groups using the `groups_list` argument.

#'

#' @inheritParams split_cols_by_groups

#' @inheritParams argument_convention

#' @param .stats (`character`)\cr statistics to select for the table.

#'

#'   Options are: ``r shQuote(get_stats("estimate_odds_ratio"), type = "sh")``

#' @param method (`string`)\cr whether to use the correct (`"exact"`) calculation in the conditional likelihood or one

#'   of the approximations. See [survival::clogit()] for details.

#'

#' @note

#' * This function uses logistic regression for unstratified analyses, and conditional logistic regression for

#'   stratified analyses. The Wald confidence interval is calculated with the specified confidence level.

#' * For stratified analyses, there is currently no implementation for conditional likelihood confidence intervals,

#'   therefore the likelihood confidence interval is not available as an option.

#' * When `vars` contains only responders or non-responders no odds ratio estimation is possible so the returned

#'   values will be `NA`.

#'

#' @seealso Relevant helper function [h_odds_ratio()].

#'

#' @name odds_ratio

#' @order 1

NULL

#' @describeIn odds_ratio Statistics function which estimates the odds ratio

#'   between a treatment and a control. A `variables` list with `arm` and `strata`

#'   variable names must be passed if a stratified analysis is required.

#'

#' @return

#' * `s_odds_ratio()` returns a named list with the statistics `or_ci`

#'   (containing `est`, `lcl`, and `ucl`) and `n_tot`.

#'

#' @examples

#' # Unstratified analysis.

#' s_odds_ratio(

#'   df = subset(dta, grp == "A"),

#'   .var = "rsp",

#'   .ref_group = subset(dta, grp == "B"),

#'   .in_ref_col = FALSE,

#'   .df_row = dta

#' )

#'

#' # Stratified analysis.

#' s_odds_ratio(

#'   df = subset(dta, grp == "A"),

#'   .var = "rsp",

#'   .ref_group = subset(dta, grp == "B"),

#'   .in_ref_col = FALSE,

#'   .df_row = dta,

#'   variables = list(arm = "grp", strata = "strata")

#' )

#'

#' @export

s_odds_ratio <- function(df,

                         .var,

                         .ref_group,

                         .in_ref_col,

                         .df_row,

                         variables = list(arm = NULL, strata = NULL),

                         conf_level = 0.95,

                         groups_list = NULL,

                         method = "exact") {

        )

      )

    } else {

      # The group variable prepared for clogit must be synchronised with combination groups definition.

      } else {

        # If more than one level in reference col.

        )

        # If more than one level in treatment col.

        )

      }

      # The reference level in `grp` must be the same as in the `rtables` column split.

      )

    }

  }

    )

  }

  )

  )

}

#' @describeIn odds_ratio Formatted analysis function which is used as `afun` in `estimate_odds_ratio()`.

#'

#' @return

#' * `a_odds_ratio()` returns the corresponding list with formatted [rtables::CellValue()].

#'

#' @examples

#' a_odds_ratio(

#'   df = subset(dta, grp == "A"),

#'   .var = "rsp",

#'   .ref_group = subset(dta, grp == "B"),

#'   .in_ref_col = FALSE,

#'   .df_row = dta

#' )

#'

#' @export

a_odds_ratio <- make_afun(

  s_odds_ratio,

  .formats = c(or_ci = "xx.xx (xx.xx - xx.xx)"),

  .indent_mods = c(or_ci = 1L)

)

#' @describeIn odds_ratio Layout-creating function which can take statistics function arguments

#'   and additional format arguments. This function is a wrapper for [rtables::analyze()].

#'

#' @return

#' * `estimate_odds_ratio()` returns a layout object suitable for passing to further layouting functions,

#'   or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing

#'   the statistics from `s_odds_ratio()` to the table layout.

#'

#' @examples

#' set.seed(12)

#' dta <- data.frame(

#'   rsp = sample(c(TRUE, FALSE), 100, TRUE),

#'   grp = factor(rep(c("A", "B"), each = 50), levels = c("A", "B")),

#'   strata = factor(sample(c("C", "D"), 100, TRUE))

#' )

#'

#' l <- basic_table() %>%

#'   split_cols_by(var = "grp", ref_group = "B") %>%

#'   estimate_odds_ratio(vars = "rsp")

#'

#' build_table(l, df = dta)

#'

#' @export

#' @order 2

estimate_odds_ratio <- function(lyt,

                                vars,

                                variables = list(arm = NULL, strata = NULL),

                                conf_level = 0.95,

                                groups_list = NULL,

                                na_str = default_na_str(),

                                nested = TRUE,

                                method = "exact",

                                show_labels = "hidden",

                                table_names = vars,

                                var_labels = vars,

                                .stats = "or_ci",

                                .formats = NULL,

                                .labels = NULL,

                                .indent_mods = NULL) {

  )

  )

}

#' Helper functions for odds ratio estimation

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Functions to calculate odds ratios in [estimate_odds_ratio()].

#'

#' @inheritParams odds_ratio

#' @inheritParams argument_convention

#' @param data (`data.frame`)\cr data frame containing at least the variables `rsp` and `grp`, and optionally

#'   `strata` for [or_clogit()].

#'

#' @return A named `list` of elements `or_ci` and `n_tot`.

#'

#' @seealso [odds_ratio]

#'

#' @name h_odds_ratio

NULL

#' @describeIn h_odds_ratio Estimates the odds ratio based on [stats::glm()]. Note that there must be

#'   exactly 2 groups in `data` as specified by the `grp` variable.

#'

#' @examples

#' # Data with 2 groups.

#' data <- data.frame(

#'   rsp = as.logical(c(1, 1, 0, 1, 0, 0, 1, 1)),

#'   grp = letters[c(1, 1, 1, 2, 2, 2, 1, 2)],

#'   strata = letters[c(1, 2, 1, 2, 2, 2, 1, 2)],

#'   stringsAsFactors = TRUE

#' )

#'

#' # Odds ratio based on glm.

#' or_glm(data, conf_level = 0.95)

#'

#' @export

or_glm <- function(data, conf_level) {

  )

  # Note that here we need to discard the intercept.

  )

}

#' @describeIn h_odds_ratio Estimates the odds ratio based on [survival::clogit()]. This is done for

#'   the whole data set including all groups, since the results are not the same as when doing

#'   pairwise comparisons between the groups.

#'

#' @examples

#' # Data with 3 groups.

#' data <- data.frame(

#'   rsp = as.logical(c(1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0)),

#'   grp = letters[c(1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3)],

#'   strata = LETTERS[c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2)],

#'   stringsAsFactors = TRUE

#' )

#'

#' # Odds ratio based on stratified estimation by conditional logistic regression.

#' or_clogit(data, conf_level = 0.95)

#'

#' @export

or_clogit <- function(data, conf_level, method = "exact") {

  # Deviation from convention: `survival::strata` must be simply `strata`.

  # Create a list with one set of OR estimates and CI per coefficient, i.e.

  # comparison of one group vs. the reference group.

    )

  }

}

#' Helper functions for subgroup treatment effect pattern (STEP) calculations

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Helper functions that are used internally for the STEP calculations.

#'

#' @inheritParams argument_convention

#'

#' @name h_step

#' @include control_step.R

NULL

#' @describeIn h_step Creates the windows for STEP, based on the control settings

#'   provided.

#'

#' @param x (`numeric`)\cr biomarker value(s) to use (without `NA`).

#' @param control (named `list`)\cr output from `control_step()`.

#'

#' @return

#' * `h_step_window()` returns a list containing the window-selection matrix `sel`

#'   and the interval information matrix `interval`.

#'

#' @export

h_step_window <- function(x,

                          control = control_step()) {

    # Create windows according to percentile cutoffs.

      )

    }

    # Center is the middle point of the percentile window.

  } else {

    # Create windows according to cutoffs.

      )

    }

    # Center is the same as the point for predicting.

  }

}

#' @describeIn h_step Calculates the estimated treatment effect estimate

#'   on the linear predictor scale and corresponding standard error from a STEP `model` fitted

#'   on `data` given `variables` specification, for a single biomarker value `x`.

#'   This works for both `coxph` and `glm` models, i.e. for calculating log hazard ratio or log odds

#'   ratio estimates.

#'

#' @param model (`coxph` or `glm`)\cr the regression model object.

#'

#' @return

#' * `h_step_trt_effect()` returns a vector with elements `est` and `se`.

#'

#' @export

h_step_trt_effect <- function(data,

                              model,

                              variables,

                              x) {

  # Note: It is important to use the coef subset from matrix, otherwise intercept and

  # strata are included for coxph() models.

  )

}

#' @describeIn h_step Builds the model formula used in survival STEP calculations.

#'

#' @return

#' * `h_step_survival_formula()` returns a model formula.

#'

#' @export

h_step_survival_formula <- function(variables,

                                    control = control_step()) {

  }

  }

  }

}

#' @describeIn h_step Estimates the model with `formula` built based on

#'   `variables` in `data` for a given `subset` and `control` parameters for the

#'   Cox regression.

#'

#' @param formula (`formula`)\cr the regression model formula.

#' @param subset (`logical`)\cr subset vector.

#'

#' @return

#' * `h_step_survival_est()` returns a matrix of number of observations `n`,

#'   `events`, log hazard ratio estimates `loghr`, standard error `se`,

#'   and Wald confidence interval bounds `ci_lower` and `ci_upper`. One row is

#'   included for each biomarker value in `x`.

#'

#' @export

h_step_survival_est <- function(formula,

                                data,

                                variables,

                                x,

                                subset = rep(TRUE, nrow(data)),

                                control = control_coxph()) {

  # Note: `subset` in `coxph` needs to be an expression referring to `data` variables.

        )

      },

      }

    ),

    }

  )

    ))

  }

  # Produce a matrix with one row per `x` and columns `est` and `se`.

  ))

  )

}

#' @describeIn h_step Builds the model formula used in response STEP calculations.

#'

#' @return

#' * `h_step_rsp_formula()` returns a model formula.

#'

#' @export

h_step_rsp_formula <- function(variables,

                               control = c(control_step(), control_logistic())) {

  )

  }

  }

    } else {

    }

  }

}

#' @describeIn h_step Estimates the model with `formula` built based on

#'   `variables` in `data` for a given `subset` and `control` parameters for the

#'   logistic regression.

#'

#' @param formula (`formula`)\cr the regression model formula.

#' @param subset (`logical`)\cr subset vector.

#'

#' @return

#' * `h_step_rsp_est()` returns a matrix of number of observations `n`, log odds

#'   ratio estimates `logor`, standard error `se`, and Wald confidence interval bounds

#'   `ci_lower` and `ci_upper`. One row is included for each biomarker value in `x`.

#'

#' @export

h_step_rsp_est <- function(formula,

                           data,

                           variables,

                           x,

                           subset = rep(TRUE, nrow(data)),

                           control = control_logistic()) {

  # Note: `subset` in `glm` needs to be an expression referring to `data` variables.

          )

        } else {

          # clogit needs coxph and strata imported

          )

        }

      },

      }

    ),

    }

  )

    ))

  }

  # Produce a matrix with one row per `x` and columns `est` and `se`.

  ))

  )

}

#' Control functions for Kaplan-Meier plot annotation tables

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Auxiliary functions for controlling arguments for formatting the annotation tables that can be added to plots

#' generated via [g_km()].

#'

#' @param x (`proportion`)\cr x-coordinate for center of annotation table.

#' @param y (`proportion`)\cr y-coordinate for center of annotation table.

#' @param w (`proportion`)\cr relative width of the annotation table.

#' @param h (`proportion`)\cr relative height of the annotation table.

#' @param fill (`flag` or `character`)\cr whether the annotation table should have a background fill color.

#'   Can also be a color code to use as the background fill color. If `TRUE`, color code defaults to `"#00000020"`.

#'

#' @return A list of components with the same names as the arguments.

#'

#' @seealso [g_km()]

#'

#' @name control_annot

NULL

#' @describeIn control_annot Control function for formatting the median survival time annotation table. This annotation

#'   table can be added in [g_km()] by setting `annot_surv_med=TRUE`, and can be configured using the

#'   `control_surv_med_annot()` function by setting it as the `control_annot_surv_med` argument.

#'

#' @examples

#' control_surv_med_annot()

#'

#' @export

control_surv_med_annot <- function(x = 0.8, y = 0.85, w = 0.32, h = 0.16, fill = TRUE) {

}

#' @describeIn control_annot Control function for formatting the Cox-PH annotation table. This annotation table can be

#'   added in [g_km()] by setting `annot_coxph=TRUE`, and can be configured using the `control_coxph_annot()` function

#'   by setting it as the `control_annot_coxph` argument.

#'

#' @param ref_lbls (`flag`)\cr whether the reference group should be explicitly printed in labels for the

#'   annotation table. If `FALSE` (default), only comparison groups will be printed in the table labels.

#'

#' @examples

#' control_coxph_annot()

#'

#' @export

control_coxph_annot <- function(x = 0.29, y = 0.51, w = 0.4, h = 0.125, fill = TRUE, ref_lbls = FALSE) {

}

#' Helper function to calculate x-tick positions

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Calculate the positions of ticks on the x-axis. However, if `xticks` already

#' exists it is kept as is. It is based on the same function `ggplot2` relies on,

#' and is required in the graphic and the patient-at-risk annotation table.

#'

#' @inheritParams g_km

#' @inheritParams h_ggkm

#'

#' @return A vector of positions to use for x-axis ticks on a `ggplot` object.

#'

#' @examples

#' library(dplyr)

#' library(survival)

#'

#' data <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(formula = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_data_plot()

#'

#' h_xticks(data)

#' h_xticks(data, xticks = seq(0, 3000, 500))

#' h_xticks(data, xticks = 500)

#' h_xticks(data, xticks = 500, max_time = 6000)

#' h_xticks(data, xticks = c(0, 500), max_time = 300)

#' h_xticks(data, xticks = 500, max_time = 300)

#'

#' @export

h_xticks <- function(data, xticks = NULL, max_time = NULL) {

    } else {

    }

    } else {

    }

  } else {

      )

    )

  }

}

#' Helper function for survival estimations

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Transform a survival fit to a table with groups in rows characterized by N, median and confidence interval.

#'

#' @inheritParams h_data_plot

#'

#' @return A summary table with statistics `N`, `Median`, and `XX% CI` (`XX` taken from `fit_km`).

#'

#' @examples

#' library(dplyr)

#' library(survival)

#'

#' adtte <- tern_ex_adtte %>% filter(PARAMCD == "OS")

#' fit <- survfit(

#'   formula = Surv(AVAL, 1 - CNSR) ~ ARMCD,

#'   data = adtte

#' )

#' h_tbl_median_surv(fit_km = fit)

#'

#' @export

h_tbl_median_surv <- function(fit_km, armval = "All") {

  } else {

  }

  )

  )

}

#' Helper function for generating a pairwise Cox-PH table

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Create a `data.frame` of pairwise stratified or unstratified Cox-PH analysis results.

#'

#' @inheritParams g_km

#' @param annot_coxph_ref_lbls (`flag`)\cr whether the reference group should be explicitly printed in labels for the

#'   `annot_coxph` table. If `FALSE` (default), only comparison groups will be printed in `annot_coxph` table labels.

#'

#' @return A `data.frame` containing statistics `HR`, `XX% CI` (`XX` taken from `control_coxph_pw`),

#'   and `p-value (log-rank)`.

#'

#' @examples

#' library(dplyr)

#'

#' adtte <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   mutate(is_event = CNSR == 0)

#'

#' h_tbl_coxph_pairwise(

#'   df = adtte,

#'   variables = list(tte = "AVAL", is_event = "is_event", arm = "ARM"),

#'   control_coxph_pw = control_coxph(conf_level = 0.9)

#' )

#'

#' @export

h_tbl_coxph_pairwise <- function(df,

                                 variables,

                                 ref_group_coxph = NULL,

                                 control_coxph_pw = control_coxph(),

                                 annot_coxph_ref_lbls = FALSE) {

    )

  }

    )

      ),

    )

}

#' Helper function to tidy survival fit data

#'

#' @description `r lifecycle::badge("stable")`

#'

#' Convert the survival fit data into a data frame designed for plotting

#' within `g_km`.

#'

#' This starts from the [broom::tidy()] result, and then:

#'   * Post-processes the `strata` column into a factor.

#'   * Extends each stratum by an additional first row with time 0 and probability 1 so that

#'     downstream plot lines start at those coordinates.

#'   * Adds a `censor` column.

#'   * Filters the rows before `max_time`.

#'

#' @inheritParams g_km

#' @param fit_km (`survfit`)\cr result of [survival::survfit()].

#' @param armval (`string`)\cr used as strata name when treatment arm variable only has one level. Default is `"All"`.

#'

#' @return A `tibble` with columns `time`, `n.risk`, `n.event`, `n.censor`, `estimate`, `std.error`, `conf.high`,

#'   `conf.low`, `strata`, and `censor`.

#'

#' @examples

#' library(dplyr)

#' library(survival)

#'

#' # Test with multiple arms

#' tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(formula = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_data_plot()

#'

#' # Test with single arm

#' tern_ex_adtte %>%

#'   filter(PARAMCD == "OS", ARMCD == "ARM B") %>%

#'   survfit(formula = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .) %>%

#'   h_data_plot(armval = "ARM B")

#'

#' @export

h_data_plot <- function(fit_km,

                        armval = "All",

                        max_time = NULL) {

    )

  } else {

  }

      )

    }

  )

  }

}

## Deprecated Functions ----

#' Helper function to create a KM plot

#'

#' @description `r lifecycle::badge("deprecated")`

#'

#' Draw the Kaplan-Meier plot using `ggplot2`.

#'

#' @inheritParams g_km

#' @param data (`data.frame`)\cr survival data as pre-processed by `h_data_plot`.

#'

#' @return A `ggplot` object.

#'

#' @examples

#' \donttest{

#' library(dplyr)

#' library(survival)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(formula = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   censor_show = TRUE,

#'   xticks = xticks,

#'   xlab = "Days",

#'   yval = "Survival",

#'   ylab = "Survival Probability",

#'   title = "Survival"

#' )

#' gg

#' }

#'

#' @export

h_ggkm <- function(data,

                   xticks = NULL,

                   yval = "Survival",

                   censor_show,

                   xlab,

                   ylab,

                   ylim = NULL,

                   title,

                   footnotes = NULL,

                   max_time = NULL,

                   lwd = 1,

                   lty = NULL,

                   pch = 3,

                   size = 2,

                   col = NULL,

                   ci_ribbon = FALSE,

                   ggtheme = nestcolor::theme_nest()) {

  )

    } else {

    }

  }

  # change estimates of survival to estimates of failure (1 - survival)

  }

      )

    ) +

  }

  }

  }

  }

      ),

    ) +

      )

  }

    } else {

    }

  }

  }

  )

}

#' `ggplot` decomposition

#'

#' @description `r lifecycle::badge("deprecated")`

#'

#' The elements composing the `ggplot` are extracted and organized in a `list`.

#'

#' @param gg (`ggplot`)\cr a graphic to decompose.

#'

#' @return A named `list` with elements:

#'   * `panel`: The panel.

#'   * `yaxis`: The y-axis.

#'   * `xaxis`: The x-axis.

#'   * `xlab`: The x-axis label.

#'   * `ylab`: The y-axis label.

#'   * `guide`: The legend.

#'

#' @examples

#' \donttest{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(formula = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   yval = "Survival",

#'   censor_show = TRUE,

#'   xticks = xticks, xlab = "Days", ylab = "Survival Probability",

#'   title = "tt",

#'   footnotes = "ff"

#' )

#'

#' g_el <- h_decompose_gg(gg)

#' grid::grid.newpage()

#' grid.rect(gp = grid::gpar(lty = 1, col = "red", fill = "gray85", lwd = 5))

#' grid::grid.draw(g_el$panel)

#'

#' grid::grid.newpage()

#' grid.rect(gp = grid::gpar(lty = 1, col = "royalblue", fill = "gray85", lwd = 5))

#' grid::grid.draw(with(g_el, cbind(ylab, yaxis)))

#' }

#'

#' @export

h_decompose_gg <- function(gg) {

  )

  )

}

#' Helper function to prepare a KM layout

#'

#' @description `r lifecycle::badge("deprecated")`

#'

#' Prepares a (5 rows) x (2 cols) layout for the Kaplan-Meier curve.

#'

#' @inheritParams g_km

#' @inheritParams h_ggkm

#' @param g_el (`list` of `gtable`)\cr list as obtained by `h_decompose_gg()`.

#' @param annot_at_risk (`flag`)\cr compute and add the annotation table reporting the number of

#'   patient at risk matching the main grid of the Kaplan-Meier curve.

#'

#' @return A grid layout.

#'

#' @details The layout corresponds to a grid of two columns and five rows of unequal dimensions. Most of the

#'   dimension are fixed, only the curve is flexible and will accommodate with the remaining free space.

#'   * The left column gets the annotation of the `ggplot` (y-axis) and the names of the strata for the patient

#'     at risk tabulation. The main constraint is about the width of the columns which must allow the writing of

#'     the strata name.

#'   * The right column receive the `ggplot`, the legend, the x-axis and the patient at risk table.

#'

#' @examples

#' \donttest{

#' library(dplyr)

#' library(survival)

#' library(grid)

#'

#' fit_km <- tern_ex_adtte %>%

#'   filter(PARAMCD == "OS") %>%

#'   survfit(formula = Surv(AVAL, 1 - CNSR) ~ ARMCD, data = .)

#' data_plot <- h_data_plot(fit_km = fit_km)

#' xticks <- h_xticks(data = data_plot)

#' gg <- h_ggkm(

#'   data = data_plot,

#'   censor_show = TRUE,

#'   xticks = xticks, xlab = "Days", ylab = "Survival Probability",

#'   title = "tt", footnotes = "ff", yval = "Survival"

#' )

#' g_el <- h_decompose_gg(gg)

#' lyt <- h_km_layout(data = data_plot, g_el = g_el, title = "t", footnotes = "f")

#' grid.show.layout(lyt)

#' }

#'

#' @export

h_km_layout <- function(data, g_el, title, footnotes, annot_at_risk = TRUE, annot_at_risk_title = TRUE) {

  )

        )

      )

    )

  )

  }

  )