Precision and Alignment

Introduction

vignette("format_strings") covers format strings whose widths you declare yourself: xx.x is always two integer positions and one decimal. That works when you know the scale of the data in advance. Two situations break it.

The first is a table that covers variables of different scales. A lab listing might report sodium in whole numbers, ALT to one decimal, and creatinine to two. No single hardcoded format string serves all three: xxx.x prints sodium’s minimum as 132.0, inventing a decimal the assay never measured, while rendering creatinine as 0.9 and dropping a digit the SAP requires. Writing a separate layer per parameter with hand-tuned widths is tedious and goes stale the moment the data changes.

The second is ragged delimiters. Padding a number to a fixed width means the opening parenthesis can end up a space or two away from the digit it encloses, which many sponsor mocks disallow:

 14 ( 16.3%)
  7 (  8.1%)

tplyr2 answers the first with auto-precision (a and A), which lets the data set the width at build time, and the second with parenthesis hugging (X and A), which relocates padding without changing the total width. This vignette covers both, and the case where you want them together.

Auto-Precision

Lowercase a behaves exactly like x, except the width is not read from the template – it is measured from the data during the build.

At build time tplyr2 scans a variable and records two numbers per precision group:

• max_int – the largest number of integer digits present
• max_dec – the largest number of meaningful decimal places present, up to base R’s seven-significant-digit display limit. Integer magnitude eats into it: a value of 140.123456 measures as four decimals, not six, while 0.123456 measures as six.

An a on the integer side resolves to max_int, and an a on the decimal side resolves to max_dec. Four layer_settings() arguments control how those widths are resolved – the first three shape the scan, and the fourth replaces it:

set.seed(42)
n_subj <- 30
params <- data.frame(
  PARAM  = c("Sodium (mmol/L)", "Alanine Aminotransferase (U/L)", "Creatinine (mg/dL)"),
  mu     = c(140,  28,   0.9),
  sigma  = c(  3,   9,   0.15),
  digits = c(  0,   1,   2)      # the precision each assay reports
)

labs <- do.call(rbind, lapply(seq_len(nrow(params)), function(i) {
  base <- round(rnorm(n_subj, params$mu[i], params$sigma[i]), params$digits[i])
  post <- round(base + rnorm(n_subj, 0, params$sigma[i] / 2), params$digits[i])
  data.frame(
    USUBJID = sprintf("S%03d", seq_len(n_subj)),
    TRTA    = rep(c("Placebo", "Drug"), each = n_subj / 2),
    PARAM   = params$PARAM[i],
    AVAL    = post,
    BASE    = base,
    CHG     = post - base
  )
}))

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_desc("AVAL",
      by = "PARAM",
      settings = layer_settings(
        precision_by = "PARAM",
        precision_on = "AVAL",
        format_strings = list(
          "n"         = f_str("xx", "n"),
          "Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd"),
          "Median"    = f_str("a.a+1", "median"),
          "Min, Max"  = f_str("a.a, a.a", "min", "max")
        )
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

value_block <- group_desc("AVAL",
  by = c(label("Value at Week 8"), "PARAM"),
  settings = layer_settings(
    precision_by = "PARAM",
    precision_on = "AVAL",
    format_strings = list("Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd"))
  )
)

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    value_block,
    group_desc("CHG",
      by = c(label("Change from Baseline"), "PARAM"),
      settings = layer_settings(
        precision_by = "PARAM",        # no precision_on: measures CHG
        format_strings = list("Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd"))
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    value_block,
    group_desc("CHG",
      by = c(label("Change from Baseline"), "PARAM"),
      settings = layer_settings(
        precision_by = "PARAM",
        precision_on = "AVAL",         # measure AVAL, summarize CHG
        format_strings = list("Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd"))
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_desc("AVAL",
      by = "PARAM",
      settings = layer_settings(
        precision_on = "AVAL",         # no precision_by
        format_strings = list(
          "Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd")
        )
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

Capping Precision

Auto-precision follows the data, and data is not always well behaved. A single value carried to more decimals than the rest – a unit conversion artifact, an imputed value – drags the whole column several digits wider than the assay warrants. precision_cap sets an upper bound:

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_desc("AVAL",
      by = "PARAM",
      settings = layer_settings(
        precision_by  = "PARAM",
        precision_on  = "AVAL",
        precision_cap = c(int = 3, dec = 1),
        format_strings = list(
          "Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd"),
          "Min, Max"  = f_str("a.a, a.a", "min", "max")
        )
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

The cap applies to the measured width, before +N is added. With dec = 1, creatinine’s measured 2 decimals is capped to 1, so a.a+1 renders two decimals (0.89) rather than the three it did above (0.890), and a.a renders one (0.7, 1.1). ALT was already at 1 decimal, so the cap does not touch it and a.a+1 still gives 28.76. Getting this ordering backwards is the most common surprise with capping: a cap of dec = 1 does not guarantee one decimal in the output, it guarantees one decimal before your offsets.

Either component may be given alone – c(dec = 2) caps decimals and leaves integer width uncapped.

tplyr2_options(precision_cap = ...) sets a session-wide default, and a layer-level precision_cap overrides it. That combination is the useful one: a conservative session default protects every table in the study, and the occasional layer that genuinely needs more digits asks for them explicitly. See vignette("options").

Supplying Precision From Outside

When the statistical analysis plan fixes the display precision per parameter, you do not want it inferred from whatever happens to be in the extract. precision_data takes a data frame with a max_int column, a max_dec column, and the precision_by variables:

sap_precision <- data.frame(
  PARAM = c("Sodium (mmol/L)",
            "Alanine Aminotransferase (U/L)",
            "Creatinine (mg/dL)"),
  max_int = c(3L, 3L, 1L),
  max_dec = c(0L, 1L, 2L)
)

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_desc("AVAL",
      by = "PARAM",
      settings = layer_settings(
        precision_by   = "PARAM",
        precision_on   = "AVAL",
        precision_data = sap_precision,
        format_strings = list(
          "Mean (SD)" = f_str("a.a+1 (a.a+2)", "mean", "sd")
        )
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

The +N offsets still apply on top of the supplied widths, so the SAP specifies the data precision once and the display convention stays in the format string.

Two things to know. Coverage is checked, but only with a warning. A group with no row in precision_data has no widths to resolve and renders as a blank cell; the build warns and names the groups it could not cover. A precision_data that omits the precision_by columns entirely is also accepted, with a warning, and its widths are applied to every group. Both are warnings rather than errors because a deliberately partial table is legitimate – but read them, because a blank cell is the alternative.

Nothing tells you when the data moves. That is the point of pinning precision to the SAP, but it means the table keeps rendering at the declared widths even if the extract arrives at a different precision – so a genuine upstream change in the assay looks like nothing at all.

counts <- data.frame(TRT = "A", GROUP = c(rep("Common", 250), rep("Rare", 3)))

spec <- tplyr_spec(
  cols = "TRT",
  layers = tplyr_layers(
    group_count("GROUP",
      settings = layer_settings(
        format_strings = list(n_counts = f_str("a (xx.x%)", "n", "pct"))
      )
    )
  )
)

c(as_display(tplyr_build(spec, counts))$res1)
#> [1] "250 (98.8%)" "3 ( 1.2%)"

Parenthesis Hugging

Padding a number to a fixed width leaves space between the number and whatever literal precedes it. Uppercase X and A relocate that space.

A hugged format group moves its leading spaces to the far side of the number, just inside the last character of the trailing literal. The number ends up flush against its opening delimiter, the closing delimiter stays at the end of the cell, and the displaced spaces sit between them. Nothing is added or removed, so the total width – and therefore the column alignment – is unchanged.

# standard: padding sits between "(" and the number
apply_formats(f_str("xxx (xxx.x%)", "n", "pct"), c(1, 78), c(1.2, 90.7))
#> [1] "  1 (  1.2%)" " 78 ( 90.7%)"

# hugged: the same padding moves to just before ")"
apply_formats(f_str("xxx (XXX.x%)", "n", "pct"), c(1, 78), c(1.2, 90.7))
#> [1] "  1 (1.2%  )" " 78 (90.7% )"

Every cell above is 12 characters wide, hugged or not. In the hugged version the ( sits against the first digit, the % travels along with the number it belongs to, and the closing ) stays pinned at the end of the cell with the displaced spaces in between.

That is the general rule: hugging splits the trailing literal at its last character, keeps everything before it attached to the number, and leaves that last character where it was. So any closing delimiter works, not just a parenthesis:

apply_formats(f_str("xxx [XXX.x]", "n", "pct"), c(1, 78), c(1.2, 90.7))
#> [1] "  1 [1.2  ]" " 78 [90.7 ]"

apply_formats(f_str("xx (XX.xx%)", "n", "pct"), 12, 4.2)
#> [1] "12 (4.20% )"
apply_formats(f_str("xx (xx.XX%)", "n", "pct"), 12, 4.2)
#> [1] "12 (4.20% )"
apply_formats(f_str("xx (XX.XX%)", "n", "pct"), 12, 4.2)
#> [1] "12 (4.20% )"

apply_formats(f_str("XXX", "n"), 12)   # nothing precedes the number
#> Warning: Format string "XXX": format group 1 uses parenthesis hugging (X/A) but
#> has no literal text before it, so there is nothing to hug -- the number will be
#> left-justified with trailing spaces. Use lowercase x/a for a leading group.
#> [1] "12 "
apply_formats(f_str("xxx", "n"), 12)   # what you almost certainly wanted
#> [1] " 12"

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_desc("AVAL",
      by = "PARAM",
      settings = layer_settings(
        precision_by = "PARAM",
        precision_on = "AVAL",
        format_strings = list(
          "Mean (SD)" = f_str("a.a+1 (A.a+2)", "mean", "sd")
        )
      )
    )
  )
)

result <- tplyr_build(spec, labs)
show_table(result)

nchar(result$res1)
#> [1] 14 14 14

Putting It Together

A complete lab summary combining everything in this vignette: precision measured per parameter, capped so no parameter can run away, the standard +1/+2 offsets, the SD hugged against its parenthesis, and a placeholder for groups with nothing to report.

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_desc("AVAL",
      by = "PARAM",
      settings = layer_settings(
        precision_by  = "PARAM",
        precision_on  = "AVAL",
        precision_cap = c(int = 4, dec = 3),
        format_strings = list(
          "n"         = f_str("xx", "n"),
          "Mean (SD)" = f_str("a.a+1 (A.a+2)", "mean", "sd"),
          "Median"    = f_str("a.a+1", "median",
                              empty = c(.overall = "NE")),
          "Q1, Q3"    = f_str("a.a+1, a.a+1", "q1", "q3"),
          "Min, Max"  = f_str("a.a, a.a", "min", "max")
        )
      )
    )
  )
)

show_table(tplyr_build(spec, labs))

Where to Go From Here

• vignette("format_strings") – the format string grammar, statistic keywords, rounding, and missing-value handling.
• vignette("display_conventions") – <1% and >99% percents, zero-count suppression, statistics as separate columns, denominator rows.
• vignette("desc") – descriptive statistics layers, custom summaries, and multi-variable summaries.
• vignette("options") – the session-wide precision_cap and IBMRounding.