mirror of
https://github.com/msberends/AMR.git
synced 2026-11-16 04:20:53 +01:00
Let aggregated analyses follow the guideline for the 'I' category in count_df(), proportion_df(), sir_df(), the plotting functions, antibiogram(), wisca(), and bug_drug_combinations(), deprecate combine_SI in favour of guideline, fix format() on bug_drug_combinations() counting I as resistant, and add a shared section 'Interpretation of SIR'
This commit is contained in:
1 parent
dbd95ffa46
commit
0efc8826c8
32 files changed
+511
-199
No files matched your search
+1
-1
@@ -41,7 +41,7 @@
|
||||
#' * `AMR_custom_ab` \cr A file location to an RDS file, to use custom antimicrobial drugs with this package. This is explained in [add_custom_antimicrobials()].
|
||||
#' * `AMR_custom_mo` \cr A file location to an RDS file, to use custom microorganisms with this package. This is explained in [add_custom_microorganisms()].
|
||||
#' * `AMR_eucastrules` \cr A [character] to set the default types of rules for [eucast_rules()] function, must be one or more of: `"breakpoints"`, `"expert"`, `"other"`, `"custom"`, `"all"`, and defaults to `c("breakpoints", "expert")`.
|
||||
#' * `AMR_guideline` \cr A [character] to set the default guideline used throughout the `AMR` package wherever a `guideline` argument is available. This option is used as the default in e.g. [as.sir()], [resistance()], [susceptibility()], [interpretive_rules()] and many plotting functions. **While unset**, the AMR package uses the latest implemented EUCAST guideline (currently `r AMR::clinical_breakpoints$guideline[1]`).
|
||||
#' * `AMR_guideline` \cr A [character] to set the default guideline used throughout the `AMR` package wherever a `guideline` argument is available. This option is used as the default in e.g. [as.sir()], [resistance()], [susceptibility()], [interpretive_rules()] and many plotting functions. **While unset**, the AMR package uses the latest implemented EUCAST guideline (currently `r AMR::clinical_breakpoints$guideline[1]`). In aggregated analyses, this option determines whether the 'I' category is considered susceptible (EUCAST) or resistant (CLSI), see section *Interpretation of SIR* in [as.sir()]; setting it also silences the message that EUCAST is assumed.
|
||||
#'
|
||||
#' - For [as.sir()], this determines which clinical breakpoint guideline is used to interpret MIC values and disk diffusion diameters. It can be either the guideline name (e.g., `"CLSI"` or `"EUCAST"`) or the name including a year (e.g., `"CLSI 2019"`). Supported guidelines are EUCAST `r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))` to `r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`, and CLSI `r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))` to `r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))`.
|
||||
#'
|
||||
|
||||
+44
-17
@@ -60,7 +60,8 @@
|
||||
#' @param col_mo Column name of the names or codes of the microorganisms (see [as.mo()]) - the default is the first column of class [`mo`]. Values will be coerced using [as.mo()].
|
||||
#' @param language Language to translate text, which defaults to the system language (see [get_AMR_locale()]).
|
||||
#' @param minimum The minimum allowed number of available (tested) isolates. Any isolate count lower than `minimum` will return `NA` with a warning. The default number of `30` isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see *Source*.
|
||||
#' @param combine_SI A [logical] to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is `TRUE`).
|
||||
#' @param combine_SI *(deprecated in favour of `guideline`)* A [logical]. If set, it takes precedence over `guideline`: `TRUE` considers S, SDD, and I susceptible, and `FALSE` only S.
|
||||
#' @param guideline A guideline name, `"EUCAST"` or `"CLSI"` (or any version thereof, e.g. `"CLSI 2025"`), to determine whether the 'I' category is considered susceptible (EUCAST) or resistant (CLSI). 'SDD' is always considered susceptible. The default is the package option [`AMR_guideline`][AMR-options], or `"EUCAST"` if it is not set. See section *Interpretation of SIR* below.
|
||||
#' @param sep A separating character for antimicrobial columns in combination antibiograms.
|
||||
#' @param sort_columns A [logical] to indicate whether the antimicrobial columns must be sorted on name.
|
||||
#' @param wisca A [logical] to indicate whether a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) must be generated (default is `FALSE`). This will use a Bayesian decision model to estimate regimen coverage probabilities using [Monte Carlo simulations](https://en.wikipedia.org/wiki/Monte_Carlo_method). Per \doi{10.1093/jac/dkv397}, susceptibility priors are \eqn{\beta(0.5, 0.5)} (Jeffreys) and intrinsically resistant pairs (based on [intrinsic_resistant]) use \eqn{\beta(1, 9999)}.
|
||||
@@ -137,7 +138,7 @@
|
||||
#'
|
||||
#' ### Inclusion in Combination Antibiograms
|
||||
#'
|
||||
#' For combination antibiograms, the results of the antimicrobials are combined using the same rules as [sir_combine()], see the section *Combination Therapy* below. Whether isolates must be tested for all antimicrobials can be set with the `only_all_tested` argument (default is `FALSE`). The 'I' and 'SDD' categories are considered susceptible if `combine_SI = TRUE` (default), which also determines whether a missing result can be ignored. To use a combination in other analyses as well, create a new variable with [sir_combine()].
|
||||
#' For combination antibiograms, the results of the antimicrobials are combined using the same rules as [sir_combine()], see the section *Combination Therapy* below. Whether isolates must be tested for all antimicrobials can be set with the `only_all_tested` argument (default is `FALSE`). Whether the 'I' category is considered susceptible follows the `guideline` argument, which also determines whether a missing result can be ignored. To use a combination in other analyses as well, create a new variable with [sir_combine()].
|
||||
#'
|
||||
#' ### Plotting
|
||||
#'
|
||||
@@ -159,6 +160,7 @@
|
||||
#'
|
||||
#' For the full mathematical derivation and worked examples, see the [WISCA vignette](https://amr-for-r.org/articles/WISCA.html).
|
||||
#' @inheritSection sir_combine Combination Therapy
|
||||
#' @inheritSection as.sir Interpretation of SIR
|
||||
#' @references
|
||||
#' * Hebert C *et al.* (2012). **Demonstration of the weighted-incidence syndromic combination antibiogram: an empiric prescribing decision aid.** *Infection Control & Hospital Epidemiology* 33(4):381-388; \doi{10.1086/664768}
|
||||
#' * Bielicki JA *et al.* (2016). **Selecting appropriate empirical antibiotic regimens for paediatric bloodstream infections: application of a Bayesian decision model to local and pooled antimicrobial resistance surveillance data.** *Journal of Antimicrobial Chemotherapy* 71(3):794-802; \doi{10.1093/jac/dkv397}
|
||||
@@ -312,7 +314,8 @@ wisca <- function(x,
|
||||
formatting_type = getOption("AMR_antibiogram_formatting_type", 14),
|
||||
col_mo = NULL,
|
||||
language = get_AMR_locale(),
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
sep = " + ",
|
||||
sort_columns = TRUE,
|
||||
simulations = 1000,
|
||||
@@ -321,6 +324,9 @@ wisca <- function(x,
|
||||
info = interactive(),
|
||||
parallel = FALSE,
|
||||
...) {
|
||||
if (missing(guideline) && missing(combine_SI)) {
|
||||
message_antibiogram_guideline_assumed(wisca = TRUE)
|
||||
}
|
||||
antibiogram(
|
||||
x = x,
|
||||
antimicrobials = antimicrobials,
|
||||
@@ -333,6 +339,7 @@ wisca <- function(x,
|
||||
col_mo = col_mo,
|
||||
language = language,
|
||||
combine_SI = combine_SI,
|
||||
guideline = guideline,
|
||||
sep = sep,
|
||||
sort_columns = sort_columns,
|
||||
wisca = TRUE,
|
||||
@@ -359,7 +366,8 @@ antibiogram <- function(x,
|
||||
col_mo = NULL,
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
sep = " + ",
|
||||
sort_columns = TRUE,
|
||||
wisca = FALSE,
|
||||
@@ -386,7 +394,8 @@ antibiogram.default <- function(x,
|
||||
col_mo = NULL,
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
sep = " + ",
|
||||
sort_columns = TRUE,
|
||||
wisca = FALSE,
|
||||
@@ -427,7 +436,18 @@ antibiogram.default <- function(x,
|
||||
meet_criteria(col_mo, allow_class = "character", has_length = 1, allow_NULL = TRUE, is_in = colnames(x))
|
||||
language <- validate_language(language)
|
||||
meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
fn <- ifelse(isTRUE(wisca), "wisca", "antibiogram")
|
||||
if (!missing(combine_SI)) {
|
||||
# deprecated argument, if set it must be followed literally, regardless of the guideline
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
deprecation_warning("combine_SI", "guideline", fn = fn, is_argument = TRUE, extra_msg = "As long as `combine_SI` is set, it takes precedence over `guideline`. Use `guideline = \"EUCAST\"` to consider S, SDD, and I susceptible, or `guideline = \"CLSI\"` to consider S and SDD susceptible.")
|
||||
S_values <- c("S", "WT", if (isTRUE(combine_SI)) c("SDD", "I"))
|
||||
} else {
|
||||
if (missing(guideline)) {
|
||||
message_antibiogram_guideline_assumed(wisca = wisca)
|
||||
}
|
||||
S_values <- get_susceptible_values(validate_sir_guideline(guideline, fn = fn))
|
||||
}
|
||||
meet_criteria(sep, allow_class = "character", has_length = 1)
|
||||
meet_criteria(sort_columns, allow_class = "logical", has_length = 1)
|
||||
meet_criteria(simulations, allow_class = c("numeric", "integer"), has_length = 1, is_finite = TRUE, is_positive = TRUE)
|
||||
@@ -604,10 +624,6 @@ antibiogram.default <- function(x,
|
||||
next
|
||||
} else {
|
||||
# determine whether this new column should contain S, I, R, or NA
|
||||
S_values <- c("S", "WT")
|
||||
if (isTRUE(combine_SI)) {
|
||||
S_values <- c(S_values, "SDD", "I")
|
||||
}
|
||||
# same rules as sir_combine(), after which the result is reduced to S or R
|
||||
combined <- as.character(sir_combine_engine(as.list(x[, abx, drop = FALSE]), S_values = S_values, only_all_tested = only_all_tested))
|
||||
combined[!is.na(combined)] <- ifelse(combined[!is.na(combined)] %in% S_values, "S", "R")
|
||||
@@ -643,7 +659,8 @@ antibiogram.default <- function(x,
|
||||
bug_drug_combinations(
|
||||
col_mo = ".mo",
|
||||
FUN = function(x) x,
|
||||
include_n_rows = TRUE
|
||||
include_n_rows = TRUE,
|
||||
guideline = NULL # only counts are used here, S_values determines what is susceptible
|
||||
)
|
||||
colnames(out)[colnames(out) == "total"] <- "n_tested"
|
||||
colnames(out)[colnames(out) == "total_rows"] <- "n_total"
|
||||
@@ -652,10 +669,7 @@ antibiogram.default <- function(x,
|
||||
|
||||
counts <- out
|
||||
|
||||
out$n_susceptible <- out$S + out$WT
|
||||
if (isTRUE(combine_SI)) {
|
||||
out$n_susceptible <- out$n_susceptible + out$I + out$SDD
|
||||
}
|
||||
out$n_susceptible <- rowSums(out[, S_values, drop = FALSE])
|
||||
if (all(out$n_tested < minimum, na.rm = TRUE) && wisca == FALSE) {
|
||||
warning_("All combinations had less than {.arg minimum} = ", minimum, " results, returning an empty antibiogram")
|
||||
return(as_original_data_class(data.frame(), class(x), extra_class = "antibiogram"))
|
||||
@@ -1109,7 +1123,7 @@ antibiogram.default <- function(x,
|
||||
out <- structure(as_original_data_class(new_df, class(x), extra_class = "antibiogram"),
|
||||
has_syndromic_group = has_syndromic_group,
|
||||
antibiogram_groups = attr(x, "antibiogram_groups", exact = TRUE),
|
||||
combine_SI = combine_SI,
|
||||
combine_SI = "I" %in% S_values,
|
||||
wisca = wisca,
|
||||
conf_interval = conf_interval,
|
||||
simulations = if (isFALSE(wisca)) NULL else simulations,
|
||||
@@ -1124,6 +1138,14 @@ antibiogram.default <- function(x,
|
||||
out
|
||||
}
|
||||
|
||||
message_antibiogram_guideline_assumed <- function(wisca) {
|
||||
term <- ifelse(isTRUE(wisca), "covered", "susceptible")
|
||||
message_guideline_assumed(
|
||||
ifelse(isTRUE(wisca), "wisca", "antibiogram"),
|
||||
txt = paste0(", so S, SDD, and I count as ", term, ". Use {.code guideline = \"CLSI\"} to only count S and SDD as ", term, ".")
|
||||
)
|
||||
}
|
||||
|
||||
#' @method antibiogram grouped_df
|
||||
#' @export
|
||||
antibiogram.grouped_df <- function(x,
|
||||
@@ -1138,7 +1160,8 @@ antibiogram.grouped_df <- function(x,
|
||||
col_mo = NULL,
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
sep = " + ",
|
||||
sort_columns = TRUE,
|
||||
wisca = FALSE,
|
||||
@@ -1151,6 +1174,9 @@ antibiogram.grouped_df <- function(x,
|
||||
stop_ifnot(is.null(mo_transform), "{.arg mo_transform} must not be set if creating an antibiogram using a grouped tibble. The groups will become the variables over which the antimicrobials are calculated, which could include the pathogen information (though not necessary). Nonetheless, this makes {.arg mo_transform} redundant.", call = FALSE)
|
||||
stop_ifnot(is.null(syndromic_group), "{.arg syndromic_group} must not be set if creating an antibiogram using a grouped tibble. The groups will become the variables over which the antimicrobials are calculated, making {.arg syndromic_group} redundant.", call = FALSE)
|
||||
|
||||
if (missing(guideline) && missing(combine_SI)) {
|
||||
message_antibiogram_guideline_assumed(wisca = wisca)
|
||||
}
|
||||
groups <- attributes(x)$groups
|
||||
group_cols <- intersect(colnames(groups), colnames(x))
|
||||
# paste group together, will be split later in antibiogram.default()
|
||||
@@ -1170,6 +1196,7 @@ antibiogram.grouped_df <- function(x,
|
||||
language = language,
|
||||
minimum = minimum,
|
||||
combine_SI = combine_SI,
|
||||
guideline = guideline,
|
||||
sep = sep,
|
||||
sort_columns = sort_columns,
|
||||
wisca = wisca,
|
||||
|
||||
@@ -31,7 +31,8 @@
|
||||
#'
|
||||
#' Determine antimicrobial resistance (AMR) of all bug-drug combinations in your data set where at least 30 (default) isolates are available per species. Use [format()] on the result to prettify it to a publishable/printable format, see *Examples*.
|
||||
#' @inheritParams eucast_rules
|
||||
#' @param combine_SI A [logical] to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is `TRUE`.
|
||||
#' @param guideline A guideline name, `"EUCAST"` or `"CLSI"` (or any version thereof, e.g. `"CLSI 2025"`), to determine whether the 'I' category is considered susceptible (EUCAST) or resistant (CLSI) when calculating resistance with [format()]. The default is the package option [`AMR_guideline`][AMR-options], or `"EUCAST"` if it is not set. In [bug_drug_combinations()], this can also be `NULL` or `FALSE`, after which [format()] requires its own `guideline` to be set. In [format()], the default is the guideline used in [bug_drug_combinations()], which can be overridden by setting it. See section *Interpretation of SIR* below.
|
||||
#' @param combine_SI *(deprecated in favour of `guideline`)* A [logical]. If set, it takes precedence over `guideline`: `TRUE` bases resistance on R only, and `FALSE` on SDD, I, and R.
|
||||
#' @param add_ab_group A [logical] to indicate where the group of the antimicrobials must be included as a first column.
|
||||
#' @param remove_intrinsic_resistant [logical] to indicate that rows and columns with 100% resistance for all tested antimicrobials must be removed from the table.
|
||||
#' @param FUN The function to call on the `mo` column to transform the microorganism codes - the default is [mo_shortname()].
|
||||
@@ -40,10 +41,11 @@
|
||||
#' @param ... Arguments passed on to `FUN`.
|
||||
#' @inheritParams sir_df
|
||||
#' @inheritParams base::formatC
|
||||
#' @details The function [format()] calculates the resistance per bug-drug combination and returns a table ready for reporting/publishing. Use `combine_SI = TRUE` (default) to test R vs. S+I and `combine_SI = FALSE` to test R+I vs. S. This table can also directly be used in R Markdown / Quarto without the need for e.g. [knitr::kable()].
|
||||
#' @inheritSection as.sir Interpretation of SIR
|
||||
#' @details The function [format()] calculates the resistance per bug-drug combination and returns a table ready for reporting/publishing. Following the `guideline`, resistance is based on R (EUCAST) or on I and R (CLSI), see section *Interpretation of SIR* below. This table can also directly be used in R Markdown / Quarto without the need for e.g. [knitr::kable()].
|
||||
#' @export
|
||||
#' @rdname bug_drug_combinations
|
||||
#' @return The function [bug_drug_combinations()] returns a [data.frame] with columns "mo", "ab", "S", "SDD", "I", "R", "WT, "NWT", and "total".
|
||||
#' @return The function [bug_drug_combinations()] returns a [data.frame] with columns "mo", "ab", "S", "SDD", "I", "R", "NI", "WT", "NWT", "NS", and "total".
|
||||
#' @examples
|
||||
#' # example_isolates is a data set available in the AMR package.
|
||||
#' # run ?example_isolates for more info.
|
||||
@@ -72,8 +74,11 @@ bug_drug_combinations <- function(x,
|
||||
col_mo = NULL,
|
||||
FUN = mo_shortname,
|
||||
include_n_rows = FALSE,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
...) {
|
||||
meet_criteria(x, allow_class = "data.frame")
|
||||
guideline_assumed <- missing(guideline)
|
||||
guideline <- validate_sir_guideline(guideline, fn = "bug_drug_combinations", allow_none = TRUE)
|
||||
x <- ascertain_sir_classes(x, "x")
|
||||
meet_criteria(col_mo, allow_class = "character", is_in = colnames(x), has_length = 1, allow_NULL = TRUE)
|
||||
meet_criteria(FUN, allow_class = "function", has_length = 1)
|
||||
@@ -202,6 +207,9 @@ bug_drug_combinations <- function(x,
|
||||
out <- out %pm>% pm_arrange(mo, ab)
|
||||
class(out) <- c("bug_drug_combinations", if (data_has_groups) "grouped" else NULL, class(out))
|
||||
rownames(out) <- NULL
|
||||
# the guideline is used by format() to calculate resistance, FALSE means that 'I' must not be merged
|
||||
attr(out, "guideline") <- if (is.null(guideline)) FALSE else guideline
|
||||
attr(out, "guideline_assumed") <- guideline_assumed
|
||||
out
|
||||
}
|
||||
|
||||
@@ -212,7 +220,8 @@ format.bug_drug_combinations <- function(x,
|
||||
translate_ab = "name (ab, atc)",
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = attr(x, "guideline"),
|
||||
add_ab_group = TRUE,
|
||||
remove_intrinsic_resistant = FALSE,
|
||||
decimal.mark = getOption("OutDec"),
|
||||
@@ -222,7 +231,26 @@ format.bug_drug_combinations <- function(x,
|
||||
meet_criteria(translate_ab, allow_class = c("character", "logical"), has_length = 1, allow_NA = TRUE)
|
||||
language <- validate_language(language)
|
||||
meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
if (!missing(combine_SI)) {
|
||||
# deprecated argument, if set it must be followed literally, regardless of the guideline
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
deprecation_warning("combine_SI", "guideline", fn = "format", is_argument = TRUE, extra_msg = "As long as `combine_SI` is set, it takes precedence over `guideline`. Use `guideline = \"EUCAST\"` to base resistance on R only, or `guideline = \"CLSI\"` to base resistance on I and R.")
|
||||
R_values <- c("R", "NWT", "NS", if (isFALSE(combine_SI)) c("SDD", "I"))
|
||||
} else {
|
||||
guideline_assumed <- FALSE
|
||||
if (missing(guideline)) {
|
||||
guideline_assumed <- !isFALSE(attr(x, "guideline_assumed"))
|
||||
if (is.null(guideline)) {
|
||||
# e.g., created with an older version of this package
|
||||
guideline <- getOption("AMR_guideline", "EUCAST")
|
||||
}
|
||||
}
|
||||
guideline <- validate_sir_guideline(guideline, fn = "bug_drug_combinations")
|
||||
if (isTRUE(guideline_assumed)) {
|
||||
message_guideline_assumed("bug_drug_combinations", txt = " when calculating resistance in {.fun format} (R vs. S+SDD+I). Use {.code guideline = \"CLSI\"} for I+R vs. S+SDD.")
|
||||
}
|
||||
R_values <- c("R", "NWT", "NS", if (identical(guideline, "CLSI")) "I")
|
||||
}
|
||||
meet_criteria(add_ab_group, allow_class = "logical", has_length = 1)
|
||||
meet_criteria(remove_intrinsic_resistant, allow_class = "logical", has_length = 1)
|
||||
meet_criteria(decimal.mark, allow_class = "character", has_length = 1)
|
||||
@@ -265,10 +293,7 @@ format.bug_drug_combinations <- function(x,
|
||||
x <- subset(x, R != total)
|
||||
}
|
||||
|
||||
x$isolates <- x$R + x$NWT
|
||||
if (combine_SI == TRUE) {
|
||||
x$isolates <- x$isolates + x$I + x$SDD
|
||||
}
|
||||
x$isolates <- rowSums(x[, R_values, drop = FALSE])
|
||||
|
||||
give_ab_name <- function(ab, format, language) {
|
||||
format <- tolower(format)
|
||||
|
||||
@@ -33,11 +33,6 @@
|
||||
#'
|
||||
#' [count_resistant()] should be used to count resistant isolates, [count_susceptible()] should be used to count susceptible isolates.
|
||||
#' @param ... One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with [as.sir()] if needed.
|
||||
#' @param guideline Either `"EUCAST"` (default) or `"CLSI"`. With EUCAST, the 'I' category will be considered as susceptible (see [EUCAST website](https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/)), but with with CLSI, it will be considered resistant. Therefore:
|
||||
#' * EUCAST: [count_susceptible()] \eqn{= N_{S} + N_{I}}, [count_resistant()] \eqn{= N_{R}}
|
||||
#' * CLSI: [count_susceptible()] \eqn{= N_{S} + N_{SDD}}, [count_resistant()] \eqn{= N_{I} + N_{R}}
|
||||
#'
|
||||
#' You can also use e.g. [count_R()] or [count_S()] instead, to be explicit.
|
||||
#' @inheritParams proportion
|
||||
#' @inheritSection as.sir Interpretation of SIR
|
||||
#' @details These functions are meant to count isolates. Use the [resistance()]/[susceptibility()] functions to calculate microbial resistance/susceptibility.
|
||||
@@ -126,16 +121,10 @@ count_resistant <- function(...,
|
||||
only_all_tested = FALSE,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
# other arguments for meet_criteria are handled by sir_calc()
|
||||
if (guideline %like% "EUCAST") {
|
||||
guideline <- "EUCAST"
|
||||
} else if (guideline %like% "CLSI") {
|
||||
guideline <- "CLSI"
|
||||
}
|
||||
meet_criteria(guideline, allow_class = "character", is_in = c("EUCAST", "CLSI"), has_length = 1)
|
||||
if (is.null(getOption("AMR_guideline")) && missing(guideline) && message_not_thrown_before("count_resistant", "eucast_default", entire_session = TRUE)) {
|
||||
message_("{.help [{.fun count_resistant}](AMR::count_resistant)} assumes the EUCAST guideline and thus considers the 'I' category susceptible. 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.")
|
||||
if (missing(guideline)) {
|
||||
message_guideline_assumed("count_resistant", txt = ". Use {.code guideline = \"CLSI\"} to consider it resistant.")
|
||||
}
|
||||
guideline <- validate_sir_guideline(guideline, fn = "count_resistant")
|
||||
tryCatch(
|
||||
sir_calc(...,
|
||||
ab_result = c(
|
||||
@@ -156,16 +145,10 @@ count_susceptible <- function(...,
|
||||
only_all_tested = FALSE,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
# other arguments for meet_criteria are handled by sir_calc()
|
||||
if (guideline %like% "EUCAST") {
|
||||
guideline <- "EUCAST"
|
||||
} else if (guideline %like% "CLSI") {
|
||||
guideline <- "CLSI"
|
||||
}
|
||||
meet_criteria(guideline, allow_class = "character", is_in = c("EUCAST", "CLSI"), has_length = 1)
|
||||
if (is.null(getOption("AMR_guideline")) && missing(guideline) && message_not_thrown_before("count_susceptible", "eucast_default", entire_session = TRUE)) {
|
||||
message_("{.help [{.fun count_susceptible}](AMR::count_susceptible)} assumes the EUCAST guideline and thus considers the 'I' category susceptible. 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.")
|
||||
if (missing(guideline)) {
|
||||
message_guideline_assumed("count_susceptible", txt = ". Use {.code guideline = \"CLSI\"} to consider it resistant.")
|
||||
}
|
||||
guideline <- validate_sir_guideline(guideline, fn = "count_susceptible")
|
||||
tryCatch(
|
||||
sir_calc(...,
|
||||
ab_result = c(
|
||||
@@ -267,15 +250,15 @@ n_sir <- count_all
|
||||
count_df <- function(data,
|
||||
translate_ab = "name",
|
||||
language = get_AMR_locale(),
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
guideline <- get_aggregation_guideline(guideline, missing(guideline), combine_SI, missing(combine_SI), fn = "count_df")
|
||||
tryCatch(
|
||||
sir_calc_df(
|
||||
type = "count",
|
||||
data = data,
|
||||
translate_ab = translate_ab,
|
||||
language = language,
|
||||
combine_SI = combine_SI,
|
||||
confidence_level = 0.95, # doesn't matter, will be removed
|
||||
guideline = guideline
|
||||
),
|
||||
|
||||
+6
-7
@@ -49,6 +49,7 @@
|
||||
#' @param x.title Text to show as x axis description.
|
||||
#' @param y.title Text to show as y axis description.
|
||||
#' @param ... Other arguments passed on to [geom_sir()] or, in case of [scale_sir_colours()], named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See *Examples*.
|
||||
#' @inheritSection as.sir Interpretation of SIR
|
||||
#' @details At default, the names of antimicrobials will be shown on the plots using [ab_name()]. This can be set with the `translate_ab` argument. See [count_df()].
|
||||
#'
|
||||
#' [geom_sir()] will take any variable from the data that has an [`sir`] class (created with [as.sir()]) using [sir_df()] and will plot bars with the percentage S, I, and R. The default behaviour is to have the bars stacked and to have the different antimicrobials on the x axis.
|
||||
@@ -171,7 +172,7 @@ ggplot_sir <- function(data,
|
||||
breaks = seq(0, 1, 0.1),
|
||||
limits = NULL,
|
||||
translate_ab = "name",
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
minimum = 30,
|
||||
language = get_AMR_locale(),
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
@@ -203,7 +204,7 @@ ggplot_sir <- function(data,
|
||||
meet_criteria(breaks, allow_class = c("numeric", "integer"))
|
||||
meet_criteria(limits, allow_class = c("numeric", "integer"), has_length = 2, allow_NULL = TRUE, allow_NA = TRUE)
|
||||
meet_criteria(translate_ab, allow_class = c("character", "logical"), has_length = 1, allow_NA = TRUE)
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
guideline <- get_aggregation_guideline(guideline, missing(guideline), combine_SI, missing(combine_SI), fn = "ggplot_sir")
|
||||
meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
|
||||
language <- validate_language(language)
|
||||
meet_criteria(nrow, allow_class = c("numeric", "integer"), has_length = 1, allow_NULL = TRUE, is_positive = TRUE, is_finite = TRUE)
|
||||
@@ -243,7 +244,7 @@ ggplot_sir <- function(data,
|
||||
geom_sir(
|
||||
position = position, x = x, fill = fill, translate_ab = translate_ab,
|
||||
minimum = minimum, language = language,
|
||||
combine_SI = combine_SI, guideline = guideline, ...
|
||||
guideline = guideline, ...
|
||||
) +
|
||||
theme_sir()
|
||||
|
||||
@@ -263,7 +264,6 @@ ggplot_sir <- function(data,
|
||||
translate_ab = translate_ab,
|
||||
minimum = minimum,
|
||||
language = language,
|
||||
combine_SI = combine_SI,
|
||||
guideline = guideline,
|
||||
datalabels.size = datalabels.size,
|
||||
datalabels.colour = datalabels.colour
|
||||
@@ -293,7 +293,7 @@ geom_sir <- function(position = NULL,
|
||||
translate_ab = "name",
|
||||
minimum = 30,
|
||||
language = get_AMR_locale(),
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
...) {
|
||||
x <- x[1]
|
||||
@@ -305,7 +305,7 @@ geom_sir <- function(position = NULL,
|
||||
meet_criteria(translate_ab, allow_class = c("character", "logical"), has_length = 1, allow_NA = TRUE)
|
||||
meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
|
||||
language <- validate_language(language)
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
guideline <- get_aggregation_guideline(guideline, missing(guideline), combine_SI, missing(combine_SI), fn = "geom_sir")
|
||||
|
||||
y <- "value"
|
||||
if (missing(position) || is.null(position)) {
|
||||
@@ -337,7 +337,6 @@ geom_sir <- function(position = NULL,
|
||||
translate_ab = translate_ab,
|
||||
language = language,
|
||||
minimum = minimum,
|
||||
combine_SI = combine_SI,
|
||||
guideline = guideline
|
||||
)
|
||||
},
|
||||
|
||||
@@ -40,7 +40,7 @@
|
||||
#' @param vanB [logical] values, or a column name containing logical values, indicating the presence of a *vanB* gene (or production of its proteins).
|
||||
#' @inheritParams eucast_rules
|
||||
#' @param pct_required_classes Minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for *S. aureus*. Setting this `pct_required_classes` argument to `0.5` (default) means that for every *S. aureus* isolate at least 8 different classes must be available. Any lower number of available classes will return `NA` for that isolate.
|
||||
#' @param combine_SI A [logical] to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the [mdro()] function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using `combine_SI = FALSE`, resistance is considered when isolates are R or I.
|
||||
#' @param combine_SI A [logical] to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the [mdro()] function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using `combine_SI = FALSE`, resistance is considered when isolates are R or I. In a future version, the handling of 'I' will follow the selected MDRO guideline ([#323](https://github.com/msberends/AMR/issues/323)).
|
||||
#' @param verbose A [logical] to turn Verbose mode on and off (default is off). In Verbose mode, the function returns a data set with the MDRO results in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not.
|
||||
#' @param infer_from_combinations A [logical] to indicate whether resistance for a missing base beta-lactam drug should be inferred from an available drug+inhibitor combination (e.g., piperacillin from piperacillin/tazobactam). The clinical basis is that resistance in a combination always implies resistance in the base drug, since the enzyme inhibitor provides no benefit when the organism is truly resistant. Only resistance is inferred; susceptibility in a combination does **not** imply susceptibility in the base drug (the inhibitor may be responsible). Defaults to `TRUE`.
|
||||
#' @details
|
||||
|
||||
+3
-4
@@ -1546,14 +1546,14 @@ theme_sir <- function() {
|
||||
)
|
||||
}
|
||||
|
||||
#' @rdname plot
|
||||
#' @rdname ggplot_sir
|
||||
#' @export
|
||||
labels_sir_count <- function(position = NULL,
|
||||
x = "antibiotic",
|
||||
translate_ab = "name",
|
||||
minimum = 30,
|
||||
language = get_AMR_locale(),
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
guideline = getOption("AMR_guideline", "EUCAST"),
|
||||
datalabels.size = 3,
|
||||
datalabels.colour = "grey15") {
|
||||
@@ -1563,7 +1563,7 @@ labels_sir_count <- function(position = NULL,
|
||||
meet_criteria(translate_ab, allow_class = c("character", "logical"), has_length = 1, allow_NA = TRUE)
|
||||
meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
|
||||
language <- validate_language(language)
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
guideline <- get_aggregation_guideline(guideline, missing(guideline), combine_SI, missing(combine_SI), fn = "labels_sir_count")
|
||||
meet_criteria(datalabels.size, allow_class = c("numeric", "integer"), has_length = 1, is_positive = TRUE, is_finite = TRUE)
|
||||
meet_criteria(datalabels.colour, allow_class = "character", has_length = 1)
|
||||
|
||||
@@ -1586,7 +1586,6 @@ labels_sir_count <- function(position = NULL,
|
||||
transformed <- sir_df(
|
||||
data = x,
|
||||
translate_ab = translate_ab,
|
||||
combine_SI = combine_SI,
|
||||
minimum = minimum,
|
||||
language = language,
|
||||
guideline = guideline
|
||||
|
||||
+10
-26
@@ -38,13 +38,9 @@
|
||||
#' @param only_all_tested (for combination therapies, i.e. using more than one variable for `...`): a [logical] to indicate that isolates must be tested for all antimicrobials, see section *Combination Therapy* below. Use [sir_combine()] to create a new variable for a combination therapy.
|
||||
#' @param data A [data.frame] containing columns with class [`sir`] (see [as.sir()]).
|
||||
#' @param translate_ab A column name of the [antimicrobials] data set to translate the antibiotic abbreviations to, using [ab_property()].
|
||||
#' @param guideline Either `"EUCAST"` (default) or `"CLSI"`. With EUCAST, the 'I' category will be considered as susceptible (see [EUCAST website](https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/)), but with with CLSI, it will be considered resistant. Therefore:
|
||||
#' * EUCAST: [susceptibility()] \eqn{= \%S + \%I}, [resistance()] \eqn{= \%R}
|
||||
#' * CLSI: [susceptibility()] \eqn{= \%S + \%SDD}, [resistance()] \eqn{= \%I + \%R}
|
||||
#'
|
||||
#' You can also use e.g. [proportion_R()] or [proportion_S()] instead, to be explicit. For [proportion_df()], [count_df()], and [sir_df()], the guideline determines how 'I' is merged when `combine_SI = TRUE`.
|
||||
#' @param guideline A guideline name, `"EUCAST"` or `"CLSI"` (or any version thereof, e.g. `"CLSI 2025"`), to determine whether the 'I' category is considered susceptible (EUCAST) or resistant (CLSI). The default is the package option [`AMR_guideline`][AMR-options], or `"EUCAST"` if it is not set. For functions that return results per category, i.e., [count_df()], [proportion_df()], [sir_df()], [ggplot_sir()], [geom_sir()], and [labels_sir_count()], this can also be `NULL` or `FALSE` to keep S, I, and R separate. See section *Interpretation of SIR* below.
|
||||
#' @inheritParams ab_property
|
||||
#' @param combine_SI A [logical] to indicate whether the 'I' category must be merged with another category, so the output only consists of susceptible vs. resistant - the default is `TRUE`. Following the `guideline` argument, the output then consists of `"SI"` (S+SDD+I) vs. `"R"` with EUCAST, and of `"S"` (S+SDD) vs. `"IR"` (I+R) with CLSI.
|
||||
#' @param combine_SI *(deprecated in favour of `guideline`)* A [logical]. If set, it takes precedence over `guideline`: `TRUE` merges S, SDD, and I into `"SI"` vs. `"R"`, and `FALSE` keeps S, I, and R separate.
|
||||
#' @param ab_result Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R".
|
||||
#' @param confidence_level The confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using [binom.test()], i.e., the Clopper-Pearson method.
|
||||
#' @param side The side of the confidence interval to return. The default is `"both"` for a length 2 vector, but can also be (abbreviated as) `"min"`/`"left"`/`"lower"`/`"less"` or `"max"`/`"right"`/`"higher"`/`"greater"`.
|
||||
@@ -199,16 +195,10 @@ resistance <- function(...,
|
||||
only_all_tested = FALSE,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
# other arguments for meet_criteria are handled by sir_calc()
|
||||
if (guideline %like% "EUCAST") {
|
||||
guideline <- "EUCAST"
|
||||
} else if (guideline %like% "CLSI") {
|
||||
guideline <- "CLSI"
|
||||
}
|
||||
meet_criteria(guideline, allow_class = "character", is_in = c("EUCAST", "CLSI"), has_length = 1)
|
||||
if (is.null(getOption("AMR_guideline")) && missing(guideline) && message_not_thrown_before("resistance", "eucast_default", entire_session = TRUE)) {
|
||||
message_("{.help [{.fun resistance}](AMR::resistance)} assumes the EUCAST guideline and thus considers the 'I' category susceptible. 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.")
|
||||
if (missing(guideline)) {
|
||||
message_guideline_assumed("resistance", txt = ". Use {.code guideline = \"CLSI\"} to consider it resistant.")
|
||||
}
|
||||
guideline <- validate_sir_guideline(guideline, fn = "resistance")
|
||||
tryCatch(
|
||||
sir_calc(...,
|
||||
ab_result = c(
|
||||
@@ -233,16 +223,10 @@ susceptibility <- function(...,
|
||||
only_all_tested = FALSE,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
# other arguments for meet_criteria are handled by sir_calc()
|
||||
if (guideline %like% "EUCAST") {
|
||||
guideline <- "EUCAST"
|
||||
} else if (guideline %like% "CLSI") {
|
||||
guideline <- "CLSI"
|
||||
}
|
||||
meet_criteria(guideline, allow_class = "character", is_in = c("EUCAST", "CLSI"), has_length = 1)
|
||||
if (is.null(getOption("AMR_guideline")) && missing(guideline) && message_not_thrown_before("susceptibility", "eucast_default", entire_session = TRUE)) {
|
||||
message_("{.help [{.fun susceptibility}](AMR::susceptibility)} assumes the EUCAST guideline and thus considers the 'I' category susceptible. 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.")
|
||||
if (missing(guideline)) {
|
||||
message_guideline_assumed("susceptibility", txt = ". Use {.code guideline = \"CLSI\"} to consider it resistant.")
|
||||
}
|
||||
guideline <- validate_sir_guideline(guideline, fn = "susceptibility")
|
||||
tryCatch(
|
||||
sir_calc(...,
|
||||
ab_result = c(
|
||||
@@ -430,9 +414,10 @@ proportion_df <- function(data,
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
as_percent = FALSE,
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
confidence_level = 0.95,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
guideline <- get_aggregation_guideline(guideline, missing(guideline), combine_SI, missing(combine_SI), fn = "proportion_df")
|
||||
tryCatch(
|
||||
sir_calc_df(
|
||||
type = "proportion",
|
||||
@@ -441,7 +426,6 @@ proportion_df <- function(data,
|
||||
language = language,
|
||||
minimum = minimum,
|
||||
as_percent = as_percent,
|
||||
combine_SI = combine_SI,
|
||||
confidence_level = confidence_level,
|
||||
guideline = guideline
|
||||
),
|
||||
|
||||
@@ -173,7 +173,25 @@ VALID_SIR_LEVELS <- c("S", "SDD", "I", "R", "NI", "WT", "NWT", "NS")
|
||||
#' @section Interpretation of SIR:
|
||||
#' In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R (<https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/>).
|
||||
#'
|
||||
#' This AMR package follows insight; use [susceptibility()] (equal to [proportion_SI()]) to determine antimicrobial susceptibility and [count_susceptible()] (equal to [count_SI()]) to count susceptible isolates.
|
||||
#' In aggregated analyses, such as proportions, counts, antibiograms, and plots, the 'I' category must be considered either susceptible or resistant. In epidemiological AMR data analysis, this follows the guideline: EUCAST considers 'I' susceptible, while CLSI considers 'I' resistant. The dose-dependent susceptibility of CLSI ('SDD') is always considered susceptible, as it equals what EUCAST defines as 'I'. All functions with a `guideline` argument for this purpose use these categories:
|
||||
#'
|
||||
#' | `guideline` | Susceptible | Resistant |
|
||||
#' |---|---|---|
|
||||
#' | `"EUCAST"` | S, SDD, I, WT | R, NWT, NS |
|
||||
#' | `"CLSI"` | S, SDD, WT | I, R, NWT, NS |
|
||||
#'
|
||||
#' The values 'WT' (wild type) and 'NWT' (non-wild type) result from epidemiological cut-off values (ECOFFs) instead of clinical breakpoints. Since they are no clinical categories, 'WT' is always considered susceptible and 'NWT' always resistant, regardless of the guideline. The value 'NS' (non-susceptible) is always considered resistant, and 'NI' (non-interpretable) is always considered a missing result.
|
||||
#'
|
||||
#' The `guideline` argument can be:
|
||||
#'
|
||||
#' * **Left unset**, to use the package option [`AMR_guideline`][AMR-options], or `"EUCAST"` if this option is not set. In the latter case, a message is shown once per session (but not in R Markdown or Quarto documents); set the option to silence it.
|
||||
#' * **`"EUCAST"`**, or any EUCAST version such as `"EUCAST 2025"`, to consider 'I' susceptible, e.g., to return `"SI"` vs. `"R"` in [proportion_df()].
|
||||
#' * **`"CLSI"`**, or any CLSI version such as `"CLSI 2025"`, to consider 'I' resistant, e.g., to return `"S"` vs. `"IR"` in [proportion_df()].
|
||||
#' * **`NULL` or `FALSE`**, to keep S, I, and R separate. This is only possible in functions that return results per category: [count_df()], [proportion_df()], [sir_df()], [ggplot_sir()], [geom_sir()], [labels_sir_count()], and [bug_drug_combinations()]. Functions that return a single proportion or count, such as [susceptibility()], [count_resistant()], [antibiogram()], [wisca()], and [format()] on the result of [bug_drug_combinations()], require 'I' to be considered either susceptible or resistant, and return an error.
|
||||
#'
|
||||
#' Use [susceptibility()] and [resistance()] (or [count_susceptible()] and [count_resistant()]) to follow the guideline, or e.g. [proportion_SI()] and [proportion_R()] to be explicit regardless of the guideline.
|
||||
#'
|
||||
#' The `combine_SI` argument of the functions that return results per category, [antibiogram()], and [wisca()] is deprecated in favour of `guideline`. If set, it is followed literally and takes precedence over `guideline`.
|
||||
#' @return Ordered [factor] with new class `sir`
|
||||
#' @aliases sir
|
||||
#' @export
|
||||
|
||||
+53
-11
@@ -35,6 +35,55 @@ dots2vars <- function(...) {
|
||||
paste0(dots[dots != "."], collapse = "+")
|
||||
}
|
||||
|
||||
validate_sir_guideline <- function(guideline, fn, allow_none = FALSE) {
|
||||
# returns "EUCAST" or "CLSI" to consider 'I' susceptible or resistant, or NULL to not merge 'I' at all, see the section 'Interpretation of SIR' in ?as.sir
|
||||
if (is.null(guideline) || isFALSE(guideline)) {
|
||||
stop_ifnot(
|
||||
allow_none,
|
||||
"{.arg guideline} must be {.val EUCAST} or {.val CLSI} in {.help [{.fun ", fn, "}](AMR::", fn, ")}, since a single proportion or count requires the 'I' category to be considered either susceptible (EUCAST) or resistant (CLSI). See the section 'Interpretation of SIR' in {.help [{.fun as.sir}](AMR::as.sir)}.",
|
||||
call = FALSE
|
||||
)
|
||||
return(NULL)
|
||||
}
|
||||
stop_ifnot(
|
||||
is.character(guideline) && length(guideline) == 1 && !is.na(guideline) && (guideline %like% "EUCAST" || guideline %like% "CLSI"),
|
||||
"{.arg guideline} must be {.val EUCAST} or {.val CLSI}", ifelse(allow_none, ", or {.code NULL} to keep S, I, and R separate,", ""), " in {.help [{.fun ", fn, "}](AMR::", fn, ")}. See the section 'Interpretation of SIR' in {.help [{.fun as.sir}](AMR::as.sir)}.",
|
||||
call = FALSE
|
||||
)
|
||||
if (guideline %like% "EUCAST") "EUCAST" else "CLSI"
|
||||
}
|
||||
|
||||
message_guideline_assumed <- function(fn, txt) {
|
||||
# informs once per session that EUCAST is assumed, only to be called when the `guideline` argument is missing
|
||||
# - not when the AMR_guideline option is set, since that is a deliberate choice
|
||||
# - not when knitting R Markdown or Quarto documents, so it will not end up in reports
|
||||
if (is.null(getOption("AMR_guideline")) && !isTRUE(getOption("knitr.in.progress")) && message_not_thrown_before(fn, "guideline_assumed", entire_session = TRUE)) {
|
||||
message_(
|
||||
"{.help [{.fun ", fn, "}](AMR::", fn, ")} assumes the EUCAST guideline and thus considers the 'I' category susceptible", txt,
|
||||
" Set the {.arg guideline} argument, or set the {.code AMR_guideline} option to change the default (see {.topic [AMR-options](AMR::AMR-options)}). This message is shown once per session."
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
get_aggregation_guideline <- function(guideline, guideline_missing, combine_SI, combine_SI_missing, fn) {
|
||||
# for functions that return results per category: returns "EUCAST" ("SI" vs. "R"), "CLSI" ("S" vs. "IR"), or NULL (S, I, and R separately)
|
||||
if (!combine_SI_missing) {
|
||||
# deprecated argument, if set it must be followed literally, regardless of the guideline
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1, .call_depth = 1)
|
||||
deprecation_warning("combine_SI", "guideline", fn = fn, is_argument = TRUE, extra_msg = "As long as `combine_SI` is set, it takes precedence over `guideline`. Use `guideline = \"EUCAST\"` to merge 'I' with S, `guideline = \"CLSI\"` to merge 'I' with R, or `guideline = NULL` to keep S, I, and R separate.")
|
||||
if (isTRUE(combine_SI)) {
|
||||
return("EUCAST")
|
||||
} else {
|
||||
return(NULL)
|
||||
}
|
||||
}
|
||||
guideline <- validate_sir_guideline(guideline, fn = fn, allow_none = TRUE)
|
||||
if (isTRUE(guideline_missing) && !is.null(guideline)) {
|
||||
message_guideline_assumed(fn, txt = paste0(" (S+SDD+I vs. R). Use {.code guideline = \"CLSI\"} for S+SDD vs. I+R, or {.code guideline = NULL} to keep S, I, and R separate."))
|
||||
}
|
||||
guideline
|
||||
}
|
||||
|
||||
sir_calc <- function(...,
|
||||
ab_result,
|
||||
minimum = 0,
|
||||
@@ -219,9 +268,8 @@ sir_calc_df <- function(type, # "proportion", "count" or "both"
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
as_percent = FALSE,
|
||||
combine_SI = TRUE,
|
||||
confidence_level = 0.95,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
guideline = "EUCAST") { # must be "EUCAST", "CLSI", or NULL, see get_aggregation_guideline()
|
||||
meet_criteria(type, is_in = c("proportion", "count", "both"), has_length = 1)
|
||||
meet_criteria(data, allow_class = "data.frame")
|
||||
data <- ascertain_sir_classes(data, "data")
|
||||
@@ -229,16 +277,10 @@ sir_calc_df <- function(type, # "proportion", "count" or "both"
|
||||
language <- validate_language(language)
|
||||
meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
|
||||
meet_criteria(as_percent, allow_class = "logical", has_length = 1)
|
||||
meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
|
||||
meet_criteria(confidence_level, allow_class = "numeric", has_length = 1)
|
||||
meet_criteria(guideline, allow_class = "character", has_length = 1)
|
||||
if (guideline %like% "EUCAST") {
|
||||
guideline <- "EUCAST"
|
||||
} else if (guideline %like% "CLSI") {
|
||||
guideline <- "CLSI"
|
||||
}
|
||||
meet_criteria(guideline, allow_class = "character", is_in = c("EUCAST", "CLSI"), has_length = 1)
|
||||
# with EUCAST, 'I' is merged with S into 'SI', with CLSI, 'I' is merged with R into 'IR'
|
||||
meet_criteria(guideline, allow_class = "character", has_length = 1, is_in = c("EUCAST", "CLSI"), allow_NULL = TRUE)
|
||||
# with EUCAST, 'I' is merged with S into 'SI', with CLSI, 'I' is merged with R into 'IR', and with NULL, 'I' is not merged
|
||||
combine_SI <- !is.null(guideline)
|
||||
combined_levels <- if (identical(guideline, "CLSI")) c("S", "IR") else c("SI", "R")
|
||||
|
||||
translate_ab <- get_translate_ab(translate_ab)
|
||||
|
||||
+8
-13
@@ -38,7 +38,8 @@
|
||||
#' @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 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].
|
||||
#' @param guideline A guideline name, `"EUCAST"` or `"CLSI"` (or any version thereof, e.g. `"CLSI 2025"`), to determine whether the 'I' category is considered susceptible (EUCAST) or resistant (CLSI). This only affects isolates with a missing result for any of the antimicrobials when `only_all_tested = FALSE`, see *Combination Therapy* below. The default is the package option [`AMR_guideline`][AMR-options], or `"EUCAST"` if it is not set. See section *Interpretation of SIR* below.
|
||||
#' @inheritSection as.sir Interpretation of SIR
|
||||
#' @section Combination Therapy:
|
||||
#' 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.
|
||||
#'
|
||||
@@ -82,7 +83,7 @@
|
||||
#' 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.
|
||||
#' In [antibiogram()] and [wisca()], the result of the combination therapy (`"most_susceptible"`) is used, the 'I' category is considered susceptible or not following the `guideline` argument ('SDD' is always considered susceptible), 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
|
||||
@@ -142,13 +143,8 @@
|
||||
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") {
|
||||
guideline <- "EUCAST"
|
||||
} else if (guideline %like% "CLSI") {
|
||||
guideline <- "CLSI"
|
||||
}
|
||||
meet_criteria(guideline, allow_class = "character", is_in = c("EUCAST", "CLSI"), has_length = 1)
|
||||
guideline_missing <- missing(guideline)
|
||||
guideline <- validate_sir_guideline(guideline, fn = "sir_combine")
|
||||
|
||||
# unpack data frames, so that e.g. sir_combine(df[, c("GEN", "TOB")], CIP) works
|
||||
cols <- list()
|
||||
@@ -166,12 +162,11 @@ sir_combine <- function(..., method = c("most_susceptible", "most_resistant"), o
|
||||
|
||||
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)) {
|
||||
if (isFALSE(only_all_tested) && is.null(getOption("AMR_guideline")) && guideline_missing) {
|
||||
# only notify about the assumed guideline if it affected the result
|
||||
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.")
|
||||
if (!identical(out, out_clsi)) {
|
||||
message_guideline_assumed("sir_combine", txt = ", which affected the result for 'I' results combined with a missing result. Use {.code guideline = \"CLSI\"} to consider it resistant.")
|
||||
}
|
||||
}
|
||||
out
|
||||
|
||||
+2
-2
@@ -34,9 +34,10 @@ sir_df <- function(data,
|
||||
language = get_AMR_locale(),
|
||||
minimum = 30,
|
||||
as_percent = FALSE,
|
||||
combine_SI = TRUE,
|
||||
combine_SI,
|
||||
confidence_level = 0.95,
|
||||
guideline = getOption("AMR_guideline", "EUCAST")) {
|
||||
guideline <- get_aggregation_guideline(guideline, missing(guideline), combine_SI, missing(combine_SI), fn = "sir_df")
|
||||
tryCatch(
|
||||
sir_calc_df(
|
||||
type = "both",
|
||||
@@ -45,7 +46,6 @@ sir_df <- function(data,
|
||||
language = language,
|
||||
minimum = minimum,
|
||||
as_percent = as_percent,
|
||||
combine_SI = combine_SI,
|
||||
confidence_level = confidence_level,
|
||||
guideline = guideline
|
||||
),
|
||||
|
||||
@@ -69,6 +69,7 @@ as.data.frame.deprecated_amr_dataset <- function(x, ...) {
|
||||
# currently deprecated arguments at least:
|
||||
# - `antibiotics` in `antibiogram()`
|
||||
# - `converse_capped_values` in `as.sir()`
|
||||
# - `combine_SI` in `count_df()`, `proportion_df()`, `sir_df()`, `ggplot_sir()`, `geom_sir()`, `labels_sir_count()`, `antibiogram()`, `wisca()`, and `format()` for `bug_drug_combinations()`
|
||||
|
||||
#' @rdname AMR-deprecated
|
||||
#' @export
|
||||
|
||||
Reference in new issue
Block a user