From 12cf144b19fce0e0d06add6a09f71fb8ca54efd5 Mon Sep 17 00:00:00 2001 From: Matthijs Berends Date: Thu, 12 Feb 2026 20:34:06 +0100 Subject: [PATCH] (v3.0.1.9021) add `guideline` to `resistance()` and `susceptibility()` --- DESCRIPTION | 4 ++-- NEWS.md | 5 ++-- R/aa_options.R | 20 ++++++++++++---- R/count.R | 39 ++++++++++++++++++++++++++------ R/mean_amr_distance.R | 2 +- R/proportion.R | 33 +++++++++++++++++++++++---- R/sir.R | 4 ++-- R/zzz.R | 15 ++++++++++++ man/AMR-options.Rd | 15 +++++++++--- man/as.sir.Rd | 4 ++-- man/count.Rd | 18 +++++++++++---- man/proportion.Rd | 14 ++++++++++-- tests/testthat/test-count.R | 6 +++-- tests/testthat/test-proportion.R | 2 ++ 14 files changed, 145 insertions(+), 36 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 03430d621..19d52aaa4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 3.0.1.9020 -Date: 2026-02-09 +Version: 3.0.1.9021 +Date: 2026-02-12 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) data analysis and to work with microbial and antimicrobial properties by diff --git a/NEWS.md b/NEWS.md index 0ce89e0e0..4e91ef4e0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 3.0.1.9020 +# AMR 3.0.1.9021 ### New * Integration with the **tidymodels** framework to allow seamless use of SIR, MIC and disk data in modelling pipelines via `recipes` @@ -18,13 +18,14 @@ ### Fixes * Fixed a bug in `antibiogram()` for when no antimicrobials are set -* Fixed a bug in `as.sir()` where for numeric input the arguments `S`, `i`, and `R` would not be considered (#244) +* Fixed a bug in `as.sir()` where for numeric input the arguments `S`, `I`, and `R` would not be considered (#244) * Fixed some foreign translations of antimicrobial drugs * Fixed a bug for printing column names to the console when using `mutate_at(vars(...), as.mic)` (#249) * Fixed a bug to disregard `NI` for susceptibility proportion functions * Fixed Italian translation of CoNS to Stafilococco coagulasi-negativo and CoPS to Stafilococco coagulasi-positivo (#256) ### Updates +* `susceptibility()` and `resistance()` gained the argument `guideline`, which defaults to EUCAST, for interpreting the 'I' category correctly. * `as.mic()` and `rescale_mic()` gained the argument `round_to_next_log2`, which can be set to `TRUE` to round all values up to the nearest next log2 level (#255) * `antimicrobials$group` is now a `list` instead of a `character`, to contain any group the drug is in (#246) * `ab_group()` gained an argument `all_groups` to return all groups the antimicrobial drug is in (#246) diff --git a/R/aa_options.R b/R/aa_options.R index 64e2e4bec..5a05573df 100755 --- a/R/aa_options.R +++ b/R/aa_options.R @@ -29,8 +29,11 @@ #' Options for the AMR package #' -#' This is an overview of all the package-specific [options()] you can set in the `AMR` package. -#' @section Options: +#' @description +#' This is an overview of all the package-specific options you can set in the `AMR` package. Set them using the [options()] function, e.g.: +#' +#' `options(AMR_guideline = "CLSI")` +#' @section Options (alphabetical order): #' * `AMR_antibiogram_formatting_type` \cr A [numeric] (1-22) to use in [antibiogram()], to indicate which formatting type to use. #' * `AMR_breakpoint_type` \cr A [character] to use in [as.sir()], to indicate which breakpoint type to use. This must be either `r vector_or(clinical_breakpoints$type)`. #' * `AMR_capped_mic_handling` \cr A [character] to use in [as.sir()], to indicate how capped MIC values (`<`, `<=`, `>`, `>=`) should be interpreted. Must be one of `"none"`, `"conservative"`, `"standard"`, or `"lenient"` - the default is `"conservative"`. @@ -38,6 +41,15 @@ #' * `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]`). +#' +#' - 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)))`. +#' +#' - For [resistance()] and [susceptibility()], this setting determines how the `"I"` (Intermediate / Increased exposure) category is handled in calculations. Under CLSI, `"I"` is considered *resistant* in susceptibility calculations; under EUCAST, `"I"` is considered *susceptible* in susceptibility calculations. Explicitly setting this option ensures reproducible AMR proportion estimates. +#' +#' - For [interpretive_rules()], this determines which guideline-specific interpretive (expert) rules are applied to antimicrobial test results, either EUCAST or CLSI. +#' +#' - 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_guideline` \cr A [character] to set the default guideline for interpreting MIC values and disk diffusion diameters with [as.sir()]. Can be only the guideline name (e.g., `"CLSI"`) or the name with a year (e.g. `"CLSI 2019"`). The default to the latest implemented EUCAST guideline, currently \code{"`r clinical_breakpoints$guideline[1]`"}. Supported guideline are currently EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`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)))`-`r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))`). #' * `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`. @@ -63,9 +75,9 @@ #' #' ...to add Portuguese language support of antimicrobials, and allow PK/PD rules when interpreting MIC values with [as.sir()]. #' -#' ### Share Options Within Team +#' ## Share Options Within Team #' -#' For a more global approach, e.g. within a (data) team, save an options file to a remote file location, such as a shared network drive, and have each user read in this file automatically at start-up. This would work in this way: +#' For a more collaborative approach, e.g. within a (data) team, save an options file to a remote file location, such as a shared network drive, and have each user read in this file automatically at start-up. This would work in this way: #' #' 1. Save a plain text file to e.g. "X:/team_folder/R_options.R" and fill it with preferred settings. #' diff --git a/R/count.R b/R/count.R index c3a19d621..1c17d3806 100755 --- a/R/count.R +++ b/R/count.R @@ -33,13 +33,16 @@ #' #' [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. #' -#' The function [count_resistant()] is equal to the function [count_R()]. The function [count_susceptible()] is equal to the function [count_SI()]. -#' -#' The function [n_sir()] is an alias of [count_all()]. They can be used to count all available isolates, i.e. where all input antimicrobials have an available result (S, I or R). Their use is equal to `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 all input antimicrobials have an available result (S, I or R). Their use is equal to `dplyr`'s `n_distinct()`. 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 proportion Combination Therapy @@ -119,10 +122,21 @@ #' count_df(translate = FALSE) #' } #' } -count_resistant <- function(..., only_all_tested = FALSE) { +count_resistant <- function(..., + only_all_tested = FALSE, + guideline = getOption("AMR_guideline", "EUCAST")) { + # other arguments for meet_criteria are handled by sir_calc() + 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_("`count_resistant()` assumes the EUCAST guideline and thus considers the 'I' category susceptible. Set the `guideline` argument or the `AMR_guideline` option to either \"CLSI\" or \"EUCAST\", see `?AMR-options`.") + message_("This message will be shown once per session.") + } tryCatch( sir_calc(..., - ab_result = c("R", "NWT", "NS"), + ab_result = c( + "R", "NWT", "NS", + if (identical(guideline, "CLSI")) "I" + ), only_all_tested = only_all_tested, only_count = TRUE ), @@ -132,10 +146,21 @@ count_resistant <- function(..., only_all_tested = FALSE) { #' @rdname count #' @export -count_susceptible <- function(..., only_all_tested = FALSE) { +count_susceptible <- function(..., + only_all_tested = FALSE, + guideline = getOption("AMR_guideline", "EUCAST")) { + # other arguments for meet_criteria are handled by sir_calc() + 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_("`count_susceptible()` assumes the EUCAST guideline and thus considers the 'I' category susceptible. Set the `guideline` argument or the `AMR_guideline` option to either \"CLSI\" or \"EUCAST\", see `?AMR-options`.") + message_("This message will be shown once per session.") + } tryCatch( sir_calc(..., - ab_result = c("S", "SDD", "I", "WT"), + ab_result = c( + "S", "SDD", "WT", + if (identical(guideline, "EUCAST")) "I" + ), only_all_tested = only_all_tested, only_count = TRUE ), diff --git a/R/mean_amr_distance.R b/R/mean_amr_distance.R index 08611a63a..905e99d9d 100755 --- a/R/mean_amr_distance.R +++ b/R/mean_amr_distance.R @@ -118,7 +118,7 @@ mean_amr_distance.disk <- function(x, ...) { mean_amr_distance.sir <- function(x, ..., combine_SI = TRUE) { meet_criteria(combine_SI, allow_class = "logical", has_length = 1, .call_depth = -1) if (isTRUE(combine_SI)) { - x[x %in% c("I", "SDD")] <- "S" + x[x %in% c("I", "SDD")] <- "S" # do not acknowledge CLSI/EUCAST guideline here to keep the numeric mean_amr_distance consistent between systems } mean_amr_distance(as.double(x)) } diff --git a/R/proportion.R b/R/proportion.R index 40c37a24f..fb151b1b6 100644 --- a/R/proportion.R +++ b/R/proportion.R @@ -38,6 +38,11 @@ #' @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. #' @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. #' @inheritParams ab_property #' @param combine_SI A [logical] to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is `TRUE`. #' @param ab_result Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R". @@ -228,10 +233,20 @@ resistance <- function(..., minimum = 30, as_percent = FALSE, - only_all_tested = FALSE) { + only_all_tested = FALSE, + guideline = getOption("AMR_guideline", "EUCAST")) { + # other arguments for meet_criteria are handled by sir_calc() + 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_("`resistance()` assumes the EUCAST guideline and thus considers the 'I' category susceptible. Set the `guideline` argument or the `AMR_guideline` option to either \"CLSI\" or \"EUCAST\", see `?AMR-options`.") + message_("This message will be shown once per session.") + } tryCatch( sir_calc(..., - ab_result = c("R", "NWT", "NS"), + ab_result = c( + "R", "NWT", "NS", + if (identical(guideline, "CLSI")) "I" + ), minimum = minimum, as_percent = as_percent, only_all_tested = only_all_tested, @@ -246,10 +261,20 @@ resistance <- function(..., susceptibility <- function(..., minimum = 30, as_percent = FALSE, - only_all_tested = FALSE) { + only_all_tested = FALSE, + guideline = getOption("AMR_guideline", "EUCAST")) { + # other arguments for meet_criteria are handled by sir_calc() + 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_("`susceptibility()` assumes the EUCAST guideline and thus considers the 'I' category susceptible. Set the `guideline` argument or the `AMR_guideline` option to either \"CLSI\" or \"EUCAST\", see `?AMR-options`.") + message_("This message will be shown once per session.") + } tryCatch( sir_calc(..., - ab_result = c("S", "SDD", "I", "WT"), + ab_result = c( + "S", "SDD", "WT", + if (identical(guideline, "EUCAST")) "I" + ), minimum = minimum, as_percent = as_percent, only_all_tested = only_all_tested, diff --git a/R/sir.R b/R/sir.R index 8641794ab..9755aa9ab 100755 --- a/R/sir.R +++ b/R/sir.R @@ -156,9 +156,9 @@ VALID_SIR_LEVELS <- c("S", "SDD", "I", "R", "NI", "WT", "NWT", "NS") #' #' ### After Interpretation #' -#' After using [as.sir()], you can use the [eucast_rules()] defined by EUCAST to (1) apply inferred susceptibility and resistance based on results of other antimicrobials and (2) apply intrinsic resistance based on taxonomic properties of a microorganism. +#' After using [as.sir()], you can use the [interpretive_rules()] to (1) apply inferred susceptibility and resistance based on results of other antimicrobials and (2) apply intrinsic resistance based on taxonomic properties of a microorganism. #' -#' To determine which isolates are multi-drug resistant, be sure to run [mdro()] (which applies the MDR/PDR/XDR guideline from 2012 at default) on a data set that contains S/I/R values. Read more about [interpreting multidrug-resistant organisms here][mdro()]. +#' To determine which isolates are multi-drug resistant, be sure to run [mdro()] (which applies the MDR/PDR/XDR guideline from 2012 at default) on a data set that contains S/I/R values. Read more about [detecting multidrug-resistant organisms here][mdro()]. #' #' ### Other #' diff --git a/R/zzz.R b/R/zzz.R index d5e864b33..dec14dd17 100755 --- a/R/zzz.R +++ b/R/zzz.R @@ -115,6 +115,21 @@ AMR_env$cross_icon <- if (isTRUE(base::l10n_info()$`UTF-8`)) "\u00d7" else "x" } .onAttach <- function(libname, pkgname) { + if (interactive() && is.null(getOption("AMR_guideline"))) { + packageStartupMessage( + word_wrap( + "Welcome to AMR v", format(utils::packageVersion("AMR")), ". ", + "You have not set the 'AMR_guideline' option to either \"CLSI\" or \"EUCAST\". ", + "You can set it using either:\n", + " options(AMR_guideline = \"CLSI\")\n", + " options(AMR_guideline = \"EUCAST\")\n", + "See `?AMR-options`. While unset, the AMR package uses the current default guideline: ", AMR::clinical_breakpoints$guideline[1], ".", + add_fn = NULL + ) + ) + } + + # if custom ab option is available, load it if (!is.null(getOption("AMR_custom_ab")) && file.exists(getOption("AMR_custom_ab", default = ""))) { if (getOption("AMR_custom_ab") %unlike% "[.]rds$") { diff --git a/man/AMR-options.Rd b/man/AMR-options.Rd index 9e8cfd904..fa23f3cc5 100644 --- a/man/AMR-options.Rd +++ b/man/AMR-options.Rd @@ -4,9 +4,11 @@ \alias{AMR-options} \title{Options for the AMR package} \description{ -This is an overview of all the package-specific \code{\link[=options]{options()}} you can set in the \code{AMR} package. +This is an overview of all the package-specific options you can set in the \code{AMR} package. Set them using the \code{\link[=options]{options()}} function, e.g.: + +\code{options(AMR_guideline = "CLSI")} } -\section{Options}{ +\section{Options (alphabetical order)}{ \itemize{ \item \code{AMR_antibiogram_formatting_type} \cr A \link{numeric} (1-22) to use in \code{\link[=antibiogram]{antibiogram()}}, to indicate which formatting type to use. @@ -16,6 +18,13 @@ This is an overview of all the package-specific \code{\link[=options]{options()} \item \code{AMR_custom_ab} \cr A file location to an RDS file, to use custom antimicrobial drugs with this package. This is explained in \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}}. \item \code{AMR_custom_mo} \cr A file location to an RDS file, to use custom microorganisms with this package. This is explained in \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}}. \item \code{AMR_eucastrules} \cr A \link{character} to set the default types of rules for \code{\link[=eucast_rules]{eucast_rules()}} function, must be one or more of: \code{"breakpoints"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expert")}. +\item \code{AMR_guideline} \cr A \link{character} to set the default guideline used throughout the \code{AMR} package wherever a \code{guideline} argument is available. This option is used as the default in e.g. \code{\link[=as.sir]{as.sir()}}, \code{\link[=resistance]{resistance()}}, \code{\link[=susceptibility]{susceptibility()}}, \code{\link[=interpretive_rules]{interpretive_rules()}} and many plotting functions. \strong{While unset}, the AMR package uses the latest implemented EUCAST guideline (currently EUCAST 2025). +\itemize{ +\item For \code{\link[=as.sir]{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., \code{"CLSI"} or \code{"EUCAST"}) or the name including a year (e.g., \code{"CLSI 2019"}). Supported guidelines are EUCAST 2011 to 2025, and CLSI 2011 to 2025. +\item For \code{\link[=resistance]{resistance()}} and \code{\link[=susceptibility]{susceptibility()}}, this setting determines how the \code{"I"} (Intermediate / Increased exposure) category is handled in calculations. Under CLSI, \code{"I"} is considered \emph{resistant} in susceptibility calculations; under EUCAST, \code{"I"} is considered \emph{susceptible} in susceptibility calculations. Explicitly setting this option ensures reproducible AMR proportion estimates. +\item For \code{\link[=interpretive_rules]{interpretive_rules()}}, this determines which guideline-specific interpretive (expert) rules are applied to antimicrobial test results, either EUCAST or CLSI. +\item For many plotting functions (e.g., for MIC or disk diffusion values), supplying \code{mo} and \code{ab} enables automatic SIR-based interpretative colouring. These colours are derived from \code{\link[=as.sir]{as.sir()}} in the background and therefore depend on the active \code{guideline} setting, which again uses EUCAST 2025 if not set explicitly. +} \item \code{AMR_guideline} \cr A \link{character} to set the default guideline for interpreting MIC values and disk diffusion diameters with \code{\link[=as.sir]{as.sir()}}. Can be only the guideline name (e.g., \code{"CLSI"}) or the name with a year (e.g. \code{"CLSI 2019"}). The default to the latest implemented EUCAST guideline, currently \code{"EUCAST 2025"}. Supported guideline are currently EUCAST (2011-2025) and CLSI (2011-2025). \item \code{AMR_ignore_pattern} \cr A \link[base:regex]{regular expression} to ignore (i.e., make \code{NA}) any match given in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions. \item \code{AMR_include_PKPD} \cr A \link{logical} to use in \code{\link[=as.sir]{as.sir()}}, to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. @@ -43,7 +52,7 @@ In this file, you can set options such as... ...to add Portuguese language support of antimicrobials, and allow PK/PD rules when interpreting MIC values with \code{\link[=as.sir]{as.sir()}}. \subsection{Share Options Within Team}{ -For a more global approach, e.g. within a (data) team, save an options file to a remote file location, such as a shared network drive, and have each user read in this file automatically at start-up. This would work in this way: +For a more collaborative approach, e.g. within a (data) team, save an options file to a remote file location, such as a shared network drive, and have each user read in this file automatically at start-up. This would work in this way: \enumerate{ \item Save a plain text file to e.g. "X:/team_folder/R_options.R" and fill it with preferred settings. \item For each user, open the \code{.Rprofile} file using \code{utils::file.edit("~/.Rprofile")} and put in there: diff --git a/man/as.sir.Rd b/man/as.sir.Rd index 279038b15..8d4bbb441 100644 --- a/man/as.sir.Rd +++ b/man/as.sir.Rd @@ -247,9 +247,9 @@ Regarding choice of veterinary guidelines, these might be the best options to se \subsection{After Interpretation}{ -After using \code{\link[=as.sir]{as.sir()}}, you can use the \code{\link[=eucast_rules]{eucast_rules()}} defined by EUCAST to (1) apply inferred susceptibility and resistance based on results of other antimicrobials and (2) apply intrinsic resistance based on taxonomic properties of a microorganism. +After using \code{\link[=as.sir]{as.sir()}}, you can use the \code{\link[=interpretive_rules]{interpretive_rules()}} to (1) apply inferred susceptibility and resistance based on results of other antimicrobials and (2) apply intrinsic resistance based on taxonomic properties of a microorganism. -To determine which isolates are multi-drug resistant, be sure to run \code{\link[=mdro]{mdro()}} (which applies the MDR/PDR/XDR guideline from 2012 at default) on a data set that contains S/I/R values. Read more about \link[=mdro]{interpreting multidrug-resistant organisms here}. +To determine which isolates are multi-drug resistant, be sure to run \code{\link[=mdro]{mdro()}} (which applies the MDR/PDR/XDR guideline from 2012 at default) on a data set that contains S/I/R values. Read more about \link[=mdro]{detecting multidrug-resistant organisms here}. } \subsection{Other}{ diff --git a/man/count.Rd b/man/count.Rd index 3cf1c59f3..43d5de5cc 100644 --- a/man/count.Rd +++ b/man/count.Rd @@ -14,9 +14,11 @@ \alias{count_df} \title{Count Available Isolates} \usage{ -count_resistant(..., only_all_tested = FALSE) +count_resistant(..., only_all_tested = FALSE, + guideline = getOption("AMR_guideline", "EUCAST")) -count_susceptible(..., only_all_tested = FALSE) +count_susceptible(..., only_all_tested = FALSE, + guideline = getOption("AMR_guideline", "EUCAST")) count_S(..., only_all_tested = FALSE) @@ -40,6 +42,14 @@ count_df(data, translate_ab = "name", language = get_AMR_locale(), \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below.} +\item{guideline}{Either \code{"EUCAST"} (default) or \code{"CLSI"}. With EUCAST, the 'I' category will be considered as susceptible (see \href{https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}{EUCAST website}), but with with CLSI, it will be considered resistant. Therefore: +\itemize{ +\item EUCAST: \code{\link[=count_susceptible]{count_susceptible()}} \eqn{= N_{S} + N_{I}}, \code{\link[=count_resistant]{count_resistant()}} \eqn{= N_{R}} +\item CLSI: \code{\link[=count_susceptible]{count_susceptible()}} \eqn{= N_{S} + N_{SDD}}, \code{\link[=count_resistant]{count_resistant()}} \eqn{= N_{I} + N_{R}} +} + +You can also use e.g. \code{\link[=count_R]{count_R()}} or \code{\link[=count_S]{count_S()}} instead, to be explicit.} + \item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}}).} \item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}.} @@ -59,9 +69,7 @@ These functions can be used to count resistant/susceptible microbial isolates. A \details{ These functions are meant to count isolates. Use the \code{\link[=resistance]{resistance()}}/\code{\link[=susceptibility]{susceptibility()}} functions to calculate microbial resistance/susceptibility. -The function \code{\link[=count_resistant]{count_resistant()}} is equal to the function \code{\link[=count_R]{count_R()}}. The function \code{\link[=count_susceptible]{count_susceptible()}} is equal to the function \code{\link[=count_SI]{count_SI()}}. - -The function \code{\link[=n_sir]{n_sir()}} is an alias of \code{\link[=count_all]{count_all()}}. They can be used to count all available isolates, i.e. where all input antimicrobials have an available result (S, I or R). Their use is equal to \code{n_distinct()}. Their function is equal to \code{count_susceptible(...) + count_resistant(...)}. +The function \code{\link[=n_sir]{n_sir()}} is an alias of \code{\link[=count_all]{count_all()}}. They can be used to count all available isolates, i.e. where all input antimicrobials have an available result (S, I or R). Their use is equal to \code{dplyr}'s \code{n_distinct()}. Their function is equal to \code{count_susceptible(...) + count_resistant(...)}. The function \code{\link[=count_df]{count_df()}} takes any variable from \code{data} that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) and counts the number of S's, I's and R's. It also supports grouped variables. The function \code{\link[=sir_df]{sir_df()}} works exactly like \code{\link[=count_df]{count_df()}}, but adds the percentage of S, I and R. } diff --git a/man/proportion.Rd b/man/proportion.Rd index a77609d32..96824377d 100644 --- a/man/proportion.Rd +++ b/man/proportion.Rd @@ -19,10 +19,12 @@ } \usage{ resistance(..., minimum = 30, as_percent = FALSE, - only_all_tested = FALSE) + only_all_tested = FALSE, guideline = getOption("AMR_guideline", + "EUCAST")) susceptibility(..., minimum = 30, as_percent = FALSE, - only_all_tested = FALSE) + only_all_tested = FALSE, guideline = getOption("AMR_guideline", + "EUCAST")) sir_confidence_interval(..., ab_result = "R", minimum = 30, as_percent = FALSE, only_all_tested = FALSE, confidence_level = 0.95, @@ -60,6 +62,14 @@ sir_df(data, translate_ab = "name", language = get_AMR_locale(), \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below.} +\item{guideline}{Either \code{"EUCAST"} (default) or \code{"CLSI"}. With EUCAST, the 'I' category will be considered as susceptible (see \href{https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}{EUCAST website}), but with with CLSI, it will be considered resistant. Therefore: +\itemize{ +\item EUCAST: \code{\link[=susceptibility]{susceptibility()}} \eqn{= \%S + \%I}, \code{\link[=resistance]{resistance()}} \eqn{= \%R} +\item CLSI: \code{\link[=susceptibility]{susceptibility()}} \eqn{= \%S + \%SDD}, \code{\link[=resistance]{resistance()}} \eqn{= \%I + \%R} +} + +You can also use e.g. \code{\link[=proportion_R]{proportion_R()}} or \code{\link[=proportion_S]{proportion_S()}} instead, to be explicit.} + \item{ab_result}{Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R".} \item{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 \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.} diff --git a/tests/testthat/test-count.R b/tests/testthat/test-count.R index e27555d0a..c298fba65 100644 --- a/tests/testthat/test-count.R +++ b/tests/testthat/test-count.R @@ -30,8 +30,10 @@ test_that("test-count.R", { skip_on_cran() - expect_equal(count_resistant(example_isolates$AMX), count_R(example_isolates$AMX)) - expect_equal(count_susceptible(example_isolates$AMX), count_SI(example_isolates$AMX)) + expect_equal(count_R(example_isolates$AMX), count_resistant(example_isolates$AMX)) + expect_equal(count_SI(example_isolates$AMX), count_susceptible(example_isolates$AMX)) + expect_equal(count_IR(example_isolates$AMX), count_resistant(example_isolates$AMX, guideline = "CLSI")) + expect_equal(count_S(example_isolates$AMX), count_susceptible(example_isolates$AMX, guideline = "CLSI")) expect_equal(count_all(example_isolates$AMX), n_sir(example_isolates$AMX)) # AMX resistance in `example_isolates` diff --git a/tests/testthat/test-proportion.R b/tests/testthat/test-proportion.R index bce5c78c7..93a01ad6e 100755 --- a/tests/testthat/test-proportion.R +++ b/tests/testthat/test-proportion.R @@ -32,6 +32,8 @@ test_that("test-proportion.R", { expect_equal(proportion_R(example_isolates$AMX), resistance(example_isolates$AMX)) expect_equal(proportion_SI(example_isolates$AMX), susceptibility(example_isolates$AMX)) + expect_equal(proportion_IR(example_isolates$AMX), resistance(example_isolates$AMX, guideline = "CLSI")) + expect_equal(proportion_S(example_isolates$AMX), susceptibility(example_isolates$AMX, guideline = "CLSI")) # AMX resistance in `example_isolates` expect_equal(proportion_R(example_isolates$AMX), 0.5955556, tolerance = 0.0001) expect_equal(proportion_I(example_isolates$AMX), 0.002222222, tolerance = 0.0001)