StatsTFLValR (version 1.0.0)

mean_by: Summary Table: Mean and Related Statistics by Group

Description

This function calculates common summary statistics (N, Mean, SD, Median, Q1, Q3, Min, Max) for a numeric variable, grouped by a treatment or category variable. It supports optional SAS-style rounding (round half away from zero) and formats the results for table-ready display. Missing treatment groups are automatically added with zero values.

Usage

mean_by(
  data,
  group_var,
  uniq_var,
  label,
  sec_ord,
  precision_override = NULL,
  indent = 3,
  use_sas_round = FALSE,
  id_var = "USUBJID"
)

Value

A tibble with the following columns:

• stats : internal statistic code (n1, mn, sd, etc.)

• stat : display label (" N", " MEAN", etc.)

• sort_ord : row ordering number

• sec_ord : section ordering number (from input)

• Treatment columns (trt1, trt2, ...): formatted values per treatment group

Arguments

data

A data frame or tibble containing the input data.

group_var

The grouping variable (e.g., treatment arm). Can be unquoted (tidy evaluation) or a string.

uniq_var

The numeric variable to summarise. Can be unquoted (tidy evaluation) or a string.

label

Character string: table section label for the output (e.g., "BMI (WEIGHT [KG]/ HEIGHT [M2])").

sec_ord

Integer: section order value (for downstream table ordering).

precision_override

Optional integer to manually set decimal precision; if NULL, the function infers precision from the data.

indent

Integer: number of leading spaces in statistic labels (default = 3).

use_sas_round

Logical: if TRUE, applies SAS-compatible rounding (round half away from zero). Default is FALSE.

id_var

Character: name of subject ID variable (default = "USUBJID"). If not found, function attempts to auto-detect common ID variable names.

Details

The function:

1. Auto-detects precision if precision_override is NULL.

2. Calculates N, mean, SD, quartiles, min, max.

3. Applies SAS-style rounding if use_sas_round = TRUE.

4. Converts statistics into a display format suitable for RTF or text output.

5. Ensures all treatment columns appear in output, filling missing ones with "0".

SAS-style rounding logic: Values exactly halfway between two increments are rounded away from zero (e.g., 1.25 → 1.3, -1.25 → -1.3 with 1 decimal place).

Examples

library(dplyr)

df <- tibble::tibble(
  USUBJID = rep(1:6, each = 1),
  TRTAN   = c(1, 1, 2, 2, 3, 3),
  BMIBL   = c(25.1, 26.3, 24.8, NA, 23.4, 27.6)
)
mean_by(
  data          = df,
  group_var     = TRTAN,
  uniq_var      = BMIBL,
  label         = "BMI (kg/m^2)",
  sec_ord       = 1
)


mean_by(
  data          = df,
  group_var     = TRTAN,
  uniq_var      = BMIBL,
  label         = "BMI (kg/m^2)",
  sec_ord       = 1,
  precision_override = 2
)


mean_by(
  data          = df,
  group_var     = TRTAN,
  uniq_var      = BMIBL,
  label         = "BMI (kg/m^2)",
  sec_ord       = 1,
  use_sas_round = TRUE
)


df2 <- tibble::tibble(
  USUBJID = c(1, 2, 3, 4),
  TRTAN   = c(1, 1, 3, 3),
  BMIBL   = c(25.1, 26.3, 23.4, 27.6)
)

mean_by(
  data      = df2,
  group_var = TRTAN,
  uniq_var  = BMIBL,
  label     = "BMI (kg/m^2)",
  sec_ord   = 1
)