mirror of
https://github.com/msberends/AMR.git
synced 2026-11-16 07:50:50 +01:00
(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:
1 parent
239c5a87a8
commit
bf12e3abe7
13 files changed
+322
-141
No files matched your search
+76
-33
@@ -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)
|
||||
}
|
||||
Reference in new issue
Block a user