t-end-of-study

id: t-end-of-study
title: "Summary of End of Study Data"
regulatory_id: DST03
type: table
dataset: adsl
# "Intent-to-Treat" is the population line the report prints above Table 14-1.02.
# See the note in t-populations/analysis.yaml: in this ADSL the ITT set and the
# whole file are the same 254 subjects, so this choice moves no number — it makes
# the display state the population its reference states.
analysis_set: itt
denominator: adsl
# COMP24FL and DCREASCD are collected facts carried in the CDISC pilot's own
# ADSL. The {pharmaverseadam} re-derivation of this study has neither, which is
# why this display names its source rather than taking the default registry.
sources: phuse
# Planned treatment, as in the reference report.
group:
  - TRT01P
total: true
analyses:
  # ---- completion status --------------------------------------------------
  # The SAP compares "protocol completed" across arms with Fisher's exact test,
  # so this row is the custom count-and-test; the other two are plain counts.
  - name: completed_wk24
    method: subject_count
    custom: ard_count_and_fisher
    label: "Completed Week 24"
    variable: COMP24FL
    filter: "COMP24FL == 'Y'"
  - name: early_term
    method: subject_count
    label: "Early Termination (prior to Week 24)"
    variable: COMP24FL
    filter: "COMP24FL == 'N'"
  - name: completion_missing
    method: subject_count
    label: "Completion status missing"
    variable: COMP24FL
    filter: "!(COMP24FL %in% c('Y', 'N'))"
  # ---- reason for early termination, among the early terminations ---------
  # Every reason is counted over the same column denominator as the completion
  # rows (the treatment group), not over the early terminations, which is what
  # the reference report does.
  - name: et_ae
    method: subject_count
    custom: ard_count_and_fisher
    label: "Early termination: adverse event"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Adverse Event'"
  - name: et_death
    method: subject_count
    label: "Early termination: death"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Death'"
  - name: et_loe
    method: subject_count
    custom: ard_count_and_fisher
    label: "Early termination: lack of efficacy"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Lack of Efficacy'"
  - name: et_ltfu
    method: subject_count
    label: "Early termination: lost to follow-up"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Lost to Follow-up'"
  - name: et_withdrew
    method: subject_count
    label: "Early termination: subject decided to withdraw"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Withdrew Consent'"
  - name: et_physician
    method: subject_count
    label: "Early termination: physician decided to withdraw subject"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Physician Decision'"
  - name: et_ie
    method: subject_count
    label: "Early termination: protocol criteria not met"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'I/E Not Met'"
  - name: et_protocol
    method: subject_count
    label: "Early termination: protocol violation"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Protocol Violation'"
  - name: et_sponsor
    method: subject_count
    label: "Early termination: sponsor decision"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & DCREASCD == 'Sponsor Decision'"
  - name: et_missing
    method: subject_count
    label: "Early termination: reason missing"
    variable: DCREASCD
    filter: "COMP24FL == 'N' & (is.na(DCREASCD) | !nzchar(DCREASCD))"

id: t-end-of-study
title: "Summary of End of Study Data"
study: CDISCPILOT01
population_label: "Intent-to-Treat"
cutoff: "2015-03-05"
source: "Source: adsl (phuse-org/phuse-scripts, data/adam/cdisc — the CDISC pilot submission's own ADaM package). Data cut-off: 2015-03-05."
footnotes:
  - "[1] Fisher's exact test, comparing the row against the rest of the treatment group across all three groups at once. The statistical analysis plan (section 9.7.1.2) specifies this test for protocol completion, lack of efficacy and adverse event only; the other rows are descriptive and carry no p-value."
  - "[2] Lack of efficacy is based on either patient/caregiver perception or physician perception."
  - "N in the column headers is the number of subjects randomised to that treatment group; every percentage on this table, including the reasons for early termination, is based on it rather than on the number of early terminations — as the reference report does. The reference's own note calls N the number of subjects \"entered in study (i.e., signed informed consent)\"; this display does not repeat that wording, because 306 subjects were screened and 254 randomised, and it is the 254 that N counts."
  - "The population line above reads Intent-to-Treat because that is what the reference report prints above this table. In this study it selects the same 254 subjects as the whole analysis dataset, since every subject in it carries ITTFL = Y."
  - "Completion status is the study's own COMP24FL and the reason is its DCREASCD. Both are collected fields carried in the CDISC pilot's ADSL; neither exists in the pharmaverse re-derivation of this study, so this display reads the pilot package directly."
  - "Treatment groups are planned (randomised) treatment, TRT01P. In this ADSL planned and actual treatment agree for all 254 subjects."
  - "144 subjects discontinued the study in total; the 136 counted here are those who did so before Week 24. The remaining 8 discontinued after completing Week 24."
  - "The cut-off shown is the latest subject end date (RFENDT) recorded in the vendored ADSL. The CDISC pilot package states no separate database-lock date."
columns:
  order: [Placebo, "Xanomeline Low Dose", "Xanomeline High Dose", Total, "p-value"]
  patterns:
    "p-value": pvalue
format:
  pvalue: "{p_value_fmt}"
  digits:
    p: 0
rows:
  - { label: "Completion Status:", section: true }
  - { analysis: completed_wk24, label: "Completed Week 24 [1]", pattern: n_pct, indent: 1 }
  - { analysis: early_term, label: "Early Termination (prior to Week 24)", pattern: n_pct, indent: 1 }
  - { analysis: completion_missing, label: "Missing", pattern: n_pct, indent: 1 }
  - { label: "Reason for Early Termination (prior to Week 24):", section: true }
  - { analysis: et_ae, label: "Adverse Event [1]", pattern: n_pct, indent: 1 }
  - { analysis: et_death, label: "Death", pattern: n_pct, indent: 1 }
  - { analysis: et_loe, label: "Lack of Efficacy [1][2]", pattern: n_pct, indent: 1 }
  - { analysis: et_ltfu, label: "Lost to Follow-up", pattern: n_pct, indent: 1 }
  - { analysis: et_withdrew, label: "Subject decided to withdraw", pattern: n_pct, indent: 1 }
  - { analysis: et_physician, label: "Physician decided to withdraw subject", pattern: n_pct, indent: 1 }
  - { analysis: et_ie, label: "Protocol criteria not met", pattern: n_pct, indent: 1 }
  - { analysis: et_protocol, label: "Protocol violation", pattern: n_pct, indent: 1 }
  - { analysis: et_sponsor, label: "Sponsor decision", pattern: n_pct, indent: 1 }
  - { analysis: et_missing, label: "Missing", pattern: n_pct, indent: 1 }
variants:
  post_text: {}
  in_text:
    title: "Summary of End of Study Data (Summary)"

# Display-specific statistics for t-end-of-study.
#
# The statistical analysis plan for CDISCPILOT01 specifies one hypothesis test
# on this table (SAP section 9.7.1.2): "Specific reasons for early study
# discontinuation (protocol completed, lack of efficacy, and adverse event) were
# compared using a Fisher's exact test." Three rows therefore carry a p-value;
# every other row does not. The v0 method vocabulary (contract section 2) has no
# hypothesis test, so those three rows set `custom: ard_count_and_fisher` and
# this function is dispatched instead of the built-in `subject_count`.
#
# It returns the same subject counts the built-in method would — the counting is
# the same {cards} call with the same arguments — plus two extra statistics
# addressed to a `p-value` display column. Making the test result an ordinary
# ARD row at its own group level is what lets display.yaml place it with
# `columns.patterns` instead of the renderer knowing anything about p-values.
#
# Contract: the function receives (data, spec, denominator) and returns a
# {cards}-shaped ARD. `spec$group` holds the grouping variable actually in
# force, which is how the engine also re-runs it for the Total column.

#' Flatten a {cards} ARD to the plain columns build_ard() reads
#'
#' {cards} stores levels and conditions in list columns. The engine coerces them
#' on the way into the ARD row schema; doing the same here means the counts and
#' the appended test rows can be a single data frame with no list-column
#' mismatch on `rbind`.
#' @noRd
flatten_cards_ard <- function(ard) {
  chr <- function(nm) {
    if (!nm %in% names(ard)) {
      return(rep(NA_character_, nrow(ard)))
    }
    x <- ard[[nm]]
    if (!is.list(x)) {
      return(as.character(x))
    }
    vapply(x, function(el) {
      if (is.null(el) || length(el) == 0) NA_character_ else paste(as.character(el), collapse = "; ")
    }, character(1))
  }
  out <- data.frame(
    group1 = chr("group1"), group1_level = chr("group1_level"),
    group2 = chr("group2"), group2_level = chr("group2_level"),
    variable = chr("variable"), variable_level = chr("variable_level"),
    context = chr("context"), stat_name = chr("stat_name"),
    stat_label = chr("stat_label"), warning = chr("warning"), error = chr("error"),
    stringsAsFactors = FALSE
  )
  out$stat <- lapply(ard$stat, function(x) if (is.null(x) || length(x) == 0) NA else x)
  out
}

#' Subject counts for one row, plus the SAP's Fisher's exact test across arms
#'
#' @param data Analysis dataset, already restricted to the analysis set and to
#'   the analysis entry's `filter` — i.e. the subjects this row counts.
#' @param spec The analysis entry (a list), including `spec$group`.
#' @param denominator Subject-level denominator dataset, restricted to the
#'   analysis set. Supplies both the row's denominator and the "not in this
#'   category" cell of the test's 2 x k table.
#' @return A data frame carrying the `{cards}` ARD columns: N, n and p per
#'   treatment group, and (when there is more than one group to compare) the
#'   test's p-value at group level `p-value`.
ard_count_and_fisher <- function(data, spec, denominator) {
  group <- spec$group
  # `%||%` is base R only from 4.4; a library file must run on the pinned 4.1
  # floor in DESCRIPTION, so the fallbacks here are spelled out.
  id <- if (is.null(spec$id)) "USUBJID" else spec$id
  label_var <- if (is.null(spec$variable)) spec$name else spec$variable
  flag_var <- ".opencsr_flag"
  denominator[[flag_var]] <- denominator[[id]] %in% unique(data[[id]])

  # Identical to the built-in subject_count method: the count is computed on the
  # denominator with a derived flag, so the denominator is always the analysis
  # set, never the number of rows that survived the filter.
  counts <- if (length(group)) {
    cards::ard_dichotomous(
      denominator,
      by = dplyr::all_of(group), variables = dplyr::all_of(flag_var),
      value = stats::setNames(list(TRUE), flag_var)
    )
  } else {
    cards::ard_dichotomous(
      denominator,
      variables = dplyr::all_of(flag_var),
      value = stats::setNames(list(TRUE), flag_var)
    )
  }
  counts <- flatten_cards_ard(counts)
  counts$variable <- label_var
  counts$variable_level <- "Y"
  counts$context <- "subject_count"

  if (!length(group)) {
    return(counts)
  }
  g <- as.character(denominator[[group]])
  levels_present <- if (is.factor(denominator[[group]])) {
    intersect(levels(denominator[[group]]), g)
  } else {
    sort(unique(g[!is.na(g)]))
  }
  # One group is the Total column, which the engine produces by re-running this
  # function against a constant grouping variable. There is no comparison to
  # make there, so no test row is emitted and the cell renders empty — rather
  # than a p-value for a hypothesis nobody stated.
  if (length(levels_present) < 2) {
    return(counts)
  }

  k <- vapply(levels_present, function(lv) sum(g == lv & denominator[[flag_var]], na.rm = TRUE), numeric(1))
  n <- vapply(levels_present, function(lv) sum(g == lv, na.rm = TRUE), numeric(1))
  tested <- stats::fisher.test(rbind(k, n - k))
  p_value <- unname(tested$p.value)

  test_rows <- data.frame(
    group1 = "statistic",
    group1_level = "p-value",
    group2 = NA_character_,
    group2_level = NA_character_,
    variable = label_var,
    variable_level = "Y",
    context = "hypothesis_test",
    stat_name = c("p_value", "p_value_fmt"),
    stat_label = c("Fisher's exact p-value", "Fisher's exact p-value (formatted)"),
    warning = NA_character_,
    error = NA_character_,
    stringsAsFactors = FALSE
  )
  # The numeric p-value is the analysis result and is what the ARD carries for
  # anyone re-checking it. The string is its presentation: the reference report
  # writes p < 0.0001 as "<.0001", which no {stat_name} pattern can express, and
  # a display must never round 6.1e-07 to "0.0000".
  test_rows$stat <- list(
    p_value,
    if (p_value < 0.0001) "<.0001" else formatC(p_value, format = "f", digits = 4)
  )
  rbind(counts, test_rows)
}