#' Cumulative counts of numeric variable by thresholds

#'

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

#'

#' The analyze function [count_cumulative()] creates a layout element to calculate cumulative counts of values in a

#' numeric variable that are less than, less or equal to, greater than, or greater or equal to user-specified

#' threshold values.

#'

#' This function analyzes numeric variable `vars` against the threshold values supplied to the `thresholds`

#' argument as a numeric vector. Whether counts should include the threshold values, and whether to count

#' values lower or higher than the threshold values can be set via the `include_eq` and `lower_tail`

#' parameters, respectively.

#'

#' @inheritParams h_count_cumulative

#' @inheritParams argument_convention

#' @param thresholds (`numeric`)\cr vector of cutoff values for the counts.

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

#'

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

#'

#' @seealso Relevant helper function [h_count_cumulative()], and descriptive function [d_count_cumulative()].

#'

#' @name count_cumulative

#' @order 1

NULL

#' Helper function for `s_count_cumulative()`

#'

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

#'

#' Helper function to calculate count and fraction of `x` values in the lower or upper tail given a threshold.

#'

#' @inheritParams argument_convention

#' @param threshold (`numeric(1)`)\cr a cutoff value as threshold to count values of `x`.

#' @param lower_tail (`flag`)\cr whether to count lower tail, default is `TRUE`.

#' @param include_eq (`flag`)\cr whether to include value equal to the `threshold` in

#'   count, default is `TRUE`.

#'

#' @return A named vector with items:

#'   * `count`: the count of values less than, less or equal to, greater than, or greater or equal to a threshold

#'     of user specification.

#'   * `fraction`: the fraction of the count.

#'

#' @seealso [count_cumulative]

#'

#' @examples

#' set.seed(1, kind = "Mersenne-Twister")

#' x <- c(sample(1:10, 10), NA)

#' .N_col <- length(x)

#'

#' h_count_cumulative(x, 5, denom = .N_col)

#' h_count_cumulative(x, 5, lower_tail = FALSE, include_eq = FALSE, na_rm = FALSE, denom = .N_col)

#' h_count_cumulative(x, 0, lower_tail = FALSE, denom = .N_col)

#' h_count_cumulative(x, 100, lower_tail = FALSE, denom = .N_col)

#'

#' @export

h_count_cumulative <- function(x,

                               threshold,

                               lower_tail = TRUE,

                               include_eq = TRUE,

                               na_rm = TRUE,

                               denom) {

  }

  )

}

#' Description of cumulative count

#'

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

#'

#' This is a helper function that describes the analysis in [s_count_cumulative()].

#'

#' @inheritParams h_count_cumulative

#'

#' @return Labels for [s_count_cumulative()].

#'

#' @export

d_count_cumulative <- function(threshold, lower_tail = TRUE, include_eq = TRUE) {

}

#' @describeIn count_cumulative Statistics function that produces a named list given a numeric vector of thresholds.

#'

#' @return

#' * `s_count_cumulative()` returns a named list of `count_fraction`s: a list with each `thresholds` value as a

#'   component, each component containing a vector for the count and fraction.

#'

#' @keywords internal

s_count_cumulative <- function(x,

                               thresholds,

                               lower_tail = TRUE,

                               include_eq = TRUE,

                               denom = c("N_col", "n", "N_row"),

                               .N_col, # nolint

                               .N_row, # nolint

                               na_rm = TRUE,

                               ...) {

    )

}

#' @describeIn count_cumulative Formatted analysis function which is used as `afun`

#'   in `count_cumulative()`.

#'

#' @return

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

#'

#' @keywords internal

a_count_cumulative <- function(x,

                               ...,

                               .stats = NULL,

                               .stat_names = NULL,

                               .formats = NULL,

                               .labels = NULL,

                               .indent_mods = NULL) {

  # Check if there are user-defined functions

  # Adding automatically extra parameters to the statistic function (see ?rtables::additional_fun_params)

  )

  # Main statistical functions application

    )

  )

  # Fill in with stats defaults if needed

  )

  # Fill in formats/indents/labels with custom input and defaults

  )

  # Unlist stats

  # Auto format handling

  )

  # Get and check statistical names from defaults

  )

}

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

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

#'

#' @return

#' * `count_cumulative()` 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_count_cumulative()` to the table layout.

#'

#' @examples

#' basic_table() %>%

#'   split_cols_by("ARM") %>%

#'   add_colcounts() %>%

#'   count_cumulative(

#'     vars = "AGE",

#'     thresholds = c(40, 60)

#'   ) %>%

#'   build_table(tern_ex_adsl)

#'

#' @export

#' @order 2

count_cumulative <- function(lyt,

                             vars,

                             thresholds,

                             lower_tail = TRUE,

                             include_eq = TRUE,

                             var_labels = vars,

                             show_labels = "visible",

                             na_str = default_na_str(),

                             nested = TRUE,

                             table_names = vars,

                             ...,

                             na_rm = TRUE,

                             .stats = c("count_fraction"),

                             .stat_names = NULL,

                             .formats = NULL,

                             .labels = NULL,

                             .indent_mods = NULL) {

  # Depending on main functions

    ...

  )

  # Needed defaults

  # Adding all additional information from layout to analysis functions (see ?rtables::additional_fun_params)

  )

  # Main {rtables} structural call

  )

}

#' Univariate formula special term

#'

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

#'

#' The special term `univariate` indicate that the model should be fitted individually for

#' every variable included in univariate.

#'

#' @param x (`character`)\cr a vector of variable names separated by commas.

#'

#' @return When used within a model formula, produces univariate models for each variable provided.

#'

#' @details

#' If provided alongside with pairwise specification, the model

#' `y ~ ARM + univariate(SEX, AGE, RACE)` lead to the study and comparison of the models

#' + `y ~ ARM`

#' + `y ~ ARM + SEX`

#' + `y ~ ARM + AGE`

#' + `y ~ ARM + RACE`

#'

#' @export

univariate <- function(x) {

}

# Get the right-hand-term of a formula

rht <- function(x) {

}

#' Hazard ratio estimation in interactions

#'

#' This function estimates the hazard ratios between arms when an interaction variable is given with

#' specific values.

#'

#' @param variable,given (`character(2)`)\cr names of the two variables in the interaction. We seek the estimation of

#'   the levels of `variable` given the levels of `given`.

#' @param lvl_var,lvl_given (`character`)\cr corresponding levels given by [levels()].

#' @param mmat (named `numeric`) a vector filled with `0`s used as a template to obtain the design matrix.

#' @param coef (`numeric`)\cr vector of estimated coefficients.

#' @param vcov (`matrix`)\cr variance-covariance matrix of underlying model.

#' @param conf_level (`proportion`)\cr confidence level of estimate intervals.

#'

#' @details Given the cox regression investigating the effect of Arm (A, B, C; reference A)

#'   and Sex (F, M; reference Female). The model is abbreviated: y ~ Arm + Sex + Arm x Sex.

#'   The cox regression estimates the coefficients along with a variance-covariance matrix for:

#'

#'   - b1 (arm b), b2 (arm c)

#'   - b3 (sex m)

#'   - b4 (arm b: sex m), b5 (arm c: sex m)

#'

#'   Given that I want an estimation of the Hazard Ratio for arm C/sex M, the estimation

#'   will be given in reference to arm A/Sex M by exp(b2 + b3 + b5)/ exp(b3) = exp(b2 + b5),

#'   therefore the interaction coefficient is given by b2 + b5 while the standard error is obtained

#'   as $1.96 * sqrt(Var b2 + Var b5 + 2 * covariance (b2,b5))$ for a confidence level of 0.95.

#'

#' @return A list of matrices (one per level of variable) with rows corresponding to the combinations of

#'   `variable` and `given`, with columns:

#'   * `coef_hat`: Estimation of the coefficient.

#'   * `coef_se`: Standard error of the estimation.

#'   * `hr`: Hazard ratio.

#'   * `lcl, ucl`: Lower/upper confidence limit of the hazard ratio.

#'

#' @seealso [s_cox_multivariate()].

#'

#' @examples

#' library(dplyr)

#' library(survival)

#'

#' ADSL <- tern_ex_adsl %>%

#'   filter(SEX %in% c("F", "M"))

#'

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

#' adtte$ARMCD <- droplevels(adtte$ARMCD)

#' adtte$SEX <- droplevels(adtte$SEX)

#'

#' mod <- coxph(

#'   formula = Surv(time = AVAL, event = 1 - CNSR) ~ (SEX + ARMCD)^2,

#'   data = adtte

#' )

#'

#' mmat <- stats::model.matrix(mod)[1, ]

#' mmat[!mmat == 0] <- 0

#'

#' @keywords internal

estimate_coef <- function(variable, given,

                          lvl_var, lvl_given,

                          coef,

                          mmat,

                          vcov,

                          conf_level = 0.95) {

    }

  )

    }

  )

  })

  })

  )

}

#' `tryCatch` around `car::Anova`

#'

#' Captures warnings when executing [car::Anova].

#'

#' @inheritParams car::Anova

#'

#' @return A list with item `aov` for the result of the model and `error_text` for the captured warnings.

#'

#' @examples

#' # `car::Anova` on cox regression model including strata and expected

#' # a likelihood ratio test triggers a warning as only Wald method is

#' # accepted.

#'

#' library(survival)

#'

#' mod <- coxph(

#'   formula = Surv(time = futime, event = fustat) ~ factor(rx) + strata(ecog.ps),

#'   data = ovarian

#' )

#'

#' @keywords internal

try_car_anova <- function(mod,

                          test.statistic) { # nolint

          ),

        )

      },

        # If a warning is detected it is handled as "w".

        # A warning is sometimes expected, then, we want to restart

        # the execution while ignoring the warning.

      }

    ),

    }

  )

}

#' Fit a Cox regression model and ANOVA

#'

#' The functions derives the effect p-values using [car::Anova()] from [survival::coxph()] results.

#'

#' @inheritParams t_coxreg

#'

#' @return A list with items `mod` (results of [survival::coxph()]), `msum` (result of `summary`) and

#'   `aov` (result of [car::Anova()]).

#'

#' @noRd

fit_n_aov <- function(formula,

                      data = data,

                      conf_level = conf_level,

                      pval_method = c("wald", "likelihood"),

                      ...) {

    # We expect some warnings due to coxph which fails strict programming.

  })

    )

  )

}

# argument_checks

check_formula <- function(formula) {

  }

}

check_covariate_formulas <- function(covariates) {

  }

}

name_covariate_names <- function(covariates) {

}

check_increments <- function(increments, covariates) {

            )

          )

        }

      }

    )

  }

}

#' Multivariate Cox model - summarized results

#'

#' Analyses based on multivariate Cox model are usually not performed for the Controlled Substance Reporting or

#' regulatory documents but serve exploratory purposes only (e.g., for publication). In practice, the model usually

#' includes only the main effects (without interaction terms). It produces the hazard ratio estimates for each of the

#' covariates included in the model.

#' The analysis follows the same principles (e.g., stratified vs. unstratified analysis and tie handling) as the

#' usual Cox model analysis. Since there is usually no pre-specified hypothesis testing for such analysis,

#' the p.values need to be interpreted with caution. (**Statistical Analysis of Clinical Trials Data with R**,

#' `NEST's bookdown`)

#'

#' @param formula (`formula`)\cr a formula corresponding to the investigated [survival::Surv()] survival model

#'   including covariates.

#' @param data (`data.frame`)\cr a data frame which includes the variable in formula and covariates.

#' @param conf_level (`proportion`)\cr the confidence level for the hazard ratio interval estimations. Default is 0.95.

#' @param pval_method (`string`)\cr the method used for the estimation of p-values, should be one of

#'   `"wald"` (default) or `"likelihood"`.

#' @param ... optional parameters passed to [survival::coxph()]. Can include `ties`, a character string specifying the

#'   method for tie handling, one of `exact` (default), `efron`, `breslow`.

#'

#' @return A `list` with elements `mod`, `msum`, `aov`, and `coef_inter`.

#'

#' @details The output is limited to single effect terms. Work in ongoing for estimation of interaction terms

#'   but is out of scope as defined by the  Global Data Standards Repository

#'   (**`GDS_Standard_TLG_Specs_Tables_2.doc`**).

#'

#' @seealso [estimate_coef()].

#'

#' @examples

#' library(dplyr)

#'

#' adtte <- tern_ex_adtte

#' adtte_f <- subset(adtte, PARAMCD == "OS") # _f: filtered

#' adtte_f <- filter(

#'   adtte_f,

#'   PARAMCD == "OS" &

#'     SEX %in% c("F", "M") &

#'     RACE %in% c("ASIAN", "BLACK OR AFRICAN AMERICAN", "WHITE")

#' )

#' adtte_f$SEX <- droplevels(adtte_f$SEX)

#' adtte_f$RACE <- droplevels(adtte_f$RACE)

#'

#' @keywords internal

s_cox_multivariate <- function(formula, data,

                               conf_level = 0.95,

                               pval_method = c("wald", "likelihood"),

                               ...) {

      }

    }

  )

  # Results directly exported from environment(fit_n_aov) to environment(s_function_draft)

    ...

  )

      )

    }

      }

    )

  }

}

#' 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 <- function(df,

                         ...,

                         .stats = NULL,

                         .stat_names = NULL,

                         .formats = NULL,

                         .labels = NULL,

                         .indent_mods = NULL) {

  # Check for additional parameters to the statistics function

  # Check for user-defined functions

  # Apply statistics function

    )

  )

  # Fill in formatting defaults

  )

  )

  # Auto format handling

  # Get and check statistical names

  )

}

#' @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,

                                method = "exact",

                                na_str = default_na_str(),

                                nested = TRUE,

                                ...,

                                table_names = vars,

                                show_labels = "hidden",

                                var_labels = vars,

                                .stats = "or_ci",

                                .stat_names = NULL,

                                .formats = NULL,

                                .labels = NULL,

                                .indent_mods = NULL) {

  # Process standard extra arguments

  # Process additional arguments to the statistic function

    ...

  )

  # Append additional info from layout to the analysis function

  )

}

#' 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.

    )

  }

}

# summarize_glm_count ----------------------------------------------------------

#' Summarize Poisson negative binomial regression

#'

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

#'

#' Summarize results of a Poisson negative binomial regression.

#' This can be used to analyze count and/or frequency data using a linear model.

#' It is specifically useful for analyzing count data (using the Poisson or Negative

#' Binomial distribution) that is result of a generalized linear model of one (e.g. arm) or more

#' covariates.

#'

#' @inheritParams h_glm_count

#' @inheritParams argument_convention

#' @param rate_mean_method (`character(1)`)\cr method used to estimate the mean odds ratio. Defaults to `emmeans`.

#'   see details for more information.

#' @param scale (`numeric(1)`)\cr linear scaling factor for rate and confidence intervals. Defaults to `1`.

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

#'

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

#'

#' @details

#' `summarize_glm_count()` uses `s_glm_count()` to calculate the statistics for the table. This

#' analysis function uses [h_glm_count()] to estimate the GLM with [stats::glm()] for Poisson and Quasi-Poisson

#' distributions or [MASS::glm.nb()] for Negative Binomial distribution. All methods assume a

#' logarithmic link function.

#'

#' At this point, rates and confidence intervals are estimated from the model using

#' either [emmeans::emmeans()] when `rate_mean_method = "emmeans"` or [h_ppmeans()]

#' when `rate_mean_method = "ppmeans"`.

#'

#' If a reference group is specified while building the table with `split_cols_by(ref_group)`,

#' no rate ratio or `p-value` are calculated. Otherwise, we use [emmeans::contrast()] to

#' calculate the rate ratio and `p-value` for the reference group. Values are always estimated

#' with `method = "trt.vs.ctrl"` and `ref` equal to the first `arm` value.

#'

#' @name summarize_glm_count

NULL

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

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

#'

#' @return

#' * `summarize_glm_count()` 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_glm_count()` to the table layout.

#'

#' @examples

#' library(dplyr)

#'

#' anl <- tern_ex_adtte %>% filter(PARAMCD == "TNE")

#' anl$AVAL_f <- as.factor(anl$AVAL)

#'

#' lyt <- basic_table() %>%

#'   split_cols_by("ARM", ref_group = "B: Placebo") %>%

#'   add_colcounts() %>%

#'   analyze_vars(

#'     "AVAL_f",

#'     var_labels = "Number of exacerbations per patient",

#'     .stats = c("count_fraction"),

#'     .formats = c("count_fraction" = "xx (xx.xx%)"),

#'     .labels = c("Number of exacerbations per patient")

#'   ) %>%

#'   summarize_glm_count(

#'     vars = "AVAL",

#'     variables = list(arm = "ARM", offset = "lgTMATRSK", covariates = NULL),

#'     conf_level = 0.95,

#'     distribution = "poisson",

#'     rate_mean_method = "emmeans",

#'     var_labels = "Adjusted (P) exacerbation rate (per year)",

#'     table_names = "adjP",

#'     .stats = c("rate"),

#'     .labels = c(rate = "Rate")

#'   ) %>%

#'   summarize_glm_count(

#'     vars = "AVAL",

#'     variables = list(arm = "ARM", offset = "lgTMATRSK", covariates = c("REGION1")),

#'     conf_level = 0.95,

#'     distribution = "quasipoisson",

#'     rate_mean_method = "ppmeans",

#'     var_labels = "Adjusted (QP) exacerbation rate (per year)",

#'     table_names = "adjQP",

#'     .stats = c("rate", "rate_ci", "rate_ratio", "rate_ratio_ci", "pval"),

#'     .labels = c(

#'       rate = "Rate", rate_ci = "Rate CI", rate_ratio = "Rate Ratio",

#'       rate_ratio_ci = "Rate Ratio CI", pval = "p value"

#'     )

#'   ) %>%

#'   summarize_glm_count(

#'     vars = "AVAL",

#'     variables = list(arm = "ARM", offset = "lgTMATRSK", covariates = c("REGION1")),

#'     conf_level = 0.95,

#'     distribution = "negbin",

#'     rate_mean_method = "emmeans",

#'     var_labels = "Adjusted (NB) exacerbation rate (per year)",

#'     table_names = "adjNB",

#'     .stats = c("rate", "rate_ci", "rate_ratio", "rate_ratio_ci", "pval"),

#'     .labels = c(

#'       rate = "Rate", rate_ci = "Rate CI", rate_ratio = "Rate Ratio",

#'       rate_ratio_ci = "Rate Ratio CI", pval = "p value"

#'     )

#'   )

#'

#' build_table(lyt = lyt, df = anl)

#'

#' @export

summarize_glm_count <- function(lyt,

                                vars,

                                variables,

                                distribution,

                                conf_level,

                                rate_mean_method = c("emmeans", "ppmeans")[1],

                                weights = stats::weights,

                                scale = 1,

                                var_labels,

                                na_str = default_na_str(),

                                nested = TRUE,

                                ...,

                                show_labels = "visible",

                                table_names = vars,

                                .stats = c("n", "rate", "rate_ci", "rate_ratio", "rate_ratio_ci", "pval"),

                                .stat_names = NULL,

                                .formats = NULL,

                                .labels = NULL,

                                .indent_mods = list("rate_ci" = 1L, "rate_ratio_ci" = 1L, "pval" = 1L)) {

  # Process standard extra arguments

  # Process additional arguments to the statistic function

    ...

  )

  # Append additional info from layout to the analysis function

  )

}

#' @describeIn summarize_glm_count Statistics function that produces a named list of results

#'   of the investigated Poisson model.

#'

#' @return

#' * `s_glm_count()` returns a named `list` of 5 statistics:

#'   * `n`: Count of complete sample size for the group.

#'   * `rate`: Estimated event rate per follow-up time.

#'   * `rate_ci`: Confidence level for estimated rate per follow-up time.

#'   * `rate_ratio`: Ratio of event rates in each treatment arm to the reference arm.

#'   * `rate_ratio_ci`: Confidence level for the rate ratio.

#'   * `pval`: p-value.

#'

#' @keywords internal

s_glm_count <- function(df,

                        .var,

                        .df_row,

                        .ref_group,

                        .in_ref_col,

                        variables,

                        distribution,

                        conf_level,

                        rate_mean_method,

                        weights,

                        scale = 1,

                        ...) {

  # ensure there is only 1 value

  )

  }

  # This happens if there is a reference col. No Ratio is calculated?

      ),

      ),

    )

  } else {

      )

    )

    )

        ),

      ),

      ),

      ),

      ),

      )

    )

  }

}

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

#'

#' @return

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

#'

#' @keywords internal

a_glm_count <- function(df,

                        ...,

                        .stats = NULL,

                        .stat_names = NULL,

                        .formats = NULL,

                        .labels = NULL,

                        .indent_mods = NULL) {

  # Check for additional parameters to the statistics function

  # Check for user-defined functions

  # Apply statistics function

    )

  )

  # Fill in formatting defaults

  )

  # Auto format handling

  # Get and check statistical names

  )

}

# h_glm_count ------------------------------------------------------------------

#' Helper functions for Poisson models

#'

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

#'

#' Helper functions that returns the results of [stats::glm()] when Poisson or Quasi-Poisson

#' distributions are needed (see `family` parameter), or [MASS::glm.nb()] for Negative Binomial

#' distributions. Link function for the GLM is `log`.

#'

#' @inheritParams argument_convention

#'

#' @seealso [summarize_glm_count]

#'

#' @name h_glm_count

NULL

#' @describeIn h_glm_count Helper function to return the results of the

#'   selected model (Poisson, Quasi-Poisson, negative binomial).

#'

#' @param .df_row (`data.frame`)\cr dataset that includes all the variables that are called

#'   in `.var` and `variables`.

#' @param variables (named `list` of `string`)\cr list of additional analysis variables, with

#'   expected elements:

#'   * `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple

#'     groups will be summarized. Specifically, the first level of `arm` variable is taken as the

#'     reference group.

#'   * `covariates` (`character`)\cr a vector that can contain single variable names (such as

#'     `"X1"`), and/or interaction terms indicated by `"X1 * X2"`.

#'   * `offset` (`numeric`)\cr a numeric vector or scalar adding an offset.

#' @param distribution (`character`)\cr a character value specifying the distribution

#'   used in the regression (Poisson, Quasi-Poisson, negative binomial).

#' @param weights (`character`)\cr a character vector specifying weights used

#'   in averaging predictions. Number of weights must equal the number of levels included in the covariates.

#'   Weights option passed to [emmeans::emmeans()].

#'

#' @return

#' * `h_glm_count()` returns the results of the selected model.

#'

#' @keywords internal

h_glm_count <- function(.var,

                        .df_row,

                        variables,

                        distribution,

                        weights) {

  )

}

#' @describeIn h_glm_count Helper function to return results of a Poisson model.

#'

#' @return

#' * `h_glm_poisson()` returns the results of a Poisson model.

#'

#' @keywords internal

h_glm_poisson <- function(.var,

                          .df_row,

                          variables,

                          weights) {

    " + ",

    " + ",

  ))