Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
5127333
fix(be): classify the bioequivalence design from each endpoint's rows
billdenney Nov 9, 2026
7e75d73
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 9, 2026
d54547e
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 9, 2026
5d24435
fix(be): classify the design from the study rows, not each endpoint's…
billdenney Nov 9, 2026
73b7091
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 9, 2026
4dfd9ee
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 9, 2026
2f33bcc
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
db71b62
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
dce4438
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
6cbb7b5
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
555d4c4
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
69eb928
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
4eb9f7c
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
a3f62df
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 10, 2026
746f6e1
Merge branch 'fix/no-tau-warning-group' into fix/be-design-per-endpoint
billdenney Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -710,6 +710,26 @@ the generated intervals:
sequence, so no model drops such rows while the subject count includes them.
(@billdenney)

* `be_assess()`, `be_compare()`, and `be_fit_models()` classify the design from
the subjects, periods, and treatments of the requested endpoints, one row per
subject and period, so long data with several `PPTESTCD` values give the
study design: a 2x2 crossover with Cmax and AUC rows is `"2x2x2"`, where
reference scaling is not feasible, and a parallel study with two endpoints is
`"parallel"` and uses the fixed-effects ANOVA. An administration whose value
is missing (an `aucinf.obs` without an estimable lambda.z) still counts, so
missing values do not change the design. `be_dataset()` stops with
`pknca_error_be_dataset_duplicate_period` when an endpoint has more than one
value for a subject and period (results with several intervals), and with
`pknca_error_be_dataset_design_conflict` when endpoints disagree on a
subject's treatment or sequence in a period; `be_compare()` raises both once.
An endpoint left with one value per subject stops a mixed model with
`pknca_error_be_endpoint_not_repeated`. `be_design()` and `be_within_var()`
stop with `pknca_error_be_design_duplicate_period` and
`pknca_error_be_within_var_duplicate_period` when a subject has more than one
row in a period, which is what the rows of several endpoints look like. A
covariate missing only in rows of an endpoint that is not assessed is not an
error. (@billdenney)

* The expanding-limits frameworks of `be_assess()` widen only the endpoints
their guidances allow (@billdenney). The EMA and the GCC widen Cmax and keep
AUC at 80.00-125.00%; Health Canada widens AUC and judges Cmax by its point
Expand Down
116 changes: 101 additions & 15 deletions R/bioequivalence.R
Original file line number Diff line number Diff line change
Expand Up @@ -394,6 +394,28 @@ be_expand_limits <- function(swR, regulator) {
paste(trt[idx], collapse = "")
}

# Stop when a subject has more than one row in a period. The design and the
# within-subject variances are defined for one endpoint, with one row per
# subject and period; the long data of several endpoints (several `PPTESTCD`
# values) would otherwise read as replicated administrations. `subj` and `per`
# are the subject and period of each row (a missing period counts as a period),
# and `msg` is a sprintf() format whose one `%s` receives the subjects (the
# first five).
.be_check_one_row_per_period <- function(subj, per, class, msg) {
dup <- duplicated(data.frame(subj = subj, per = as.character(per)))
if (any(dup)) {
rlang::abort(
sprintf(msg, paste(utils::head(unique(subj[dup]), 5), collapse = ", ")),
class = class
)
}
}

# The message of .be_check_one_row_per_period() for a function given the rows
# of one endpoint
.be_one_endpoint_msg <-
"Subject(s) %s have more than one row in a period; give one row per subject and period, such as the rows of one endpoint (`PPTESTCD`) and one interval."

#' Classify a bioequivalence crossover design
#'
#' `be_design()` inspects the treatment-by-period pattern of a crossover study
Expand All @@ -402,8 +424,8 @@ be_expand_limits <- function(swR, regulator) {
#' scaling (EMA/HC/GCC/FDA) requires the reference to be replicated; the narrow
#' therapeutic index frameworks additionally require the test to be replicated.
#'
#' @param data A long data.frame with one row per concentration-derived
#' observation (subject, period, treatment).
#' @param data A long data.frame with one row per subject and period for a
#' single endpoint (filter long NCA results to one `PPTESTCD` first).
#' @param subject,sequence,period,treatment Column names (length-1 character)
#' identifying the subject, randomization sequence, period, and treatment.
#' `sequence` may be `NA` to derive it from the treatment-by-period pattern.
Expand Down Expand Up @@ -454,6 +476,7 @@ be_design <- function(data, subject, sequence, period, treatment, reference_valu
subj <- as.character(data[[subject]])
trt <- as.character(data[[treatment]])
per <- data[[period]]
.be_check_one_row_per_period(subj, per, "pknca_error_be_design_duplicate_period", .be_one_endpoint_msg)
# Per-subject treatment pattern, ordered by period -- the realized sequence.
patterns <- tapply(seq_len(nrow(data)), subj, .be_subject_pattern, per = per, trt = trt)
# Per-subject replication counts of the reference.
Expand Down Expand Up @@ -675,6 +698,10 @@ be_within_var <- function(data, value, subject, period, treatment, reference_val
}
assert_numeric_between(alpha, lower = 0, upper = 1)
reference_value <- as.character(reference_value)
.be_check_one_row_per_period(
as.character(data[[subject]]), data[[period]], "pknca_error_be_within_var_duplicate_period",
.be_one_endpoint_msg
)

work <- data.frame(
.subject = factor(as.character(data[[subject]])),
Expand Down Expand Up @@ -1436,8 +1463,11 @@ print.be_within_var <- function(x, ...) {
#' @returns An object of class `be_dataset`: a list with `data` (the
#' standardized long frame, including a `.units` column and one `.cov_<name>`
#' column per covariate), `columns` (the resolved column names, including
#' `units` and `covariates`), `reference_value`, `test_levels`, and
#' `endpoints` (those present). For the results of a sparse bootstrap (see
#' `units` and `covariates`), `reference_value`, `test_levels`, `endpoints`
#' (those present), and `design_rows` (the distinct subject, sequence, period,
#' and treatment combinations of the requested endpoints, including those
#' whose value is missing, from which [be_design()] classifies the study).
#' For the results of a sparse bootstrap (see
#' [sparse_bootstrap()]), `data` has one row per bootstrap replicate, group,
#' and endpoint instead of one per subject and period.
#' @family Bioequivalence
Expand Down Expand Up @@ -1494,12 +1524,31 @@ be_dataset.default <- function(object, reference_col, reference_value,
)
}

data <- data[!is.na(data[[value_col]]) & data[[value_col]] > 0, , drop = FALSE]
.be_check_design_cols(
has_value <- !is.na(data[[value_col]]) & data[[value_col]] > 0
design_rows <- .be_design_rows(
data[data$PPTESTCD %in% endpoints, , drop = FALSE],
has_value = has_value[data$PPTESTCD %in% endpoints],
cols = c(subject, if (!is.na(sequence)) sequence, period, reference_col)
)
data <- data[has_value, , drop = FALSE]
analyzed <- data[data$PPTESTCD %in% endpoints, , drop = FALSE]
.be_check_design_cols(
analyzed,
subject = subject, sequence = sequence, period = period, treatment = reference_col
)
missing_cov <- covariates[vapply(data[covariates], anyNA, logical(1))]
.be_check_one_row_per_period(
sprintf("%s for %s", analyzed[[subject]], analyzed$PPTESTCD), analyzed[[period]],
"pknca_error_be_dataset_duplicate_period",
paste(
"Subject(s) %s have more than one value in a period; the results may hold several intervals for an endpoint.",
"Filter them to one interval per endpoint before the bioequivalence assessment."
)
)
.be_check_one_row_per_period(
design_rows[[subject]], design_rows[[period]], "pknca_error_be_dataset_design_conflict",
"Subject(s) %s have a period whose treatment or sequence differs between endpoints."
)
missing_cov <- covariates[vapply(analyzed[covariates], anyNA, logical(1))]
if (length(missing_cov) > 0) {
rlang::abort(
sprintf(
Expand Down Expand Up @@ -1534,12 +1583,25 @@ be_dataset.default <- function(object, reference_col, reference_value,
),
reference_value = reference_value,
test_levels = setdiff(levels(data$.trt), reference_value),
endpoints = present
endpoints = present,
design_rows = design_rows
),
class = "be_dataset"
)
}

# The rows that define the study design: the distinct subject, sequence,
# period, and treatment combinations (`cols`) of the requested endpoints'
# rows, `data`. Rows whose value is missing (`has_value` is FALSE) still
# count when their design columns are complete, so an endpoint that could not
# be calculated for an administration does not change the design.
.be_design_rows <- function(data, has_value, cols) {
keep <- has_value | stats::complete.cases(data[cols])
rows <- unique(data[keep, cols, drop = FALSE])
rownames(rows) <- NULL
rows
}

# Stop when a design column (subject, sequence, period, or treatment) is
# missing in a row that would be analyzed, or when a subject has more than one
# sequence. The model fits would otherwise drop those rows while the subject
Expand Down Expand Up @@ -2351,7 +2413,8 @@ be_table <- function(params, regulator, alpha = 0.10, design = NA_character_, mo
#'
#' `be_fit_models()` runs the single bioequivalence calculation path and returns
#' the regulatory pass/fail table. It coordinates the stages in order:
#' [be_dataset()] to prepare the data, [be_design()] to classify the design and
#' [be_dataset()] to prepare the data, [be_design()] to classify the design
#' (from the subjects, periods, and treatments of the requested endpoints) and
#' choose the model, [be_fit_model_single()] to fit, [be_extract_param()] to
#' extract the parameters, and [be_table()] to apply the regulatory decision.
#' [be_assess()] and [be_compare()] are thin verbs over it.
Expand All @@ -2375,10 +2438,7 @@ be_fit_models <- function(object, reference_col, reference_value,
covariates = covariates
)
if (is.null(design)) {
design <- be_design(
ds$data, ds$columns$subject, ds$columns$sequence, ds$columns$period,
ds$columns$treatment, ds$reference_value
)
design <- .be_design_dataset(ds)
} else if (!inherits(design, "be_design")) {
rlang::abort(
"`design` must be a `be_design` object from `be_design()`.",
Expand All @@ -2405,6 +2465,7 @@ be_fit_models <- function(object, reference_col, reference_value,
params <- list()
for (ep in ds$endpoints) {
ds_ep <- ds$data[!is.na(ds$data$PPTESTCD) & ds$data$PPTESTCD == ep, , drop = FALSE]
.be_check_endpoint_repeated(ds_ep, model_type, ep)
fit <- be_fit_model_single(ds_ep, model_type, scaling = reg$scaling != "none")
p <- be_extract_param(fit, ds_ep, alpha)
p$endpoint <- ep
Expand All @@ -2421,6 +2482,30 @@ be_fit_models <- function(object, reference_col, reference_value,
.be_table_finish(tbl, ds, caption = caption)
}

# The design of a be_dataset(), classified from its design rows (see
# .be_design_rows()): one row per subject and period, whichever endpoints
# have a value there.
.be_design_dataset <- function(ds) {
be_design(
ds$design_rows, ds$columns$subject, ds$columns$sequence, ds$columns$period,
ds$columns$treatment, ds$reference_value
)
}

# Stop when an endpoint has one measurement per subject but `model_type` needs
# repeated measures (the endpoint is missing in the other periods)
.be_check_endpoint_repeated <- function(ds_ep, model_type, endpoint) {
if (model_type %in% c("lmer", "nlme") && .be_is_parallel(ds_ep)) {
rlang::abort(
sprintf(
"Endpoint %s has one value per subject, so model_type = '%s', which needs repeated measures, cannot be fit; assess it separately.",
endpoint, model_type
),
class = c("pknca_error_be_endpoint_not_repeated", "pknca_error_be_not_estimable")
)
}
}

# Order the table from be_table() by endpoint (in the requested order) then by
# test formulation (in the reference-first treatment factor order), omit the
# units column (with a warning) when units are unavailable, and add the caption
Expand Down Expand Up @@ -2712,8 +2797,9 @@ be_fit_models <- function(object, reference_col, reference_value,
#' @param subject,sequence,period Column names for the subject, randomization
#' sequence, and period. When `NULL` they are taken from the `PKNCAresults`
#' object or detected from common column names. `sequence` may be absent.
#' @param design An optional [be_design()] object; computed from the data when
#' `NULL`.
#' @param design An optional [be_design()] object. When `NULL`, the design is
#' classified from the subjects, periods, and treatments of the requested
#' endpoints, including administrations where an endpoint's value is missing.
#' @param covariates An optional character vector of column names added to
#' every model as additive fixed effects (numeric columns as linear terms,
#' character or factor columns as factors). They must not be missing in any
Expand Down
5 changes: 3 additions & 2 deletions man/be_assess.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions man/be_compare.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 5 additions & 2 deletions man/be_dataset.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/be_design.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 5 additions & 3 deletions man/be_fit_models.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

41 changes: 41 additions & 0 deletions tests/testthat/test-bioequivalence-assess.R
Original file line number Diff line number Diff line change
Expand Up @@ -131,8 +131,49 @@ test_that("be_design errors on an unknown reference value", {
)
})

test_that("be_design needs one row per subject and period", {
# The long data of two endpoints give each subject two rows per period, which
# would otherwise read as a replicated reference and test.
d <- generate_be_replicate(16, 3, "2x2")
expect_error(
be_design(rbind(d, d), "subject", "sequence", "period", "treatment", "R"),
regexp = "Subject(s) 1, 2, 3, 4, 5 have more than one row in a period",
fixed = TRUE,
class = "pknca_error_be_design_duplicate_period"
)
par <- data.frame(subject = 1:8, period = 1L, treatment = rep(c("R", "T"), each = 4))
expect_error(
be_design(rbind(par, par), "subject", NA, "period", "treatment", "R"),
class = "pknca_error_be_design_duplicate_period"
)
# A missing period is one period: one row per subject is still parallel.
par$period <- NA
expect_identical(be_design(par, "subject", NA, "period", "treatment", "R")$design, "parallel")
par2 <- rbind(par, par[1, ])
expect_error(
be_design(par2, "subject", NA, "period", "treatment", "R"),
regexp = "Subject(s) 1 have",
fixed = TRUE,
class = "pknca_error_be_design_duplicate_period"
)
})

# be_within_var -------------------------------------------------------------

test_that("be_within_var needs one row per subject and period", {
# Two endpoints of a 2x2 crossover would otherwise give a "replicated"
# reference and a within-subject variance between the endpoints.
d <- generate_be_replicate(16, 3, "2x2")
expect_error(
be_within_var(rbind(d, d), "PK", "subject", "period", "treatment", "R"),
class = "pknca_error_be_within_var_duplicate_period"
)
expect_error(
be_within_var(rbind(d, d), "PK", "subject", "period", "treatment", "R", model_type = "isc"),
class = "pknca_error_be_within_var_duplicate_period"
)
})

test_that("be_within_var (anova) matches the ANOVA within-subject variances", {
# Pinned to the reference implementation's CV.calc on the high-variability
# full replicate: swR = 0.446... here is dataset-specific.
Expand Down
Loading
Loading