# Standard Column Structures

#### 2026-05-04

# Structures With Difference Columns

Many standard tables call for a set of difference columns to be added alongside the main tabulation; this, combined with the spanning column labels favored by Johnson&Johnson shells, results in a complex final column structure.

To ease the creation of these structures, particularly in the presence of virtual combination arms, we provide the `grouped_cols_w_diffs` function. It provides the flexibility to be used in standard template scripts, as we will see below.

## Basic Usage

At it’s most basic, `grouped_cols_w_diffs` takes a column-span treatment map, as created by `create_colspan_map`. This creates a column structure with spanning labels over active and non-active treatment groups, as well as difference columns comparing each active treatments individually against each non-active treatment:

    library(junco)
    adsl <- create_colspan_var(pharmaverseadamjnj::adsl)
    adae <- create_colspan_var(pharmaverseadamjnj::adae)
    trt_map <- create_colspan_map(adsl)
    print(trt_map)
    #>          colspan_trt               TRT01A
    #> 1 Active Study Agent Xanomeline High Dose
    #> 2 Active Study Agent  Xanomeline Low Dose
    #> 3                                 Placebo

    lyt <- basic_table() |>
      grouped_cols_w_diffs(trt_map)

    build_table(lyt, adsl)
    #>                Active Study Agent                                                 Risk Differences
    #>    Xanomeline High Dose   Xanomeline Low Dose   Placebo   Xanomeline High Dose vs Placebo   Xanomeline Low Dose vs Placebo
    #> ——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

### A Note About Types Of Differences

`grouped_cols_w_diffs` creates only the column structure; the contents of the difference columns are calculated by the analysis function used in the layout. The structure for the various types of difference columns (risk, mean, eair, etc) differs only in the spanning label for the difference columns. `grouped_cols_w_diffs` accepts `diffs_label` for this purpose:

    lyt2 <- basic_table() |>
      grouped_cols_w_diffs(trt_map, diffs_label = "Mean Differences")

    build_table(lyt2, adsl)
    #>                Active Study Agent                                                 Mean Differences
    #>    Xanomeline High Dose   Xanomeline Low Dose   Placebo   Xanomeline High Dose vs Placebo   Xanomeline Low Dose vs Placebo
    #> ——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

Care should be taken to choose the correct analysis function to create the types of differences required by your shell.

### Turning Off The Difference Columns

Despite the function’s name, we can turn off difference columns when using `grouped_cols_w_diffs` via the `diff_cols` argument. This allows us to use the function unconditionally in our layouts while retaining the ability to turn off difference columns , e.g., in shells where they are optional.

    lyt_nodiff <- basic_table() |>
      grouped_cols_w_diffs(trt_map, diff_cols = FALSE)

    build_table(lyt_nodiff, adsl)
    #>                Active Study Agent
    #>    Xanomeline High Dose   Xanomeline Low Dose   Placebo
    #> ———————————————————————————————————————————————————————

## Advanced Usage

Beyond the basic usage, `grouped_cols_w_diffs` offers fine-grained control over both the arms (notably the addition of combination arms) and comparisons between arms displayed in your table.

### Including Virtual Combination Arms

Combination levels are declared via a “combo data.frame” similar to those accepted by `rtables::add_combo_levels`. In particular, we use a data.frame with the following columns:

- `valname` - (`character`) Name of the combination level (as it will appear in paths)
- `label` - (`character`) Label for the combination level (as it will appear in the table)
- `levelcombo` - (`list` of `character`s) The levels which should be combined into the combination level
- `exargs` - (`list`) Extra arguments to be passed to a/cfuns associated with the combination level
- `is_control` Optional (`logical`) When `TRUE`, the combination level will be added to the second (non-active) group of treatments. Assumed `FALSE` if not specified.
- `compare_against` Optional (`list` of `character`s) The levels the combination level should be compared against (as the first/active element). Assumed to be `select_all_levels` if not specified.

Thus at its most basic, we use this argument like so:

    library(tibble)
    combodf1 <- tribble(
      ~valname, ~label, ~levelcombo, ~exargs,
      "all_active", "All Xanomeline", c("Xanomeline High Dose", "Xanomeline Low Dose"), list()
    )

    lyt3 <- basic_table() |>
      grouped_cols_w_diffs(trt_map, combo_map_df = combodf1)
    #> none of the combination levels appeared in the colspan treatment map; adding them automatically.

    build_table(lyt3, adsl)
    #>                        Active Study Agent                                                                        Risk Differences
    #>    Xanomeline High Dose   Xanomeline Low Dose   All Xanomeline   Placebo   Xanomeline High Dose vs Placebo   Xanomeline Low Dose vs Placebo   All Xanomeline vs Placebo
    #> ———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

We can instead add a second virtual control or referene group by including the `is_control` column and setting it to `TRUE` for some or all of our combination levels:

    combodf2 <- tribble(
      ~valname, ~label, ~levelcombo, ~exargs, ~is_control,
      "all_active", "All Xanomeline", c("Xanomeline High Dose", "Xanomeline Low Dose"), list(), FALSE,
      "placebo_redux", "Double Placebo!!", c("Placebo"), list(), TRUE
    )

    lyt4 <- basic_table() |>
      grouped_cols_w_diffs(trt_map, combo_map_df = combodf2)
    #> none of the combination levels appeared in the colspan treatment map; adding them automatically.

    build_table(lyt4, adsl)
    #>                        Active Study Agent                                                                                                                                                        Risk Differences
    #>    Xanomeline High Dose   Xanomeline Low Dose   All Xanomeline   Placebo   Double Placebo!!   Xanomeline High Dose vs Placebo   Xanomeline Low Dose vs Placebo   All Xanomeline vs Placebo   Xanomeline High Dose vs Double Placebo!!   Xanomeline Low Dose vs Double Placebo!!   All Xanomeline vs Double Placebo!!
    #> ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

As we can see, this allows us full flexibility to include combination levels as both active and non-active virtual arms, including using them in both sides of comparisons (even simultaneously).

### Direct Control Of Comparisons

Finally, we have complete control over which comparisons appear in our table via the `comp_map` argument. When non-null, the exact set of comparisons specified in `comp_map` will appear in our table.

`comp_map` accepts a data.frame with the columns `active`, and `comparator`, as well optional `active_is_combo` and `comparator_is_combo` columns. The values in `active` and `comparator` should be the names (as opposed to labels) of the respective arms:

    comp_map1 <- tribble(
      ~active, ~comparator,
      "Xanomeline High Dose", "Placebo",
      "Xanomeline Low Dose", "placebo_redux",
      "all_active", "placebo_redux"
    )

    lyt5 <- basic_table() |>
      grouped_cols_w_diffs(trt_map, combo_map_df = combodf2, comp_map = comp_map1)
    #> none of the combination levels appeared in the colspan treatment map; adding them automatically.

    build_table(lyt5, adsl)
    #>                        Active Study Agent                                                                                                    Risk Differences
    #>    Xanomeline High Dose   Xanomeline Low Dose   All Xanomeline   Placebo   Double Placebo!!   Xanomeline High Dose vs Placebo   Xanomeline Low Dose vs Double Placebo!!   All Xanomeline vs Double Placebo!!
    #> ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

We can also use `comp_map` to compare one active treatment to another:

    comp_map2 <- tribble(
      ~active, ~comparator,
      "Xanomeline High Dose", "Xanomeline Low Dose",
      "Xanomeline High Dose", "Placebo",
      "Xanomeline Low Dose", "Placebo"
    )

    lyt6 <- basic_table() |>
      grouped_cols_w_diffs(trt_map, comp_map = comp_map2)

    build_table(lyt6, adsl)
    #>                Active Study Agent                                                                        Risk Differences
    #>    Xanomeline High Dose   Xanomeline Low Dose   Placebo   Xanomeline High Dose vs Xanomeline Low Dose   Xanomeline High Dose vs Placebo   Xanomeline Low Dose vs Placebo
    #> ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————