Package {junco}

Custom unlist function

Description

Unlist a list, but retain NULL as 'NULL' or NA.

Usage

.unlist_keep_nulls(lst, null_placeholder = "NULL", recursive = FALSE)

Combined Proportion, Risk Difference, and Risk Difference Test Analysis Function with Method Selection Based on the Mantel-Fleiss Criterion

Description

Performs a combined analysis of proportions, treatment-vs-control risk differences, and tests of risk differences.

The method used for the risk difference and risk difference test is selected based on the Mantel-Fleiss criterion. If the Mantel-Fleiss (MF) criterion is satisfied, the Cochran-Mantel-Haenszel (CMH) method with Sato variance is used for both the risk difference and the corresponding statistical test.

If the Mantel-Fleiss criterion is not satisfied, an exact method is used. Specifically, the exact unconditional method is used for estimation of the risk difference, and Fisher's exact test is used for the hypothesis test.

Usage

a_combo_prop_diff_pval_mf(
  df,
  .var,
  .df_row,
  .spl_context,
  val,
  colpaths,
  id = "USUBJID",
  trt_var,
  ctrl_group,
  variables = list(strata = NULL),
  mf_threshold = NULL,
  conf_level = 0.95,
  alternative = c("two.sided", "less", "greater"),
  exact_footnote = rtables::RefFootnote("Exact Inference", 1L, "+"),
  .stats = NULL,
  .formats = NULL,
  ...
)

Arguments

Details

The analysis function determines which type of result to calculate based on the current column path specified by colpaths.

• "prop": calculates and displays the proportion for the current analysis facet.

• "diff": calculates the treatment-vs-control proportion difference.

• "pval": calculates the treatment-vs-control p-value.

For proportion columns, a_freq_j() is used. For risk difference and p-value columns, the control group is identified from .df_row using trt_var and ctrl_group, and the corresponding a_proportion_diff_mf() or a_test_proportion_diff_mf() function is called.

The current column is identified using in_column() against each element of colpaths list. If the current column does not correspond to any of the configured prop, diff, or pval paths, an empty rtables::rcell().

The function first determines the current row label from .spl_context. If the current split represents the root of the analysis, the label "Full analysis set" is used; otherwise, the value of the leaf split is used.

Value

Returns the corresponding CellValue or RowsVerticalSection object with formatted results.

Author(s)

WW

See Also

a_freq_j(), a_proportion_diff_mf(), a_test_proportion_diff_mf(),

Examples

library(dplyr)

adrs_f <- formatters::ex_adrs |>
  filter(
    ARM %in% c("A: Drug X", "B: Placebo"),
    PARAMCD == "BESRSPI"
  ) |>
  droplevels() |>
  mutate(
    rsp = factor(ifelse(AVALC == "CR", "Y", "N")),
    ARM_FOR_RISKCOLS = ARM # Required for Risk Difference and p-value columns
  )

riskcols_combodf <- tribble(
  ~valname, ~label, ~levelcombo, ~exargs,
  "diff", "Risk Difference", "A: Drug X", list(),
  "pval", "p-value", "B: Placebo", list()
)

col_split_fun <- add_combo_levels(
  riskcols_combodf,
  keep_levels = riskcols_combodf$valname
)

# Additional arguments for a_combo_prop_diff_pval_mf().
extra_args <- list(
  colpaths = list(
    prop = c("ARM", "*"),
    diff = c("ARM_FOR_RISKCOLS", "diff"),
    pval = c("ARM_FOR_RISKCOLS", "pval")
  ),
  id = "SUBJID",
  trt_var = "ARM",
  ctrl_group = "B: Placebo",
  val = "Y",
  variables = list(strata = "BMRKR2"),
  .stats = list(diff = "diff")
)

lyt <- basic_table(top_level_section_div = " ") |>
  split_cols_by("ARM") |>
  split_cols_by(
    "ARM_FOR_RISKCOLS",
    split_fun = col_split_fun,
    nested = FALSE
  ) |>
  analyze(
    "rsp",
    afun = a_combo_prop_diff_pval_mf,
    extra_args = extra_args
  ) |>
  split_rows_by(
    var = "SEX",
    split_label = "Gender",
    child_labels = "hidden",
    label_pos = "visible"
  ) |>
  analyze(
    vars = "rsp",
    afun = a_combo_prop_diff_pval_mf,
    extra_args = extra_args,
    show_labels = "hidden"
  )

tbl <- build_table(lyt, adrs_f)
tbl

Conditional proportion with adaptive CI (exact vs. Wald)

Description

Usage

a_cond_proportion_j(
  df,
  .var,
  ...,
  .stats = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL,
  .df_row = NULL
)

s_cond_proportion_j(
  df,
  .var,
  conf_level = 0.95,
  long = FALSE,
  na.rm = FALSE,
  num_limit = 0,
  denom_limit = 10,
  denom = c("n", "N_row"),
  method_scope = c("cell", "row"),
  .df_row = NULL
)

d_cond_proportion_j(
  conf_level,
  long = FALSE,
  num_limit = NULL,
  denom_limit = NULL,
  method = NULL,
  method_denom = NULL,
  method_rsp = NULL
)

Arguments

Details

The analysis function a_cond_proportion_j() is used to create a layout element that estimates a response proportion with confidence interval, automatically selecting between exact and Wald methods based on observed counts and user-defined limits.

The statistics function mirrors tern::s_proportion() usage and output but removes the method argument and decides internally between "clopper-pearson" and "wald".

The exact method is used when any of these are true: (a) the number of responders is num_limit (or less), (b) all subjects except num_limit (or less) have observed response, or (c) the observed group size is less than denom_limit.

Depending on the method_scope choice, this decision is either taken based on the response data for an individual cell (method_scope = "cell"), or based on the response data for the entire row (method_scope = "row"):

• With method_scope = "cell", the counts used for the decision are:

  • numerator: the number of responders in the current cell;

  • denominator: the total number of observations in the cell (using df) if denom = "n", or across the row (using .df_row) if denom = "N_row".

• With method_scope = "row", the counts used for the decision are:

  • numerator: the total number of responders across the row (using .df_row);

  • denominator: the total number of observations across the row (from .df_row).

CI computation follows tern::s_proportion() conventions: helper functions are called with n = denom, so when denom = "N_row", this row-level denominator is used for the interval.

Value

• a_cond_proportion_j() returns the corresponding list with formatted rtables::CellValue().

• s_cond_proportion_j() returns statistics n_prop (n responders and proportion) and prop_ci (proportion CI), formatted consistently with tern::s_proportion().

• d_cond_proportion_j() returns a string describing the analysis label.

Functions

• a_cond_proportion_j(): Formatted analysis function which is used as afun for conditional proportion with adaptive CI selection (exact vs. Wald).

• s_cond_proportion_j(): Statistics function estimating a proportion along with its confidence interval, with adaptive method selection.

• d_cond_proportion_j(): Description helper function for the conditional proportion summary label.

Examples

nex <- 100
dta <- data.frame(
  "rsp" = sample(c(TRUE, FALSE), nex, TRUE),
  "grp" = sample(c("A", "B"), nex, TRUE),
  "f1"  = sample(c("a1", "a2"), nex, TRUE),
  stringsAsFactors = TRUE
)

l <- basic_table() |>
  split_cols_by(var = "grp") |>
  analyze(
    vars = "rsp",
    afun = a_cond_proportion_j,
    extra_args = list(
      conf_level = 0.90,
      num_limit = 0,
      denom_limit = 10
    )
  )

build_table(l, df = dta)

# Logical vector input
rsp_v <- c(TRUE, FALSE, TRUE, TRUE, FALSE, TRUE, FALSE, FALSE)
s_cond_proportion_j(rsp_v)

# Data frame input
dta <- data.frame(rsp = c(TRUE, TRUE, FALSE, TRUE, FALSE, NA))
s_cond_proportion_j(dta, .var = "rsp", na.rm = TRUE)

# Using method_scope = "row" (requires .df_row in ...)
df_row <- data.frame(rsp = rep(rsp_v, 2))
s_cond_proportion_j(
  dta, .var = "rsp", method_scope = "row",
  .df_row = df_row, na.rm = TRUE
)

d_cond_proportion_j(conf_level = 0.90, long = FALSE, num_limit = 0, denom_limit = 10)

# With dedicated row-wise method:
d_cond_proportion_j(
  conf_level = 0.90, long = TRUE, num_limit = 0, denom_limit = 10,
  method = "wald", method_denom = 10, method_rsp = 8)

a_coxph_hr

Description

a_coxph_hr Use tern:::a_coxph_pairwise()⁠instead, and use⁠tern::coxph_pairwise()' as the layout-level wrapper.

Usage

a_coxph_hr(
  df,
  .var,
  ref_path,
  .spl_context,
  ...,
  .stats = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Exposure-Adjusted Incidence Rate

Description

Statistical/Analysis Function for presenting Exposure-Adjusted Incidence Rate summary data

Usage

s_eair100_levii_j(
  levii,
  df,
  .df_row,
  .var,
  .alt_df_full = NULL,
  id = "USUBJID",
  fup_var,
  occ_var,
  occ_dy,
  num_p_year = 100,
  count_multiple_events = FALSE,
  conf_level = 0.95,
  conf_type_diff = c("wald", "waldcc", "mn", "scas"),
  conf_type_eair = c("exact", "normal", "normal_log", "byar"),
  vs_ref_group = FALSE,
  .in_ref_col,
  cur_col_expr,
  ref_col_expr,
  inriskdiffcol = FALSE
)

a_eair100_j(
  df,
  labelstr = NULL,
  .var,
  .df_row,
  .spl_context,
  .alt_df_full = NULL,
  id = "USUBJID",
  fup_var,
  occ_var,
  occ_dy = NULL,
  num_p_year = 100,
  count_multiple_events = FALSE,
  drop_levels = FALSE,
  riskdiff = TRUE,
  ref_path = NULL,
  .stats = c("eair"),
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL,
  na_str = rep("NA", 3),
  conf_level = 0.95,
  conf_type_diff = c("wald", "waldcc", "mn", "scas"),
  conf_type_eair = c("normal", "normal_log", "exact", "byar"),
  row_labels_adj = FALSE,
  riskdiff_setup = c("horizontal", "vertical")
)

Arguments

Details

The exposure-adjusted incidence rate (EAIR) is defined as:

• When (occ_var not NULL) or count_multiple_events = FALSE:
  the number of subjects with at least one occurrence of a specified adverse event divided by the total at-risk exposure time across all subjects.

• When occ_var = NULL and count_multiple_events = TRUE:
  the total number of events across of a specified adverse event divided by the total at-risk exposure time across all subjects.

Total at-risk exposure time is calculated for each subject as:

• When occ_var not NULL

  • for subjects with the event: relative day (from the start of exposure) of the onset date of the first occurrence of the specified event (occ_var and occ_dy), transformed from days into years as occ_dy/365.25, or

  • for subjects without the event: total duration of follow-up (expressed in years) (e.g., treatment discontinuation, completion, or censoring) (fup_var).

• When occ_var = NULL
  for all subjects: total duration of follow-up (expressed in years) (e.g., treatment discontinuation, completion, or censoring) (fup_var).

The EAIR is expressed as:

\mathrm{EAIR} = \hat r = \frac{n}{T}

where:

• n is the number of subjects with at least one occurrence of the event

• T = \sum_{i=1}^{N} t_i, with

• t_i is the at-risk exposure time for subject i, expressed in subject-years

The difference between two EAIRs is \hat \theta = (\hat r_1 - \hat r_2).

Wald's method for the confidence interval approximation is used (Liu et al., 2006), which uses the standard error

\mathrm{se}(\hat r_1 - \hat r_2) = \sqrt{\frac{n_1}{T_1^2} + \frac{n_2}{T_2^2}}

and the 100(1-\alpha)\% confidence interval is

(\hat r_1 - \hat r_2) \pm z_{1-\alpha/2}\,\mathrm{se}(\hat r_1 - \hat r_2)

where z_{1-\alpha/2} is the standard normal quantile. 1

Other methods for confidence interval for difference can be specified in conf_type_diff argument.

EAIR is commonly reported per 100 subject-years:

\mathrm{EAIR}_{100} = 100 \times \hat r

Value

• s_eair100_levii_j() returns a list containing the following statistics:

  • n_event: Number of subjects with the event, or total event count if count_multiple_events = TRUE

  • person_years: Total person-years of follow-up

  • eair: Exposure-adjusted incidence rate per num_p_year person-years

  • n_eair: Combination of n_event and eair statistics.

  • eair_n: Combination of eair and n_event statistics.

  • eair_n_py: Combination of eair, n_event and person_years statistics.

  • eair_ci: Confidence interval for eair, method specified in conf_type_eair.

  • eair_est_ci: Combination of eair and eair_ci.

  • eair_diff_est: Difference in EAIR between current group and reference group (if diff=TRUE and inriskdiffcol=TRUE)

  • eair_diff_ci: Confidence interval for difference in EAIR between current group and reference group (if diff=TRUE and inriskdiffcol=TRUE)

  • eair_diff_est_ci: Combination of eair_diff_est and eair_diff_ci.

  The list of available statistics (core columns) can also be viewed by running junco_get_stats("a_eair100_j").

• a_eair100_j returns the corresponding list with formatted rtables::CellValue().
  Within a risk difference column, the statistics eair and n_eair are replaced by eair_diff_est_ci (difference in EAIR between current group and reference group, together with it's confidence interval).

Functions

• s_eair100_levii_j(): calculates exposure-adjusted incidence rates (EAIR) per num_p_year person-years for a specific level of a variable.

• a_eair100_j(): Formatted analysis function for exposure adjusted incidence rate summary which is used as afun in analyze or cfun in summarize_row_groups.
  

References

Liu, G. F., Wang, J., Liu, K., and Snavely, D. B. (2006). Confidence intervals for an exposure adjusted incidence rate difference with applications to clinical trials. Statistics in Medicine, 25(8), 1275–1286. doi:10.1002/sim.2335

Examples

library(tern)
library(dplyr)
trtvar <- "ARM"
ctrl_grp <- "B: Placebo"
cutoffd <- as.Date("2023-09-24")


adexsum <- ex_adsl |>
  create_colspan_var(
    non_active_grp          = ctrl_grp,
    non_active_grp_span_lbl = " ",
    active_grp_span_lbl     = "Active Study Agent",
    colspan_var             = "colspan_trt",
    trt_var                 = trtvar
  ) |>
  mutate(
    rrisk_header = "Risk Difference (95% CI)",
    rrisk_label = paste(!!rlang::sym(trtvar), "vs", ctrl_grp),
    TRTDURY = case_when(
      !is.na(EOSDY) ~ EOSDY,
      TRUE ~ as.integer(cutoffd - as.Date(TRTSDTM) + 1)
    )
  ) |>
  select(USUBJID, !!rlang::sym(trtvar), colspan_trt, rrisk_header, rrisk_label, TRTDURY)

adexsum$TRTDURY <- as.numeric(adexsum$TRTDURY)

adae <- ex_adae |>
  group_by(USUBJID, AEDECOD) |>
  select(USUBJID, AEDECOD, ASTDY) |>
  mutate(rwnum = row_number()) |>
  mutate(AOCCPFL = case_when(
    rwnum == 1 ~ "Y",
    TRUE ~ NA
  )) |>
  filter(AOCCPFL == "Y")

aefup <- left_join(adae, adexsum, by = "USUBJID")

colspan_trt_map <- create_colspan_map(adexsum,
  non_active_grp = ctrl_grp,
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = trtvar
)

ref_path <- c("colspan_trt", " ", trtvar, ctrl_grp)

################################################################################
# Define layout and build table:
################################################################################

lyt <- basic_table(show_colcounts = TRUE, colcount_format = "N=xx", top_level_section_div = " ") |>
  split_cols_by("colspan_trt", split_fun = trim_levels_to_map(map = colspan_trt_map)) |>
  split_cols_by(trtvar) |>
  split_cols_by("rrisk_header", nested = FALSE) |>
  split_cols_by(trtvar, labels_var = "rrisk_label", split_fun = remove_split_levels(ctrl_grp)) |>
  analyze("TRTDURY",
    show_labels = "hidden",
    afun = a_patyrs_j
  ) |>
  analyze(
    vars = "AEDECOD",
    afun = a_eair100_j,
    extra_args = list(
      fup_var = "TRTDURY",
      occ_var = "AOCCPFL",
      occ_dy = "ASTDY",
      ref_path = ref_path,
      drop_levels = TRUE
    )
  )

result <- build_table(lyt, aefup, alt_counts_df = adexsum)
head(result, 5)

Stratified Exposure-Adjusted Incidence Rate (EAIR)

Description

Statistical/Analysis function for presenting a stratified exposure-adjusted incidence rate (EAIR) and its Wald confidence interval across strata (e.g., study size weighted exposure).

This function is an extension to the unstratified function a_eair100_j().

Usage

s_eair_strat_levii_j(
  levii,
  df,
  .df_row,
  .alt_df_full,
  .var,
  strata,
  id = "USUBJID",
  fup_var,
  occ_var = NULL,
  occ_dy = NULL,
  num_p_year = 100,
  count_multiple_events = FALSE,
  conf_level = 0.95,
  vs_ref_group = FALSE,
  .in_ref_col,
  cur_col_expr,
  ref_col_expr,
  inriskdiffcol = FALSE
)

a_eair_strat_j(
  df,
  labelstr = NULL,
  .var,
  .df_row,
  .spl_context,
  .alt_df_full = NULL,
  id = "USUBJID",
  strata,
  fup_var,
  occ_var = NULL,
  occ_dy = NULL,
  num_p_year = 100,
  count_multiple_events = FALSE,
  drop_levels = FALSE,
  riskdiff = FALSE,
  ref_path = NULL,
  conf_level = 0.95,
  .stats = "eair_strat",
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL,
  na_str = rep("NA", 3),
  row_labels_adj = FALSE,
  riskdiff_setup = c("horizontal", "vertical")
)

Arguments

Details

The weighting method uses raw event counts n_ti in both the rate and variance.

\hat r_{ti} = \texttt{num\_p\_year} \times \frac{n_{ti}}{T_{ti}}

The strata weight is w_i = T_0i + T_1i (total person-years across all groups in strata i), and the pooled weighted rate is:

\hat r_t = \sum_i \frac{w_i}{W} \hat r_{ti}, \quad W = \sum_i w_i

The Wald 95% CI for the pooled rate is:

\hat r_t \pm z_{1-\alpha/2} \times \frac{\texttt{num\_p\_year}}{W} \sqrt{\sum_i w_i^2 \frac{n_{ti}}{T_{ti}^2}}

.

The weighted rate difference and its Wald CI are:

\hat\delta = \sum_i \frac{w_i}{W}(\hat r_{1i} - \hat r_{0i})

\hat\delta \pm z_{1-\alpha/2} \times \frac{\texttt{num\_p\_year}}{W} \sqrt{\sum_i w_i^2 \left(\frac{n_{1i}+c}{T_{1i}^2} + \frac{n_{0i}}{T_{0i}^2}\right)}

Value

• s_eair_strat_levii_j() returns a list containing the following statistics:

• n_event_total: total event count across strata (current arm)

• person_years_total: total person-years across strata (current arm)

• eair_strat: stratified pooled EAIR per num_p_year person-years

• n_eair_strat: composite of n_event_total and eair_strat

• eair_strat_ci: Wald CI for eair_strat

• eair_strat_est_ci: composite of eair_strat and eair_strat_ci

• eair_strat_n: composite of eair_strat and n_event_total

• eair_strat_n_py: composite of eair_strat, n_event_total and person_years_total

• eair_strat_diff_est_ci: stratified rate difference with Wald CI (only when vs_ref_group = TRUE, otherwise NULL)

• eair_strat_diff_est: estimate for the difference in stratified rate

• eair_strat_diff_ci: CI (Wald type) for the difference in stratified rate

The list of available statistics (core columns) can also be viewed by running junco_get_stats("a_eair_strat_j").

• a_eair_strat_j() returns a list of formatted rtables::CellValue() rows. Within a risk difference column, the statistics eair_strat and n_eair_strat are replaced by eair_strat_diff_est_ci (difference in EAIR between current group and reference group, together with it's confidence interval).

Functions

• a_eair_strat_j(): Formatted analysis function for stratified (eg study size-weighted) EAIR, used as afun in rtables::analyze().

References

Scosyrev, E & Pethe, A (2022). Confidence intervals for exposure-adjusted rate differences in randomized trials. Pharmaceutical Statistics, 2022;21:103–121. doi: 10.1002/pst.2155

Crowe, B., Chuang-Stein, C., Lettis, S., & Brueckner, A. (2016). Reporting adverse drug reactions in product labels. Therapeutic Innovation & Regulatory Science, 50(4), 455-463. doi: 10.1177/2168479016628574

See Also

a_eair100_j()

Examples

library(tern)
library(dplyr)

set.seed(42)
n <- 120
adsl <- data.frame(
  USUBJID = paste0("S", seq_len(n)),
  ARM = rep(c("Treatment", "Placebo"), each = n / 2),
  STUDY = rep(c("Study1", "Study2", "Study3"), times = n / 3),
  TRTDURY = runif(n, 0.5, 3),
  stringsAsFactors = FALSE
)
adae <- data.frame(
  USUBJID = sample(adsl$USUBJID, 40),
  AEDECOD = "Headache",
  ASTDY = sample(30:500, 40, replace = TRUE),
  AOCCPFL = "Y",
  stringsAsFactors = FALSE
)
aefup <- merge(adae, adsl, by = "USUBJID")

# Standard method (matches rdcomaeinci SAS macro)
lyt <- basic_table() |>
  split_cols_by("ARM") |>
  analyze(
    "AEDECOD",
    afun = a_eair_strat_j,
    extra_args = list(
      strata = "STUDY",
      fup_var = "TRTDURY",
      occ_var = "AOCCPFL",
      occ_dy = "ASTDY",
      .stats = c("eair_strat", "eair_strat_ci")
    )
  )
result <- build_table(lyt, aefup, alt_counts_df = adsl)
result

Analysis function count and percentage in column design controlled by combosdf

Description

Analysis function count and percentage in column design controlled by combosdf

Usage

a_freq_combos_j(
  df,
  labelstr = NULL,
  .var = NA,
  val = NULL,
  combosdf = NULL,
  do_not_filter = NULL,
  filter_var = NULL,
  flag_var = NULL,
  .df_row,
  .spl_context,
  .N_col,
  id = "USUBJID",
  denom = c("N_col", "n_df", "n_altdf", "n_rowdf", "n_parentdf"),
  label = NULL,
  label_fstr = NULL,
  label_map = NULL,
  .alt_df_full = NULL,
  denom_by = NULL,
  .stats = "count_unique_denom_fraction",
  .formats = NULL,
  .labels_n = NULL,
  .indent_mods = NULL,
  na_str = rep("NA", 3)
)

Arguments

Value

list of requested statistics with formatted rtables::CellValue().

See Also

a_freq_j() for extensive label_map usage examples.

Examples

library(dplyr)
ADSL <- ex_adsl |> select(USUBJID, ARM, EOSSTT, EOSDT, EOSDY, TRTSDTM)

cutoffd <- as.Date("2023-09-24")

ADSL <- ADSL |>
  mutate(
    TRTDURY = case_when(
      !is.na(EOSDY) ~ EOSDY,
      TRUE ~ as.integer(cutoffd - as.Date(TRTSDTM) + 1)
    )
  ) |>
  mutate(ACAT1 = case_when(
    TRTDURY < 183 ~ "0-6 Months",
    TRTDURY < 366 ~ "6-12 Months",
    TRUE ~ "+12 Months"
  )) |>
  mutate(ACAT1 = factor(ACAT1, levels = c("0-6 Months", "6-12 Months", "+12 Months")))


ADAE <- ex_adae |> select(USUBJID, ARM, AEBODSYS, AEDECOD, ASTDY)

ADAE <- ADAE |>
  mutate(TRTEMFL = "Y") |>
  mutate(ACAT1 = case_when(
    ASTDY < 183 ~ "0-6 Months",
    ASTDY < 366 ~ "6-12 Months",
    TRUE ~ "+12 Months"
  )) |>
  mutate(ACAT1 = factor(ACAT1, levels = c("0-6 Months", "6-12 Months", "+12 Months")))

combodf <- tribble(
  ~valname, ~label, ~levelcombo, ~exargs,
  "Tot", "Total", c("0-6 Months", "6-12 Months", "+12 Months"), list(),
  "A_0-6 Months", "0-6 Months", c("0-6 Months", "6-12 Months", "+12 Months"), list(),
  "B_6-12 Months", "6-12 Months", c("6-12 Months", "+12 Months"), list(),
  "C_+12 Months", "+12 Months", c("+12 Months"), list()
)


lyt <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("ARM") |>
  split_cols_by("ACAT1",
    split_fun = rtables::add_combo_levels(
      combosdf = combodf,
      trim = FALSE, keep_levels = combodf$valname
    )
  ) |>
  analyze("TRTEMFL",
    show_labels = "hidden",
    afun = a_freq_combos_j,
    extra_args = list(
      val = "Y",
      label = "Subjects with >= 1 AE",
      combosdf = combodf,
      filter_var = "ACAT1",
      do_not_filter = "Tot"
    )
  )


result <- build_table(lyt, df = ADAE, alt_counts_df = ADSL)

result

Analysis/statistical function for count and percentage in core columns and (optional) relative risk columns

Description

Analysis/statistical function for count and percentage in core columns and (optional) relative risk columns

Usage

s_freq_j(
  df,
  .var,
  .df_row,
  val = NULL,
  drop_levels = FALSE,
  excl_levels = NULL,
  alt_df,
  parent_df,
  id = "USUBJID",
  denom = c("n_df", "n_altdf", "N_col", "n_rowdf", "n_parentdf"),
  .N_col,
  countsource = c("df", "altdf", "altdf_subset")
)

a_freq_j(
  df,
  labelstr = NULL,
  .var = NA,
  val = NULL,
  drop_levels = FALSE,
  excl_levels = NULL,
  new_levels = NULL,
  new_levels_after = FALSE,
  addstr2levs = NULL,
  .df_row,
  .spl_context,
  .N_col,
  id = "USUBJID",
  denom = c("N_col", "n_df", "n_altdf", "N_colgroup", "n_rowdf", "n_parentdf"),
  riskdiff = TRUE,
  ref_path = NULL,
  variables = list(strata = NULL),
  conf_level = 0.95,
  method = c("wald", "waldcc", "cmh", "ha", "newcombe", "newcombecc", "strat_newcombe",
    "strat_newcombecc", "cmh_sato", "cmh_mn", "uncond_exact_diff"),
  weights_method = "cmh",
  label = NULL,
  label_fstr = NULL,
  label_map = NULL,
  .alt_df_full = NULL,
  denom_by = NULL,
  .stats = "count_unique_denom_fraction",
  .formats = NULL,
  .indent_mods = NULL,
  na_str = rep("NA", 3),
  .labels_n = NULL,
  extrablankline = FALSE,
  extrablanklineafter = NULL,
  restr_columns = NULL,
  colgroup = NULL,
  countsource = c("df", "altdf", "altdf_subset")
)

a_freq_j_with_exclude(
  df,
  labelstr = NULL,
  exclude_levels,
  .var = NA,
  .spl_context,
  .df_row,
  .N_col,
  .alt_df_full = NULL,
  .stats = "count_unique_denom_fraction",
  .formats = NULL,
  .indent_mods = NULL,
  .labels_n = NULL,
  ...
)

Arguments

Details

denom controls the denominator used to calculate proportions/percents. It must be one of

• N_col Column count,
  

• n_df Number of patients (based upon the main input dataframe df),
  

• n_altdf Number of patients from the secondary dataframe (.alt_df_full),
  Note that argument denom_by will perform a row-split on the .alt_df_full dataframe.
  It is a requirement that variables specified in denom_by are part of the row split specifications.
  

• N_colgroup Number of patients from the column group variable (note that this is based upon the input .alt_df_full dataframe).
  Note that the argument colgroup (column variable) needs to be provided, as it cannot be retrieved directly from the column layout definition.

• n_rowdf Number of patients from the current row-level dataframe (.row_df from the rtables splitting machinery).
  

• n_parentdf Number of patients from a higher row-level split than the current split.
  This higher row-level split is specified in the argument denom_by.
  

Value

• s_freq_j: returns a list of following statistics
  

  • n_df

  • n_rowdf

  • n_parentdf

  • n_altdf

  • denom

  • count

  • count_unique

  • count_unique_fraction

  • count_unique_denom_fraction

  • unique_fraction

• a_freq_j: returns a list of requested statistics with formatted rtables::CellValue().
  Within the relative risk difference columns, the following stats are blanked out:

  • any of the n-statistics (n_df, n_altdf, n_parentdf, n_rowdf, denom)

  • count

  • count_unique

  For the others (count_unique_fraction, count_unique_denom_fraction, unique_fraction), the statistic is replaced by the relative risk difference + confidence interval.

Functions

• a_freq_j_with_exclude(): Wrapper for the afun which can exclude row split levels from producing the analysis. These have to be specified in the exclude_levels argument, see ?do_exclude_split for details.

Examples

library(dplyr)

adsl <- ex_adsl |> select("USUBJID", "SEX", "ARM")
adae <- ex_adae |> select("USUBJID", "AEBODSYS", "AEDECOD")
adae[["TRTEMFL"]] <- "Y"

trtvar <- "ARM"
ctrl_grp <- "B: Placebo"
adsl$colspan_trt <- factor(ifelse(adsl[[trtvar]] == ctrl_grp, " ", "Active Study Agent"),
  levels = c("Active Study Agent", " ")
)

adsl$rrisk_header <- "Risk Difference (%) (95% CI)"
adsl$rrisk_label <- paste(adsl[[trtvar]], paste("vs", ctrl_grp))

adae <- adae |> left_join(adsl)

colspan_trt_map <- create_colspan_map(adsl,
  non_active_grp = "B: Placebo",
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = trtvar
)

ref_path <- c("colspan_trt", " ", trtvar, ctrl_grp)

lyt <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("colspan_trt", split_fun = trim_levels_to_map(map = colspan_trt_map)) |>
  split_cols_by(trtvar) |>
  split_cols_by("rrisk_header", nested = FALSE) |>
  split_cols_by(trtvar, labels_var = "rrisk_label", split_fun = remove_split_levels(ctrl_grp))

lyt1 <- lyt |>
  analyze("TRTEMFL",
    show_labels = "hidden",
    afun = a_freq_j,
    extra_args = list(
      method = "wald",
      .stats = c("count_unique_denom_fraction"),
      ref_path = ref_path
    )
  )

result1 <- build_table(lyt1, adae, alt_counts_df = adsl)

result1

x_drug_x <- list(length(unique(subset(adae, adae[[trtvar]] == "A: Drug X")[["USUBJID"]])))
N_x_drug_x <- length(unique(subset(adsl, adsl[[trtvar]] == "A: Drug X")[["USUBJID"]]))
y_placebo <- list(length(unique(subset(adae, adae[[trtvar]] == ctrl_grp)[["USUBJID"]])))
N_y_placebo <- length(unique(subset(adsl, adsl[[trtvar]] == ctrl_grp)[["USUBJID"]]))

tern::stat_propdiff_ci(
  x = x_drug_x,
  N_x = N_x_drug_x,
  y = y_placebo,
  N_y = N_y_placebo
)

x_combo <- list(length(unique(subset(adae, adae[[trtvar]] == "C: Combination")[["USUBJID"]])))
N_x_combo <- length(unique(subset(adsl, adsl[[trtvar]] == "C: Combination")[["USUBJID"]]))

tern::stat_propdiff_ci(
  x = x_combo,
  N_x = N_x_combo,
  y = y_placebo,
  N_y = N_y_placebo
)


extra_args_rr <- list(
  denom = "n_altdf",
  denom_by = "SEX",
  riskdiff = FALSE,
  .stats = c("count_unique")
)

extra_args_rr2 <- list(
  denom = "n_altdf",
  denom_by = "SEX",
  riskdiff = TRUE,
  ref_path = ref_path,
  method = "wald",
  .stats = c("count_unique_denom_fraction"),
  na_str = rep("NA", 3)
)

lyt2 <- basic_table(
  top_level_section_div = " ",
  colcount_format = "N=xx"
) |>
  split_cols_by("colspan_trt", split_fun = trim_levels_to_map(map = colspan_trt_map)) |>
  split_cols_by(trtvar, show_colcounts = TRUE) |>
  split_cols_by("rrisk_header", nested = FALSE) |>
  split_cols_by(trtvar,
    labels_var = "rrisk_label", split_fun = remove_split_levels("B: Placebo"),
    show_colcounts = FALSE
  ) |>
  split_rows_by("SEX", split_fun = drop_split_levels) |>
  summarize_row_groups("SEX",
    cfun = a_freq_j,
    extra_args = append(extra_args_rr, list(label_fstr = "Gender: %s"))
  ) |>
  split_rows_by("TRTEMFL",
    split_fun = keep_split_levels("Y"),
    indent_mod = -1L,
    section_div = c(" ")
  ) |>
  summarize_row_groups("TRTEMFL",
    cfun = a_freq_j,
    extra_args = append(extra_args_rr2, list(
      label =
        "Subjects with >=1 AE", extrablankline = TRUE
    ))
  ) |>
  split_rows_by("AEBODSYS",
    split_label = "System Organ Class",
    split_fun = trim_levels_in_group("AEDECOD"),
    label_pos = "topleft",
    section_div = c(" "),
    nested = TRUE
  ) |>
  summarize_row_groups("AEBODSYS",
    cfun = a_freq_j,
    extra_args = extra_args_rr2
  ) |>
  analyze("AEDECOD",
    afun = a_freq_j,
    extra_args = extra_args_rr2
  )

result2 <- build_table(lyt2, adae, alt_counts_df = adsl)

# -------------------------------------------------------------------------
# Examples using the label_map argument
# -------------------------------------------------------------------------

adsl <- ex_adsl |> select("USUBJID", "SEX", "ARM")
adae <- ex_adae |> select("USUBJID", "AEBODSYS", "AEDECOD")
adae[["TRTEMFL"]] <- "Y"

trtvar <- "ARM"
adae <- adae |> left_join(adsl)

# -------------------------------------------------------------------------
# 1. Simple mapping.
# Remaps factor levels (value) to custom new labels (label).
# -------------------------------------------------------------------------

label_map_simple <- data.frame(
  value = c("M", "F", "UNDIFFERENTIATED", "U"),
  label = c("Male", "Female", "Undifferentiated", "Unknown")
)

lyt_lmap1 <- basic_table(show_colcounts = TRUE) |>
  split_cols_by(trtvar) |>
  analyze("SEX",
    afun = a_freq_j,
    extra_args = list(
      .stats = "count_unique_fraction",
      label_map = label_map_simple
    )
  )

result_lmap1 <- build_table(lyt_lmap1, adsl, alt_counts_df = adsl)
result_lmap1

# -------------------------------------------------------------------------
# 2. Multi-variable mapping.
# Useful in situations where multiple Y/N variables can be analyzed in one
# [rtables::analyze()] call.
# -------------------------------------------------------------------------

multi_vars <- c("DTH30FL", "DTHA30FL", "DTHB30FL")
adslx <- pharmaverseadamjnj::adsl
# ensure the variables are factor with levels Y/N - and variable label is kept
adslx <- adslx |>
  mutate(across(all_of(multi_vars), \(x) structure(
    factor(x, levels = c("Y", "N")),
    label = attr(x, "label")
  )))

map_multi <- data.frame(
  var = multi_vars,
  value = "Y",
  label = c(
    "Death <=30D of Last Trt Flag",
    "Death >30D from Last Trt Flag",
    "Death <=30D of First Trt Flag"
  )
)

lyt_lmap1 <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("ARM") |>
  analyze(multi_vars,
    afun = a_freq_j,
    extra_args = list(
      .stats = "count_unique_denom_fraction",
      label_map = map_multi,
      val = "Y"
    ),
    show_labels = "hidden"
  )

result_lmap2 <- build_table(lyt_lmap1, adslx)
result_lmap2

# -------------------------------------------------------------------------
# 3. Conditional-on-row-split mapping.
# -------------------------------------------------------------------------

map_rowsplit <- data.frame(
  SEX = c("M", "F"),
  value = c("Y", "Y"),
  label = c("Male subjects with >=1 TE AE", "Female subjects with >=1 TE AE")
)

adsl <- ex_adsl |> select("USUBJID", "ARM", "SEX")
adae <- ex_adae |> select("USUBJID", "AEBODSYS", "AEDECOD")
adae[["TRTEMFL"]] <- "Y"
adae <- adae |> left_join(adsl)

lyt_lmap3 <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("ARM") |>
  split_rows_by("SEX", split_fun = keep_split_levels(c("F", "M")), child_labels = "hidden") |>
  analyze("TRTEMFL",
    afun = a_freq_j,
    extra_args = list(
      .stats = "count_unique_denom_fraction",
      label_map = map_rowsplit,
      val = "Y"
    ),
    show_labels = "hidden"
  )

result_lmap3 <- build_table(lyt_lmap3, adae, alt_counts_df = adsl)
result_lmap3

# -----------------------------------------------------------------------------------
# 4. Conditional-on-row-split multi-variable mapping.
# -----------------------------------------------------------------------------------
adsl_jnj <- pharmaverseadamjnj::adsl
advs_jnj <- pharmaverseadamjnj::advs

multi_vars <- c("CRIT1FL", "CRIT2FL", "CRIT3FL")

map_multi_rowsplit <- data.frame(
  PARAMCD = c(rep("DIABP", 3), rep("SYSBP", 3)),
  var = rep(multi_vars, 2),
  value = rep("Y", 6),
  label = c(
    "<50 mmHg and with >20 mmHg decrease from baseline",
    ">105 mmHg and with >30 mmHg increase from baseline",
    "Diastolic blood pressure<60",
    "<90 mmHg and with >30 mmHg decrease from baseline",
    ">180 mmHg and with >40 mmHg increase from baseline",
    "Systolic blood pressure<90"
  )
)

lyt_lmap4 <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("TRT01A") |>
  split_rows_by("PARAMCD", split_fun = keep_split_levels(c("DIABP", "SYSBP"))) |>
  analyze(multi_vars,
    afun = a_freq_j,
    extra_args = list(
      .stats = "count_unique_denom_fraction",
      label_map = map_multi_rowsplit,
      val = "Y"
    ),
    show_labels = "hidden"
  )

result_lmap4 <- build_table(lyt_lmap4, advs_jnj, alt_counts_df = adsl_jnj)
result_lmap4

Analysis Function for Response Variables

Description

This function calculates counts and percentages for response variables (Y/N values), with optional risk difference calculations.

Usage

a_freq_resp_var_j(
  df,
  .var,
  .df_row,
  .N_col,
  .spl_context,
  resp_var = NULL,
  id = "USUBJID",
  drop_levels = FALSE,
  riskdiff = TRUE,
  ref_path = NULL,
  variables = list(strata = NULL),
  conf_level = formals(s_proportion_diff)$conf_level,
  method = c("wald", "waldcc", "cmh", "ha", "newcombe", "newcombecc", "strat_newcombe",
    "strat_newcombecc", "cmh_sato", "cmh_mn", "uncond_exact_diff"),
  weights_method = formals(s_proportion_diff)$weights_method,
  .formats = NULL,
  na_str = rep("NA", 3),
  legacy = FALSE
)

Arguments

Value

Formatted analysis function which is used as afun in analyze_vars() and as cfun in summarize_row_groups().

Examples

library(dplyr)
ADSL <- ex_adsl |> select(USUBJID, ARM, SEX)

ADAE <- ex_adae |> select(USUBJID, ARM, SEX, AEBODSYS, AEDECOD)

ADAE <- ADAE |>
  mutate(TRTEMFL = "Y")

lyt <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("ARM") |>
  analyze("SEX",
    show_labels = "visible",
    afun = a_freq_resp_var_j,
    extra_args = list(resp_var = "TRTEMFL", riskdiff = FALSE)
  )

result <- build_table(lyt, df = ADAE, alt_counts_df = ADSL)

result

Analysis function count and percentage with extra column-subsetting in selected columns (controlled by subcol_* arguments)

Description

Analysis function count and percentage with extra column-subsetting in selected columns (controlled by subcol_* arguments)

Usage

a_freq_subcol_j(
  df,
  labelstr = NULL,
  .var = NA,
  val = NULL,
  subcol_split = NULL,
  subcol_var = NULL,
  subcol_val = NULL,
  .df_row,
  .spl_context,
  .N_col,
  id = "USUBJID",
  denom = c("N_col", "n_df", "n_altdf", "n_rowdf", "n_parentdf"),
  label = NULL,
  label_fstr = NULL,
  label_map = NULL,
  .alt_df_full = NULL,
  denom_by = NULL,
  .stats = c("count_unique_denom_fraction"),
  .formats = NULL,
  .labels_n = NULL,
  .indent_mods = NULL,
  na_str = rep("NA", 3)
)

Arguments

Value

list of requested statistics with formatted rtables::CellValue().

See Also

a_freq_j() for extensive label_map usage examples.

Examples

library(dplyr)

ADSL <- ex_adsl |>
  select(USUBJID, ARM)

ADSL$COLSPAN_REL <- "AEs"

ADAE <- ex_adae |>
  select(USUBJID, ARM, AEDECOD, AREL)

ADAE <- ADAE |>
  mutate(
    AEREL = case_when(
      AREL == "Y" ~ "RELATED",
      AREL == "N" ~ "NOT RELATED"
    ),
    AEREL = factor(AEREL),
    COLSPAN_REL = "AEs"
  )

combodf <- tribble(
  ~valname,  ~label,        ~levelcombo, ~exargs,
  "RELATED", "Related AEs", c("AEs"),    list()
)

lyt <- basic_table(show_colcounts = TRUE) |>
  split_cols_by("COLSPAN_REL", split_fun = rtables::add_combo_levels(combodf, trim = TRUE)) |>
  split_cols_by("ARM") |>
  analyze("AEDECOD",
    afun = a_freq_subcol_j,
    extra_args = list(
      subcol_split = "RELATED",
      subcol_var = "AEREL",
      subcol_val = "RELATED"
    )
  )

result <- build_table(lyt, ADAE, alt_counts_df = ADSL)

result

a_kaplan_meier

Description

Use tern::a_surv_time() instead.

Usage

a_kaplan_meier(
  df,
  .var,
  ...,
  .stats = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Calculate Count and Percentage of the Maximum Level of an Ordered Factor per Subject.

Description

A formatted analysis function used as an afun in analyze and as a cfun in summarize_row_groups.

It computes count and proportion statistics for the maximum level of an ordered factor, df[[.var]], for each unique subject in df[[id]]. Specifically, for each subject, the function identifies the highest level of df[[.var]], producing one value per subject. Then, if any_level = TRUE, the function reports the total number of maximum values, excluding those specified in any_level_exclude. Otherwise, it tabulates the frequency of each maximum level across all subjects.

This function is particularly useful for identifying the maximum severity of adverse events in a treatment sequence, where the most severe event experienced by a subject is used for reporting.

Usage

a_maxlev(
  df,
  labelstr = NULL,
  .var,
  .spl_context,
  id = "USUBJID",
  .alt_df_full = NULL,
  any_level = FALSE,
  any_level_exclude = "Missing",
  ...
)

Arguments

Details

For each unique subject, only the maximum level of the ordered factor df[[.var]] is included in the final count and percentage statistics.

Value

A RowsVerticalSection object.

Note

The denominator for proportions is computed using the denom_df argument. This serves as a temporary workaround until the next version of rtables is released, which will support .alt_count_df for use in afun/cfun.

Author(s)

WW

Examples

treatments <- factor(c("a", "b", "c"))
ae_severities <- c("Missing", "Mild", "Moderate", "Severe")
ae_severities <- ordered(ae_severities, levels = ae_severities)
my_adae <- data.frame(
  ID = c(1, 1, 1, 2, 2, 3, 3, 3, 3, 4),
  TRT = factor(c("a", "b", "b", "b", "c", "c", "a", "c", "b", "b")),
  AESEV = ae_severities[c(4L, 1L, 2L, 1L, 2L, 1L, 2L, 3L, 1L, 2L)]
)
my_adsl <- data.frame(
  ID = rep(1:5, each = 3),
  TRT = factor(rep(c("a", "b", "c"), times = 5))
)

aesevall_spf <- make_combo_splitfun(
  nm = "AESEV_ALL",
  label = "Any AE",
  levels = NULL,
)

lyt <- basic_table() |>
  split_cols_by("TRT") |>
  add_overall_col("Total") |>
  split_rows_by("AESEV", split_fun = aesevall_spf) |>
  summarize_row_groups(
    "AESEV",
    cfun = a_maxlev,
    extra_args = list(id = "ID", any_level = TRUE)
  ) |>
  analyze(
    "AESEV",
    afun = a_maxlev,
    extra_args = list(id = "ID")
  )
build_table(lyt, my_adae, alt_counts_df = my_adsl)

Patient years exposure

Description

Statistical/Analysis Function for presenting Patient years exposure summary data

Usage

s_patyrs_j(
  df,
  .var,
  id = "USUBJID",
  .alt_df_full,
  source = c("alt_df", "df"),
  inriskdiffcol = FALSE
)

a_patyrs_j(
  df,
  .var,
  .df_row,
  id = "USUBJID",
  .alt_df_full = NULL,
  .formats = NULL,
  .labels = NULL,
  source = c("alt_df", "df"),
  .spl_context,
  .stats = "patyrs"
)

Arguments

Value

• s_patyrs_j() returns a list containing the patient years statistics. The list of available statistics for can be viewed by running junco_get_stats("a_patyrs_j"). Currently, this is just a single statistic patyrs, patient years of exposure.

• a_patyrs_j returns the corresponding list with formatted rtables::CellValue().

Functions

• s_patyrs_j(): Statistical Function for Patient years exposure summary data

• a_patyrs_j(): Formatted analysis function for patient years summary which is used as afun in analyze or cfun in summarize_row_groups.

Examples

library(tern)
library(dplyr)
trtvar <- "ARM"
ctrl_grp <- "B: Placebo"
cutoffd <- as.Date("2023-09-24")


adexsum <- ex_adsl |>
  create_colspan_var(
    non_active_grp          = ctrl_grp,
    non_active_grp_span_lbl = " ",
    active_grp_span_lbl     = "Active Study Agent",
    colspan_var             = "colspan_trt",
    trt_var                 = trtvar
  ) |>
  mutate(
    rrisk_header = "Risk Difference (95% CI)",
    rrisk_label = paste(!!rlang::sym(trtvar), "vs", ctrl_grp),
    TRTDURY = case_when(
      !is.na(EOSDY) ~ EOSDY,
      TRUE ~ as.integer(cutoffd - as.Date(TRTSDTM) + 1)
    )
  ) |>
  select(USUBJID, !!rlang::sym(trtvar), colspan_trt, rrisk_header, rrisk_label, TRTDURY)

adae <- ex_adae |>
  group_by(USUBJID, AEDECOD) |>
  select(USUBJID, AEDECOD, ASTDY) |>
  mutate(rwnum = row_number()) |>
  mutate(AOCCPFL = case_when(
    rwnum == 1 ~ "Y",
    TRUE ~ NA
  )) |>
  filter(AOCCPFL == "Y")

aefup <- left_join(adae, adexsum, by = "USUBJID")

colspan_trt_map <- create_colspan_map(adexsum,
  non_active_grp = ctrl_grp,
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = trtvar
)

ref_path <- c("colspan_trt", " ", trtvar, ctrl_grp)

################################################################################
# Define layout and build table:
################################################################################

lyt <- basic_table(show_colcounts = TRUE, colcount_format = "N=xx", top_level_section_div = " ") |>
  split_cols_by("colspan_trt", split_fun = trim_levels_to_map(map = colspan_trt_map)) |>
  split_cols_by(trtvar) |>
  split_cols_by("rrisk_header", nested = FALSE) |>
  split_cols_by(trtvar, labels_var = "rrisk_label", split_fun = remove_split_levels(ctrl_grp)) |>
  analyze("TRTDURY",
    nested = FALSE,
    show_labels = "hidden",
    afun = a_patyrs_j
  )
result <- build_table(lyt, aefup, alt_counts_df = adexsum)
result

Formatted Analysis Function For Proportion Confidence Interval for Factor

Description

Formatted Analysis Function For Proportion Confidence Interval for Factor.

Usage

a_proportion_ci_factor(df, .var, ...)

Arguments

Value

The rtables::rcell() result.

Examples

a_proportion_ci_factor(
  df = DM,
  .var = "SEX",
  .alt_df = DM,
  conf_level = 0.95,
  formats = list(prop_ci = jjcsformat_xx("xx.x%, xx.x%")),
  method = "clopper-pearson"
)

Formatted Analysis Function For Proportion Confidence Interval for Logical

Description

Formatted Analysis Function For Proportion Confidence Interval for Logical.

Usage

a_proportion_ci_logical(x, .alt_df, conf_level, method, formats)

Arguments

Value

The rtables::rcell() result.

Examples

a_proportion_ci_logical(
  x = DM$SEX == "F",
  .alt_df = DM,
  conf_level = 0.95,
  formats = list(prop_ci = jjcsformat_xx("xx.xx% - xx.xx%")),
  method = "wald"
)

Relative risk estimation

Description

The analysis function a_relative_risk() is used to create a layout element to estimate the relative risk for response within a studied population. Only the CMH method is available currently. The primary analysis variable, vars, is a logical variable indicating whether a response has occurred for each record. A stratification variable must be supplied via the strata element of the variables argument.

Usage

a_relative_risk(
  df,
  .var,
  ref_path,
  .spl_context,
  ...,
  .stats = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_relative_risk(
  df,
  .var,
  .ref_group,
  .in_ref_col,
  variables = list(strata = NULL),
  conf_level = 0.95,
  method = "cmh",
  weights_method = "cmh"
)

Arguments

Details

The variance of the CMH relative risk estimate is calculated using the Greenland and Robins (1985) variance estimation.

Value

• a_relative_risk() returns the corresponding list with formatted rtables::CellValue().

• s_relative_risk() returns a named list of elements rel_risk_ci and pval.

Functions

• a_relative_risk(): Formatted analysis function which is used as afun. Note that the junco specific ref_path and .spl_context arguments are used for reference column information.

• s_relative_risk(): Statistics function estimating the relative risk for response.

Note

This has been adapted from the odds_ratio functions in the tern package.

Examples

nex <- 100
dta <- data.frame(
  "rsp" = sample(c(TRUE, FALSE), nex, TRUE),
  "grp" = sample(c("A", "B"), nex, TRUE),
  "f1" = sample(c("a1", "a2"), nex, TRUE),
  "f2" = sample(c("x", "y", "z"), nex, TRUE),
  stringsAsFactors = TRUE
)

l <- basic_table() |>
  split_cols_by(var = "grp") |>
  analyze(
    vars = "rsp",
    afun = a_relative_risk,
    extra_args = list(
      conf_level = 0.90,
      variables = list(strata = "f1"),
      ref_path = c("grp", "B")
    )
  )

build_table(l, df = dta)
nex <- 100
dta <- data.frame(
  "rsp" = sample(c(TRUE, FALSE), nex, TRUE),
  "grp" = sample(c("A", "B"), nex, TRUE),
  "f1" = sample(c("a1", "a2"), nex, TRUE),
  "f2" = sample(c("x", "y", "z"), nex, TRUE),
  stringsAsFactors = TRUE
)

s_relative_risk(
  df = subset(dta, grp == "A"),
  .var = "rsp",
  .ref_group = subset(dta, grp == "B"),
  .in_ref_col = FALSE,
  variables = list(strata = c("f1", "f2")),
  conf_level = 0.90
)

Analysis Function: Sum and Ratio of Sums

Description

Computes one or more of the following statistics for use with rtables::analyze():

• "sum": sum(.var)

• "sum_unique": sum(.var) after keeping unique rows by id_var

• "ratio": sum(.var) / sum(denom_by)

• "ratio_unique": same ratio after keeping unique rows by id_var

Both .var and denom_by columns must be numeric (integer, double, or logical coerced to numeric).

Usage

a_sum_ratio_j(
  df,
  .var,
  .stats = "sum",
  denom_by = NULL,
  id_var = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL,
  na_str = NULL,
  ...
)

Arguments

Value

A RowsVerticalSection for use by rtables.

Author(s)

VR

Examples

df <- data.frame(
  USUBJID = c("S01", "S01", "S02", "S03"),
  ARM     = factor(c("A", "A", "A", "B")),
  EVENTS  = c(1, 1, 0, 1),
  DAYS    = c(10, 10, 20, 15)
)

# All 4 stats in a layout (S01 duplicate tests unique logic)
lyt <- basic_table() |>
  split_cols_by("ARM") |>
  analyze(
    "EVENTS",
    afun = a_sum_ratio_j,
    extra_args = list(
      .stats   = c("sum", "sum_unique", "ratio", "ratio_unique"),
      denom_by = "DAYS",
      id_var   = "USUBJID"
    )
  )

build_table(lyt, df)

ANCOVA Summary Function

Description

Combination of tern::s_summary, and ANCOVA based estimates for mean and diff between columns, based on ANCOVA function s_ancova_j.

Usage

a_summarize_ancova_j(
  df,
  .var,
  .df_row,
  ref_path,
  .spl_context,
  ...,
  .stats = c("n", "mean_sd", "median", "range", "quantiles", "lsmean_se", "lsmean_ci",
    "lsmean_diff_with_ci", "pval"),
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_summarize_ancova_j(df, .var, .df_row, .ref_group, .in_ref_col, ...)

Arguments

Details

Combination of tern::s_summary, and ANCOVA based estimates for mean and diff between columns, based on ANCOVA function s_ancova_j

Value

• a_summarize_ancova_j() returns the corresponding list with formatted rtables::CellValue().

returns the statistics from tern::s_summary(x), appended with a new statistics based upon ANCOVA

Functions

• a_summarize_ancova_j(): Formatted analysis function which is used as afun. Note that the junco specific ref_path and .spl_context arguments are used for reference column information.

See Also

Other Inclusion of ANCOVA Functions: a_summarize_aval_chg_diff_j(), s_ancova_j()

Examples

basic_table() |>
  split_cols_by("Species") |>
  add_colcounts() |>
  analyze(
    vars = "Petal.Length",
    afun = a_summarize_ancova_j,
    show_labels = "hidden",
    na_str = tern::default_na_str(),
    table_names = "unadj",
    var_labels = "Unadjusted comparison",
    extra_args = list(
      variables = list(arm = "Species", covariates = NULL),
      conf_level = 0.95,
      .labels = c(lsmean = "Mean", lsmean_diff = "Difference in Means"),
      ref_path = c("Species", "setosa")
    )
  ) |>
  analyze(
    vars = "Petal.Length",
    afun = a_summarize_ancova_j,
    show_labels = "hidden",
    na_str = tern::default_na_str(),
    table_names = "adj",
    var_labels = "Adjusted comparison (covariates: Sepal.Length and Sepal.Width)",
    extra_args = list(
      variables = list(
        arm = "Species",
        covariates = c("Sepal.Length", "Sepal.Width")
      ),
      conf_level = 0.95,
      ref_path = c("Species", "setosa")
    )
  ) |>
  build_table(iris)

library(dplyr)
library(tern)

df <- iris |> filter(Species == "virginica")
.df_row <- iris
.var <- "Petal.Length"
variables <- list(arm = "Species", covariates = "Sepal.Length * Sepal.Width")
.ref_group <- iris |> filter(Species == "setosa")
conf_level <- 0.95
s_summarize_ancova_j(
  df,
  .var = .var,
  .df_row = .df_row,
  variables = variables,
  .ref_group = .ref_group,
  .in_ref_col = FALSE,
  conf_level = conf_level
)

Analysis function 3-column presentation

Description

Analysis functions to produce a 1-row summary presented in a 3-column layout in the columns (column 1 = N, column 2 = Value, column 3 = Change).
In the difference columns, only 1 column will be presented : difference + CI
When ancova = TRUE, the presented statistics will be based on ANCOVA method (s_summarize_ancova_j).
mean and ci (both for Value (column 2) and CHG (column 3)) using statistic lsmean_ci
mean and ci for the difference column are based on same ANCOVA model using statistic lsmean_diff_with_ci
When ancova = FALSE, descriptive statistics will be used instead.
In the difference column, the 2-sample t-test will be used.

Usage

a_summarize_aval_chg_diff_j(
  df,
  .df_row,
  .spl_context,
  ancova = FALSE,
  comp_btw_group = TRUE,
  ref_path = NULL,
  .N_col,
  denom = c("N", ".N_col"),
  indatavar = NULL,
  d = 0,
  id = "USUBJID",
  interaction_y = FALSE,
  interaction_item = NULL,
  conf_level = 0.95,
  variables = list(arm = "TRT01A", covariates = NULL),
  format_na_str = "",
  .stats = list(col1 = "count_denom_frac", col23 = "mean_ci_3d", coldiff =
    "mean_diff_with_ci"),
  .formats = list(col1 = NULL, col23 = "xx.dx (xx.dx, xx.dx)", coldiff =
    "xx.dx (xx.dx, xx.dx)"),
  .formats_fun = list(col1 = jjcsformat_count_denom_fraction, col23 = jjcsformat_xx,
    coldiff = jjcsformat_xx),
  multivars = c("AVAL", "AVAL", "CHG"),
  weights_emmeans = NULL,
  method_combo = c("contrasts", "collapse"),
  weights_combo = NULL
)

Arguments

Details

See Description

Value

A function that can be used in an analyze function call

See Also

Other Inclusion of ANCOVA Functions: a_summarize_ancova_j(), s_ancova_j()

Examples

library(dplyr)

ADEG <- data.frame(
  STUDYID = c(
    "DUMMY", "DUMMY", "DUMMY", "DUMMY", "DUMMY",
    "DUMMY", "DUMMY", "DUMMY", "DUMMY", "DUMMY"
  ),
  USUBJID = c(
    "XXXXX01", "XXXXX02", "XXXXX03", "XXXXX04", "XXXXX05",
    "XXXXX06", "XXXXX07", "XXXXX08", "XXXXX09", "XXXXX10"
  ),
  TRT01A = c(
    "ARMA", "ARMA", "ARMA", "ARMA", "ARMA", "Placebo",
    "Placebo", "Placebo", "ARMA", "ARMA"
  ),
  PARAM = c("BP", "BP", "BP", "BP", "BP", "BP", "BP", "BP", "BP", "BP"),
  AVISIT = c(
    "Visit 1", "Visit 1", "Visit 1", "Visit 1", "Visit 1",
    "Visit 1", "Visit 1", "Visit 1", "Visit 1", "Visit 1"
  ),
  AVAL = c(56, 78, 67, 87, 88, 93, 39, 87, 65, 55),
  CHG = c(2, 3, -1, 9, -2, 0, 6, -2, 5, 2)
)

ADEG <- ADEG |>
  mutate(
    TRT01A = as.factor(TRT01A),
    STUDYID = as.factor(STUDYID)
  )

ADEG$colspan_trt <- factor(ifelse(ADEG$TRT01A == "Placebo", " ", "Active Study Agent"),
  levels = c("Active Study Agent", " ")
)
ADEG$rrisk_header <- "Risk Difference (%) (95% CI)"
ADEG$rrisk_label <- paste(ADEG$TRT01A, paste("vs", "Placebo"))

colspan_trt_map <- create_colspan_map(ADEG,
  non_active_grp = "Placebo",
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = "TRT01A"
)
ref_path <- c("colspan_trt", " ", "TRT01A", "Placebo")

lyt <- basic_table() |>
  split_cols_by(
    "colspan_trt",
    split_fun = trim_levels_to_map(map = colspan_trt_map)
  ) |>
  split_cols_by("TRT01A") |>
  split_rows_by(
    "PARAM",
    label_pos = "topleft",
    split_label = "Blood Pressure",
    section_div = " ",
    split_fun = drop_split_levels
  ) |>
  split_rows_by(
    "AVISIT",
    label_pos = "topleft",
    split_label = "Study Visit",
    split_fun = drop_split_levels,
    child_labels = "hidden"
  ) |>
  split_cols_by_multivar(
    c("AVAL", "AVAL", "CHG"),
    varlabels = c("n/N (%)", "Mean (CI)", "CFB (CI)")
  ) |>
  split_cols_by("rrisk_header", nested = FALSE) |>
  split_cols_by(
    "TRT01A",
    split_fun = remove_split_levels("Placebo"),
    labels_var = "rrisk_label"
  ) |>
  split_cols_by_multivar(c("CHG"), varlabels = c(" ")) |>
  analyze("STUDYID",
    afun = a_summarize_aval_chg_diff_j,
    extra_args = list(
      format_na_str = "-", d = 0,
      ref_path = ref_path, variables = list(arm = "TRT01A", covariates = NULL)
    )
  )

result <- build_table(lyt, ADEG)

result

Tabulation for Exposure Tables

Description

A function to create the appropriate statistics needed for exposure table

Usage

s_summarize_ex_j(
  df,
  .var,
  .df_row,
  .spl_context,
  comp_btw_group = TRUE,
  ref_path = NULL,
  ancova = FALSE,
  interaction_y,
  interaction_item,
  conf_level,
  daysconv,
  variables
)

a_summarize_ex_j(
  df,
  .var,
  .df_row,
  .spl_context,
  comp_btw_group = TRUE,
  ref_path = NULL,
  ancova = FALSE,
  interaction_y = FALSE,
  interaction_item = NULL,
  conf_level = 0.95,
  variables,
  .stats = c("mean_sd", "median", "range", "quantiles", "total_subject_years"),
  .formats = c(diff_mean_est_ci = jjcsformat_xx("xx.xx (xx.xx, xx.xx)")),
  .labels = c(quantiles = "Interquartile range"),
  .indent_mods = NULL,
  na_str = rep("NA", 3),
  daysconv = 1
)

Arguments

Details

Creates statistics needed for standard exposure table. This includes differences and 95% CI and total treatment years. This is designed to be used as an analysis (afun in analyze) function.

Value

• a_summarize_ex_j() returns the corresponding list with formatted rtables::CellValue().

Functions

• s_summarize_ex_j(): Statistics function needed for the exposure tables.

• a_summarize_ex_j(): Formatted analysis function which is used as afun.

Examples

library(dplyr)
ADEX <- ex_adsl |> select(USUBJID, ARM, TRTSDTM, EOSSTT, EOSDY)

trtvar <- "ARM"
ctrl_grp <- "B: Placebo"
cutoffd <- as.Date("2023-09-24")

ADEX <- ADEX |>
  create_colspan_var(
    non_active_grp          = ctrl_grp,
    non_active_grp_span_lbl = " ",
    active_grp_span_lbl     = "Active Study Agent",
    colspan_var             = "colspan_trt",
    trt_var                 = trtvar
  ) |>
  mutate(
    diff_header = "Difference in Means (95% CI)",
    diff_label = paste(!!rlang::sym(trtvar), "vs", ctrl_grp),
    TRTDURY = case_when(
      !is.na(EOSDY) ~ EOSDY,
      TRUE ~ as.integer(cutoffd - as.Date(TRTSDTM) + 1)
    )
  )

colspan_trt_map <- create_colspan_map(ADEX,
  non_active_grp = ctrl_grp,
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = trtvar
)

ref_path <- c("colspan_trt", "", trtvar, ctrl_grp)

lyt <- basic_table() |>
  split_cols_by(
    "colspan_trt",
    split_fun = trim_levels_to_map(map = colspan_trt_map)
  ) |>
  split_cols_by(trtvar) |>
  split_cols_by("diff_header", nested = FALSE) |>
  split_cols_by(
    trtvar,
    split_fun = remove_split_levels(ctrl_grp),
    labels_var = "diff_label"
  ) |>
  analyze("EOSDY",
    afun = a_summarize_ex_j, var_labels = "Duration of treatment (Days)",
    show_labels = "visible",
    indent_mod = 0L,
    extra_args = list(
      daysconv = 1,
      ref_path = ref_path,
      variables = list(arm = trtvar, covariates = NULL),
      ancova = TRUE,
      comp_btw_group = TRUE
    )
  )

result <- build_table(lyt, ADEX, alt_counts_df = ADEX)
result

Wrappers Around tern::a_summary() with Row Split Exclusion

Description

These wrappers around tern::a_summary() allow selected row split levels to be excluded from producing the analysis.

Usage

a_summary_j_with_exclude(df, .var, exclude_levels, .spl_context, ...)

Arguments

Details

tern::a_summary() is a formatted analysis function that computes summary statistics for a single variable. In typical use within the rtables framework, the analysis variable is first extracted from a data frame and then passed to tern::a_summary() as a standalone vector.

a_summary_j_with_exclude() extends this behavior by:

• accepting a data frame (df) as input,

• checking whether the current row split path should be excluded,

• returning NULL for excluded row split levels,

• extracting the analysis variable .var for all other row split levels,

• and passing the resulting vector to tern::a_summary().

Value

Returns the same type of object as tern::a_summary(), or NULL when the current row split path is excluded by exclude_levels.

Functions

• a_summary_j_with_exclude(): Analysis function which can exclude row split levels from producing the analysis. These have to be specified in the exclude_levels argument, see ?do_exclude_split for details.

See Also

tern::a_summary(), do_exclude_split()

Examples

df <- data.frame(
  USUBJID = 1:8,
  AVISIT = factor(rep(c("Baseline", "Week 1"), 4)),
  ARM = factor(rep(c("A", "B"), each = 4)),
  AVAL = c(1.2, 3, -1.5, 0.8, 3.5, 2, -1.1, 0.3)
)

lyt <- basic_table() |>
  split_cols_by("ARM") |>
  split_rows_by("AVISIT") |>
  analyze(
    "AVAL",
    afun = a_summary_j_with_exclude,
    extra_args = list(exclude_levels = list(AVISIT = "Baseline"))
  )

build_table(lyt, df)

Two Tier Analysis Function

Description

a_two_tier(): The analysis function used as an afun in analyze. This function simulates a final additional level of nesting with a traditional analyze call inside it.

This makes it possible to create what appear to be group summary or content rows and to optionally or conditionally generate one or more "detail" rows underneath it.

For example, in a disposition table, one might want counts for completed and ongoing patients with no further detail underneath, but a breakdown of specific reasons beneath the count of patients who discontinued treatment.

a_three_tier(): Extends a_two_tier() by adding a third level of nesting: a group summary outer row, mid-level detail rows (one per level of inner_var1), and innermost detail rows (one per level of inner_var2) nested beneath each mid-level row.

Usage

a_two_tier(
  df,
  labelstr = NULL,
  .var,
  .N_col,
  .df_row,
  inner_var,
  drill_down_levs,
  .spl_context,
  use_all_levels = FALSE,
  grp_fun,
  detail_fun,
  .alt_df_full = NULL,
  ...
)

a_three_tier(
  df,
  labelstr = NULL,
  .var,
  .N_col,
  .df_row,
  inner_var1,
  inner_var2,
  drill_down_levs,
  .spl_context,
  use_all_levels = FALSE,
  grp_fun,
  detail_fun,
  .alt_df_full = NULL,
  ...
)

Arguments

Details

a_two_tier(): Both the analysis variable and inner_var must be factors. Detail rows are differentiated by having an indent mod of one, causing them to hang indented under their corresponding group row.

a_three_tier(): The analysis variable, inner_var1, and inner_var2 must all be factors. Mid-level rows are indented by one and innermost rows by two, relative to the group summary row.

Value

a_two_tier(): A RowsVerticalSection object including both the group row and all detail rows, if applicable, for the facet.

a_three_tier(): A RowsVerticalSection object including the group row, mid-level detail rows, and innermost detail rows, if applicable, for the facet.

Note

In its current form, this function may not retain any formatting or labeling instructions added by grp_fun or detail_fun, and it will override any .indent_mods values specified by them. This behavior may change in future versions.

Author(s)

GB, WW.

Examples

# Example 1

lyt_obs_levels <- basic_table() |>
  split_cols_by("ARM") |>
  split_rows_by("EOSSTT", child_labels = "hidden") |>
  analyze("EOSSTT",
    afun = a_two_tier,
    extra_args = list(
      grp_fun = simple_analysis,
      detail_fun = simple_analysis,
      inner_var = "DCSREAS",
      drill_down_levs = "DISCONTINUED"
    )
  )

tbl <- build_table(lyt_obs_levels, ex_adsl)
tbl

lyt_all_levels <- basic_table() |>
  split_cols_by("ARM") |>
  split_rows_by("EOSSTT", child_labels = "hidden") |>
  analyze("EOSSTT",
    afun = a_two_tier,
    extra_args = list(
      grp_fun = simple_analysis,
      detail_fun = simple_analysis,
      inner_var = "DCSREAS",
      drill_down_levs = "DISCONTINUED",
      use_all_levels = TRUE
    )
  )

adsl_subset <- subset(ex_adsl, DCSREAS != "ADVERSE EVENT")
levels(adsl_subset$DCSREAS)

tbl_all_levels <- build_table(lyt_all_levels, adsl_subset)
tbl_all_levels

tbl_obs_levels <- build_table(lyt_obs_levels, adsl_subset)
tbl_obs_levels

# Example 2

library(dplyr)

trtvar <- "ARM"
ctrl_grp <- "B: Placebo"

adsl <- ex_adsl |> select(c("USUBJID", "STRATA1", "EOSSTT", "DCSREAS", all_of(trtvar)))
adsl$colspan_trt <- factor(
  ifelse(adsl[[trtvar]] == ctrl_grp, " ", "Active Study Agent"),
  levels = c("Active Study Agent", " ")
)
adsl$rrisk_header <- "Risk Difference (%) (95% CI)"
adsl$rrisk_label <- paste(adsl[[trtvar]], paste("vs", ctrl_grp))

colspan_trt_map <- create_colspan_map(
  df = adsl,
  non_active_grp = ctrl_grp,
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = trtvar
)

a_freq_j_args <- list(
  .stats = "count_unique_fraction",
  denom = "n_altdf",
  ref_path = c("colspan_trt", " ", trtvar, ctrl_grp)
)

two_tier_args <- list(
  grp_fun = a_freq_j,
  detail_fun = a_freq_j,
  inner_var = "DCSREAS",
  drill_down_levs = "DISCONTINUED"
)

lyt_rrisk <- basic_table() |>
  split_cols_by("colspan_trt", split_fun = trim_levels_to_map(map = colspan_trt_map)) |>
  split_cols_by(trtvar) |>
  split_cols_by("rrisk_header", nested = FALSE) |>
  split_cols_by(trtvar, labels_var = "rrisk_label", split_fun = remove_split_levels(ctrl_grp)) |>
  split_rows_by("STRATA1") |>
  split_rows_by("EOSSTT", child_labels = "hidden") |>
  analyze("EOSSTT", afun = a_two_tier, extra_args = c(two_tier_args, a_freq_j_args))

adsl_subset <- subset(
  adsl,
  EOSSTT != "COMPLETED" & (is.na(DCSREAS) | DCSREAS != "PROTOCOL VIOLATION")
)

tbl_rrisk <- build_table(lyt_rrisk, adsl_subset, alt_counts_df = adsl_subset)
tbl_rrisk

Analysis and Content Summary Function Producing Blank Line

Description

Analysis and Content Summary Function Producing Blank Line

Usage

ac_blank_line(df, labelstr = "")

Arguments

Shortcut Layout Function for Standard Continuous Variable Analysis

Description

Shortcut Layout Function for Standard Continuous Variable Analysis

Usage

analyze_values(lyt, vars, ..., formats)

Arguments

Value

Modified layout.

Pruning Function for pruning based on a fraction and/or a difference from the control arm

Description

This is a pruning constructor function which identifies records to be pruned based on the the fraction from the percentages. In addition to just looking at a fraction within an arm, this function also allows further flexibility to also prune based on a comparison versus the control arm.

Usage

bspt_pruner(
  fraction = 0.05,
  keeprowtext = "Analysis set: Safety",
  reg_expr = FALSE,
  control = NULL,
  diff_from_control = NULL,
  only_more_often = TRUE,
  cols = c("TRT01A")
)

Arguments

Value

Function that can be utilized as pruning function in prune_table.

Examples

ADSL <- data.frame(
  USUBJID = c(
    "XXXXX01", "XXXXX02", "XXXXX03", "XXXXX04", "XXXXX05",
    "XXXXX06", "XXXXX07", "XXXXX08", "XXXXX09", "XXXXX10"
  ),
  TRT01P = c(
    "ARMA", "ARMB", "ARMA", "ARMB", "ARMB",
    "Placebo", "Placebo", "Placebo", "ARMA", "ARMB"
  ),
  FASFL = c("Y", "Y", "Y", "Y", "N", "Y", "Y", "Y", "Y", "Y"),
  SAFFL = c("N", "N", "N", "N", "N", "N", "N", "N", "N", "N"),
  PKFL = c("N", "N", "N", "N", "N", "N", "N", "N", "N", "N")
)

ADSL <- ADSL |>
  dplyr::mutate(TRT01P = as.factor(TRT01P)) |>
  dplyr::mutate(SAFFL = factor(SAFFL, c("Y", "N"))) |>
  dplyr::mutate(PKFL = factor(PKFL, c("Y", "N")))

lyt <- basic_table() |>
  split_cols_by("TRT01P") |>
  add_overall_col("Total") |>
  split_rows_by(
    "FASFL",
    split_fun = drop_and_remove_levels("N"),
    child_labels = "hidden"
  ) |>
  analyze("FASFL",
    var_labels = "Analysis set:",
    afun = a_freq_j,
    show_labels = "visible",
    extra_args = list(label = "Full", .stats = "count_unique_fraction")
  ) |>
  split_rows_by(
    "SAFFL",
    split_fun = remove_split_levels("N"),
    child_labels = "hidden"
  ) |>
  analyze("SAFFL",
    var_labels = "Analysis set:",
    afun = a_freq_j,
    show_labels = "visible",
    extra_args = list(label = "Safety", .stats = "count_unique_fraction")
  ) |>
  split_rows_by(
    "PKFL",
    split_fun = remove_split_levels("N"),
    child_labels = "hidden"
  ) |>
  analyze("PKFL",
    var_labels = "Analysis set:",
    afun = a_freq_j,
    show_labels = "visible",
    extra_args = list(label = "PK", .stats = "count_unique_fraction")
  )

result <- build_table(lyt, ADSL)

result

result <- prune_table(
  result,
  prune_func = bspt_pruner(
    fraction = 0.05,
    keeprowtext = "Safety",
    cols = c("Total")
  )
)

result

Building Model Formula

Description

This builds the model formula which is used inside fit_mmrm_j() and provided to mmrm::mmrm() internally. It can be instructive to look at the resulting formula directly sometimes. In particular, if a subgroup variable is included in vars, then the formula will include the interaction of subgroup with arm and visit.

Usage

build_formula(
  vars,
  cor_struct = c("unstructured", "toeplitz", "heterogeneous toeplitz", "ante-dependence",
    "heterogeneous ante-dependence", "auto-regressive", "heterogeneous auto-regressive",
    "compound symmetry", "heterogeneous compound symmetry")
)

Arguments

Value

Formula to use in mmrm::mmrm().

Examples

vars <- list(
  response = "AVAL",
  covariates = c("RACE", "SEX"),
  id = "USUBJID",
  arm = "ARMCD",
  visit = "AVISIT",
  subgroup = "REGION"
)
build_formula(vars, "auto-regressive")
build_formula(vars)

c_function for proportion of TRUE in logical vector

Description

A simple statistics function which prepares the numbers with percentages in the required format, for use in a split content row. The denominator here is from the column N. Note that we don't use here .alt_df because that might not have required row split variables available.

Usage

c_proportion_logical(x, labelstr, label_fstr, format, .N_col)

Arguments

Value

The rtables::in_rows() result with the proportion statistics.

See Also

s_proportion_logical() for the related statistics function.

Simple Content Row Function to Count Rows

Description

Simple Content Row Function to Count Rows

Usage

c_row_counts(df, labelstr, label_fstr)

Value

a VertalRowsSection object (as returned by rtables::in_rows() containing counts from the data.

Simple Content Row Function to Count Rows from Alternative Data

Description

Simple Content Row Function to Count Rows from Alternative Data

Usage

c_row_counts_alt(df, labelstr, label_fstr, .alt_df)

Value

a VertalRowsSection object (as returned by rtables::in_rows() containing counts from the alt data.

Categorize p-values

Description

Assigns each p-value to a category defined by a named list of lower and upper bounds.

Usage

categorize_pval(p, pvalcat)

Arguments

Details

Categories are evaluated in the order supplied by pvalcat. Bounds are lower-inclusive and upper-exclusive, except that the upper bound of the final category is inclusive. P-values that do not fall in a category, including missing values, are returned as NA_character_.

Value

A character vector of category labels, with one element per value in p.

Examples

pvalcat <- list(
  "<0.001" = c(0, 0.001),
  "0.001 to <0.05" = c(0.001, 0.05),
  ">=0.05" = c(0.05, 1)
)

categorize_pval(c(0, 0.001, 0.049, 0.05, 1, NA), pvalcat)

Check Word Wrapping

Description

Check a set of column widths for word-breaking wrap behavior.

Usage

check_wrap_nobreak(tt, colwidths, fontspec)

Arguments

Value

TRUE if the wrap is able to be done without breaking words, FALSE if wordbreaking is required to apply colwidths.

Cochran-Mantel-Haenszel Row Mean Scores test

Description

See https://psiaims.github.io/CAMIS/Comp/r-sas_cmh.html for a general comparison overview between R and SAS.

Usage

a_cmhrms_j(
  df,
  .var,
  ref_path,
  .spl_context,
  .ref_group,
  .in_ref_col,
  .df_row,
  ...,
  variables,
  collapse_combo = TRUE,
  .stats = NULL,
  .formats = NULL,
  .indent_mods = NULL,
  .labels = NULL
)

s_cmhrms_j(
  df,
  .var,
  .ref_group,
  .in_ref_col,
  ...,
  .df_row,
  variables,
  collapse_combo = FALSE
)

a_cmhrms_j_with_exclude(
  df,
  exclude_levels,
  .var,
  .spl_context,
  .ref_group,
  .in_ref_col,
  .df_row,
  ...,
  .stats = NULL,
  .formats = NULL,
  .indent_mods = NULL,
  .labels = NULL
)

Arguments

Value

• s_cmhrms_j a single element list containing the p-value from row mean score test.

• a_cmhrms_j a VerticalRowsSection object (single row).

Functions

• a_cmhrms_j(): Formatted analysis function which is used as afun.

• s_cmhrms_j(): Statistics function for the calculation of the p-value based upon the row mean scores test.

• a_cmhrms_j_with_exclude(): Wrapper for the afun which can exclude row split levels from producing the analysis. These have to be specified in the exclude_levels argument, see ?do_exclude_split for details.

Summary Analysis Function for Compliance Columns

Description

A simple statistics function which prepares the numbers with percentages in the required format, for use in a split content row. The denominator here is from the expected visits column.

Usage

cmp_cfun(df, labelstr, .spl_context, variables, formats)

Arguments

Value

The rtables::in_rows() result with the counts and proportion statistics.

See Also

cmp_post_fun() for the corresponding split function.

Split Function for Compliance Columns

Description

Here we just split into 3 columns for expected, received and missing visits.

Usage

cmp_post_fun(ret, spl, fulldf, .spl_context)

cmp_split_fun(df, spl, vals = NULL, labels = NULL, trim = FALSE, .spl_context)

Arguments

Value

a split function for use with rtables::split_rows_by when creating proportion-based tables with compliance columns.

See Also

rtables::make_split_fun() describing the requirements for this kind of post-processing function.

Statistics within the column space

Description

A function used for obtaining statistics within the columns of your table. Used in change from baseline tables. This takes the visit names as its row labels.

Usage

column_stats(
  df,
  .var,
  .spl_context,
  .formats = NULL,
  formats_var = NULL,
  exclude_visits = c("Baseline (DB)"),
  var_names = c("AVAL", "CHG", "BASE")
)

Arguments

Value

An analysis function (for use with rtables::analyze) implementing the specified statistics.
Typically used in a layout that has been setup by stats_in_cols_setup()

Examples

# example code
library(dplyr)
advs <- ex_advs |>
  filter(AVISIT %in% toupper(c("Screening", "Baseline", "Week 1 Day 8", "Week 2 Day 15"))) |>
  mutate(AVISIT = droplevels(AVISIT)) |>
  filter(PARAMCD %in% c("DIABP", "SYSBP"))
advs_fmt <- tribble(
  ~PARAMCD, ~fmt_d,
  "DIABP", list(
    mean = "xx.xx", sd = "xx.xxx", se = "xx.xxx", median = "xx.xx",
    min = "xx.x", max = "xx.x", mean_sd = "xx.xx (xx.xxx)"
  ),
  "SYSBP", list(
    mean = "xx.x", sd = "xx.xx", se = "xx.xx", median = "xx.x",
    min = "xx.", max = "xx.", mean_sd = "xx.x (xx.xx)"
  )
)

advs <- left_join(advs, advs_fmt)

mysplitfun <- make_split_fun(
  post = list(stats_in_cols_setup())
)

lyt <- basic_table() |>
  split_cols_by_multivar(
    c("AVAL", "BASE", "CHG"),
    varlabels = c("Visit Values", " ", "Change from Baseline")
  ) |>
  split_cols_by("STUDYID", split_fun = mysplitfun) |>
  split_rows_by("PARAM", split_fun = drop_split_levels) |>
  split_rows_by("ARMCD", labels_var = "ARM") |>
  analyze("AVISIT", afun = column_stats, extra_args = list(
    exclude_visits = toupper(c("Baseline", "Screening")),
    .formats = "default",
    formats_var = "fmt_d"
  ))
result <- build_table(lyt, advs, round_type = "sas")
head(result, 20)

Conditional Removal of Facets

Description

Conditional Removal of Facets

Usage

cond_rm_facets(
  facets = NULL,
  facets_regex = NULL,
  ancestor_pos = 1,
  split = NULL,
  split_regex = NULL,
  value = NULL,
  value_regex = NULL,
  keep_matches = FALSE
)

Arguments

Details

Facet removal occurs when the specified condition(s) on the split(s) and or value(s) are met within at least one of the split_context rows indicated by ancestor_pos; otherwise the set of facets is returned unchanged.

If facet removal is performed, either all facets which match facets (or facets_regex will be removed ( the default keep_matches == FALSE case), or all non-matching facets will be removed (when keep_matches_only == TRUE).

Value

A function suitable for use in make_split_fun's post argument which encodes the specified condition.

Note

A degenerate table is likely to be returned if all facets are removed.

Examples

rm_a_from_placebo <- cond_rm_facets(
  facets = "A",
  ancestor_pos = NA,
  value_regex = "Placeb",
  split = "ARM"
)
mysplit <- make_split_fun(post = list(rm_a_from_placebo))

lyt <- basic_table() |>
  split_cols_by("ARM") |>
  split_cols_by("STRATA1", split_fun = mysplit) |>
  analyze("AGE", mean, format = "xx.x")
build_table(lyt, ex_adsl)

rm_bc_from_combo <- cond_rm_facets(
  facets = c("B", "C"),
  ancestor_pos = -1,
  value_regex = "Combi"
)
mysplit2 <- make_split_fun(post = list(rm_bc_from_combo))

lyt2 <- basic_table() |>
  split_cols_by("ARM") |>
  split_cols_by("STRATA1", split_fun = mysplit2) |>
  analyze("AGE", mean, format = "xx.x")
tbl2 <- build_table(lyt2, ex_adsl)
tbl2

rm_bc_from_combo2 <- cond_rm_facets(
  facets_regex = "^A$",
  ancestor_pos = -1,
  value_regex = "Combi",
  keep_matches = TRUE
)
mysplit3 <- make_split_fun(post = list(rm_bc_from_combo2))

lyt3 <- basic_table() |>
  split_cols_by("ARM") |>
  split_cols_by("STRATA1", split_fun = mysplit3) |>
  analyze("AGE", mean, format = "xx.x")
tbl3 <- build_table(lyt3, ex_adsl)

stopifnot(identical(cell_values(tbl2), cell_values(tbl3)))

Formatting functions for count and fraction, and for count denominator and fraction values

Description

Formats a count together with fraction (and/or denominator) with special consideration when count is 0, or fraction is 1.
See also: tern::format_count_fraction_fixed_dp()

Usage

jjcsformat_cnt_den_fract_fct(
  d = 1,
  type = c("count_fraction", "count_denom_fraction", "fraction_count_denom"),
  verbose = FALSE,
  legacy = FALSE
)

jjcsformat_count_fraction(x, round_type = valid_round_type, output, ...)

jjcsformat_count_denom_fraction(x, round_type = valid_round_type, output, ...)

jjcsformat_count_denom_fraction_legacy(
  x,
  round_type = valid_round_type,
  output,
  ...
)

jjcsformat_fraction_count_denom(x, round_type = valid_round_type, output, ...)

jjcsformat_fraction_count_denom_legacy(
  x,
  round_type = valid_round_type,
  output,
  ...
)

Arguments

Value

A formatting function to format input into string in the format ⁠count / denom (ratio percent)⁠. If count is 0, the format is 0. If fraction is >0.99, the format is ⁠count / denom (>99.9 percent)⁠

See Also

Other JJCS formatting functions: jjcsformat_fraction(), jjcsformat_xx()

Examples

jjcsformat_count_fraction(c(7, 0.7))
jjcsformat_count_fraction(c(70000, 70000 / 70001))
jjcsformat_count_fraction(c(235, 235 / 235))
fmt <- jjcsformat_cnt_den_fract_fct(type = "count_fraction", d = 2)
fmt(c(23, 23 / 235))

jjcsformat_count_denom_fraction(c(7, 10, 0.7))
jjcsformat_count_denom_fraction(c(70000, 70001, 70000 / 70001))
jjcsformat_count_denom_fraction(c(235, 235, 235 / 235))
fmt <- jjcsformat_cnt_den_fract_fct(type = "count_denom_fraction", d = 2)
fmt(c(23, 235, 23 / 235))
jjcsformat_count_denom_fraction_legacy(c(0, 235, 0 / 235))

jjcsformat_fraction_count_denom(c(7, 10, 0.7))
jjcsformat_fraction_count_denom(c(70000, 70001, 70000 / 70001))
jjcsformat_fraction_count_denom(c(235, 235, 235 / 235))
fmt <- jjcsformat_cnt_den_fract_fct(type = "fraction_count_denom", d = 2)
fmt(c(23, 235, 23 / 235))
jjcsformat_fraction_count_denom_legacy(c(0, 235, 0 / 235))

Count Pruner

Description

This is a pruning constructor function which identifies records to be pruned based on the count (assumed to be the first statistic displayed when a compound statistic (e.g., ## / ## (XX.X percent) is presented).

Usage

count_pruner(
  count = 0,
  cat_include = NULL,
  cat_exclude = NULL,
  cols = c("TRT01A")
)

Arguments

Value

Function that can be utilized as pruning function in prune_table.

Examples

ADSL <- data.frame(
  USUBJID = c(
    "XXXXX01", "XXXXX02", "XXXXX03", "XXXXX04", "XXXXX05",
    "XXXXX06", "XXXXX07", "XXXXX08", "XXXXX09", "XXXXX10"
  ),
  TRT01P = factor(
    c(
      "ARMA", "ARMB", "ARMA", "ARMB", "ARMB",
      "Placebo", "Placebo", "Placebo", "ARMA", "ARMB"
    )
  ),
  FASFL = c("Y", "Y", "Y", "Y", "N", "Y", "Y", "Y", "Y", "Y"),
  SAFFL = c("N", "N", "N", "N", "N", "N", "N", "N", "N", "N"),
  PKFL = c("N", "N", "N", "N", "N", "N", "N", "N", "N", "N")
)

lyt <- basic_table() |>
  split_cols_by("TRT01P") |>
  add_overall_col("Total") |>
  analyze("FASFL",
    var_labels = "Analysis set:",
    afun = a_freq_j,
    extra_args = list(label = "Full", val = "Y"),
    show_labels = "visible"
  ) |>
  analyze("SAFFL",
    var_labels = "Analysis set:",
    afun = a_freq_j,
    extra_args = list(label = "Safety", val = "Y"),
    show_labels = "visible"
  ) |>
  analyze("PKFL",
    var_labels = "Analysis set:",
    afun = a_freq_j,
    extra_args = list(label = "PK", val = "Y"),
    show_labels = "visible"
  )

result <- build_table(lyt, ADSL)

result

result <- prune_table(
  result,
  prune_func = count_pruner(cat_exclude = c("Safety"), cols = "Total")
)

result

Creation of Column Spanning Mapping Dataframe

Description

A function used for creating a data frame containing the map that is compatible with the rtables split function rtables::trim_levels_to_map().

Usage

create_colspan_map(
  df,
  non_active_grp = c("Placebo"),
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = "TRT01A",
  active_first = TRUE
)

Arguments

Details

This function creates a data frame containing the map that is compatible with the rtables split function rtables::trim_levels_to_map(). The levels of the specified trt_var variable will be stored within the trt_var variable and the colspan_var variable will contain the corresponding spanning header value for each treatment group.

Value

A data frame that contains the map to be used with the rtables split function rtables::trim_levels_to_map().

See Also

rtables::add_combo_levels() for creating split functions that utilize combination levels.

Examples

library(tibble)

df <- tribble(
  ~TRT01A,
  "Placebo",
  "Active 1",
  "Active 2"
)

df$TRT01A <- factor(df$TRT01A, levels = c("Placebo", "Active 1", "Active 2"))

colspan_map <- create_colspan_map(
  df = df,
  non_active_grp = c("Placebo"),
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = "TRT01A"
)

colspan_map

Creation of Column Spanning Variables

Description

A function used for creating a spanning variable for treatment groups.

Usage

create_colspan_var(
  df,
  non_active_grp = c("Placebo"),
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = "TRT01A"
)

Arguments

Details

This function creates a spanning variable for treatment groups that is intended to be used within the column space.

Value

A data frame that contains the new variable as specified in colspan_var.

Examples

library(tibble)

df <- tribble(
  ~TRT01A,
  "Placebo",
  "Active 1",
  "Active 2"
)

df$TRT01A <- factor(df$TRT01A, levels = c("Placebo", "Active 1", "Active 2"))

colspan_var <- create_colspan_var(
  df = df,
  non_active_grp = c("Placebo"),
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Treatment",
  colspan_var = "colspan_trt",
  trt_var = "TRT01A"
)

colspan_var

Utilities for the Current Column Split Path

Description

These helper functions are intended for use in rtables custom analysis functions that depend on the current column split context.

Usage

cur_col_split_path(.spl_context)

in_column(col_path, .spl_context)

Arguments

Value

• cur_col_split_path() returns a character vector containing the current column split path extracted from .spl_context, interleaved as c(var1, val1, var2, val2, ...).

• in_column() returns a single logical value indicating whether the current column split matches the specified col_path.

Functions

• cur_col_split_path(): Get the current column split path.

• in_column(): Determine whether a given column path matches the current column split path.

Author(s)

WW

See Also

• rtables::col_paths() for obtaining column paths from a built table.

Examples

.spl_context_1 <- data.frame(
  cur_col_split = I(list(c("ARM"))),
  cur_col_split_val = I(list(c("Placebo")))
)

.spl_context_2 <- data.frame(
  cur_col_split = I(list(c("ARM", "desc_stat"))),
  cur_col_split_val = I(list(c("Placebo", "N")))
)

cur_col_split_path(.spl_context_1)
cur_col_split_path(.spl_context_2)

in_column(c("ARM", "Placebo"), .spl_context_1)
in_column(c("ARM", "*"), .spl_context_1)
in_column(c("ARM", "X"), .spl_context_1)

in_column(c("ARM", "*", "desc_stat", "N"), .spl_context_2)
in_column(c("ARM", "*", "desc_stat", "Mean"), .spl_context_2)

# Use in an rtables custom analysis function.

data <- formatters::ex_adsl
data$desc_stat <- "phantom"

# analysis function
a_N_mean <- function(x, .spl_context) {
  if (in_column(c("ARM", "*", "desc_stat", "N"), .spl_context)) {
    rcell(length(x))
  } else if (in_column(c("ARM", "*", "desc_stat", "Mean"), .spl_context)) {
    rcell(mean(x), format = "xx.x")
  } else {
    rcell(NULL)
  }
}

combodf <- data.frame(
  valname = c("N", "Mean"),
  label = c("N", "Mean"),
  levelcombo = I(list(select_all_levels, select_all_levels)),
  exargs = I(list(list(), list()))
)

lyt <- basic_table() |>
  split_cols_by("ARM") |>
  split_cols_by(
    "desc_stat",
    split_fun = add_combo_levels(combodf, keep_levels = c("N", "Mean"))
  ) |>
  analyze("AGE", afun = a_N_mean)

tbl <- build_table(lyt, data)
tbl

Get default statistical methods and their associated formats, labels, and indent modifiers

Description

Utility functions to get valid statistic methods for different method groups (.stats) and their associated formats (.formats), labels (.labels), and indent modifiers (.indent_mods). This utility is used across junco, but some of its working principles can be seen in tern::analyze_vars().

Usage

junco_get_stats(
  method_groups = "analyze_vars_numeric",
  stats_in = NULL,
  custom_stats_in = NULL,
  add_pval = FALSE
)

junco_get_formats_from_stats(stats, formats_in = NULL, levels_per_stats = NULL)

junco_get_labels_from_stats(
  stats,
  labels_in = NULL,
  levels_per_stats = NULL,
  label_attr_from_stats = NULL
)

get_label_attr_from_stats(x_stats)

junco_get_indents_from_stats(stats, indents_in = NULL, levels_per_stats = NULL)

format_stats(
  x_stats,
  method_groups,
  stats_in,
  formats_in,
  labels_in,
  indents_in,
  .cell_footnotes = list(NULL),
  .row_footnotes = list(NULL)
)

junco_default_stats

junco_default_formats

junco_default_labels

junco_default_indents

Arguments

Format

• junco_default_stats is a named list of available statistics, with each element named for their corresponding statistical method group.

• junco_default_formats is a named vector of available default formats, with each element named for their corresponding statistic.

• junco_default_labels is a named character vector of available default labels, with each element named for their corresponding statistic.

• junco_default_indents is a named integer vector of available default indents, with each element named for their corresponding statistic. Only indentations different from zero need to be recorded here.

Details

Current choices for type are counts and numeric for tern::analyze_vars() and affect junco_get_stats().

Value

• junco_get_stats() returns a character vector of statistical methods.

• junco_get_formats_from_stats() returns a named list of formats as strings or functions.

• junco_get_labels_from_stats() returns a named list of labels as strings.

• junco_get_indents_from_stats() returns a named list of indentation modifiers as integers. By default all of the indentations will be zero.

• format_stats() returns the correspondingly formatted rtables::in_rows() result.

Functions

• junco_get_stats(): Get statistics available for a given method group (analyze function). To check available defaults see junco_default_stats list.

• junco_get_formats_from_stats(): Get formats corresponding to a list of statistics. To check available defaults see list junco_default_formats.

• junco_get_labels_from_stats(): Get labels corresponding to a list of statistics. To check for available defaults see list junco_default_labels.

• get_label_attr_from_stats(): Get label attributes from statistics list.

• junco_get_indents_from_stats(): Get row indent modifiers corresponding to a list of statistics/rows.

• format_stats(): Format statistics results according to format specifications.

• junco_default_stats: Named list of available statistics by method group for junco.

• junco_default_formats: Named vector of default formats for junco.

• junco_default_labels: Named character vector of default labels for junco.

• junco_default_indents: Named integer vector of default indents for junco.

Note

These defaults are experimental because we use the names of functions to retrieve the default statistics. This should be generalized in groups of methods according to more reasonable groupings.

These functions have been modified from the tern file utils_default_stats_formats_labels.R. This file contains junco specific wrappers of functions called within the afun functions, in order to point to junco specific default statistics, formats and labels.

Formats in tern or junco and rtables can be functions that take in the table cell value and return a string. This is well documented in vignette('custom_appearance', package = 'rtables').

Default String Mapping for Special Characters

Description

A tibble that maps special characters to their UTF-8 equivalents for use in RTF output. Currently it maps ">=" and "<=" to the Unicode characters.

Usage

default_str_map

Value

A tibble with columns 'pattern' and 'value', where 'pattern' contains the string to be replaced and 'value' contains the replacement.

Difference in Means

Description

Computes estimates and associated inferential statistics for the estimand defined as the difference in population means between two distributions.

The following quantities are available:

diff_means_n1

Sample size of Group 1.

diff_means_n2

Sample size of Group 2.

diff_means_est

Point estimate of the difference in population means.

diff_means_se

Standard error of the estimator of the difference in population means.

diff_means_est_se

The point estimate and the standard error.

diff_means_ci

Confidence interval for the difference in population means.

diff_means_est_ci

The point estimate and the confidence interval.

Usage

s_diff_means(df1, df2, .var, paired = FALSE, paired_by = NULL, ...)

a_diff_means(
  df,
  .var,
  .spl_context,
  ref_path = NULL,
  ...,
  .stats = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Details

Supports both non-paired and paired samples. For non-paired samples, the estimator is defined as the difference between sample means. For paired samples, the estimator is defined as the mean of within-pair differences.

Inferential statistics, including standard errors and confidence intervals, are obtained using a t-distribution framework via the internal safe_t_test() function.

It supports only numeric variables. Only complete (non-missing) observations are used in statistical computations. Non-finite values (i.e., Inf, -Inf) are not allowed.

Value

• s_diff_means() returns a named list containing the quantities described in the Description section.

• a_diff_means() returns formatted rtables::in_rows() result with the quantities requested in .stats.

Functions

• s_diff_means(): Statistical function that computes estimates of the difference in means. The first sample is taken from df1[[.var]] and the second from df2[[.var]].

  If paired = FALSE, missing values are removed separately from each sample prior to statistical computations. If paired = TRUE, observations are matched using paired_by prior to statistical analysis, and only complete pairs are used.

  Data extraction, alignment, and missing-value handling are delegated to the internal extract_vectors() function, which prepares cleaned numeric vectors for both paired and unpaired settings.

  Inferential statistics are then computed using safe_t_test() applied to the processed vectors.

• a_diff_means(): Formatted analysis function which is used as afun in rtables::analyze().

  The sample from the first distribution is df[[.var]], and the sample from the second distribution is .ref_group[[.var]], where .ref_group is computed by get_ref_info() using .spl_context and ref_path.

  If ref_path = NULL, then a_diff_means() returns an rtables::in_rows() result with an empty formatted_cell for every statistic specified in .stats.

Author(s)

WW

See Also

safe_t_test(), extract_vectors()

Examples

## Statistics function:

df1 <- data.frame(id = c("A", "B", "C", "D"), value = 1:4)
df2 <- data.frame(id = c("A", "C", "D", "E", "F"), value = c(3:1, NA, 16))

# Unpaired samples.
s_diff_means(df1, df2, "value", conf.level = .8)

# Paired samples.
s_diff_means(df1, df2, "value", paired = TRUE, paired_by = "id")


## Analysis  function:

lyt <- basic_table() |>
  split_cols_by("ARM") |>
  split_rows_by(
    "PARAMCD",
    labels_var = "PARAM",
    split_fun = keep_split_levels(c("SYSBP", "DIABP"))
  ) |>
  split_rows_by(
    "AVISIT",
    split_fun = keep_split_levels(c("BASELINE", "WEEK 1 DAY 8"))
  ) |>
  analyze(
    "AVAL",
    afun = tern::a_summary,
    extra_args = list(.stats = c("n", "mean")),
    show_labels = "hidden"
  ) |>
  analyze(
    "AVAL",
    afun = a_diff_means,
    table_names = "aval_diff",
    extra_args = list(
      .stats = "diff_means_est_ci",
      ref_path = c("ARM", "B: Placebo")
    ),
    show_labels = "hidden"
  )

tbl <- build_table(lyt, formatters::ex_advs)
tbl

Predicate to Check if Split Should be Excluded

Description

Predicate to Check if Split Should be Excluded

Usage

do_exclude_split(exclude_levels, .spl_context)

Arguments

Value

TRUE if the current split context matches any of the exclude levels, FALSE otherwise.

Examples

do_exclude_split(
  exclude_levels = list(AVISIT = "Baseline"),
  .spl_context = data.frame(
    split = c("AVISIT", "ARM"),
    value = c("Week 4", "Placebo")
  )
)
do_exclude_split(
  exclude_levels = list(AVISIT = "Baseline"),
  .spl_context = data.frame(
    split = c("AVISIT", "ARM"),
    value = c("Baseline", "Placebo")
  )
)

Workaround statistics function to time point survival estimate with CI

Description

This is a workaround for tern::s_surv_timepoint(), which adds a statistic containing the time point specific survival estimate together with the confidence interval.

Usage

a_event_free(
  df,
  .var,
  ...,
  .stats = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_event_free(
  df,
  .var,
  time_point,
  time_unit,
  is_event,
  percent = FALSE,
  control = control_surv_timepoint()
)

Arguments

Value

• s_event_free returns a list as returned by the tern::s_surv_timepoint() with an additional three-dimensional statistic event_free_ci which combines the event_free_rate and rate_ci statistics.

• a_event_free is analogous to tern::a_surv_timepoint but with the additional three-dimensional statistic described above available via .stats.

Functions

• a_event_free(): Formatted analysis function which is used as afun.

• s_event_free(): Statistics function which works like tern::s_surv_timepoint(), the difference is that it returns the additional statistic event_free_ci.

Examples

adtte_f <- tern::tern_ex_adtte |>
  dplyr::filter(PARAMCD == "OS") |>
  dplyr::mutate(
    AVAL = tern::day2month(AVAL),
    is_event = CNSR == 0
  )

basic_table() |>
  split_cols_by(var = "ARMCD") |>
  analyze(
    vars = "AVAL",
    afun = a_event_free,
    show_labels = "hidden",
    na_str = tern::default_na_str(),
    extra_args = list(
      time_unit = "week",
      time_point = 3,
      is_event = "is_event"
    )
  ) |>
  build_table(df = adtte_f)
adtte_f <- tern::tern_ex_adtte |>
  dplyr::filter(PARAMCD == "OS") |>
  dplyr::mutate(
    AVAL = tern::day2month(AVAL),
    is_event = CNSR == 0
  )

s_event_free(
  df = adtte_f,
  .var = "AVAL",
  time_point = 6,
  is_event = "is_event",
  time_unit = "month"
)

Export a TLG (Table, Listing, Graph) to .docx format

Description

Export a TLG (Table, Listing, Graph) to .docx format

Usage

export_TLG_as_docx(
  obj = NULL,
  tblid = NULL,
  output_dir = NULL,
  theme = theme_docx_default_j(font = "Times New Roman", font_size = 9L, bold = NULL),
  add_page_break = FALSE,
  titles_as_header = TRUE,
  integrate_footers = TRUE,
  section_properties = officer::prop_section(page_size = officer::page_size(width = 11,
    height = 8.5, orient = orientation), page_margins = officer::page_mar(bottom = 1, top
    = 1, right = 1, left = 1, gutter = 0, footer = 1, header = 1)),
  doc_metadata = NULL,
  template_file = NULL,
  orientation = "portrait",
  paginate = tlgtype == "Table",
  nosplitin = list(row = character(), col = character()),
  string_map = default_str_map,
  markup_df_docx = dps_markup_df_docx,
  combined_docx = FALSE,
  tlgtype = ifelse(is.null(obj), "Figure", tlg_type(obj)),
  col_gap = ifelse(tlgtype == "Listing", 0.5, 3),
  pagenum = ifelse(tlgtype == "Listing", TRUE, FALSE),
  round_type = ifelse(tlgtype %in% c("Table", "Listing"),
    formatters::obj_round_type(obj), "iec"),
  alignments = list(),
  border = flextable::fp_border_default(width = 0.875, color = "black"),
  border_mat = NULL,
  export_csv = FALSE,
  output_csv_directory = NULL,
  markup_df = dps_markup_df,
  validate = TRUE,
  watermark = NULL,
  plotnames = NULL,
  title = NULL,
  footers = NULL,
  plotwidth = 8,
  plotheight = 5.51,
  units = c("in", "cm", "mm", "px")[1],
  ...
)

Arguments

Note

This function may be removed from junco in the future if the functionality is merged into rtables.officer.

For more information, refer to the vignette table_and_listing_customizations (browseVignettes("junco"))

Examples

adsl <- ex_adsl
adae <- ex_adae
extra_args_1 <- list(
  .stats = c("count_unique_denom_fraction")
)
lyt1 <- basic_table(show_colcounts = TRUE) |>
split_cols_by("ARM") |>
analyze(
  vars = "COUNTRY",
  afun = a_freq_j,
  extra_args = extra_args_1
)
tbl1 <- build_table(lyt1, adsl)
tab_titles <- list(
  "title" = "This is the main Title",
  "subtitles" = NULL,
  "main_footer" = c(
  "footer 1",
  "footer 2"
  ),
  "prov_footer" = NULL)
tbl1b <- set_titles(tbl1, tab_titles)

export_TLG_as_docx(
  obj = tbl1b,
  tblid = "test",
  output_dir = tempdir(),
  theme = theme_docx_default_j(), add_page_break = FALSE,
  titles_as_header = TRUE, integrate_footers = TRUE,
  section_properties = officer::prop_section(
    page_size = officer::page_size(width = 11, height = 8.5, orient = "portrait"),
    page_margins = officer::page_mar(
                             bottom = 1,
                             top = 1,
                             right = 1,
                             left = 1,
                             gutter = 0,
                             footer = 1,
                             header = 1)
  ),
  doc_metadata = NULL,
  template_file = NULL,
  orientation = "portrait",
  paginate = FALSE,
  nosplitin = list(
    row = character(),
    col = character()
  ),
  string_map = default_str_map,
  markup_df_docx = junco:::dps_markup_df_docx,
  combined_docx = FALSE,
  tlgtype = "Table",
  col_gap = 3,
  pagenum = FALSE,
  round_type = "iec",
  alignments = list(),
  border = flextable::fp_border_default(width = 0.875, color = "black"),
  border_mat = NULL,
  watermark = NULL,
  plotnames = NULL,
  title = NULL,
  footers = NULL,
  plotwidth = 8,
  plotheight = 5.51,
  units = "in"
)

Export a VTableTree or a listing_df object into docx

Description

This function is based on rtables.officer::export_as_docx().

Usage

export_as_docx_j(
  tt,
  tblid = NULL,
  output_dir = NULL,
  theme = theme_docx_default_j(font = "Times New Roman", font_size = 9L, bold = NULL),
  add_page_break = FALSE,
  titles_as_header = TRUE,
  integrate_footers = TRUE,
  section_properties = officer::prop_section(page_size = officer::page_size(width = 11,
    height = 8.5, orient = orientation), page_margins = officer::page_mar(bottom = 1, top
    = 1, right = 1, left = 1, gutter = 0, footer = 1, header = 1)),
  doc_metadata = NULL,
  template_file = NULL,
  orientation = "portrait",
  paginate = tlgtype == "Table",
  nosplitin = list(row = character(), col = character()),
  string_map = default_str_map,
  markup_df_docx = dps_markup_df_docx,
  combined_docx = FALSE,
  tlgtype = tlg_type(tt),
  col_gap = ifelse(tlgtype == "Listing", 0.5, 3),
  pagenum = ifelse(tlgtype == "Listing", TRUE, FALSE),
  round_type = formatters::obj_round_type(tt),
  alignments = list(),
  border = flextable::fp_border_default(width = 0.875, color = "black"),
  border_mat = make_header_bordmat(obj = tt),
  watermark = NULL,
  export_csv = FALSE,
  output_csv_directory = NULL,
  markup_df = dps_markup_df,
  validate = TRUE,
  ...
)

Arguments

Note

This function may be removed from junco in the future if the functionality is merged into rtables.officer.

For more information, refer to the vignette table_and_listing_customizations (browseVignettes("junco"))

export_graph_as_docx

Description

Export graph in DOCX format.

Usage

export_graph_as_docx(
  g = NULL,
  plotnames = NULL,
  tblid = NULL,
  output_dir = NULL,
  title = NULL,
  footers = NULL,
  orientation = "portrait",
  plotwidth = 8,
  plotheight = 5.51,
  units = c("in", "cm", "mm", "px")[1],
  border = flextable::fp_border_default(width = 0.875, color = "black"),
  watermark = NULL
)

Arguments

Note

This function may be removed from junco in the future if the functionality is merged into rtables.officer.

For more information, refer to the vignette table_and_listing_customizations (browseVignettes("junco"))

Create a factor with levels ordered by a separate ordering vector

Description

Converts a character vector or factor into a factor where the level order is determined by a second integer-like vector containing the corresponding order values.

Usage

factor_by_order(x, y, ordered = FALSE)

Arguments

Details

The values in x and y must define a bijection between the unique non-missing values: each unique value in x must correspond to exactly one unique value in y, and vice versa. Missing values are handled separately: NA values in x and y must occur at the same positions. Missing values are not included as factor levels.

If x is already a factor containing unobserved (unused) levels, these unobserved levels will be dropped in the resulting factor.

Value

A factor created from x, with levels ordered according to y. Attributes of x other than class and levels are preserved. If ordered = TRUE, an ordered factor is returned. If x is empty or consists entirely of missing values, a factor with no levels is returned.

Author(s)

WW

Examples

factor_by_order(c("A", "A", "B"), c(1, 1, 2))

factor_by_order(c("A", "A", "B"), c(1, 1, 2), ordered = TRUE)

factor_by_order(c("A", "A", "B"), c(2, 2, 1))

factor_by_order(c("A", "A", "B", NA), c(1, 1, 2, NA))

## Not run: 
factor_by_order(c("A", "A", "B", NA), c(1, 2, 2, 4))

## End(Not run)

Helper for Finding AVISIT after which CHG are all Missing

Description

Helper for Finding AVISIT after which CHG are all Missing.

Usage

find_missing_chg_after_avisit(df)

Arguments

Value

A string with either the factor level after which AVISIT is all missing, or NA.

Examples

df <- data.frame(
  AVISIT = factor(c(1, 2, 3, 4, 5)),
  CHG = c(5, NA, NA, NA, 3)
)
find_missing_chg_after_avisit(df)

df2 <- data.frame(
  AVISIT = factor(c(1, 2, 3, 4, 5)),
  CHG = c(5, NA, 3, NA, NA)
)
find_missing_chg_after_avisit(df2)

df3 <- data.frame(
  AVISIT = factor(c(1, 2, 3, 4, 5)),
  CHG = c(NA, NA, NA, NA, NA)
)
find_missing_chg_after_avisit(df3)

ANCOVA Analysis

Description

Performs the ANCOVA analysis, separately for each visit.

Usage

fit_ancova(
  vars = list(response = "AVAL", covariates = c(), arm = "ARM", visit = "AVISIT", id =
    "USUBJID"),
  data,
  conf_level = 0.95,
  weights_emmeans = "proportional"
)

Arguments

Value

A tern_model object which is a list with model results:

• fit: A list with a fitted stats::lm() result for each visit.

• mse: Mean squared error, i.e. variance estimate, for each visit.

• df: Degrees of freedom for the variance estimate for each visit.

• lsmeans: This is a list with data frames estimates and contrasts. The attribute weights savse the settings used (weights_emmeans).

• vars: The variable list.

• labels: Corresponding list with variable labels extracted from data.

• ref_level: The reference level for the arm variable, which is always the first level.

• treatment_levels: The treatment levels for the arm variable.

• conf_level: The confidence level which was used to construct the lsmeans confidence intervals.

Examples

library(mmrm)

fit <- fit_ancova(
  vars = list(
    response = "FEV1",
    covariates = c("RACE", "SEX"),
    arm = "ARMCD",
    id = "USUBJID",
    visit = "AVISIT"
  ),
  data = fev_data,
  conf_level = 0.9,
  weights_emmeans = "equal"
)

MMRM Analysis

Description

Does the MMRM analysis. Multiple other functions can be called on the result to produce tables and graphs.

Usage

fit_mmrm_j(
  vars = list(response = "AVAL", covariates = c(), id = "USUBJID", arm = "ARM", visit =
    "AVISIT", subgroup = NULL),
  data,
  conf_level = 0.95,
  cor_struct = "unstructured",
  weights_emmeans = "counterfactual",
  averages_emmeans = list(),
  mult_adj_emmeans = c("none", "dunnett", "step-down-dunnett"),
  ...
)

Arguments

Details

Multiple different degree of freedom adjustments are available via the method argument for mmrm::mmrm(). In addition, covariance matrix adjustments are available via vcov. Please see mmrm::mmrm_control() for details and additional useful options.

For the covariance structure (cor_struct), the user can choose among the following options.

• unstructured: Unstructured covariance matrix. This is the most flexible choice and default. If there are T visits, then T * (T+1) / 2 variance parameters are used.

• toeplitz: Homogeneous Toeplitz covariance matrix, which uses T variance parameters.

• ⁠heterogeneous toeplitz⁠: Heterogeneous Toeplitz covariance matrix, which uses 2 * T - 1 variance parameters.

• ante-dependence: Homogeneous Ante-Dependence covariance matrix, which uses T variance parameters.

• ⁠heterogeneous ante-dependence⁠: Heterogeneous Ante-Dependence covariance matrix, which uses 2 * T - 1 variance parameters.

• auto-regressive: Homogeneous Auto-Regressive (order 1) covariance matrix, which uses 2 variance parameters.

• ⁠heterogeneous auto-regressive⁠: Heterogeneous Auto-Regressive (order 1) covariance matrix, which uses T + 1 variance parameters.

• ⁠compound symmetry⁠: Homogeneous Compound Symmetry covariance matrix, which uses 2 variance parameters.

• ⁠heterogeneous compound symmetry⁠: Heterogeneous Compound Symmetry covariance matrix, which uses T + 1 variance parameters.

Value

A tern_model object which is a list with model results:

• fit: The mmrm object which was fitted to the data. Note that via mmrm::component(fit, 'optimizer') the finally used optimization algorithm can be obtained, which can be useful for refitting the model later on.

• cov_estimate: The matrix with the covariance matrix estimate.

• diagnostics: A list with model diagnostic statistics (REML criterion, AIC, corrected AIC, BIC).

• lsmeans: This is a list with data frames estimates and contrasts. The attributes averages, weights and mult_adj save the settings used (averages_emmeans, weights_emmeans and mult_adj_emmeans).

• vars: The variable list.

• labels: Corresponding list with variable labels extracted from data.

• cor_struct: input.

• ref_level: The reference level for the arm variable, which is always the first level.

• treatment_levels: The treatment levels for the arm variable.

• conf_level: The confidence level which was used to construct the lsmeans confidence intervals.

• additional: List with any additional inputs passed via ...

Note

This function has the ⁠_j⁠ suffix to distinguish it from mmrm::fit_mmrm(). It is modified from the tern.mmrm package. The new features are:

• the mult_adj_emmeans argument and its functionality

• the subgroup variable in vars and its functionality

These could later be contributed upstream in tern.mmrm.

Examples

mmrm_results <- fit_mmrm_j(
  vars = list(
    response = "FEV1",
    covariates = c("RACE", "SEX"),
    id = "USUBJID",
    arm = "ARMCD",
    visit = "AVISIT"
  ),
  data = mmrm::fev_data,
  cor_struct = "unstructured",
  weights_emmeans = "equal",
  averages_emmeans = list(
    "VIS1+2" = c("VIS1", "VIS2")
  )
)

Utilities for processing d-style string formatting specifications (eg "xx.dx")

Description

Usage

fmt_spec_single_d(
  d = 1,
  stats_in = NULL,
  fmt_d_def = junco_def_d_all,
  fmt_d_in = NULL
)

fmt_spec_df_d(
  df_d,
  d_column = "d",
  fmt_column = "fmt_d",
  stats_in = NULL,
  fmt_d_def = junco_def_d_all,
  fmt_d_in = NULL
)

fmt_spec_var_d(
  var_d,
  stats_in = NULL,
  fmt_d_def = junco_def_d_all,
  fmt_d_in = NULL
)

junco_def_d_all

junco_def_d_alt1

junco_def_d_alt2

Arguments

Format

• junco_def_d_all Used as default input vector for argument fmt_d_def in functions fmt_spec_single_d(), fmt_spec_df_d() and fmt_spec_var_d() (corresponds to the named vector of with default available formats junco_default_formats with d = 1)

• junco_def_d_alt1 Alternative vector of d-style specification defaults.

• junco_def_d_alt2 Another alternative vector of d-style specification defaults.

Details

Format specifications in d-style notation (such as "xx.dx") will be translated to string based formats (or wrapped with jjcsformat_xx()), eg "xx.dx" will be translated into "xx.xx", when d = 1.

Functions

• fmt_spec_single_d(): Function to convert a named list using d-style string format specification into a named list with valid formatters formatting specification

• fmt_spec_df_d(): Function to convert an input column with d-style formatting specification into a new column with valid formatters formatting specification.

  The new column can be passed onto argument formats_var in rtables::analyze() function.

• fmt_spec_var_d(): Function to convert a named list of variables with d-style formatting specification into a named list with valid formatters formatting specification.

  The result can be used as input for argument format in rtables::analyze() call.

• junco_def_d_all: Named vector of default format specification using d-style notation.

• junco_def_d_alt1: Alternative vector of d-style specification defaults.

• junco_def_d_alt2: Another alternative vector of d-style specification defaults.

Examples

junco_def_d <- c(
  "mean" = "xx.dx",
  "mean_sd" = "xx.dx (xx.dxx)",
  "mean_se" = "xx.dx (xx.dxx)",
  "range" = "(xx.d, xx.d)"
)
myfmts <- fmt_spec_single_d(
  d = 1,
  stats_in = c("mean", "mean_sd"),
  fmt_d_def = junco_def_d,
  fmt_d_in = NULL
)
myfmts

# example for fmt_spec_df_d ----
library(dplyr)
df_d <- tribble(
  ~PARAMCD, ~d,
  "DIABP", 2L,
  "PULSE", 3L,
  "RESP", 1L
)
yy <- fmt_spec_df_d(df_d,
  d_column = "d",
  fmt_column = "fmt_d",
  stats_in = NULL,
  fmt_d_def = junco_def_d,
  fmt_d_in = NULL
)


df <- ex_advs |>
  filter(PARAMCD %in% c("DIABP", "PULSE", "RESP")) |>
  filter(AVISIT %in% c("BASELINE", "WEEK 1 DAY 8", "WEEK 2 DAY 15"))
df <- df |>
  left_join(yy)

lyt <- basic_table() |>
  split_cols_by("ARMCD") |>
  split_rows_by("PARAMCD", split_fun = drop_split_levels) |>
  split_rows_by("AVISIT", split_fun = drop_split_levels) |>
  analyze(
    vars = "AVAL",
    afun = tern::a_summary,
    extra_args = list(
      .stats = c("n", "mean_se", "range"),
      .formats = "default"
    ),
    formats_var = "fmt_d"
  )

rslt <- build_table(lyt, df, alt_counts_df = ex_adsl)
rslt

# example for fmt_spec_var_d ----
var <- c("AGE" = 0, "BMI" = 1, "BMRKR1" = 2)
vars_fmt <- fmt_spec_var_d(var,
  stats_in = NULL,
  fmt_d_def = junco_def_d,
  fmt_d_in = NULL
)
vars_fmt
lyt <- basic_table() |>
  split_cols_by("ARMCD") |>
  analyze(
    vars = c("AGE", "BMRKR1"),
    afun = tern::a_summary,
    extra_args = list(
      .stats = c("n", "mean_sd", "range"),
      .formats = "default"
    ),
    format = vars_fmt,
    section_div = " "
  )

rslt <- build_table(lyt, ex_adsl)
rslt

Utilities for reviewing format specification objects

Description

Usage

get_fmt_details(myfmts, recursive = FALSE, as_tibble = TRUE)

compare_fmt_specs(fmt1, fmt2)

Arguments

Details

fmt_utils general details

Functions

• get_fmt_details(): A utility function to collect information on formatting specification in list or tibble format.

  The following information is collected:

  • var (variable name): Only applicable if the format specification is a named list with formattings specs (eg list("AGE" = c("mean" = "xx", "se" = "xx.x"), "BMI" = c("mean" = "xx.x", "se" = "xx.xx"))), eg processed via fmt_spec_var_d function.

  • stat (name of statistic)

  • fun_fact : name of function factory that has produced the format specification (if spec is from formatting function, blank if spec is string).
    Only the following known formatting functions are supported:

    • jjcsformat_xx

    • jjcsformat_cnt_den_fract_fct,

    • jjcsformat_pval_fct,

    • jjcsformat_range_fct,

    • tern::format_xx,

    • tern::format_extreme_values,

    • tern::format_extreme_values_ci,

    • tern::format_count_fraction_fixed_dp,

    • tern::format_count_fraction,

    • tern::format_fraction_fixed_dp,

    • format_sigfig_j

  • str: string from specification, or str from formatting function factory (jjcsformat_xx, ....)

  • str_formatters: (logical) Is the str value a valid format string as in (list_valid_format_labels())?

  • type: when formatting function factory jjcsformat_cnt_den_fract_fct is used

  • alpha: when formatting function factory jjcsformat_pval_fct is used

  • message: Message when formatting function is unknown, or input string was not valid format string as in (list_valid_format_labels())

  • fmt_package: In which package was the formatting specification defined.

  • is_fun: (logical) Is the formatting specification a function?

  • round_type: (logical) Does the formatting support round_type argument/behavior?

  • fun: Formatting string or body of the formatting function.

  Only when one of the formats provided is based upon formatting function factory format_sigfig_j setup:

  • d: value used for sigfig

  • whole_integer: value used for whole_integer

  • drop0trailing: value used for drop0trailing

  • zero_threshold: value used for zero_threshold

• compare_fmt_specs(): A utility to report findings in differences between 2 formatting specification vectors. It returns a list object with the following information:

  • spec1 : For statistics with a different specification, tibble with specification details from fmt1.

  • spec2 : For statistics with a different specification, tibble with specification details from fmt2. The tibbles in spec1 and spec2 contain information as described in get_fmt_details().

  • msg: Message on how many stats have a difference in specification.

  • comm_stats: Vector of stats in common between fmt1 and fmt2.

  • diff_stats: Vector of stats with any difference identified.

Examples

# Example for get_fmt_details --
junco_def_d <- c(
  "mean" = "xx.dx",
  "mean_sd" = "xx.dx (xx.dxx)",
  "range" = "(xx.d, xx.d)"
)

myfmts <- fmt_spec_single_d(
  d = 1,
  stats_in = c("mean", "mean_sd"),
  fmt_d_def = junco_def_d,
  fmt_d_in = NULL
)

fmt_details <- get_fmt_details(myfmts, as_tibble = TRUE)

myfmts2 <- fmt_spec_single_d(
  d = 3,
  stats_in = c("mean", "mean_sd"),
  fmt_d_def = junco_def_d,
  fmt_d_in = NULL
)
fmt_details2 <- get_fmt_details(myfmts2, as_tibble = TRUE)
fmt_details2

# Example for get_fmt_details using format specs for variables --
# processed with fmt_spec_var_d
var <- c("AGE" = 0, "BMI" = 1, "BMRKR1" = 2)
vars_fmt <- fmt_spec_var_d(var,
  stats_in = NULL,
  fmt_d_def = junco_def_d,
  fmt_d_in = NULL
)
fmt_details2 <- get_fmt_details(vars_fmt, as_tibble = TRUE, recursive = TRUE)


# Example for compare_fmt_specs --
test1_target <- junco_default_formats
# junco_def_d_all has been constructed with d = 1 as reference
# compare against junco_default_formats
test1_d <- fmt_spec_single_d(
  d = 1,
  stats_in = NULL,
  fmt_d_def = junco_def_d_all,
  fmt_d_in = NULL
)

check1 <- compare_fmt_specs(test1_d, test1_target)
check1

# more differences when using other d
test2_d <- fmt_spec_single_d(
  d = 2,
  stats_in = NULL,
  fmt_d_def = junco_def_d_all,
  fmt_d_in = NULL
)

check2 <- compare_fmt_specs(test2_d, test1_target)

Format numeric values by significant figures.

Description

Format numeric values by significant figures with controllable round_type, whole_integer and trailing zeros.
The underlying function for significant figures is modified_signif_j(), which is a modified version for base::signif()

Usage

format_sigfig_j(
  sigfig,
  format = "xx",
  whole_integer = TRUE,
  zero_threshold = 10^(-2 * sigfig),
  drop0trailing = FALSE
)

modified_signif_j(
  x,
  digits = 6,
  round_type = valid_round_type,
  whole_integer = FALSE,
  zero_threshold = 0
)

Arguments

Value

A formatting function with signature ⁠function(x, round_type, ...)⁠ that returns a formatted string. The round_type argument accepts rounding methods ("iec", "iec_mod", "sas") (see formatters::round_fmt()).

Functions

• format_sigfig_j(): A function factory that produces formatting functions to round values to a specified number of significant figures, suitable for use with formatters::format_value().
  
  The function is an alternative to tern::format_sigfig(), format_sigfig_j() has fixed the formatC argument num_fmt = "fg", and has extra options for whole_integer and drop0trailing to control the format behavior.

• modified_signif_j(): A modified version of base function base::signif with 3 extensions:

  • Rounding is performed using formatters::round_fmt(), and allows for round types ("iec", "iec_mod", "sas")
    

  • Very small absolute values can be treated as zero (zero_threshold).
    

  • All significant figures to the left of the decimal marker can be shown (whole_integer), rather than limiting the result to the specified number of significant figures.

  Returns a numeric vector of the same length as x, rounded to digits significant figures.

See Also

tern::format_sigfig()

Examples

fmt <- format_sigfig_j(3)
fmt(0.001234)
fmt(1234.5)

fmt2 <- format_sigfig_j(3, format = "xx (xx)")
fmt2(c(1234.5, 0.00567))


format_sigfig_j(3, drop0trailing = FALSE)(0.01)
format_sigfig_j(3, drop0trailing = TRUE)(0.01)
# example code
junco:::modified_signif_j(c(0.1, 1e-9, 1256.0, 1256.5, 1256.3, 1254.5, 1256.5),
  digits = 3,
  zero_threshold = 0,
  whole_integer = TRUE,
  round_type = "sas"
)

junco:::modified_signif_j(c(0.1, 1e-9, 1256.0, 1256.5, 1256.3, 1254.5, 1256.5),
  digits = 3,
  zero_threshold = 1e-6,
  whole_integer = TRUE,
  round_type = "sas"
)

Get Control Subset

Description

Retrieves a subset of the DataFrame based on treatment variable and control group.

Usage

get_ctrl_subset(df, trt_var, ctrl_grp)

Arguments

Value

Subset of the data frame.

Extract Least Square Means from MMRM

Description

Extracts the least square means from an MMRM fit.

Usage

get_mmrm_lsmeans(
  fit,
  vars,
  conf_level,
  weights,
  averages = list(),
  mult_adj = c("none", "dunnett", "step-down-dunnett")
)

Arguments

Value

A list with data frames estimates and contrasts. The attributes averages, weights and mult_adj save the settings used.

Note

This is modified from tern.mmrm and has the additional mult_adj argument.

Obtain reference group information from split context.

Description

get_ref_info() identifies a reference group defined by a column-split path and returns both the reference-group data and an indicator of whether the current column is the reference column. It is intended for use inside custom rtables analysis functions.

The reference group is specified using ref_path, which consists of alternating column-split variable names and its corresponding levels. For example, c("SEX", "F", "ARM", "Placebo") specifies the column-split path where SEX is "F" and ARM is "Placebo".

Usage

get_ref_info(ref_path, .spl_context, .var = NULL)

Arguments

Value

A list with the following elements:

• in_ref_col (logical(1) or NULL) indicates whether the current column matches the reference path. This corresponds to .in_ref_col in rtables::additional_fun_params.

• ref_group (data.frame, vector, or NULL) contains the observations belonging to the reference group. If .var is NULL, the complete data frame is returned; otherwise, the column specified by .var is returned. This corresponds to .ref_group in rtables::additional_fun_params.

If the reference path is not present in the current column-split hierarchy, both elements are NULL.

Examples

dm <- DM
dm$colspan_trt <- factor(
  ifelse(dm$ARM == "B: Placebo", " ", "Active Study Agent"),
  levels = c("Active Study Agent", " ")
)
colspan_trt_map <- create_colspan_map(
  dm,
  non_active_grp = "B: Placebo",
  non_active_grp_span_lbl = " ",
  active_grp_span_lbl = "Active Study Agent",
  colspan_var = "colspan_trt",
  trt_var = "ARM"
)

# A standard analysis function which uses a reference group.
standard_afun <- function(x, .ref_group, .in_ref_col) {
  diff_means <- if (isFALSE(.in_ref_col)) {
    mean(x) - mean(.ref_group)
  } else {
    NULL
  }
  in_rows(
    m = rcell(mean(x), label = "Mean"),
    dm = rcell(diff_means, label = "Difference in Means vs Placebo"),
    .formats = "xx.xx"
  )
}

# The custom analysis function which can work with a global reference group.
result_afun <- function(x, ref_path, .spl_context, .var) {
  ref <- get_ref_info(ref_path, .spl_context, .var)
  standard_afun(x, .ref_group = ref$ref_group, .in_ref_col = ref$in_ref_col)
}

ref_path <- c("colspan_trt", " ", "ARM", "B: Placebo")

lyt <- basic_table() |>
  split_cols_by("colspan_trt", split_fun = trim_levels_to_map(colspan_trt_map)) |>
  split_cols_by("ARM") |>
  add_overall_col("Total") |>
  analyze("AGE", afun = result_afun, extra_args = list(ref_path = ref_path))

build_table(lyt, dm)

Get Titles/Footers For Table From Sources

Description

Retrieves the titles and footnotes for a given table from a CSV/XLSX file or a data.frame.

Usage

get_titles_from_file(
  id,
  file = .find_titles_file(input_path),
  input_path = ".",
  title_df = .read_titles_file(file)
)

Arguments

Details

Retrieves the titles for a given output id (see below) and outputs a list containing the title and footnote objects supported by rtables. Both titles.csv and titles.xlsx (if readxl is installed) files are supported, with titles.csv being checked first.

     Data is expected to have `TABLE ID`, `IDENTIFIER`, and `TEXT` columns,
     where `IDENTIFIER` has the value `TITLE` for a title and `FOOT*` for
     footer materials where `*` is a positive integer. `TEXT` contains
     the value of the title/footer to be applied.

Value

List object containing: title, subtitles, main_footer, prov_footer for the table of interest. Note: the subtitles and prov_footer are currently set to NULL. Suitable for use with set_titles().

Get Visit Levels in Order Defined by Numeric Version

Description

Get Visit Levels in Order Defined by Numeric Version

Usage

get_visit_levels(visit_cat, visit_n)

Arguments

Value

The unique visit levels in the order defined by the numeric version.

Examples

get_visit_levels(
  visit_cat = c("Week 1", "Week 11", "Week 2"),
  visit_n = c(1, 5, 2)
)

Standard Column Structure With Grouped Treatments and Difference Columns

Description

Standard Column Structure With Grouped Treatments and Difference Columns

Usage

grouped_cols_w_diffs(
  lyt,
  colspan_trt_map,
  combo_map_df = NULL,
  comp_map = NULL,
  diff_cols = TRUE,
  diffs_label = "Risk Differences",
  .main_pre = list(),
  .main_post = list(),
  .rr_pre = list(),
  .rr_post = list()
)

grouped_cols_w_subgrps(
  lyt,
  colspan_trt_map = NULL,
  combo_map_df = NULL,
  trtvar = names(colspan_trt_map)[2],
  subgrp_var = NULL,
  subgrp_lbl = subgrp_var,
  total_facet = TRUE,
  total_lbl = "Total",
  .pre = list(),
  .post = list()
)

Arguments

Details

This function combines multiple rtables column splitting instructions with customized split functions to create a column structure with treatment columns for each treatment arm (optionally including combination arms), grouped by active and non-active, with risk difference columns comparing active arm(s) against one or more non-active controls. It is intended for use in layouts that will use a_freq_j() or similar junco-style analysis functions which support risk difference columns and accept a ref_path argument.

It is equivalent to the following sequence of layout instructions: