From 59e8d5c70480b5f28c29407a169b467b63851462 Mon Sep 17 00:00:00 2001 From: Bill Denney Date: Fri, 13 Nov 2026 09:02:24 -0500 Subject: [PATCH 1/3] fix: warn when an AUCinf-based AUCint is the AUCall one without a half-life Over a finite interval that ends after Tlast, aucint.inf.obs, aucint.inf.pred, aumcint.inf.obs, and aumcint.inf.pred without a half-life have given the aucint.all (or aumcint.all) value since the dose-aware AUCint work, without saying so. They now give a pknca_warning_aucint_halflife_missing warning that names the parameter and the one whose value it has. The values and the exclusion ("DO NOT EXCLUDE") do not change, and an interval that ends at or before Tlast stays silent. The method text of that fallback is a shared constant, as the half-life one is, so the writer and the check that warns cannot drift. A test enumerates every registered parameter that takes lambda.z and integrates with pk.calc.aucint() or pk.calc.aumcint(), so a new one fails until it is covered. Co-Authored-By: Claude Opus 5.5 --- NEWS.md | 10 ++++ R/aucint.R | 96 +++++++++++++++++++++++++----------- man/pk.calc.auxcint.Rd | 5 +- tests/testthat/test-aucint.R | 72 ++++++++++++++++++++++++++- 4 files changed, 150 insertions(+), 33 deletions(-) diff --git a/NEWS.md b/NEWS.md index 18b6f894..c3736b5e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1212,6 +1212,16 @@ the generated intervals: ## Bug fixes +* `aucint.inf.obs`, `aucint.inf.pred`, `aumcint.inf.obs`, and + `aumcint.inf.pred` over a finite interval that ends after Tlast, when the + half-life is missing, now give a `pknca_warning_aucint_halflife_missing` + warning saying that the value is that of `aucint.all` (or `aumcint.all`) + (#450, @billdenney). The values do not change: they were already the + AUCall-based ones (#508), which equal the AUClast-based ones unless a + concentration below the limit of quantification follows Tlast. An interval + that ends at or before Tlast does not need the half-life and gives no + warning. + * Preferred units (`concu_pref`, `doseu_pref`, and the others) with unit columns whose units differ between groups no longer stop `PKNCAdata()` with "arguments imply differing number of rows: 1, 0" when some groups are diff --git a/R/aucint.R b/R/aucint.R index 0bd2c249..d7ef3092 100644 --- a/R/aucint.R +++ b/R/aucint.R @@ -32,7 +32,10 @@ #' \item{`AUCinf`}{is extrapolated with `lambda.z` (in other words, with the #' half-life), always using the logarithmic trapezoidal rule to align with #' the exponential decay that the half-life describes. When `lambda.z` is -#' not estimable and the interval is finite, `AUCall` is used instead.} +#' not estimable and the interval is finite, `AUCall` is used instead, +#' and the `aucint.inf.*` and `aumcint.inf.*` parameters say so with a +#' `pknca_warning_aucint_halflife_missing` warning: their value is that +#' of `aucint.all` (or `aumcint.all`).} #' } #' #' When the interval ends at or before Tlast, no extrapolation happens and @@ -364,7 +367,7 @@ pk.calc.auxcint <- function(conc, time, } else if (!extrapolates) { "none" } else if (auc.type %in% "AUCinf") { - "AUCall (half-life not estimable)" + pknca_extrap_method_halflife_missing } else { auc.type } @@ -394,6 +397,31 @@ pk.calc.auxcint <- function(conc, time, # spelling it out. pknca_extrap_method_prefix <- "Extrapolation: " pknca_extrap_method_halflife <- "half-life" +# An AUCinf-based AUCint whose interval reaches past Tlast without a half-life: +# the region after Tlast is the AUCall one (see aucint_warn_halflife_missing()) +pknca_extrap_method_halflife_missing <- "AUCall (half-life not estimable)" + +#' Warn when an AUCinf-based AUCint was calculated as the AUCall-based one +#' +#' @param ret The result of [pk.calc.auxcint()] with `auc.type = "AUCinf"` +#' @param parameter,parameter_all The name of the parameter calculated and of +#' the AUCall-based parameter whose value it has +#' @returns `ret`, after a `pknca_warning_aucint_halflife_missing` warning when +#' the half-life was needed after Tlast and was missing +#' @keywords Internal +#' @noRd +aucint_warn_halflife_missing <- function(ret, parameter, parameter_all) { + if (paste0(pknca_extrap_method_prefix, pknca_extrap_method_halflife_missing) %in% attr(ret, "method")) { + rlang::warn( + sprintf( + "%s: the half-life is missing, so %s is returned (the part of the interval after Tlast is not extrapolated with the half-life)", + parameter, parameter_all + ), + class = "pknca_warning_aucint_halflife_missing" + ) + } + ret +} #' @describeIn pk.calc.auxcint Calculate AUC over an interval #' @export @@ -451,13 +479,15 @@ pk.calc.aucint.inf.obs <- function(conc, time, start=NULL, end=NULL, time.dose, ..., options=list()) { if (missing(time.dose)) time.dose <- NULL - pk.calc.aucint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.obs, - options=options, ..., - auc.type="AUCinf") + ret <- + pk.calc.aucint(conc=conc, time=time, + start=start, end=end, + time.dose=time.dose, + route=route, duration.dose=duration.dose, + lambda.z=lambda.z, clast=clast.obs, + options=options, ..., + auc.type="AUCinf") + aucint_warn_halflife_missing(ret, parameter = "aucint.inf.obs", parameter_all = "aucint.all") } pknca_concept(pk.calc.aucint.inf.obs) <- "auc" @@ -470,13 +500,15 @@ pk.calc.aucint.inf.pred <- function(conc, time, start=NULL, end=NULL, time.dose, if (missing(time.dose)) { time.dose <- NULL } - pk.calc.aucint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.pred, - options=options, ..., - auc.type="AUCinf") + ret <- + pk.calc.aucint(conc=conc, time=time, + start=start, end=end, + time.dose=time.dose, + route=route, duration.dose=duration.dose, + lambda.z=lambda.z, clast=clast.pred, + options=options, ..., + auc.type="AUCinf") + aucint_warn_halflife_missing(ret, parameter = "aucint.inf.pred", parameter_all = "aucint.all") } pknca_concept(pk.calc.aucint.inf.pred) <- "auc" @@ -599,13 +631,15 @@ pk.calc.aumcint.inf.obs <- function(conc, time, start=NULL, end=NULL, time.dose, ..., options=list()) { if (missing(time.dose)) time.dose <- NULL - pk.calc.aumcint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.obs, - options=options, ..., - auc.type="AUCinf") + ret <- + pk.calc.aumcint(conc=conc, time=time, + start=start, end=end, + time.dose=time.dose, + route=route, duration.dose=duration.dose, + lambda.z=lambda.z, clast=clast.obs, + options=options, ..., + auc.type="AUCinf") + aucint_warn_halflife_missing(ret, parameter = "aumcint.inf.obs", parameter_all = "aumcint.all") } pknca_concept(pk.calc.aumcint.inf.obs) <- "aumc" @@ -618,13 +652,15 @@ pk.calc.aumcint.inf.pred <- function(conc, time, start=NULL, end=NULL, time.dose ..., options=list()) { if (missing(time.dose)) time.dose <- NULL - pk.calc.aumcint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.pred, - options=options, ..., - auc.type="AUCinf") + ret <- + pk.calc.aumcint(conc=conc, time=time, + start=start, end=end, + time.dose=time.dose, + route=route, duration.dose=duration.dose, + lambda.z=lambda.z, clast=clast.pred, + options=options, ..., + auc.type="AUCinf") + aucint_warn_halflife_missing(ret, parameter = "aumcint.inf.pred", parameter_all = "aumcint.all") } pknca_concept(pk.calc.aumcint.inf.pred) <- "aumc" diff --git a/man/pk.calc.auxcint.Rd b/man/pk.calc.auxcint.Rd index 27614abe..0d18e068 100644 --- a/man/pk.calc.auxcint.Rd +++ b/man/pk.calc.auxcint.Rd @@ -260,7 +260,10 @@ below-the-limit-of-quantification measurement and zero after that.} \item{\code{AUCinf}}{is extrapolated with \code{lambda.z} (in other words, with the half-life), always using the logarithmic trapezoidal rule to align with the exponential decay that the half-life describes. When \code{lambda.z} is -not estimable and the interval is finite, \code{AUCall} is used instead.} +not estimable and the interval is finite, \code{AUCall} is used instead, +and the \verb{aucint.inf.*} and \verb{aumcint.inf.*} parameters say so with a +\code{pknca_warning_aucint_halflife_missing} warning: their value is that +of \code{aucint.all} (or \code{aumcint.all}).} } When the interval ends at or before Tlast, no extrapolation happens and diff --git a/tests/testthat/test-aucint.R b/tests/testthat/test-aucint.R index 0200872f..abf526a9 100644 --- a/tests/testthat/test-aucint.R +++ b/tests/testthat/test-aucint.R @@ -665,9 +665,20 @@ test_that("aucint.inf.* falls back to AUCall when the half-life is not estimable ) o_conc <- PKNCAconc(d_conc, conc ~ time) o_data <- PKNCAdata(o_conc, intervals = intervals) + # Each AUCinf-based AUCint says that it is the AUCall-based one expect_warning( - o_nca <- suppressMessages(pk.nca(o_data)), - regexp = "Too few points for half-life calculation" + expect_warning( + expect_warning( + o_nca <- suppressMessages(pk.nca(o_data)), + regexp = "Too few points for half-life calculation" + ), + regexp = "aucint.inf.obs: the half-life is missing, so aucint.all is returned", + fixed = TRUE, + class = "pknca_warning_aucint_halflife_missing" + ), + regexp = "aucint.inf.pred: the half-life is missing, so aucint.all is returned", + fixed = TRUE, + class = "pknca_warning_aucint_halflife_missing" ) res <- as.data.frame(o_nca) auc_all <- as.numeric(res$PPORRES[res$PPTESTCD %in% "aucint.all"]) @@ -683,6 +694,63 @@ test_that("aucint.inf.* falls back to AUCall when the half-life is not estimable } }) +# Whether the registered parameter `col` (an element of get.interval.cols()) +# integrates over an interval with pk.calc.aucint() or pk.calc.aumcint() and +# takes the half-life +aucint_test_uses_halflife <- function(col) { + is.character(col$FUN) && + "lambda.z" %in% names(formals(get(col$FUN))) && + any(c("pk.calc.aucint", "pk.calc.aumcint") %in% all.names(body(get(col$FUN)))) +} + +# Call the function of the registered parameter `name` with a missing +# half-life and a Clast of 10, over `interval` +aucint_test_call_no_halflife <- function(name, conc, time, interval) { + fun <- get.interval.cols()[[name]]$FUN + args <- list(conc = conc, time = time, start = interval[1], end = interval[2], lambda.z = NA_real_) + clast_arg <- intersect(c("clast.obs", "clast.pred"), names(formals(get(fun)))) + args[[clast_arg]] <- 10 + do.call(fun, args) +} + +test_that("every AUCinf-based AUCint is the AUCall-based one, with a warning, when the half-life is missing", { + family <- names(get.interval.cols())[vapply(X = get.interval.cols(), FUN = aucint_test_uses_halflife, FUN.VALUE = TRUE)] + expect_setequal(family, c("aucint.inf.obs", "aucint.inf.pred", "aumcint.inf.obs", "aumcint.inf.pred")) + # Tlast is 24 and a BLQ sample follows at 30, so AUCall (with its triangle + # to 30) differs from AUClast + conc <- c(0, 50, 80, 70, 50, 35, 10, 0) + time <- c(0, 1, 2, 4, 8, 12, 24, 30) + expected_all <- c(aucint = 915.229654, aumcint = 8376.233537) + for (current in family) { + current_all <- sub(pattern = "\\.inf\\.(obs|pred)$", replacement = ".all", x = current) + value_all <- do.call(get.interval.cols()[[current_all]]$FUN, list(conc = conc, time = time, start = 0, end = 36)) + expect_equal(as.numeric(value_all), unname(expected_all[sub("\\..*$", "", current)]), tolerance = 1e-6, info = current) + expect_warning( + value <- aucint_test_call_no_halflife(current, conc = conc, time = time, interval = c(0, 36)), + regexp = paste0(current, ": the half-life is missing, so ", current_all, " is returned"), + fixed = TRUE, + class = "pknca_warning_aucint_halflife_missing" + ) + expect_equal(as.numeric(value), as.numeric(value_all), info = current) + expect_equal(attr(value, "exclude"), "DO NOT EXCLUDE", info = current) + expect_equal( + attr(value, "method")[3], "Extrapolation: AUCall (half-life not estimable)", + info = current + ) + # An interval that ends before Tlast does not need the half-life: no + # warning, and the AUClast-based value + expect_no_warning( + value_within <- aucint_test_call_no_halflife(current, conc = conc, time = time, interval = c(0, 12)) + ) + current_last <- sub(pattern = "\\.inf\\.(obs|pred)$", replacement = ".last", x = current) + expect_equal( + as.numeric(value_within), + as.numeric(do.call(get.interval.cols()[[current_last]]$FUN, list(conc = conc, time = time, start = 0, end = 12))), + info = current + ) + } +}) + test_that("pk.calc.aucint and wrappers: method attribute is set and propagated", { aucint_params <- c("aucint", "aucint.last", "aucint.inf.obs", "aucint.inf.pred", "aucint.all") auc_methods <- c("linear", "lin up/log down", "lin-log") From f3f98cef0fd856190a30ae491e55bf0fa650658e Mon Sep 17 00:00:00 2001 From: Bill Denney Date: Fri, 13 Nov 2026 19:48:06 -0500 Subject: [PATCH 2/3] fix: warn at every place an AUCinf-based AUCint lacks the half-life Bill's answers: an interval to infinity without a half-life stays NA with the same warning, and so does a start concentration extrapolated from the profile before the dose past its Tlast (value unchanged). pk.calc.auxcint() now gives pknca_warning_aucint_halflife_missing where it decides that it has no half-life to use (after Tlast, to infinity, or for the start concentration, which interp.extrap.conc.dose() reports as an extrapolation), with the case in a halflife_missing field. The aucint.inf.* and aumcint.inf.* functions give it again with their name. This replaces reading the method text afterwards, which could not see the other two cases. The enumerating test covers all three and a first dose, which needs no half-life; NEWS says no value changes. Co-Authored-By: Claude Opus 5.5 --- NEWS.md | 23 +++-- R/aucint.R | 190 +++++++++++++++++++++++++---------- man/pk.calc.auxcint.Rd | 14 ++- tests/testthat/test-aucint.R | 96 ++++++++++++++---- 4 files changed, 236 insertions(+), 87 deletions(-) diff --git a/NEWS.md b/NEWS.md index c3736b5e..bc74b071 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1213,14 +1213,21 @@ the generated intervals: ## Bug fixes * `aucint.inf.obs`, `aucint.inf.pred`, `aumcint.inf.obs`, and - `aumcint.inf.pred` over a finite interval that ends after Tlast, when the - half-life is missing, now give a `pknca_warning_aucint_halflife_missing` - warning saying that the value is that of `aucint.all` (or `aumcint.all`) - (#450, @billdenney). The values do not change: they were already the - AUCall-based ones (#508), which equal the AUClast-based ones unless a - concentration below the limit of quantification follows Tlast. An interval - that ends at or before Tlast does not need the half-life and gives no - warning. + `aumcint.inf.pred` now give a `pknca_warning_aucint_halflife_missing` + warning, naming the parameter, whenever they need the half-life and it is + missing (#450, @billdenney). No value changes: + * over a finite interval that ends after Tlast, the value is that of + `aucint.all` (or `aumcint.all`), as it has been since the AUCall fallback + of #508; it equals the AUClast-based value unless a concentration below + the limit of quantification follows Tlast; + * over an interval to infinity, the value is `NA`, as before, because there + is no finite fallback; + * when the interval starts at a dose without a concentration measured + there, the concentration at the start is past the Tlast of the profile + before the dose and would be extrapolated with the half-life; without + one, the value is the one it was. + An interval that ends at or before Tlast and needs no concentration from the + profile before a dose does not need the half-life and gives no warning. * Preferred units (`concu_pref`, `doseu_pref`, and the others) with unit columns whose units differ between groups no longer stop `PKNCAdata()` with diff --git a/R/aucint.R b/R/aucint.R index d7ef3092..7e4c255b 100644 --- a/R/aucint.R +++ b/R/aucint.R @@ -32,10 +32,9 @@ #' \item{`AUCinf`}{is extrapolated with `lambda.z` (in other words, with the #' half-life), always using the logarithmic trapezoidal rule to align with #' the exponential decay that the half-life describes. When `lambda.z` is -#' not estimable and the interval is finite, `AUCall` is used instead, -#' and the `aucint.inf.*` and `aumcint.inf.*` parameters say so with a -#' `pknca_warning_aucint_halflife_missing` warning: their value is that -#' of `aucint.all` (or `aumcint.all`).} +#' not estimable and the interval is finite, `AUCall` is used instead; +#' over an interval to infinity there is no finite fallback, and the +#' result is `NA`.} #' } #' #' When the interval ends at or before Tlast, no extrapolation happens and @@ -46,6 +45,13 @@ #' ends. The extrapolation that was used is reported in the method (`PPANMETH`) #' column. #' +#' Whenever `AUCinf` needs `lambda.z` and it is not estimable (after Tlast, over +#' an interval to infinity, or for that concentration at `start`), a +#' `pknca_warning_aucint_halflife_missing` warning says so; the +#' `aucint.inf.*` and `aumcint.inf.*` parameters give it with their own name. +#' Their value is that of `aucint.all` (or `aumcint.all`) over a finite +#' interval, and `NA` over an interval to infinity. +#' #' # The time origin of the AUMC #' #' The AUMC is weighted by the time since `start`, which is what `aumclast` @@ -178,10 +184,12 @@ pk.calc.auxcint <- function(conc, time, } else if (is.na(lambda.z)) { if (is.infinite(interval[2])) { # Without a half-life there is no finite tail to fall back to + aucint_signal_halflife_missing("infinite") return(structure(NA_real_, exclude = "the half-life is NA")) } # With no estimable half-life, the tail of the interval is the AUCall # triangle instead (#508) + aucint_signal_halflife_missing("after_tlast") auc_type_calc <- "AUCall" } else { lambda_z_used <- TRUE @@ -263,6 +271,12 @@ pk.calc.auxcint <- function(conc, time, ... ) mask_start <- missing_times == interval[1] + if (auc.type %in% "AUCinf" && !extrapolates && is.na(lambda.z) && + "Extrapolation" %in% attr(missing_conc, "Method")[mask_start]) { + # The concentration at `start` is past the Tlast of the profile before + # the dose, where the half-life would extrapolate it (below) + aucint_signal_halflife_missing("start") + } if (auc.type %in% "AUCinf" && !extrapolates && !is.na(lambda.z) && any(mask_start)) { # The concentration at `start` may be extrapolated from the profile # before a dose (the trough before the dose that starts the interval). @@ -398,29 +412,77 @@ pk.calc.auxcint <- function(conc, time, pknca_extrap_method_prefix <- "Extrapolation: " pknca_extrap_method_halflife <- "half-life" # An AUCinf-based AUCint whose interval reaches past Tlast without a half-life: -# the region after Tlast is the AUCall one (see aucint_warn_halflife_missing()) +# the region after Tlast is the AUCall one pknca_extrap_method_halflife_missing <- "AUCall (half-life not estimable)" -#' Warn when an AUCinf-based AUCint was calculated as the AUCall-based one +#' Say that an AUCinf-based AUCint needed the half-life and it is missing +#' +#' The `aucint.inf.*` and `aumcint.inf.*` parameters give the warning again +#' with their own name (see `aucint_rename_halflife_missing()`). +#' +#' @param reason Where the half-life was needed: `"after_tlast"` (a finite +#' interval past Tlast, which is then the AUCall-based one), `"infinite"` +#' (an interval to infinity, which is then `NA`), or `"start"` (the +#' concentration at the start of the interval, past the Tlast of the profile +#' before the dose) +#' @returns `NULL`, after a `pknca_warning_aucint_halflife_missing` warning +#' whose `halflife_missing` field is `reason` +#' @keywords Internal +#' @noRd +aucint_signal_halflife_missing <- function(reason) { + rlang::warn( + aucint_halflife_missing_message(reason = reason, parameter = "The AUCinf-based AUCint", parameter_all = "the AUCall-based one"), + class = "pknca_warning_aucint_halflife_missing", + halflife_missing = reason + ) +} + +#' The message of a `pknca_warning_aucint_halflife_missing` warning #' -#' @param ret The result of [pk.calc.auxcint()] with `auc.type = "AUCinf"` -#' @param parameter,parameter_all The name of the parameter calculated and of -#' the AUCall-based parameter whose value it has -#' @returns `ret`, after a `pknca_warning_aucint_halflife_missing` warning when -#' the half-life was needed after Tlast and was missing +#' @inheritParams aucint_signal_halflife_missing +#' @param parameter,parameter_all The parameter calculated and the AUCall-based +#' one whose value it has +#' @returns The message #' @keywords Internal #' @noRd -aucint_warn_halflife_missing <- function(ret, parameter, parameter_all) { - if (paste0(pknca_extrap_method_prefix, pknca_extrap_method_halflife_missing) %in% attr(ret, "method")) { - rlang::warn( +aucint_halflife_missing_message <- function(reason, parameter, parameter_all) { + switch( + reason, + after_tlast = sprintf( "%s: the half-life is missing, so %s is returned (the part of the interval after Tlast is not extrapolated with the half-life)", parameter, parameter_all ), - class = "pknca_warning_aucint_halflife_missing" - ) - } - ret + infinite = + sprintf( + "%s: the half-life is missing, and an interval to infinity has no finite fallback, so NA is returned", + parameter + ), + start = + sprintf( + "%s: the half-life is missing, so the concentration at the start of the interval (past the Tlast of the profile before the dose) is not extrapolated with the half-life", + parameter + ) + ) +} + +#' Give a `pknca_warning_aucint_halflife_missing` warning again with the name +#' of the parameter +#' +#' A calling handler for the warning from [pk.calc.auxcint()]. +#' +#' @param cnd The warning +#' @inheritParams aucint_halflife_missing_message +#' @returns Nothing: the warning is muffled after it is given again +#' @keywords Internal +#' @noRd +aucint_rename_halflife_missing <- function(cnd, parameter, parameter_all) { + rlang::warn( + aucint_halflife_missing_message(reason = cnd$halflife_missing, parameter = parameter, parameter_all = parameter_all), + class = "pknca_warning_aucint_halflife_missing", + halflife_missing = cnd$halflife_missing + ) + invokeRestart("muffleWarning") } #' @describeIn pk.calc.auxcint Calculate AUC over an interval @@ -479,15 +541,20 @@ pk.calc.aucint.inf.obs <- function(conc, time, start=NULL, end=NULL, time.dose, ..., options=list()) { if (missing(time.dose)) time.dose <- NULL - ret <- - pk.calc.aucint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.obs, - options=options, ..., - auc.type="AUCinf") - aucint_warn_halflife_missing(ret, parameter = "aucint.inf.obs", parameter_all = "aucint.all") + withCallingHandlers( + pk.calc.aucint( + conc = conc, time = time, + start = start, end = end, + time.dose = time.dose, + route = route, duration.dose = duration.dose, + lambda.z = lambda.z, clast = clast.obs, + options = options, ..., + auc.type = "AUCinf" + ), + pknca_warning_aucint_halflife_missing = function(cnd) { + aucint_rename_halflife_missing(cnd, parameter = "aucint.inf.obs", parameter_all = "aucint.all") + } + ) } pknca_concept(pk.calc.aucint.inf.obs) <- "auc" @@ -500,15 +567,20 @@ pk.calc.aucint.inf.pred <- function(conc, time, start=NULL, end=NULL, time.dose, if (missing(time.dose)) { time.dose <- NULL } - ret <- - pk.calc.aucint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.pred, - options=options, ..., - auc.type="AUCinf") - aucint_warn_halflife_missing(ret, parameter = "aucint.inf.pred", parameter_all = "aucint.all") + withCallingHandlers( + pk.calc.aucint( + conc = conc, time = time, + start = start, end = end, + time.dose = time.dose, + route = route, duration.dose = duration.dose, + lambda.z = lambda.z, clast = clast.pred, + options = options, ..., + auc.type = "AUCinf" + ), + pknca_warning_aucint_halflife_missing = function(cnd) { + aucint_rename_halflife_missing(cnd, parameter = "aucint.inf.pred", parameter_all = "aucint.all") + } + ) } pknca_concept(pk.calc.aucint.inf.pred) <- "auc" @@ -631,15 +703,20 @@ pk.calc.aumcint.inf.obs <- function(conc, time, start=NULL, end=NULL, time.dose, ..., options=list()) { if (missing(time.dose)) time.dose <- NULL - ret <- - pk.calc.aumcint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.obs, - options=options, ..., - auc.type="AUCinf") - aucint_warn_halflife_missing(ret, parameter = "aumcint.inf.obs", parameter_all = "aumcint.all") + withCallingHandlers( + pk.calc.aumcint( + conc = conc, time = time, + start = start, end = end, + time.dose = time.dose, + route = route, duration.dose = duration.dose, + lambda.z = lambda.z, clast = clast.obs, + options = options, ..., + auc.type = "AUCinf" + ), + pknca_warning_aucint_halflife_missing = function(cnd) { + aucint_rename_halflife_missing(cnd, parameter = "aumcint.inf.obs", parameter_all = "aumcint.all") + } + ) } pknca_concept(pk.calc.aumcint.inf.obs) <- "aumc" @@ -652,15 +729,20 @@ pk.calc.aumcint.inf.pred <- function(conc, time, start=NULL, end=NULL, time.dose ..., options=list()) { if (missing(time.dose)) time.dose <- NULL - ret <- - pk.calc.aumcint(conc=conc, time=time, - start=start, end=end, - time.dose=time.dose, - route=route, duration.dose=duration.dose, - lambda.z=lambda.z, clast=clast.pred, - options=options, ..., - auc.type="AUCinf") - aucint_warn_halflife_missing(ret, parameter = "aumcint.inf.pred", parameter_all = "aumcint.all") + withCallingHandlers( + pk.calc.aumcint( + conc = conc, time = time, + start = start, end = end, + time.dose = time.dose, + route = route, duration.dose = duration.dose, + lambda.z = lambda.z, clast = clast.pred, + options = options, ..., + auc.type = "AUCinf" + ), + pknca_warning_aucint_halflife_missing = function(cnd) { + aucint_rename_halflife_missing(cnd, parameter = "aumcint.inf.pred", parameter_all = "aumcint.all") + } + ) } pknca_concept(pk.calc.aumcint.inf.pred) <- "aumc" diff --git a/man/pk.calc.auxcint.Rd b/man/pk.calc.auxcint.Rd index 0d18e068..139a3d05 100644 --- a/man/pk.calc.auxcint.Rd +++ b/man/pk.calc.auxcint.Rd @@ -260,10 +260,9 @@ below-the-limit-of-quantification measurement and zero after that.} \item{\code{AUCinf}}{is extrapolated with \code{lambda.z} (in other words, with the half-life), always using the logarithmic trapezoidal rule to align with the exponential decay that the half-life describes. When \code{lambda.z} is -not estimable and the interval is finite, \code{AUCall} is used instead, -and the \verb{aucint.inf.*} and \verb{aumcint.inf.*} parameters say so with a -\code{pknca_warning_aucint_halflife_missing} warning: their value is that -of \code{aucint.all} (or \code{aumcint.all}).} +not estimable and the interval is finite, \code{AUCall} is used instead; +over an interval to infinity there is no finite fallback, and the +result is \code{NA}.} } When the interval ends at or before Tlast, no extrapolation happens and @@ -273,6 +272,13 @@ that starts the interval, when it was not measured) is past the Tlast of that profile, so \code{AUCinf} extrapolates it with \code{lambda.z} wherever the interval ends. The extrapolation that was used is reported in the method (\code{PPANMETH}) column. + +Whenever \code{AUCinf} needs \code{lambda.z} and it is not estimable (after Tlast, over +an interval to infinity, or for that concentration at \code{start}), a +\code{pknca_warning_aucint_halflife_missing} warning says so; the +\verb{aucint.inf.*} and \verb{aumcint.inf.*} parameters give it with their own name. +Their value is that of \code{aucint.all} (or \code{aumcint.all}) over a finite +interval, and \code{NA} over an interval to infinity. } \section{The time origin of the AUMC}{ diff --git a/tests/testthat/test-aucint.R b/tests/testthat/test-aucint.R index abf526a9..49011d11 100644 --- a/tests/testthat/test-aucint.R +++ b/tests/testthat/test-aucint.R @@ -128,15 +128,21 @@ test_that("AUCint gives the same value when no interpolation/extrapolation is re test_that("AUCint falls back to AUCall over a dose when the half-life is not estimable (#508)", { concdata <- data.frame(conc = c(8, 4, 2, 1), time = 0:3) - over_dose <- - pk.calc.aucint( - conc = concdata$conc, - time = concdata$time, - interval = c(0, 4), - time.dose = 1.5, - lambda.z = NA, - auc.type = "AUCinf" - ) + # Called directly, the warning names the AUCinf-based AUCint + expect_warning( + over_dose <- + pk.calc.aucint( + conc = concdata$conc, + time = concdata$time, + interval = c(0, 4), + time.dose = 1.5, + lambda.z = NA, + auc.type = "AUCinf" + ), + regexp = "The AUCinf-based AUCint: the half-life is missing, so the AUCall-based one is returned", + fixed = TRUE, + class = "pknca_warning_aucint_halflife_missing" + ) # The dose at 1.5 is within the interval, so nothing is estimated there and # the measured concentrations on either side of it are integrated. With no # half-life to extrapolate with, the region after tlast is AUCall, which is @@ -705,9 +711,12 @@ aucint_test_uses_halflife <- function(col) { # Call the function of the registered parameter `name` with a missing # half-life and a Clast of 10, over `interval` -aucint_test_call_no_halflife <- function(name, conc, time, interval) { +aucint_test_call_no_halflife <- function(name, conc, time, interval, time.dose = NULL) { fun <- get.interval.cols()[[name]]$FUN args <- list(conc = conc, time = time, start = interval[1], end = interval[2], lambda.z = NA_real_) + if (!is.null(time.dose)) { + args$time.dose <- time.dose + } clast_arg <- intersect(c("clast.obs", "clast.pred"), names(formals(get(fun)))) args[[clast_arg]] <- 10 do.call(fun, args) @@ -748,6 +757,44 @@ test_that("every AUCinf-based AUCint is the AUCall-based one, with a warning, wh as.numeric(do.call(get.interval.cols()[[current_last]]$FUN, list(conc = conc, time = time, start = 0, end = 12))), info = current ) + # An interval to infinity has no finite fallback: NA, with the warning + expect_warning( + value_inf <- aucint_test_call_no_halflife(current, conc = conc, time = time, interval = c(0, Inf)), + regexp = paste0(current, ": the half-life is missing, and an interval to infinity has no finite fallback, so NA is returned"), + fixed = TRUE, + class = "pknca_warning_aucint_halflife_missing" + ) + expect_equal(value_inf, structure(NA_real_, exclude = "the half-life is NA"), info = current) + # The concentration at the start of an interval that starts at a dose + # without a sample there (doses at 0 and 12, interval 12 to 18) is past the + # Tlast of the profile before the dose, where the half-life would + # extrapolate it: the warning, and the AUCall-based value, unchanged + conc_md <- c(0, 50, 80, 70, 50, 90, 100, 80, 60) + time_md <- c(0, 1, 2, 4, 8, 13, 14, 16, 18) + expect_warning( + value_start <- + aucint_test_call_no_halflife(current, conc = conc_md, time = time_md, interval = c(12, 18), time.dose = c(0, 12)), + regexp = paste0(current, ": the half-life is missing, so the concentration at the start of the interval"), + fixed = TRUE, + class = "pknca_warning_aucint_halflife_missing" + ) + value_start_all <- + do.call( + get.interval.cols()[[current_all]]$FUN, + list(conc = conc_md, time = time_md, start = 12, end = 18, time.dose = c(0, 12)) + ) + expect_equal(as.numeric(value_start), as.numeric(value_start_all), info = current) + expect_equal( + as.numeric(value_start), + unname(c(aucint = 458.299201, aumcint = 1409.663714)[sub("\\..*$", "", current)]), + tolerance = 1e-6, + info = current + ) + # The first dose has no profile before it, so a missing start concentration + # needs no half-life: no warning + expect_no_warning( + aucint_test_call_no_halflife(current, conc = c(50, 80, 70, 50), time = c(1, 2, 4, 8), interval = c(0, 4), time.dose = 0) + ) } }) @@ -1172,20 +1219,27 @@ test_that("AUCint is NA when nothing was measured before the dose after the inte test_that("aucint.inf.* is NA over an infinite interval without a half-life (#508)", { conc <- c(8, 4, 2, 1) time <- 0:3 - # An unbounded tail cannot fall back to AUCall, so there is nothing to report - expect_equal( - pk.calc.aucint.inf.obs( - conc = conc, time = time, start = 0, end = Inf, - clast.obs = 1, lambda.z = NA + # An unbounded tail cannot fall back to AUCall, so the result is NA, and the + # warning says why + expect_warning( + expect_equal( + pk.calc.aucint.inf.obs( + conc = conc, time = time, start = 0, end = Inf, + clast.obs = 1, lambda.z = NA + ), + structure(NA_real_, exclude = "the half-life is NA") ), - structure(NA_real_, exclude = "the half-life is NA") + class = "pknca_warning_aucint_halflife_missing" ) - expect_equal( - pk.calc.aucint.inf.pred( - conc = conc, time = time, start = 0, end = Inf, - clast.pred = NA_real_, lambda.z = NA + expect_warning( + expect_equal( + pk.calc.aucint.inf.pred( + conc = conc, time = time, start = 0, end = Inf, + clast.pred = NA_real_, lambda.z = NA + ), + structure(NA_real_, exclude = "the half-life is NA") ), - structure(NA_real_, exclude = "the half-life is NA") + class = "pknca_warning_aucint_halflife_missing" ) }) From 1d31e1fd60177bd42b574a5aedd9ae6ee119c620 Mon Sep 17 00:00:00 2001 From: Bill Denney Date: Sat, 14 Nov 2026 11:07:36 -0500 Subject: [PATCH 3/3] fix: the AUCint half-life warning says how the value is calculated, and names the AUMC The warning for a finite interval past Tlast is given before the value is known, and the value can still be NA for another reason (a start concentration that cannot be estimated). It now says the part after Tlast is not extrapolated with the half-life and the result is calculated as the AUCall-based one is, which holds in every case. pk.calc.aumcint() gives the warning again with "The AUMCinf-based AUMCint" and "the AUMCall-based one", so a direct call names the AUMC. The aumcint.inf.* parameters still give one warning, with their own name. The comment of the enumerating test states its two limits: the integrator call must be in the parameter's own function body, and the .all and .last names are derived by a regular expression. Co-Authored-By: Claude Opus 5.5 --- R/aucint.R | 35 ++++++++----- tests/testthat/test-aucint.R | 96 ++++++++++++++++++++++++++++++++++-- 2 files changed, 114 insertions(+), 17 deletions(-) diff --git a/R/aucint.R b/R/aucint.R index 7e4c255b..66c95092 100644 --- a/R/aucint.R +++ b/R/aucint.R @@ -417,11 +417,13 @@ pknca_extrap_method_halflife_missing <- "AUCall (half-life not estimable)" #' Say that an AUCinf-based AUCint needed the half-life and it is missing #' -#' The `aucint.inf.*` and `aumcint.inf.*` parameters give the warning again -#' with their own name (see `aucint_rename_halflife_missing()`). +#' [pk.calc.aumcint()] gives the warning again for the AUMC, and the +#' `aucint.inf.*` and `aumcint.inf.*` parameters give it again with their own +#' name (see `aucint_rename_halflife_missing()`). #' #' @param reason Where the half-life was needed: `"after_tlast"` (a finite -#' interval past Tlast, which is then the AUCall-based one), `"infinite"` +#' interval past Tlast, which is then calculated as the AUCall-based one +#' is), `"infinite"` #' (an interval to infinity, which is then `NA`), or `"start"` (the #' concentration at the start of the interval, past the Tlast of the profile #' before the dose) @@ -441,8 +443,11 @@ aucint_signal_halflife_missing <- function(reason) { #' #' @inheritParams aucint_signal_halflife_missing #' @param parameter,parameter_all The parameter calculated and the AUCall-based -#' one whose value it has -#' @returns The message +#' one it is then calculated as +#' @returns The message. The `"after_tlast"` message says how the value is +#' calculated, not what it is: the warning is given before the value is +#' known, and the value can still be `NA` for another reason (for example a +#' concentration at the start of the interval that cannot be estimated). #' @keywords Internal #' @noRd aucint_halflife_missing_message <- function(reason, parameter, parameter_all) { @@ -450,7 +455,7 @@ aucint_halflife_missing_message <- function(reason, parameter, parameter_all) { reason, after_tlast = sprintf( - "%s: the half-life is missing, so %s is returned (the part of the interval after Tlast is not extrapolated with the half-life)", + "%s: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as %s is", parameter, parameter_all ), infinite = @@ -648,12 +653,18 @@ add.interval.col("aucint.inf.pred", #' @describeIn pk.calc.auxcint Calculate AUMC over an interval #' @export pk.calc.aumcint <- function(conc, time, ..., options=list()) { - pk.calc.auxcint( - conc = conc, time = time, ..., - options = options, - fun_linear = aumcintegrate_linear, - fun_log = aumcintegrate_log, - fun_inf = aumcintegrate_inf + # pk.calc.auxcint() names the AUC in its warning; this is the AUMC + withCallingHandlers( + pk.calc.auxcint( + conc = conc, time = time, ..., + options = options, + fun_linear = aumcintegrate_linear, + fun_log = aumcintegrate_log, + fun_inf = aumcintegrate_inf + ), + pknca_warning_aucint_halflife_missing = function(cnd) { + aucint_rename_halflife_missing(cnd, parameter = "The AUMCinf-based AUMCint", parameter_all = "the AUMCall-based one") + } ) } diff --git a/tests/testthat/test-aucint.R b/tests/testthat/test-aucint.R index 49011d11..0b6894a3 100644 --- a/tests/testthat/test-aucint.R +++ b/tests/testthat/test-aucint.R @@ -139,7 +139,7 @@ test_that("AUCint falls back to AUCall over a dose when the half-life is not est lambda.z = NA, auc.type = "AUCinf" ), - regexp = "The AUCinf-based AUCint: the half-life is missing, so the AUCall-based one is returned", + regexp = "The AUCinf-based AUCint: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as the AUCall-based one is", fixed = TRUE, class = "pknca_warning_aucint_halflife_missing" ) @@ -678,11 +678,11 @@ test_that("aucint.inf.* falls back to AUCall when the half-life is not estimable o_nca <- suppressMessages(pk.nca(o_data)), regexp = "Too few points for half-life calculation" ), - regexp = "aucint.inf.obs: the half-life is missing, so aucint.all is returned", + regexp = "aucint.inf.obs: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as aucint.all is", fixed = TRUE, class = "pknca_warning_aucint_halflife_missing" ), - regexp = "aucint.inf.pred: the half-life is missing, so aucint.all is returned", + regexp = "aucint.inf.pred: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as aucint.all is", fixed = TRUE, class = "pknca_warning_aucint_halflife_missing" ) @@ -702,7 +702,11 @@ test_that("aucint.inf.* falls back to AUCall when the half-life is not estimable # Whether the registered parameter `col` (an element of get.interval.cols()) # integrates over an interval with pk.calc.aucint() or pk.calc.aumcint() and -# takes the half-life +# takes the half-life. Two limits: the call must be in the body of the +# parameter's own function, so a parameter that reaches the integrator through +# a helper is not seen; and the test below derives the `.all` and `.last` names +# from the `.inf.obs` or `.inf.pred` name with a regular expression, so a +# member named otherwise needs its own case there. aucint_test_uses_halflife <- function(col) { is.character(col$FUN) && "lambda.z" %in% names(formals(get(col$FUN))) && @@ -736,7 +740,7 @@ test_that("every AUCinf-based AUCint is the AUCall-based one, with a warning, wh expect_equal(as.numeric(value_all), unname(expected_all[sub("\\..*$", "", current)]), tolerance = 1e-6, info = current) expect_warning( value <- aucint_test_call_no_halflife(current, conc = conc, time = time, interval = c(0, 36)), - regexp = paste0(current, ": the half-life is missing, so ", current_all, " is returned"), + regexp = paste0(current, ": the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as ", current_all, " is"), fixed = TRUE, class = "pknca_warning_aucint_halflife_missing" ) @@ -798,6 +802,88 @@ test_that("every AUCinf-based AUCint is the AUCall-based one, with a warning, wh } }) +# The value of `expr` and the warnings it gives, each muffled +aucint_test_warnings <- function(expr) { + acc <- new.env(parent = emptyenv()) + acc$warnings <- list() + value <- + withCallingHandlers( + expr, + warning = function(w) { + acc$warnings[[length(acc$warnings) + 1]] <- w + invokeRestart("muffleWarning") + } + ) + list(value = value, warnings = acc$warnings) +} + +# The messages of the warnings that `expr` gives +aucint_test_messages <- function(expr) { + vapply(X = aucint_test_warnings(expr)$warnings, FUN = conditionMessage, FUN.VALUE = "") +} + +test_that("the half-life warning says how the value is calculated, which holds when the value is NA for another reason", { + # The interval starts at the second dose with no profile before it to + # estimate the start concentration from, so the value is NA whatever the + # extrapolation after Tlast; the half-life warning is given before that is + # known + args <- + list( + conc = c(5, 2), time = c(13, 14), start = 12, end = 18, + time.dose = c(0, 12), lambda.z = NA, clast.obs = 2 + ) + caught <- aucint_test_warnings(do.call(pk.calc.aucint.inf.obs, args)) + value <- caught$value + warnings <- caught$warnings + expect_equal(as.numeric(value), NA_real_) + expect_equal( + vapply(X = warnings, FUN = function(w) class(w)[1], FUN.VALUE = ""), + c( + "pknca_warning_aucint_halflife_missing", "pknca_warning_interp_extrap_conc_dose", + "pknca_warning_missing_interpolated_concentrations" + ) + ) + expect_equal( + conditionMessage(warnings[[1]]), + "aucint.inf.obs: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as aucint.all is" + ) + # aucint.all is NA in the same way + expect_equal( + as.numeric(suppressWarnings(do.call(pk.calc.aucint.all, args[c("conc", "time", "start", "end", "time.dose")]))), + NA_real_ + ) +}) + +test_that("the half-life warning names the AUMC for an AUMC, once", { + conc <- c(0, 50, 80, 70, 50, 35, 10, 0) + time <- c(0, 1, 2, 4, 8, 12, 24, 30) + expect_equal( + aucint_test_messages( + pk.calc.aumcint(conc = conc, time = time, interval = c(0, 36), lambda.z = NA, auc.type = "AUCinf") + ), + "The AUMCinf-based AUMCint: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as the AUMCall-based one is" + ) + expect_equal( + aucint_test_messages( + pk.calc.aumcint(conc = conc, time = time, interval = c(0, Inf), lambda.z = NA, auc.type = "AUCinf") + ), + "The AUMCinf-based AUMCint: the half-life is missing, and an interval to infinity has no finite fallback, so NA is returned" + ) + expect_equal( + aucint_test_messages( + pk.calc.aucint(conc = conc, time = time, interval = c(0, 36), lambda.z = NA, auc.type = "AUCinf") + ), + "The AUCinf-based AUCint: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as the AUCall-based one is" + ) + # The parameter's own name replaces the AUMC's, with one warning + expect_equal( + aucint_test_messages( + pk.calc.aumcint.inf.obs(conc = conc, time = time, start = 0, end = 36, lambda.z = NA, clast.obs = 10) + ), + "aumcint.inf.obs: the half-life is missing, so the part of the interval after Tlast is not extrapolated with it, and the result is calculated as aumcint.all is" + ) +}) + test_that("pk.calc.aucint and wrappers: method attribute is set and propagated", { aucint_params <- c("aucint", "aucint.last", "aucint.inf.obs", "aucint.inf.pred", "aucint.all") auc_methods <- c("linear", "lin up/log down", "lin-log")