PK Summary Statistic Helpers

These helpers are intended primarily for pharmacokinetic (PK) concentration summaries. Together they cover the pieces needed to build PK concentration tables:

• cv() – coefficient of variation (%).

• geom_cv() – geometric coefficient of variation (%).

• geom_mean() – geometric mean.

• fmt_3sig() – format numbers to 3 significant figures.

• fmt_pct() – format numbers to a single decimal place.

• pk_imputation_rules() – apply BLQ display rules to a formatted statistic.

• pk_param_metadata() – reference table of PK parameter codes and labels.

• pk_param_sort() – order a PK data frame by the conventional parameter order.

cv(x)

geom_cv(x)

geom_mean(x, na.rm = TRUE)

fmt_3sig(x)

fmt_pct(x)

pk_imputation_rules(stat_val, label, blq_ratio, postdose, rule = "1/3")

pk_param_metadata()

pk_param_sort(pk_data, key_var = "PARAMCD")

Arguments

x

(numeric)
numeric vector.

na.rm

(logical(1))
whether to remove NA values. Default is TRUE.

stat_val

(character(1))
formatted statistic value.

label

(character(1))
label identifying the statistic type (e.g. "Median", "Max").

blq_ratio

(numeric(1))
proportion of BLQ observations (between 0 and 1).

postdose

(logical(1))
whether the timepoint is post-dose. The 1/3 rule keeps a separate set of reportable statistics for pre-dose and post-dose timepoints.

rule

(character(1))
imputation rule to apply. One of "1/3" (default) or "1/2".

pk_data

(data.frame)
pharmacokinetic data frame.

key_var

(string)
column in pk_data holding the PK parameter code, merged against the reference from pk_param_metadata(). Default is "PARAMCD".

Value

cv(), geom_cv(), and geom_mean() return a single numeric value. geom_mean() returns NA_real_ if there are no usable values or if any non-NA value is <= 0.

fmt_3sig() and fmt_pct() return a character vector the same length as x, with NA_character_ where x is NA or non-finite.

pk_imputation_rules() returns a character string: the original stat_val, "ND" (not determined), or "NE" (not estimable).

pk_param_metadata() returns a data.frame of PK parameters. pk_param_sort() returns pk_data with ordered PARAM (and TLG_DISPLAY) factors.

Details

pk_imputation_rules() applies BLQ (Below Limit of Quantification) imputation rules to a formatted PK summary statistic based on the proportion of BLQ observations and dosing timing. Two substitutions are made:

• A statistic with no value is replaced by "NE" (not estimable). This covers variability statistics that need more than one observation, such as the standard deviation, CV%, and geometric CV% when n = 1. Counts (e.g. "No. obs.") are always available and never become "NE".

• When too many observations are BLQ, statistics that cannot be meaningfully reported are replaced by "ND" (not determined).

Because the "NE" substitution happens here, the formatters (fmt_3sig(), fmt_pct()) stay purely numeric and return NA for missing values; the "NE"/"ND" display logic is applied downstream by this function.

pk_param_metadata() returns the reference table mapping PK parameter codes (PARAMCD) to their label (PARAM), display label (TLG_DISPLAY), matrix, and display order (TLG_ORDER). pk_param_sort() uses this reference to set the PARAM (and TLG_DISPLAY) factor levels of a PK data frame so tables and listings follow the conventional PK parameter order.

Examples

cv(c(1, 2, 3, 4, 5))
#> [1] 52.70463

geom_cv(c(1, 2, 3, 4, 5))
#> [1] 70.54166

geom_mean(c(1, 2, 3, 4, 5))
#> [1] 2.605171

fmt_3sig(0.001234)
#> [1] "0.00123"
fmt_3sig(123456)
#> [1] "123000"
fmt_3sig(c(0.001234, NA, 123456))
#> [1] "0.00123" NA        "123000" 

fmt_pct(45.678)
#> [1] "45.7"
fmt_pct(c(45.678, NA))
#> [1] "45.7" NA    

pk_imputation_rules("1.23", "Mean", blq_ratio = 0.5, postdose = TRUE, rule = "1/3")
#> [1] "ND"
# SD is not estimable with a single observation
pk_imputation_rules(NA, "SD", blq_ratio = 0, postdose = TRUE)
#> [1] "NE"

pk_reference <- pk_param_metadata()
head(pk_reference)
#>   PARAMCD                         PARAM  TLG_DISPLAY             MATRIX
#> 1    TMAX      Time of CMAX Observation         Tmax Plasma/Blood/Serum
#> 2    CMAX                      Max Conc         Cmax Plasma/Blood/Serum
#> 3   CMAXD         Max Conc Norm by Dose       Cmax/D Plasma/Blood/Serum
#> 4  AUCIFO              AUC Infinity Obs   AUCinf obs Plasma/Blood/Serum
#> 5  AUCIFP             AUC Infinity Pred  AUCinf pred Plasma/Blood/Serum
#> 6 AUCIFOD AUC Infinity Obs Norm by Dose AUCinf/D obs Plasma/Blood/Serum
#>   TLG_ORDER
#> 1         1
#> 2         2
#> 3         3
#> 4         4
#> 5         5
#> 6         6

if (FALSE) { # \dontrun{
adam <- syntheticadam::get_data()
pk_ordered_data <- pk_param_sort(adam$adpp)
} # }