(v3.0.1.9123) Add method argument to sir_combine() for resistance within a group (most_resistant), and restore the AMR 3.0.1 behaviour of count_*() and proportion_*() for multiple antimicrobials (#321)

This commit is contained in:
dr. M.S. (Matthijs) Berends committed 2026-10-12 21:37:13 +02:00
1 parent 239c5a87a8
commit bf12e3abe7
13 files changed
+322 -141

No files matched your search

+1 -1
View File
@@ -42,7 +42,7 @@
#' @inheritSection as.sir Interpretation of SIR
#' @details These functions are meant to count isolates. Use the [resistance()]/[susceptibility()] functions to calculate microbial resistance/susceptibility.
#'
#' The function [n_sir()] is an alias of [count_all()]. They can be used to count all available isolates, i.e. where the input antimicrobial has an available result (S, I or R), or for multiple antimicrobials, where the result of the combination is available (see *Combination Therapy* below). Their use is equal to `dplyr`'s `n_distinct()`. Their function is equal to `count_susceptible(...) + count_resistant(...)`.
#' The function [n_sir()] is an alias of [count_all()]. They can be used to count all available isolates, i.e. where the input antimicrobial has an available result (S, I or R). For multiple antimicrobials, these are isolates with a result for any of the antimicrobials, or with `only_all_tested = TRUE`, for all of the antimicrobials (see *Combination Therapy* below). Their use is equal to `dplyr`'s `n_distinct()`. For one antimicrobial, their function is equal to `count_susceptible(...) + count_resistant(...)`.
#'
#' The function [count_df()] takes any variable from `data` that has an [`sir`] class (created with [as.sir()]) and counts the number of S's, I's and R's. It also supports grouped variables. The function [sir_df()] works exactly like [count_df()], but adds the percentage of S, I and R.
#' @inheritSection sir_combine Combination Therapy
+17 -6
View File
@@ -132,20 +132,31 @@ sir_calc <- function(...,
}
if (ncol(x) == 1) {
x <- x[, 1, drop = TRUE]
} else {
# combination therapy: determine the result of the combination for every isolate, see ?sir_combine
x <- sir_combine_engine(as.list(x), S_values = get_susceptible_values(guideline), only_all_tested = only_all_tested)
} else if (isTRUE(only_all_tested)) {
# combination therapy of isolates tested for all antimicrobials, see ?sir_combine
x <- sir_combine_engine(as.list(x), S_values = get_susceptible_values(guideline), only_all_tested = TRUE)
}
} else if (!is.sir(x)) {
x <- as.sir(x)
print_warning <- TRUE
}
if ("SDD" %in% ab_result && "SDD" %in% x && message_not_thrown_before("sir_calc", only_count, ab_result, entire_session = TRUE)) {
if ("SDD" %in% ab_result && "SDD" %in% unlist(lapply(as.list(x), as.character)) && message_not_thrown_before("sir_calc", only_count, ab_result, entire_session = TRUE)) {
message_("Note that {.fun ", ifelse(only_count, "count", "proportion"), "_", ifelse("S" %in% ab_result, "S", ""), "I", ifelse("R" %in% ab_result, "R", ""), "} will also include dose-dependent susceptibility, {.val SDD}. This note will be shown once for this session.", as_note = FALSE)
}
numerator <- sum(x %in% ab_result, na.rm = TRUE)
denominator <- sum(x %in% denominator_vals, na.rm = TRUE)
if (is.data.frame(x)) {
# multiple antimicrobials with only_all_tested = FALSE: an isolate counts if any antimicrobial has a result in `ab_result`, and is considered tested if it has such a result or was tested for all antimicrobials, see ?sir_combine
# this equals sir_combine(method = "most_susceptible") for susceptibility and sir_combine(method = "most_resistant") for resistance
# 'NI' is a missing result
numerator_vals <- intersect(as.character(ab_result), denominator_vals)
is_counted <- Reduce(`|`, lapply(x, function(col) as.character(col) %in% numerator_vals))
is_complete <- Reduce(`&`, lapply(x, function(col) as.character(col) %in% denominator_vals))
numerator <- sum(is_counted)
denominator <- sum(is_counted | is_complete)
} else {
numerator <- sum(x %in% ab_result, na.rm = TRUE)
denominator <- sum(x %in% denominator_vals, na.rm = TRUE)
}
if (print_warning == TRUE) {
if (message_not_thrown_before("sir_calc")) {
+76 -33
View File
@@ -29,38 +29,60 @@
#' Combine SIR Results of Multiple Antimicrobials
#'
#' @description Combine the SIR results of two or more antimicrobials into one SIR result per isolate, e.g. to create a variable for the combination therapy of piperacillin/tazobactam with gentamicin. The result is the best result of the antimicrobials, as a combination therapy covers the isolate if any of its antimicrobials is active. See *Combination Therapy* below for the exact rules.
#' @description Combine the SIR results of two or more antimicrobials into one SIR result per isolate. This can answer two different questions, set with the `method` argument:
#'
#' The same rules are used by [antibiogram()] and [wisca()] for combination antibiograms, and by the [`count_*()`][count()] and [`proportion_*()`][proportion()] functions when more than one variable is used, so the result of [sir_combine()] can be used in any further analysis.
#' * `"most_susceptible"` (default): *Is at least one of these antimicrobials expected to work?* This is the result of a combination therapy, e.g. piperacillin/tazobactam with gentamicin, which covers the isolate if any of its antimicrobials is active.
#' * `"most_resistant"`: *Is resistance demonstrated to any of these antimicrobials?* This is the result for a group of antimicrobials, e.g. resistance to third-generation cephalosporins if an isolate is resistant to ceftazidime or ceftriaxone, as used in surveillance reports.
#'
#' See *Combination Therapy* below for the exact rules. The same rules are used by [antibiogram()] and [wisca()] for combination antibiograms, and by the [`count_*()`][count()] and [`proportion_*()`][proportion()] functions when more than one variable is used.
#' @param ... Two or more vectors (or columns) with antimicrobial interpretations, or a data frame with such columns. They will be transformed internally with [as.sir()] if needed. All vectors must be of the same length.
#' @param only_all_tested A [logical] to indicate that isolates must be tested for all antimicrobials. If `TRUE`, the result is `NA` for isolates with a missing result for any of the antimicrobials. If `FALSE` (default), a missing result only leads to `NA` if a result for the missing antimicrobial could have changed the result of the combination, see *Combination Therapy* below.
#' @param method Either `"most_susceptible"` (default) to return the most susceptible result, as for combination therapy, or `"most_resistant"` to return the most resistant result, as for resistance within a group of antimicrobials. See *Combination Therapy* below.
#' @param only_all_tested A [logical] to indicate that isolates must be tested for all antimicrobials. If `TRUE`, the result is `NA` for isolates with a missing result for any of the antimicrobials. If `FALSE` (default), a missing result only leads to `NA` if a result for the missing antimicrobial could have changed the result, see *Combination Therapy* below.
#' @param guideline Either `"EUCAST"` (default) or `"CLSI"`, to determine whether the 'I' category is considered susceptible. This only affects isolates with a missing result for any of the antimicrobials when `only_all_tested = FALSE`, see *Combination Therapy* below. The default can be changed with the `AMR_guideline` option, see [AMR-options].
#' @section Combination Therapy:
#' A combination of antimicrobials is considered as good as its most active antimicrobial: `"S"` is preferred over `"WT"`, and `"R"` over `"NWT"` and `"NS"`. The value `"NI"` (non-interpretable) is considered a missing result.
#' Results are ordered from susceptible to resistant: S (and WT), SDD, I, R (and NWT, NS). With `method = "most_susceptible"` (in [sir_combine()]), the most susceptible result of the antimicrobials is returned, and with `method = "most_resistant"`, the most resistant result. The value `"NI"` (non-interpretable) is considered a missing result.
#'
#' A missing result can only be ignored if the result of the combination is susceptible regardless of the missing result, which depends on the `only_all_tested` argument and on the guideline: under EUCAST, the 'I' category is considered susceptible (*susceptible, increased exposure*), and under CLSI, it is not.
#' A missing result can only be ignored if it cannot change the conclusion: a susceptible result for `"most_susceptible"`, and a non-susceptible result for `"most_resistant"`. Under EUCAST, the 'I' category is considered susceptible (*susceptible, increased exposure*), and under CLSI, it is not. With `only_all_tested = TRUE`, any missing result leads to `NA`.
#'
#' This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter):
#' This is an example for two antimicrobials, Drug A and Drug B, under EUCAST (the order of the antimicrobials does not matter):
#'
#' ```
#' -------------------------------------------------------------------------
#' Result of the combination
#' -----------------------------------------------------
#' Drug A Drug B only_all_tested = FALSE only_all_tested = TRUE
#' -------- -------- ---------------------------- ----------------------
#' S S, I, R S S
#' I I, R I I
#' R R R R
#' S <NA> S <NA>
#' I <NA> I (EUCAST), <NA> (CLSI) <NA>
#' R <NA> <NA> <NA>
#' <NA> <NA> <NA> <NA>
#' Result of method = Result of method =
#' "most_susceptible" "most_resistant"
#' ----------------------- -----------------------------
#' only_all_tested = only_all_tested =
#' Drug A Drug B FALSE TRUE FALSE TRUE
#' -------- -------- --------- --------- ----------- -------------
#' S S S S S S
#' S I S S I I
#' S R S S R R
#' I R I I R R
#' R R R R R R
#' S <NA> S <NA> <NA> <NA>
#' I <NA> I <NA> <NA> <NA>
#' R <NA> <NA> <NA> R <NA>
#' <NA> <NA> <NA> <NA> <NA> <NA>
#' -------------------------------------------------------------------------
#' ```
#'
#' The [`count_*()`][count()] and [`proportion_*()`][proportion()] functions, such as [susceptibility()] and [resistance()], apply exactly these rules when more than one variable is used: an isolate is considered tested if the result of the combination is not `NA`, and is then counted by the result of the combination. Consequently, [count_susceptible()] `+` [count_resistant()] `=` [count_all()], and [susceptibility()] `+` [resistance()] `= 1`, for both values of `only_all_tested`. The guideline is taken from their `guideline` argument if they have one, and otherwise from the `AMR_guideline` option.
#' Under CLSI, the combination of I with a missing result is `<NA>` for `"most_susceptible"` and I for `"most_resistant"`.
#'
#' In [antibiogram()] and [wisca()], the 'I' and 'SDD' categories are considered susceptible if `combine_SI = TRUE` (default), and the result of the combination is then reduced to S or R.
#' The [`count_*()`][count()] and [`proportion_*()`][proportion()] functions apply these rules when more than one variable is used. With `only_all_tested = FALSE` (default), the functions for susceptibility, such as [susceptibility()] and [count_susceptible()], count an isolate as susceptible if any of the antimicrobials is susceptible (`"most_susceptible"`), and the functions for resistance, such as [resistance()] and [count_resistant()], count an isolate as resistant if any of the antimicrobials is resistant (`"most_resistant"`). An isolate is considered tested if it has such a result, or if it was tested for all antimicrobials. Therefore, for combinations with `only_all_tested = FALSE`:
#'
#' ```
#' count_S() + count_I() + count_R() >= count_all()
#' proportion_S() + proportion_I() + proportion_R() >= 1
#' ```
#'
#' With `only_all_tested = TRUE`, all these functions count the result of the combination therapy (`"most_susceptible"`) of isolates tested for all antimicrobials, so that:
#'
#' ```
#' count_S() + count_I() + count_R() = count_all()
#' proportion_S() + proportion_I() + proportion_R() = 1
#' ```
#'
#' In [antibiogram()] and [wisca()], the result of the combination therapy (`"most_susceptible"`) is used, the 'I' and 'SDD' categories are considered susceptible if `combine_SI = TRUE` (default), and the result is then reduced to S or R.
#' @return A [`sir`] vector with the same length as the input.
#' @seealso [count()] and [proportion()] for counting and calculating susceptibility of (combinations of) antimicrobials, and [antibiogram()] for combination antibiograms.
#' @export
@@ -68,13 +90,19 @@
#' drug_a <- as.sir(c("S", "R", "R", "I", "I", NA, "R", "SDD"))
#' drug_b <- as.sir(c("R", "S", "R", "R", NA, NA, NA, "I"))
#'
#' # combination therapy: is at least one of them expected to work?
#' sir_combine(drug_a, drug_b)
#' sir_combine(drug_a, drug_b, guideline = "CLSI")
#' sir_combine(drug_a, drug_b, only_all_tested = TRUE)
#'
#' # resistance within a group: is resistance demonstrated to any of them?
#' sir_combine(drug_a, drug_b, method = "most_resistant")
#'
#' # the count and proportion functions use the same rules
#' susceptibility(drug_a, drug_b, minimum = 0)
#' susceptibility(sir_combine(drug_a, drug_b), minimum = 0)
#' resistance(drug_a, drug_b, minimum = 0)
#' resistance(sir_combine(drug_a, drug_b, method = "most_resistant"), minimum = 0)
#'
#' \donttest{
#' if (require("dplyr")) {
@@ -85,6 +113,12 @@
#' select(mo, TZP, GEN, TZP_GEN)
#' }
#' if (require("dplyr")) {
#' # resistance to third-generation cephalosporins
#' example_isolates %>%
#' mutate(cephalosporins_3rd = sir_combine(CAZ, CRO, method = "most_resistant")) %>%
#' count(cephalosporins_3rd)
#' }
#' if (require("dplyr")) {
#' # combine any number of antimicrobials
#' example_isolates %>%
#' mutate(any_aminoglycoside = sir_combine(GEN, TOB, AMK, KAN)) %>%
@@ -105,7 +139,8 @@
#' )
#' }
#' }
sir_combine <- function(..., only_all_tested = FALSE, guideline = getOption("AMR_guideline", "EUCAST")) {
sir_combine <- function(..., method = c("most_susceptible", "most_resistant"), only_all_tested = FALSE, guideline = getOption("AMR_guideline", "EUCAST")) {
method <- match.arg(method)
meet_criteria(only_all_tested, allow_class = "logical", has_length = 1)
meet_criteria(guideline, allow_class = "character", has_length = 1)
if (guideline %like% "EUCAST") {
@@ -129,13 +164,13 @@ sir_combine <- function(..., only_all_tested = FALSE, guideline = getOption("AMR
stop_if(length(unique(col_lengths)) > 1, "all vectors or columns must be of the same length, but they have lengths ", vector_and(sort(unique(col_lengths)), quotes = FALSE), ".")
cols <- lapply(cols, function(x) if (is.sir(x)) x else as.sir(x))
out <- sir_combine_engine(cols, S_values = get_susceptible_values(guideline), only_all_tested = only_all_tested)
out <- sir_combine_engine(cols, S_values = get_susceptible_values(guideline), only_all_tested = only_all_tested, method = method)
if (isFALSE(only_all_tested) && is.null(getOption("AMR_guideline")) && missing(guideline)) {
# only notify about the assumed guideline if it affected the result
any_missing <- Reduce(`|`, lapply(cols, function(x) is.na(x) | as.character(x) == "NI"))
if (any(any_missing & as.character(out) %in% "I") && message_not_thrown_before("sir_combine", "eucast_default", entire_session = TRUE)) {
message_("{.help [{.fun sir_combine}](AMR::sir_combine)} assumes the EUCAST guideline and thus considers the 'I' category susceptible, so a missing result does not change a combination with an 'I' result. Set the {.arg guideline} argument or the {.code AMR_guideline} option to either \"CLSI\" or \"EUCAST\", see {.topic [AMR-options](AMR::AMR-options)}.")
out_clsi <- sir_combine_engine(cols, S_values = get_susceptible_values("CLSI"), only_all_tested = only_all_tested, method = method)
if (!identical(out, out_clsi) && message_not_thrown_before("sir_combine", "eucast_default", entire_session = TRUE)) {
message_("{.help [{.fun sir_combine}](AMR::sir_combine)} assumes the EUCAST guideline and thus considers the 'I' category susceptible, which affected the result for 'I' results combined with a missing result. Set the {.arg guideline} argument or the {.code AMR_guideline} option to either \"CLSI\" or \"EUCAST\", see {.topic [AMR-options](AMR::AMR-options)}.")
message_("This message will be shown once per session.")
}
}
@@ -151,11 +186,12 @@ get_susceptible_values <- function(guideline) {
}
}
sir_combine_engine <- function(cols, S_values, only_all_tested = FALSE) {
# this is the engine for combination therapy, used by sir_combine(), sir_calc() and antibiogram()
sir_combine_engine <- function(cols, S_values, only_all_tested = FALSE, method = "most_susceptible") {
# this is the engine for combining SIR results, used by sir_combine(), sir_calc() and antibiogram()
# - cols: a list of vectors of equal length, with class 'sir' or with SIR values as character
# - S_values: the values considered susceptible, so that a missing result cannot change the result of the combination
# the order of preference: the first value is the best result, values with equal rank are resolved by this order
# - S_values: the values considered susceptible; all other values are considered non-susceptible
# - method: "most_susceptible" (combination therapy) or "most_resistant" (resistance within a group)
# the order of preference: values with equal rank are resolved by this order
preference <- c("S", "WT", "SDD", "I", "R", "NWT", "NS")
ranks <- c(1L, 1L, 2L, 3L, 4L, 4L, 4L)
cols <- lapply(cols, as.character)
@@ -164,18 +200,25 @@ sir_combine_engine <- function(cols, S_values, only_all_tested = FALSE) {
}
# 'NI' and NA get no rank, so they are missing results
col_ranks <- lapply(cols, function(x) ranks[match(x, preference)])
best <- do.call(pmin, c(col_ranks, list(na.rm = TRUE)))
out <- rep(NA_character_, length(best))
if (method == "most_susceptible") {
selected <- do.call(pmin, c(col_ranks, list(na.rm = TRUE)))
# a missing result cannot change a susceptible result
decisive_values <- S_values
} else {
selected <- do.call(pmax, c(col_ranks, list(na.rm = TRUE)))
# a missing result cannot change a non-susceptible result
decisive_values <- setdiff(preference, S_values)
}
out <- rep(NA_character_, length(selected))
for (i in seq_along(preference)) {
is_present <- Reduce(`|`, lapply(cols, function(x) x %in% preference[i]))
out[is.na(out) & best %in% ranks[i] & is_present] <- preference[i]
out[is.na(out) & selected %in% ranks[i] & is_present] <- preference[i]
}
any_missing <- Reduce(`|`, lapply(col_ranks, is.na))
if (isTRUE(only_all_tested)) {
out[any_missing] <- NA_character_
} else {
# a missing result could have been better, unless the combination is already susceptible
out[any_missing & !out %in% S_values] <- NA_character_
out[any_missing & !out %in% decisive_values] <- NA_character_
}
as_sir_structure(out)
}