Store all screening breakpoints under screening agents, and add these agents to antimicrobials (#328)

Implements the decisions ticked in #328, and the behaviour specified in https://github.com/msberends/AMR/pull/339#issuecomment-6577438074: `include_screening` now defaults to NULL, using screening breakpoints for screening agents only. With TRUE, a regular agent also takes these breakpoints, and with FALSE a screening agent gives NA with a note.

- antimicrobials gains 13 screening agents, e.g. GEN-S, ERY-S and STR1-S
- GEH and STH rows move to GEN-S and STR1-S, and as.sir() keeps accepting both codes
- Topical cut-off values move to -S agents with site "Topical"
- WHONET-based rows move as ticked, including CLSI cefoxitin for staphylococci and pefloxacin for Salmonella, and EUCAST 2012-2018 cefoxitin MIC
- Clinical breakpoints that EUCAST also allows as a screening test get a copy under the -S agent
This commit is contained in:
dr. M.S. (Matthijs) Berends committed 2026-11-02 17:31:46 +01:00
1 parent fab20c5eaa
commit 2c98dac7ae
12 files changed
+213 -37

No files matched your search

+1 -1
View File
@@ -51,7 +51,7 @@
#' - For many plotting functions (e.g., for MIC or disk diffusion values), supplying `mo` and `ab` enables automatic SIR-based interpretative colouring. These colours are derived from [as.sir()] in the background and therefore depend on the active `guideline` setting, which again uses `r AMR::clinical_breakpoints$guideline[1]` if not set explicitly.
#' * `AMR_ignore_pattern` \cr A [regular expression][base::regex] to ignore (i.e., make `NA`) any match given in [as.mo()] and all [`mo_*`][mo_property()] functions.
#' * `AMR_include_PKPD` \cr A [logical] to use in [as.sir()], to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is `TRUE`.
#' * `AMR_include_screening` \cr A [logical] to use in [as.sir()], to indicate that clinical breakpoints for screening are allowed - the default is `FALSE`.
#' * `AMR_include_screening` \cr A [logical] to use in [as.sir()], to indicate that clinical breakpoints for screening are allowed - the default is `NULL`, using these for screening agents only, such as `FOX-S`. See [as.sir()].
#' * `AMR_interpretive_rules` \cr A [character] to set the default types of rules for [interpretive_rules()], [eucast_rules()] and [clsi_rules()], must be one or more of: `"breakpoints"`, `"expected_phenotypes"`, `"expert"`, `"other"`, `"custom"`, `"all"`, and defaults to `c("breakpoints", "expected_phenotypes")`. This option replaces the old option `AMR_eucastrules`.
#' * `AMR_keep_synonyms` \cr A [logical] to use in [as.mo()] and all [`mo_*`][mo_property()] functions, to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is `FALSE`.
#' * `AMR_locale` \cr A [character] to set the language for the `AMR` package, can be one of these supported language names or [ISO 639-1 codes](https://en.wikipedia.org/wiki/ISO_639-1): `r vector_or(paste0(sapply(LANGUAGES_SUPPORTED_NAMES, function(x) x[[1]]), " (" , LANGUAGES_SUPPORTED, ")"), quotes = FALSE, sort = FALSE)`. The default is the current system language (if supported, English otherwise).
+66 -12
View File
@@ -66,7 +66,7 @@ VALID_SIR_LEVELS <- c("S", "SDD", "I", "R", "NI", "WT", "NWT", "NS")
#' @param as_wt_nwt A [logical] to return `"WT"`/`"NWT"` instead of `"S"`/`"R"`. Defaults to `TRUE` when using ECOFFs, i.e., when `breakpoint_type` is set to `"ECOFF"`.
#' @param add_intrinsic_resistance *(only useful when using a EUCAST guideline)* a [logical] to indicate whether intrinsic antibiotic resistance must also be considered for applicable bug-drug combinations, meaning that e.g. ampicillin will always return "R" in *Klebsiella* species. Determination is based on the [intrinsic_resistant] data set, that itself is based on `r format_eucast_version_nr(3.3)`.
#' @param substitute_missing_r_breakpoint A [logical] to indicate that a missing clinical breakpoints for R (resistant) must be substituted with R - the default is `FALSE`. Some (especially CLSI) breakpoints only have a breakpoint for S, meaning that the outcome can only be `"S"` or `NA`. Setting this to `TRUE` will convert the `NA`s in these cases to `"R"`. Can also be set with the package option [`AMR_substitute_missing_r_breakpoint`][AMR-options].
#' @param include_screening A [logical] to indicate that clinical breakpoints for screening are allowed - the default is `FALSE`. Can also be set with the package option [`AMR_include_screening`][AMR-options].
#' @param include_screening A [logical] to indicate that clinical breakpoints for screening are allowed. At default (`NULL`, can be set with the package option [`AMR_include_screening`][AMR-options]), these are only used for screening agents, e.g. `FOX-S`, but not for regular agents, e.g. `FOX`. Use `TRUE` to also use them for regular agents (with `FOX` then taking the breakpoints of `FOX-S`), and `FALSE` to never use them, which gives `NA` with a note for a screening agent.
#' @param include_PKPD A [logical] to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is `TRUE`. Can also be set with the package option [`AMR_include_PKPD`][AMR-options].
#' @param breakpoint_type The type of breakpoints to use, either `r vector_or(clinical_breakpoints$type, documentation = TRUE)`. ECOFF stands for Epidemiological Cut-Off values. The default is `"human"`, which can also be set with the package option [`AMR_breakpoint_type`][AMR-options]. If `host` is set to values of veterinary species, this will automatically be set to `"animal"`.
#' @param host A vector (or column name) with [character]s to indicate the host. Only useful for veterinary breakpoints, as it requires `breakpoint_type = "animal"`. The values can be any text resembling the animal species, even in any of the `r length(LANGUAGES_SUPPORTED)` supported languages of this package. For foreign languages, be sure to set the language with [set_AMR_locale()] (though it will be automatically guessed based on the system language).
@@ -664,7 +664,7 @@ as.sir.mic <- function(x,
add_intrinsic_resistance = FALSE,
reference_data = AMR::clinical_breakpoints,
substitute_missing_r_breakpoint = getOption("AMR_substitute_missing_r_breakpoint", FALSE),
include_screening = getOption("AMR_include_screening", FALSE),
include_screening = getOption("AMR_include_screening", NULL),
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
host = NULL,
@@ -711,7 +711,7 @@ as.sir.disk <- function(x,
add_intrinsic_resistance = FALSE,
reference_data = AMR::clinical_breakpoints,
substitute_missing_r_breakpoint = getOption("AMR_substitute_missing_r_breakpoint", FALSE),
include_screening = getOption("AMR_include_screening", FALSE),
include_screening = getOption("AMR_include_screening", NULL),
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
host = NULL,
@@ -758,7 +758,7 @@ as.sir.data.frame <- function(x,
add_intrinsic_resistance = FALSE,
reference_data = AMR::clinical_breakpoints,
substitute_missing_r_breakpoint = getOption("AMR_substitute_missing_r_breakpoint", FALSE),
include_screening = getOption("AMR_include_screening", FALSE),
include_screening = getOption("AMR_include_screening", NULL),
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
host = NULL,
@@ -777,7 +777,7 @@ as.sir.data.frame <- function(x,
meet_criteria(add_intrinsic_resistance, allow_class = "logical", has_length = 1)
meet_criteria(reference_data, allow_class = "data.frame")
meet_criteria(substitute_missing_r_breakpoint, allow_class = "logical", has_length = 1)
meet_criteria(include_screening, allow_class = "logical", has_length = 1)
meet_criteria(include_screening, allow_class = "logical", has_length = 1, allow_NULL = TRUE)
meet_criteria(include_PKPD, allow_class = "logical", has_length = 1)
meet_criteria(breakpoint_type, allow_class = "character", is_in = reference_data$type, has_length = 1)
meet_criteria(host, allow_class = c("character", "factor"), allow_NULL = TRUE, allow_NA = TRUE)
@@ -1385,7 +1385,7 @@ as_sir_method <- function(method_short,
meet_criteria(add_intrinsic_resistance, allow_class = "logical", has_length = 1, .call_depth = -2)
meet_criteria(reference_data, allow_class = "data.frame", .call_depth = -2)
meet_criteria(substitute_missing_r_breakpoint, allow_class = "logical", has_length = 1, .call_depth = -2)
meet_criteria(include_screening, allow_class = "logical", has_length = 1, .call_depth = -2)
meet_criteria(include_screening, allow_class = "logical", has_length = 1, allow_NULL = TRUE, .call_depth = -2)
meet_criteria(include_PKPD, allow_class = "logical", has_length = 1, .call_depth = -2)
reference_data <- check_reference_data(reference_data, .call_depth = -2)
meet_criteria(breakpoint_type, allow_class = "character", is_in = reference_data$type, has_length = 1, .call_depth = -2)
@@ -1638,17 +1638,29 @@ as_sir_method <- function(method_short,
method_coerced <- toupper(method)
ab_coerced <- as.ab(ab, info = FALSE)
# which agents hold the breakpoints of the requested agents: the high-level aminoglycoside tests have two codes, and screening breakpoints are also for the regular agent if the user allows this
ab_lookup <- function(ab_requested) {
ab_requested <- as.character(ab_requested)
ab_stored <- ab_requested
ab_stored[ab_stored == "GEH"] <- "GEN-S"
ab_stored[ab_stored == "STH"] <- "STR1-S"
from <- c(ab_requested, ab_requested)
to <- c(ab_stored, if (isTRUE(include_screening)) ifelse(endsWith(ab_stored, "-S"), ab_stored, paste0(ab_stored, "-S")) else ab_stored)
unique(data.frame(from = from, to = to, stringsAsFactors = FALSE))
}
ab_coerced_lookup <- ab_lookup(ab_coerced)
if (!custom_breakpoints_set) {
breakpoints <- reference_data %pm>%
subset(guideline %in% guideline_coerced & method == method_coerced & ab %in% ab_coerced)
subset(guideline %in% guideline_coerced & method == method_coerced & ab %in% ab_coerced_lookup$to)
if (any(ab_coerced == "AMX") && nrow(breakpoints[breakpoints$ab == "AMX", , drop = FALSE]) == 0) {
ab_coerced[ab_coerced == "AMX"] <- "AMP"
ab_coerced_lookup <- ab_lookup(ab_coerced)
breakpoints <- reference_data %pm>%
subset(guideline %in% guideline_coerced & method == method_coerced & ab %in% ab_coerced)
subset(guideline %in% guideline_coerced & method == method_coerced & ab %in% ab_coerced_lookup$to)
}
} else {
breakpoints <- reference_data %pm>%
subset(method == method_coerced & ab %in% ab_coerced)
subset(method == method_coerced & ab %in% ab_coerced_lookup$to)
}
@@ -1712,10 +1724,23 @@ as_sir_method <- function(method_short,
breakpoints <- breakpoints %pm>%
subset(type %in% breakpoint_type_lookup)
is_screening_row <- function(df) {
df$site %like% "screen" | df$ref_tbl %like% "screen" | as.character(df$ab) %like% "-S$"
}
screening_left_out <- FALSE
if (isFALSE(include_screening)) {
# remove screening rules from the breakpoints table
breakpoints <- breakpoints %pm>%
subset(site %unlike% "screen" & ref_tbl %unlike% "screen")
# remove screening rules from the breakpoints table, on explicit request also for a screening agent
screening_left_out <- any(is_screening_row(breakpoints) & as.character(breakpoints$ab) %like% "-S$")
breakpoints <- breakpoints[!is_screening_row(breakpoints), , drop = FALSE]
} else if (is.null(include_screening)) {
# at default, screening breakpoints are only for an agent that indicates screening itself
breakpoints <- breakpoints[!is_screening_row(breakpoints) | as.character(breakpoints$ab) %like% "-S$", , drop = FALSE]
}
# the breakpoints are from here on known by the requested agent
if (nrow(breakpoints) > 0) {
for (j in rev(seq_len(nrow(ab_coerced_lookup)))) {
breakpoints$ab[as.character(breakpoints$ab) == ab_coerced_lookup$to[j]] <- ab_coerced_lookup$from[j]
}
}
if (isFALSE(include_PKPD)) {
# remove PKPD rules from the breakpoints table
@@ -1738,6 +1763,35 @@ as_sir_method <- function(method_short,
has_progress_bar <- !is.null(import_fn("progress_bar", "progress", error_on_fail = FALSE)) && nrow(df_unique) >= 10
on.exit(close(p))
if (isTRUE(screening_left_out) && nrow(breakpoints) == 0) {
# a note, as this may be by accident
message_("Returning NAs for ", vector_and(unique(as.character(ab_coerced)), quotes = TRUE), ": this is a screening agent, while `include_screening = FALSE` leaves out screening breakpoints.")
out <- data.frame(
datetime = rep(Sys.time(), nrow(df)),
index = seq_len(nrow(df)),
method = rep(method_coerced, nrow(df)),
ab_given = ab.bak,
mo_given = as.character(mo.bak),
host_given = as.character(host),
input_given = as.character(df$input_original),
ab = as.character(df$ab),
mo = as.character(df$mo),
host = as.character(df$host),
input = as.character(df$input_clean),
outcome = rep(NA_sir_, nrow(df)),
notes = rep("Screening breakpoints were left out, since `include_screening = FALSE`.", nrow(df)),
guideline = df$guideline,
ref_table = rep(NA_character_, nrow(df)),
uti = df$uti,
breakpoint_S_R = rep(NA_character_, nrow(df)),
site = rep(NA_character_, nrow(df)),
stringsAsFactors = FALSE
)
AMR_env$sir_interpretation_history <- rbind_AMR(AMR_env$sir_interpretation_history, out[!is.na(out$input_given), , drop = FALSE])
load_mo_uncertainties(metadata_mo)
return(rep(NA_sir_, nrow(df)))
}
if (nrow(breakpoints) == 0) {
# apparently no breakpoints found
if (isTRUE(info)) {