---
title: "Intermediate rtables - Translating Shells To Layouts"
subtitle: Contributed by Johnson & Johnson Innovative Medicine
date: "2025-06-17"
author:
- Gabriel Becker
- Dan Hofstaedter
output:
    rmarkdown::html_document:
        theme: "spacelab"
        highlight: "kate"
        toc: true
        toc_float: true
vignette: >
  %\VignetteIndexEntry{Intermediate rtables - Translating Shells To Layouts}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  markdown:
      wrap: 72
  chunk_output_type: console
---

```{r, include = FALSE}
suggested_dependent_pkgs <- c("dplyr")
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = all(vapply(
    suggested_dependent_pkgs,
    requireNamespace,
    logical(1),
    quietly = TRUE
  ))
)
```

```{r, echo=FALSE}
knitr::opts_chunk$set(comment = "#")
```


# Introduction

The first - and often largest - hurdle to creating a table via
`rtables` is translating the desired table structure (typically in the
form of a *table shell*) into an `rtables` *layout*. We will cover
that translation process in this vignette.

## A Table Shell

Table shells can come in various forms. We will begin with a table
shell which is essentially the entire table with desired formatting
indicated instead of values:

```{r init, echo = FALSE, results = "hidden"}
suppressPackageStartupMessages(library(rtables))
suppressPackageStartupMessages(library(dplyr))

fixed_shell <- function(tt) {
  mystr <- table_shell_str(tt)
  regex_hits <- gregexpr("[(]N=[[:digit:]]+[)]", mystr)[[1]]
  hit_lens <- attr(regex_hits, "match.length")
  if (regex_hits[1] > 0) {
    for (i in seq_along(regex_hits)) {
      start <- regex_hits[i]
      len <- hit_lens[i]
      substr(mystr, start, start + len - 1) <- padstr("(N=xx)", len, just = "center")
    }
  }
  cat(mystr)
}

knitr::opts_chunk$set(comment = "")
```


```{r, echo = FALSE, result = "asis"}
adsl <- ex_adsl %>%
  filter(SEX %in% c("M", "F") & RACE %in% c("ASIAN", "BLACK OR AFRICAN AMERICAN", "WHITE")) %>%
  mutate(
    BMEASIFL = factor(as.character(BMEASIFL),
      levels = c("Y", "N"),
      labels = c("Yes", "No")
    ),
    SEX = factor(as.character(SEX),
      levels = c("M", "F", "UNDIFFERENTIATED", "U"),
      labels = c("Male", "Female", "Undifferentiated", "Unknown")
    ),
    RACE = factor(as.character(RACE),
      levels = c("ASIAN", "BLACK OR AFRICAN AMERICAN", "WHITE"),
      labels = c("Asian", "Black", "White")
    )
  )


lyt <- basic_table(
  title = "Subject Response by Race and Sex; Treated Subjects",
  show_colcounts = TRUE
) %>%
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) %>%
  split_cols_by("ARM", split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo"))) %>%
  analyze("BMEASIFL", afun = counts_wpcts, var_labels = "All Patients", show_labels = "visible") %>%
  split_rows_by(
    var = "RACE",
    label_pos = "topleft",
    split_fun = keep_split_levels(only = c("Asian", "Black", "White"))
  ) %>%
  split_rows_by(
    var = "SEX",
    label_pos = "topleft",
    split_fun = keep_split_levels(only = c("Male", "Female"))
  ) %>%
  summarize_row_groups(
    var = "SEX",
    format = "xx"
  ) %>%
  analyze(
    vars = "BMEASIFL",
    afun = counts_wpcts
  )

result <- build_table(lyt, adsl)
fixed_shell(result)
```

We will use this shell to illustrate the translation process to an
rtables layout, and thus ultimately a table output.

## A *Brief* Review Of `rtables` Layouts

For an in-depth discussion of how constructing a layout works we refer
the reader to other documentation. That said, there are a couple
things to remember as we consider translating shells into layouts:

1. Individual rows are declared by `analyze*` calls
2. Individual columns are the result of column faceting
3. New faceting will be nested within existing faceting in the same dimension (row/col) by default
4. All row faceting structures must be terminated with at least one analysis (`analyze`)
5. Row faceting which occurs directly after an `analyze` will *not* be nested

With those in mind, we will now discuss how to translate shells into layouts.

# Translating

There are three aspects to a shell that we must translate:

1. Column faceting structure
2. Row faceting structure
3. Cell contents
   - Marginal content for row facet structure
   - Individual facet content
 
We will explore each portion of the translation process separately.

## Translating Column Structure

Our first task, translating column structure, revolves around
identifying faceting in the column dimension of a shell or desired
table.

Our shell gives us the following to indicate column structure:

```{r, echo = FALSE, result="asis"}
fixed_shell(result[0, ])
```

The easiest way to identify faceting is to look at column- or
row-labels and determine the scope (i.e., the set of individual
columns or rows) they apply to.

For example, we see that the `"A"` column label applies to a group of
multiple columns each of which represent an individual arm:

```{r}
fixed_shell(result[0, c("A", "*")])
```

Thus we have strata faceting with arm faceting nested within it.

Faceting most commonly represents partitioning the data being
tabulated by the values of a categorical variable, though `rtables`
supports a generalized concept of faceting where the data group can
overlap and need not be exhaustive.

For our table, the faceting is nested faceting by the `"STRATA1"`, and
`"ARM"` variables. We achieve this by repeated calls to
`split_cols_by` (with the default `nested = TRUE`), with the call declaring
the outermost faceting first:


```{r}
lyt_cols <- basic_table() |>
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) %>%
  split_cols_by("ARM", split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo")))

build_table(lyt_cols, adsl)
```

This is almost correct. To fully achieve our shell we need the column
counts to show up, which we do via the `show_colcounts` argument in
the relevant `split_cols_by` call:

```{r}
lyt_cols <- basic_table() |>
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) %>%
  split_cols_by("ARM",
    split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo")),
    show_colcounts = TRUE
  )

build_table(lyt_cols, adsl)
```


This is a relatively straightforward column structure. We will cover
more complex ones later. Nevertheless we have translated our shell's
column space into `rtables` layouting instructions.


## Translating Row Structure

Moving to the second aspect of translation, we will now translate the
row structure of our shell. Interpreting row structure is similar to
interpreting column structure with the caveat that individual rows do
not come from faceting, but rather from analysis (which is in charge
of populating the contents of the table's primary, non-marginal
cells).

Our row structure is slightly less trivial than our column
structure. We can see two sections in our shell, one that displays the
response (`"BMEASIFL"`) of all patients collectively (by the column
structure):


```{r, echo = FALSE}
fixed_shell(tt_at_path(result, "BMEASIFL"))
```

and one that subsets the patients before displaying the response
within each subset, and with some marginal rows for context.

```{r, echo = FALSE}
fixed_shell(tt_at_path(result, "RACE"))
```

Because none of the labels or cell-values from the all patients
portion of the table apply directly to the subset analysis portion -
and vice versa - we can treat these separately.

In point of fact, the first portion does not require any structure
beyond an analysis of the `"BMEASIFL" variable with a label, so we can
leave that for the third translation step.

We can illustrate this using a dummy analyze as follows:

```{r}
dummy_afun <- function(x, ...) in_rows("Analysis" = "-")
lyt_a <- basic_table() |>
  analyze("BMEASIFL",
    afun = dummy_afun,
    var_labels = "All Patients",
    show_labels = "visible"
  )

build_table(lyt_a, adsl)
```

While we do not have the individual rows we desired, as that is left
to step 3 of translation, we can see that we have successfully created
the first portion of the row *structure*.

Note that in most tables the column and row structure are orthogonal
and so we do not need to worry about columns when we are translating
the row structure.

Also note we *could* say that there is a facet there which contains all the
patients and has the name/label `"All Patients"`; this would result in
an equivalent table from an output perspective but there isn't really
any benefit to the added layouting instructions that would be
required, so we will not do so here.

The second portion of the table contains labels and rows which *do*
apply to multiple individual rows.

We see that the `"Asian"` label, for example, applies across the
corresponding `"Male"` and `"Female"` labels/marginal rows, each of
which in turn applies to a group of individual rows (`"Yes"`, and
`"No"`).

Thus we can recreate this section via nested faceting, this time with 

```{r}
lyt_b <- basic_table() |>
  split_rows_by("RACE") |>
  split_rows_by("SEX") |>
  analyze("BMEASIFL", afun = dummy_afun)

head(build_table(lyt_b, adsl), 30)
```

We are almost there, but we see extra `"SEX"` values that weren't in
our shell. We can prevent this with the `keep_split_levels` function
provided by `rtables`:

```{r}
lyt_b2 <- basic_table() |>
  split_rows_by("RACE") |>
  split_rows_by("SEX", split_fun = keep_split_levels(only = c("Male", "Female"))) |>
  analyze("BMEASIFL", afun = dummy_afun)


build_table(lyt_b2, adsl)
```

Finally, we can combine the two sections by simply combining the relevant layout instructions:


```{r}
lyt_b3 <- basic_table() |>
  analyze("BMEASIFL",
    afun = dummy_afun,
    var_labels = "All Patients",
    show_labels = "visible"
  ) |>
  split_rows_by("RACE") |>
  split_rows_by("SEX", split_fun = keep_split_levels(only = c("Male", "Female"))) |>
  analyze("BMEASIFL", afun = dummy_afun)

build_table(lyt_b3, adsl)
```

Note here that row split instructions which directly follow an
`analyze` call will automatically be non-nested, so we do not need to
specify `nested = FALSE` in the `"RACE"` split, though doing so would
not harm anything.

We can convince ourselves that treating the column and row structure
separately by combining the layouting instructions for both to receive
something equivalent in structure (i.e., up individual rows and marginal cell contents) to our
shell:


```{r}
lyt_struct <- basic_table() |>
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) |>
  split_cols_by("ARM",
    split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo")),
    show_colcounts = TRUE
  ) |>
  analyze("BMEASIFL",
    afun = dummy_afun,
    var_labels = "All Patients",
    show_labels = "visible"
  ) |>
  split_rows_by("RACE") |>
  split_rows_by("SEX", split_fun = keep_split_levels(only = c("Male", "Female"))) |>
  analyze("BMEASIFL", afun = dummy_afun)

build_table(lyt_struct, adsl)
```

We can see that the marginal cells for `"Male"` and `"Female"` within
each race are not present, but we will handle those in the third
translation step.


## Translating Cell Contents

Finally, we will finish our translation with the third step:
translating cell contents.

Tables can contain up to two types of rows with non-empty cells as
reckoned by the `rtables` conceptual model: individual analysis rows,
and marginal group summary rows (called *content* rows by the
`rtables` internals).

Analysis rows are declared via `analyze` during layout construction;
an analysis function (the `afun` argument) specifying how *all cells
within a single facet pane should be simultaneously created*.

We see in our shell that we want two rows whenever we analyze
`BMEASIFL` response: one for `"Yes"` and one for `"No"`.

Most analysis functions provided by `rtables` or extensions like
`tern` or `junco` will automatically generate multiple rows when
analyzing a categorical variable (i.e., factor):


```{r}
rw_lyt <- basic_table() |>
  analyze("BMEASIFL",
    var_labels = "All Patients",
    show_labels = "visible"
  )

build_table(rw_lyt, adsl)
```

Further, recall that the faceting does the work of identifying subsets
and applying our analyses within those facets/subsets
automatically. Thus by applying the *structural* layout instructions
we translated above, we get something that is getting pretty close to
our desired table:


```{r}
rw_lyt_struct <- basic_table() |>
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) |>
  split_cols_by("ARM",
    split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo")),
    show_colcounts = TRUE
  ) |>
  analyze("BMEASIFL",
    var_labels = "All Patients",
    show_labels = "visible"
  ) |>
  split_rows_by("RACE") |>
  split_rows_by("SEX", split_fun = keep_split_levels(only = c("Male", "Female"))) |>
  analyze("BMEASIFL")

build_table(rw_lyt_struct, adsl)
```

Two aspects remain before we have matched our desired shell: our
marginal counts in the the individual gender rows within each race are
missing, and our analysis rows contain only counts rather than
matching the desired `"xx (xx.x%)"` format of count and percent.

`rtables` provides a (*very*) simple afun to calculate count percent
values (`counts_wpcts`) which we can use for illustration purposes
here.  We will see later that it is not flexible enough to meet a
study team's full set of needs and more complex afuns will be used in
practice in production.

```{r}
rw_lyt_structb <- basic_table() |>
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) |>
  split_cols_by("ARM",
    split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo")),
    show_colcounts = TRUE
  ) |>
  analyze("BMEASIFL",
    afun = counts_wpcts,
    var_labels = "All Patients",
    show_labels = "visible"
  ) |>
  split_rows_by("RACE") |>
  split_rows_by("SEX", split_fun = keep_split_levels(only = c("Male", "Female"))) |>
  analyze("BMEASIFL", afun = counts_wpcts)

build_table(rw_lyt_structb, adsl)
```

Now, all we need is the marginal gender counts. We do this by adding
`summarize_row_groups` *directly after* the relevant row faceting
(`split_rows_by`) instruction in the layout. This function can accept
a fully custom function (the `cfun` argument), but for our purposes,
we can control whether the percent is included in the default group
summary with the `format` argument.

```{r}
lyt_final <- basic_table() |>
  split_cols_by("STRATA1", split_fun = keep_split_levels(only = c("A", "B"))) |>
  split_cols_by("ARM",
    split_fun = keep_split_levels(only = c("A: Drug X", "B: Placebo")),
    show_colcounts = TRUE
  ) |>
  analyze("BMEASIFL",
    afun = counts_wpcts,
    var_labels = "All Patients",
    show_labels = "visible"
  ) |>
  split_rows_by("RACE") |>
  split_rows_by("SEX", split_fun = keep_split_levels(only = c("Male", "Female"))) |>
  summarize_row_groups(format = "xx") |>
  analyze("BMEASIFL", afun = counts_wpcts)

build_table(lyt_final, adsl)
```

Thus, we have fully translated our shell into an `rtables` declarative
layout and realized our desired table output.

In the remainder of this vignette we will walk through a number of
shells with more complex structural elements and how to translate them
into `rtables` layouts.

# Spanning Column Headers

Some shells will call for spanning labels in column space which do not
directly reflect a categorical variable in the raw data, but rather
represent groups of levels in a variable, e.g., trial arms.

For example, we might have the following column structure in a shell:


```{r, echo = FALSE}
span_map <- data.frame(
  ARM = c("A: Drug X", "B: Placebo", "C: Combination"),
  span_label = c("Active Treatment", " ", "Active Treatment")
)

lyt_span <- basic_table() |>
  split_cols_by("span_label", split_fun = trim_levels_to_map(span_map)) |>
  split_cols_by("ARM", show_colcounts = TRUE)

adsl2 <- adsl
adsl2$span_label <- "Active Treatment"
adsl2$span_label[adsl2$ARM == "B: Placebo"] <- " "

tbl_colspans <- build_table(lyt_span, adsl2)
fixed_shell(tbl_colspans)
```

Here we see the "Active Treatment" label spanning arms A and C, while
no label appears above the column for arm B. There are a couple things
to decode here that will collapse this column structure into a nested
faceting structure as we saw above.

Most importantly, while uneven splitting *is* possible with `rtables`,
including in column space, we can get our desired output by allowing
the B arm to have an invisible spanning label which is simply a single
space (`" "`). Viewing the structure this way, we can see that we have
two levels of faceting, one which splits between so called active
treatments and the remaining arms, and within that, we facet on
individual arm.

This brings us to our second issue: we don't have a variable for
active vs non-active treatments. There are a few ways to address this,
but the most user-friendly way is simply to create one as a
preprocessing step on the data before we make our table:

```{r}
adsl_forspans <- adsl
adsl_forspans$span_label <- "Active Treatment"
adsl_forspans$span_label[adsl_forspans$ARM == "B: Placebo"] <- " "

qtable(adsl_forspans, "ARM", "span_label")
```

With that we can build a table with the desired nested splitting:

```{r}
lyt_cspan <- basic_table() |>
  split_cols_by("span_label") |>
  split_cols_by("ARM", show_colcounts = TRUE)

build_table(lyt_cspan, adsl_forspans)
```

So we are getting close, but our individual arm columns are not only
showing up under their correct spanning label (though we see that the
*data* are being siphoned under the correct labels by the column
counts).

This type of non-full-factorial nesting is common; we often only want
facets that *make logical sense* within a nested faceting structure,
while wanting to omit any that don't (e.g., in our table, the Active
Treatment - Placebo facet).

`rtables` provides multiple ways to declare this behavior in the form
of both full *split functions* and *split function behavior building
blocks*, the latter being for use within `make_split_fun`. For now, we
will use a built-in full split function as we will be covering
`make_split_fun` in a different vignette.

Our two options for split functions are `trim_levels_in_group` and
`trim_levels_to_map`; the former is empirical and will keep all
combinations which are *observed in the data*, omitting any that
aren't. The latter requires us to provide a map of all combinations to
be displayed, but is more robust to sparse data (e.g., a data snapshot
from an in-flight trial) and allows for displaying zero counts for
unobserved but desired combinations.

Other than being empirical and declarative, respectively,
`trim_levels_in_group` and `trim_levels_to_map` behave similarly: when
used while splitting on a variable (the "outer variable"), the
observations and factor levels of of another ("inner") variable are
restricted independently within each facet for the outer variable.

In our case, our outer variable is `"span_label"`, while our inner
variable would be `"ARM"`. Thus we want to restrict the levels of
`"ARM"` within each facet of `"span_label"`. For our toy example here,
the two split functions will be equivalent, but we will use
`trim_levels_to_map` as it is more robust and appropriate for more
cases of production use.

Thus we need to create our map, a `data.frame` that contains the two
variables with each desired combination as a separate row:

```{R}
span_label_map <- tribble(
  ~span_label, ~ARM,
  "Active Treatment", "A: Drug X",
  "Active Treatment", "C: Combination",
  " ", "B: Placebo",
)

lyt_cspan_final <- basic_table() |>
  split_cols_by("span_label",
    split_fun = trim_levels_to_map(span_label_map)
  ) |>
  split_cols_by("ARM", show_colcounts = TRUE)

build_table(lyt_cspan_final, adsl_forspans)
```

Thus we have again achieved a "table" matching our desired shell. We
can consider only the column structure because in this case as
previously the column structure, row structure, and analysis are all
orthogonal. We will see an example where that isn't fully the case below

**Note:** in the general case, the level map used in
`trim_levels_to_map` will be a function of the data dictionaries for
the relevant variables within your study, thus for combinations of
actual variables these maps should not require manual construction as
we did above.

# Heterogeneous Column Structures (e.g., Risk Difference Columns)

In our previous examples, the column structure was simple nested
faceting, both in the case of faceting on two variables from the data,
and in the case we wanted spanning labels.

While this simple nesting structure is relatively common,
particularly for column structure, it does not fit the shells for all
tables we might need to create. One example of this is risk difference
columns, as found in modern FDA guidance for Adverse Event (AE)
tables.

In this section we will translate a shell with both spanning headers
and risk difference columns into a layout. To avoid subtleties about
counting we will analyze the `BMRKR2` variable in our synthetic
`ADSL` dataset rather than going for a realistic AE table. These
counting issues and realistic AE tables will be addressed elsewhere in
this series of vignettes.

## Risk Difference Columns

Many tables call for "risk difference", or comparison columns, in
addition to those used for the primary counts. When combined with
spanning labels, the column structure of our shell would look
something like:

```{r, echo = FALSE}
adsl2$rr_header <- "Risk Differences"
adsl2$rr_label <- paste(adsl2$ARM, "vs B: Placebo")
lyt_rr <- basic_table() |>
  split_cols_by("span_label", split_fun = trim_levels_to_map(span_map)) |>
  split_cols_by("ARM", show_colcounts = TRUE) |>
  split_cols_by("rr_header", nested = FALSE) |>
  split_cols_by("ARM", labels_var = "rr_label", split_fun = remove_split_levels("B: Placebo"))


tbl_rr_shell <- build_table(lyt_rr, adsl2)
fixed_shell(tbl_rr_shell)
```

We see that the first portion of the column structure is the same, but
we now have the risk difference structure in addition. There are a
number of different ways to model risk difference columns but we will
do so as a separate nested substructure. Thus as we did with the
"Active Treatment" spanning label, we will create and then facet on a
variable that gives us the "Risk Differences" label.

We can build up this substructure separately and then combine it with
the structure we created above to match the full shell.


```{r}
adsl_rr <- adsl_forspans
adsl_rr$rr_header <- "Risk Differences"

lyt_only_rr <- basic_table() |>
  split_cols_by("rr_header") |>
  split_cols_by("ARM")

build_table(lyt_only_rr, adsl_rr)
```

This is getting close there are two issues: first, we don't want a
placebo column (which would nonsensically compare placebo against
itself), and the labels are simply the individual arms rather than the
pair of arms being compared as in our shell.

We can restrict the facets generated using the `remove_split_levels`
(or sibling `keep_split_levels`) split function provided by
`rtables`. In addition the `split_*_by` functions accept the
`labels_var` argument which specifies an additional variable which
should be used for the *labels* (not names) of the facets
generated. With preprocessing to create such a variable, and combining
these two approaches, we can achieve the risk difference structure:

```{r}
adsl_rr$rr_label <- paste(adsl_rr$ARM, "vs B: Placebo")

lyt_only_rr2 <- basic_table() |>
  split_cols_by("rr_header") |>
  split_cols_by("ARM",
    split_fun = remove_split_levels("B: Placebo"),
    labels_var = "rr_label"
  )

build_table(lyt_only_rr2, adsl_rr)
```

To combine our two sections of column structure, we simply combine the
sets of layouting instructions and add `nested = FALSE` to our split
on `"rr_header"`:


```{r}
lyt_rr_cols <- basic_table() |>
  split_cols_by("span_label",
    split_fun = trim_levels_to_map(span_label_map)
  ) |>
  split_cols_by("ARM", show_colcounts = TRUE) |>
  split_cols_by("rr_header", nested = FALSE) |>
  split_cols_by("ARM",
    split_fun = remove_split_levels("B: Placebo"),
    labels_var = "rr_label"
  )

build_table(lyt_rr_cols, adsl_rr)
```

Note that because we used `show_colcounts` in our `split_cols_by` call
for `"ARM"`, rather than in `build_table`, we have counts for our main
arm columns but not for our comparison columns, as desired.

One caveat here, however, is that we will need a more sophisticated
analysis function because its behavior is no longer independent of
which facet it is in: it might generate e.g., counts for the primary
arm columns and then confidence intervals for our risk difference
columns.

Typically trial teams will be using pre-existing analysis functions
for this, but we will illustrate these can be constructed now.

## Column-structure Aware Analysis Functions

Our analysis function needs two "modes": the primary arm column mode
and the risk difference mode, and it needs to be able to distinguish
between them.

Analysis (and content, i.e., row group summary) functions can accept
the optional `.spl_context` argument to receive information where in
the faceting structure the facet they are currently populating is. We
will leave a detailed discussion of the full contents of the split
context to other documentation and simply use the portions we need
here.

In particular, we will use the `cur_col_id` column of `.spl_context`
to determine which section of the column structure we are under. Note
that due to the vagaries of the current implementation, this is
constructed of the *labels* for the column facets rather than their
names. This is the split/value pairs of each column split in order
concatenated together, so it suffices to define

```{r}
in_risk_diff <- function(spl_context) grepl("Risk Differences", spl_context$cur_col_id[1])
```


For simplicity, we will not worry about *calculating* risk differences
here, and simply write an analysis function that emits something
different to show that it can tell it is in "risk difference mode".

Thus a very simplistic afun is as follows:

```{r}
rr_afun <- function(x, .N_col, .spl_context) {
  xtbl <- table(x)
  if (in_risk_diff(.spl_context)) {
    armlabel <- tail(.spl_context$cur_col_split_val[[1]], 1) # last split value, ie arm
    armletter <- substr(armlabel, 1, 1)
    vals <- as.list(rep(paste(armletter, "vs B"), length(xtbl)))
    fmts <- rep("xx", length(xtbl))
  } else {
    vals <- lapply(xtbl, function(x) x * c(1, 1 / .N_col)) ## count and pct
    fmts <- rep("xx.x (xx.x%)", length(xtbl))
  }
  names(vals) <- names(xtbl)
  names(fmts) <- names(vals)
  in_rows(.list = vals, .formats = fmts)
}
```

With this we can create a table. We will analyze `BMRKR2` (biomarker
2) for the sake of brevity. This is an oversimplifaction, as typically
this would be, e.g., `AEDECOD` in an `adae` dataset, but this requires
more sophisticated calculation of counts and/or percents that is
important but not germane to this specific issue.

```{r}
lyt_rr_full <- basic_table() |>
  split_cols_by("span_label",
    split_fun = trim_levels_to_map(span_label_map)
  ) |>
  split_cols_by("ARM", show_colcounts = TRUE) |>
  split_cols_by("rr_header", nested = FALSE) |>
  split_cols_by("ARM",
    split_fun = remove_split_levels("B: Placebo"),
    labels_var = "rr_label"
  ) |>
  analyze("BMRKR2", afun = rr_afun)

build_table(lyt_rr_full, adsl_rr)
```

The blank space above the column counts is a known issue which we
expect to be resolved in a future release due to the fact that the
header construction/wrapping behavior is not accounting for the fact
that the two sections of the column structure are independent.

Note that while our analysis function was dependent on where in the
*column* structure we are, it remains independent of where in the
*row* faceting structure we are. Thus we can use our analysis function
within row faceting without changes:


```{r}
lyt_rr_full2 <- basic_table() |>
  split_cols_by("span_label",
    split_fun = trim_levels_to_map(span_label_map)
  ) |>
  split_cols_by("ARM", show_colcounts = TRUE) |>
  split_cols_by("rr_header", nested = FALSE) |>
  split_cols_by("ARM",
    split_fun = remove_split_levels("B: Placebo"),
    labels_var = "rr_label"
  ) |>
  split_rows_by("STRATA1") |>
  split_rows_by("SEX", split_fun = keep_split_levels(c("Female", "Male"))) |>
  analyze("BMRKR2", afun = rr_afun)

tbl <- build_table(lyt_rr_full2, adsl_rr)

cwidths <- propose_column_widths(tbl)
cwidths[cwidths > 15] <- 15
cat(export_as_txt(tbl, colwidths = cwidths)) ## for wrapping
```

A more complete exploration of creating production ready analysis
functions will be presented elsewhere in this vignette series.

# Mixed Nesting Levels

In practice, the row structure in most shells can be translated to a
layout using combinations of the methods shown above. Some shells,
however, essentially call for group summaries for all levels of a
categorical variable, but additionally call for analysis within those
groups *for only some levels of the variable*.

In clinical trial outputs we have seen this most commonly in
disposition tables, the shells of which might look something like:

```{r, echo = FALSE}
simple_two_tier_init <- function(df, .var, .N_col, inner_var, drill_down_levs) {
  outer_tbl <- table(df[[.var]])

  cells <- lapply(
    names(outer_tbl),
    function(nm) {
      cont_cell <- rcell(outer_tbl[nm] * c(1, 1 / .N_col), format = "xx (xx.x%)")
      if (nm %in% drill_down_levs) {
        inner_tbl <- table(df[[inner_var]])
        detail_cells <- lapply(
          names(inner_tbl),
          function(innm) rcell(inner_tbl[innm] * c(1, 1 / .N_col), format = "xx (xx.x%)", indent_mod = 1L)
        )
        names(detail_cells) <- names(inner_tbl)
      } else {
        detail_cells <- NULL
      }
      c(setNames(list(cont_cell), nm), detail_cells)
    }
  )

  in_rows(.list = unlist(cells, recursive = FALSE))
}

two_tier_shell_lyt <- basic_table() |>
  split_cols_by("span_label",
    split_fun = trim_levels_to_map(span_label_map)
  ) |>
  split_cols_by("ARM", show_colcounts = TRUE) |>
  split_rows_by("RACE", split_fun = keep_split_levels(c("Asian", "Black"))) |>
  analyze("EOSSTT",
    afun = simple_two_tier_init,
    extra_args = list(
      inner_var = "DCSREAS",
      drill_down_levs = "DISCONTINUED"
    )
  )

two_tier_shell <- build_table(two_tier_shell_lyt, adsl_rr) ## don't need the rr bits
fixed_shell(two_tier_shell)
```

In this shell, the `COMPLETED`, `DISCONTINUED` and `ONGOING` rows are
siblings (derived from the `EOSSTT` variable), however only the
`DISCONTINUED` row acts as a group summary row for a facet containing
further analysis; the other two essentially act as individual rows.

This type of structure where individual analysis rows and facets/group
summary rows are direct siblings is not currently supported by the
`rtables` layouting and tabulation engines, and is *somewhat*
supported when created via, e.g., trimming rows of a created table.

The above said, we can arrive at a table which renders as desired
using the *two-tier analysis function* strategy.

The key to the two-tier analysis function strategy is to generate both
levels of row in the same analysis function and simply use indent
modifiers to differentiate them.

Below is a simple `afun` that implements this strategy. For the
purposes of this lesson readers can ignore the details of what this
function does if desired; analysis function design and implementation
will be covered in another vignette in the advanced section.


```{R}
simple_two_tier <- function(df, .var, .N_col, inner_var, drill_down_levs) {
  ## group EOSSTT counts
  outer_tbl <- table(df[[.var]])

  cells <- lapply(
    names(outer_tbl),
    function(nm) {
      ## simulated group summary rows
      cont_cell <- rcell(outer_tbl[nm] * c(1, 1 / .N_col),
        format = "xx (xx.x%)"
      )
      if (nm %in% drill_down_levs) {
        ## detail (DCSREAS) counts
        inner_tbl <- table(df[[inner_var]])
        ## note indent_mod
        detail_cells <- lapply(
          names(inner_tbl),
          function(innm) {
            rcell(inner_tbl[innm] * c(1, 1 / .N_col),
              format = "xx (xx.x%)",
              ## appearance of "detail drill-down"
              indent_mod = 1L
            )
          }
        )
        names(detail_cells) <- names(inner_tbl)
      } else {
        detail_cells <- NULL
      }
      c(setNames(list(cont_cell), nm), detail_cells)
    }
  )

  in_rows(.list = unlist(cells, recursive = FALSE))
}

lyt_two_tier <- basic_table() |>
  analyze("EOSSTT",
    afun = simple_two_tier,
    extra_args = list(inner_var = "DCSREAS", drill_down_levs = "DISCONTINUED")
  )

build_table(lyt_two_tier, adsl_rr)
```

As in other cases, we can add the row- and column- structure
orthogonally (provided the analysis behavior is truly orthogonal to
the faceting, as it is in this shell):

```{r}
lyt_two_tier_full <- basic_table() |>
  split_cols_by("span_label",
    split_fun = trim_levels_to_map(span_label_map)
  ) |>
  split_cols_by("ARM", show_colcounts = TRUE) |>
  split_rows_by("RACE", split_fun = keep_split_levels(c("Asian", "Black"))) |>
  analyze("EOSSTT",
    afun = simple_two_tier,
    extra_args = list(inner_var = "DCSREAS", drill_down_levs = "DISCONTINUED")
  )

build_table(lyt_two_tier_full, adsl_rr)
```

Thus we have created our desired output.