mirror of
https://github.com/msberends/AMR.git
synced 2026-02-23 23:39:12 +01:00
(v3.0.1.9021) add guideline to resistance() and susceptibility()
This commit is contained in:
@@ -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.
|
||||
#'
|
||||
|
||||
39
R/count.R
39
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
|
||||
),
|
||||
|
||||
@@ -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))
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
|
||||
4
R/sir.R
4
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
|
||||
#'
|
||||
|
||||
15
R/zzz.R
15
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$") {
|
||||
|
||||
Reference in New Issue
Block a user