Non-standard Applications of ksformat for Clinical Trials and Other Tasks

1 Overview

ksformat is usually described as a SAS PROC FORMAT-like tool for ordinary value-to-label lookup. In practice, the package is useful in places where a clinical trial workflow needs more than a plain dictionary:

protocol-defined visit windows
subject- or arm-specific bucketing rules
composite keys built from multiple columns
reverse lookups for data cleaning and QC
report-ready numeric display for listings and summaries

This article shows a few non-standard uses that come up in clinical trials and adjacent data tasks.

2 1. Protocol windows and subject-specific buckets

A common clinical-trials task is mapping visit-day values into protocol-defined windows. The same idea extends to arm-specific rules, where one stratum has a slightly different window structure from another.

windows <- fmap_strata(
  stratum = c("ARM_A", "ARM_A", "ARM_A", "ARM_B", "ARM_B"),
  low     = c(0,        7,       28,      0,       14),
  high    = c(7,        28,      Inf,     14,      Inf),
  label   = c("Baseline", "Wk1-3", "Wk4+", "Baseline", "Wk2+"),
  inc_high = c(FALSE, FALSE, TRUE, FALSE, TRUE)
)

fnew(
  windows,
  type = "stratified_range",
  name = "visit_window",
  .other = "Outside window"
)

visit_df <- tibble(
  arm = c("ARM_A", "ARM_A", "ARM_B", "ARM_B", "ARM_C"),
  day = c(3, 35, 5, 40, 10)
) |> mutate(
  window = fputk(arm, day, format = "visit_window"),
)

visit_df

This is useful for:

visit window derivation in ADaM outputs
protocol deviation checks
windowed endpoint calculations

3 2. Composite keys for clinical mappings

Clinical trial data often uses multi-column logic: lab category + test code + unit, or population + analysis flag + visit type. fputk() can build a lookup from multiple fields without manually concatenating in the analysis step.

fnew(
  fmap(
    paste(
      c("BLOOD CHEMISTRY", "COAGULOGRAM", "COAGULATION PANEL", "COAGULOGRAM"),
      c("BLOOD",           "BLOOD",        "BLOOD",             "BLOOD"),
      c("ALB",             "FIBRINO",      "INR",               "INR"),
      c("g/L",             "g/L",           NA,                  NA),
      sep = "|"
    ),
    c("ALB", "FIBRINO", "INR", "INR")
  ),
  type = "character",
  name = "lb_param",
  ignore_case = TRUE,
  .other = NA
)

lab_df <- tibble(
  LBCAT = c("BLOOD CHEMISTRY", "COAGULOGRAM", "COAGULATION PANEL"),
  LBSPEC = c("BLOOD", "BLOOD", "BLOOD"),
  LBTESTCD = c("ALB", "INR", "INR"),
  LBSTRESU = c("g/L", NA, NA)
) |> mutate(
  PARAMCD = fputk(LBCAT, LBSPEC, LBTESTCD, LBSTRESU, format = "lb_param", na_as_string = TRUE)
)

lab_df

The same pattern is useful for:

AE grouping by term + severity + relation
CM coding by medication + route + dose form
endpoint derivations from multiple source fields

4 3. Reverse lookup for QC and cleaning

finputk() is helpful when raw labels must be normalized back to codes. In clinical programming, that makes it suitable for QC checks, mapping vendor text, and validating reviewer-facing labels.

finput(
  fmap(
    paste(c("PLACEBO", "DRUG A", "DRUG B"), c("PBO", "A50", "B100"), sep = "|"),
    c(1L, 2L, 3L)
  ),
  target_type = "integer",
  name = "trt_code_inv"
)

trt_df <- tibble(
  ARMN = c("PLACEBO", "DRUG A", "DRUG B", "UNKNOWN"),
  TRTCD = c("PBO", "A50", "B100", "X")
) |> mutate(
  TRTSEQ = finputk(ARMN, TRTCD, invalue_name = "trt_code_inv")
)

trt_df

Typical uses include:

deriving internal codes from decoded labels in QC datasets
validating data entry against controlled terminology
reconciling spreadsheet exports back to source codes

5 4. Report-ready numeric formatting

ksformat can also be used where report output needs consistent numeric presentation. This is not a lookup table; it is a pattern-driven formatter.

fnew("$%,.2f", type = "numeric", name = "currency")
fnew("%.1f%%", type = "numeric", name = "pct")

summary_df <- tibble(
  metric = c("Cost", "Response rate"),
  raw = c(1234.56, 0.153)
) |> mutate(
  display = c(fputn(raw[1], "currency"), fputn(raw[2] * 100, "pct"))
)

summary_df

Same result could be achieved using expression labels, but in base R, sprintf() itself does not support thousands separators such as commas. We can use formatC for the formatting purposes. Pattern-driven formatter looks simplier for such case.

stat_fmt <- fnew(
  #"currency"   = "sprintf('$%,.2f', .x1)", # Will not work!
  "currency"   = "formatC(.x1, digits = 2, big.mark = ',', format = 'f', decimal.mark = '.')",
  "pct" = "sprintf('%.1f%%', .x1 * 100)",
  name = "stat",
  type = "character"
)

summary_df <- tibble(
  metric = c("Cost", "Response rate"),
  raw = c(1234.56, 0.153),
  format = c("currency","pct")
) |> mutate(
  display = fput(format, stat_fmt, raw)
)

summary_df

This is useful for:

CSR and TLF output generation
QA listings for counts and rates
ad hoc review tables where consistent display matters

6 5. Bucketing dates into operational periods

Clinical teams often work with periods such as screening, treatment, follow-up, and analysis cut-offs. date_range and datetime_range let you keep those rules in one place instead of duplicating them in ad hoc code.

fparse(text = '
VALUE study_period (date_range)
  [2024-01-01, 2024-02-01) = "Screening"
  [2024-02-01, 2024-06-01) = "Treatment"
  [2024-06-01, HIGH]       = "Follow-up"
  .missing                 = "No date"
;
')

obs_dates <- as.Date(c("2024-01-15", "2024-03-10", "2024-07-01", NA))
tibble(
  date = obs_dates,
  period = fput(obs_dates, "study_period")
)

7 6. Text generation for listings and narratives

Expression labels make ksformat useful for building small text fragments in reports. In clinical settings, that can be handy for reviewer comments, summary phrases, or footnotes.

fnew(
  "high" = "sprintf('Above threshold: %s', .x1)",
  "low" = "sprintf('Below threshold: %s', .x1)",
  name = "thr_note"
)

fput(c("high", "low"), "thr_note", c(18.2, 7.4))

This is especially useful when the label depends on:

a measurement value
a threshold or cohort-specific cutoff
an external text fragment such as a reviewer comment

8 7. Practical cautions

These patterns are powerful, but they work best when the mapping rules are stable and owned by the analysis team. A few guardrails help:

keep the format definition close to the analysis spec
prefer a named format for rules reused across tables and datasets
use fclear() in examples and tests to avoid leaking state between steps
use na_as_string = TRUE only when the key was built with literal "NA" components from paste()

9 8. `fparse()` syntax for all format families

If you want to express fnew()-style rules as text, fparse() supports the same VALUE/INVALUE families as the package parser. The main idea is:

use VALUE for forward lookup formats
use INVALUE for reverse lookup formats
use pattern = ... only for date/time/datetime formats
use pattern: ... in the VALUE header for numeric display patterns
use interval syntax for numeric, date, datetime, and stratified ranges

9.1 VALUE blocks for discrete lookup

fparse(text = '
VALUE sex (character)
  "M" = "Male"
  "F" = "Female"
  .missing = "Unknown"
  .other = "Other"
;

VALUE age_group (numeric)
  [0, 18)    = "Child"
  [18, 65)   = "Adult"
  [65, HIGH] = "Senior"
;
')

9.2 INVALUE blocks for reverse lookup

fparse(text = '
INVALUE sex_inv
  "Male" = "M"
  "Female" = "F"
  .missing = "U"
;
')

9.3 Date, time, and datetime patterns

This is the direct fparse() equivalent of fnew_date(). For these blocks, pattern = ... is the right way to specify the display format.

fparse(text = '
VALUE enrldt (date)
  pattern = "DATE9."
  .missing = "Not Enrolled"
;

VALUE visit_time (time)
  pattern = "TIME8."
;

VALUE stamp (datetime)
  pattern = "DATETIME20."
;
')

9.4 Numeric display patterns

Numeric display formatting now has its own parser syntax. Put the pattern in the VALUE header and keep the block otherwise empty except for optional .missing / .other directives.

fparse(text = '
VALUE currency (numeric, pattern: "$%,.2f")
  .missing = "NO DATA"
;

VALUE pct (numeric, pattern: "%.1f%%")
;
')

tibble(
  raw = c(1234.56, -7890.12, 0, NA),
  currency = fputn(c(1234.56, -7890.12, 0, NA), "currency"),
  pct = fputn(c(0, 12.3, -4.5, NA), "pct")
)

9.5 Range formats

Range formats are expressed with interval notation. The same syntax works for numeric, date_range, and datetime_range blocks.

fparse(text = '
VALUE study_period (date_range)
  [2024-01-01, 2024-02-01) = "Screening"
  [2024-02-01, 2024-06-01) = "Treatment"
  [2024-06-01, HIGH]       = "Follow-up"
;

VALUE shift (datetime_range)
  [2024-01-15 00:00, 2024-01-15 08:00) = "Night"
  [2024-01-15 08:00, 2024-01-15 16:00) = "Day"
  [2024-01-15 16:00, 2024-01-16 00:00) = "Evening"
;
')

9.6 Stratified range formats

stratified_range combines a stratum with an inner range. The parser accepts the friendly STRATUM|[low, high) form.

fparse(text = '
VALUE visit_window (stratified_range, range_subtype: numeric)
  "ARM_A"|[0, 7)     = "Baseline"
  "ARM_A"|[7, 28)    = "Wk1-3"
  "ARM_B"|[0, 14)    = "Baseline"
  .other              = "Outside"
;
')

9.7 When to use `fnew()` anyway

fnew() remains the most concise way to create a report-formatting object when you already know you want a display pattern. fparse() is useful when the rule needs to be stored as text, versioned in a spec, or generated from another tool.

fnew("$%,.2f", type = "numeric", name = "currency_direct")
fputn(c(1234.56, -7890.12, 0), "currency_direct")

10 Conclusion

ksformat is not limited to simple code-to-label dictionaries. In clinical trials it can also serve as a compact rule engine for visit windows, composite keys, reverse mappings, report formatting, and small narrative fragments. That makes it useful anywhere repeated conditional logic would otherwise be spread across scripts, spreadsheets, or one-off helper functions.

fclear()