diff --git a/DESCRIPTION b/DESCRIPTION index 370998a4..3416b11d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: AMR -Version: 1.8.2.9119 +Version: 1.8.2.9120 Date: 2023-02-12 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) diff --git a/NEWS.md b/NEWS.md index 46a067b6..2eaeb069 100755 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 1.8.2.9119 +# AMR 1.8.2.9120 *(this beta version will eventually become v2.0! We're happy to reach a new major milestone soon!)* @@ -37,6 +37,8 @@ Furthermore, different plotting methods were implemented to allow for graphical ### Interpretation of MIC and disk diffusion values The clinical breakpoints and intrinsic resistance of EUCAST 2022 and CLSI 2022 have been added for `as.sir()`. EUCAST 2022 (v12.0) is now the new default guideline for all MIC and disks diffusion interpretations, and for `eucast_rules()` to apply EUCAST Expert Rules. The default guideline (EUCAST) can now be changed with the new `AMR_guideline` option, such as: `options(AMR_guideline = "CLSI 2020")`. + +With the new arguments `include_PKPD` (default: `TRUE`) and `include_screening` (default: `FALSE`), users can now specify whether breakpoints for screening and from the PK/PD table should be included when interpreting MICs and disks diffusion values. These options can be set globally, which can be read in [our new manual](https://msberends.github.io/AMR/reference/AMR-options.html). Interpretation guidelines older than 10 years were removed, the oldest now included guidelines of EUCAST and CLSI are from 2013. @@ -132,6 +134,7 @@ We now added extensive support for antiviral agents! For the first time, the `AM * Fix for `mo_shortname()` in case of higher taxonomic ranks (order, class, phylum) * Cleaning columns with `as.sir()`, `as.mic()`, or `as.disk()` will now show the column name in the warning for invalid results * Fix for using `g.test()` with zeroes in a 2x2 table +* `get_episode()` now returns class `integer` instead of `numeric` since they are always whole numbers ## Other diff --git a/R/aa_options.R b/R/aa_options.R index 5f0a3cf8..633690c0 100755 --- a/R/aa_options.R +++ b/R/aa_options.R @@ -37,6 +37,7 @@ #' * `AMR_guideline` \cr Used for setting 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 is \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 define input that must be ignored 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, defaults to `TRUE`. +#' * `AMR_include_screening` \cr A [logical] to use in [as.sir()], to indicate that clinical breakpoints for screening are allowed, defaults to `FALSE`. #' * `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. #' * `AMR_locale` \cr A language to use for the `AMR` package, can be one of these supported language names or ISO-639-1 codes: `r vector_or(paste0(sapply(LANGUAGES_SUPPORTED_NAMES, function(x) x[[1]]), " (" , LANGUAGES_SUPPORTED, ")"), quotes = FALSE, sort = FALSE)`. #' * `AMR_mo_source` \cr A file location for a manual code list to be used in [as.mo()] and all [`mo_*`][mo_property()] functions. This is explained in [set_mo_source()]. @@ -48,7 +49,14 @@ #' utils::file.edit("~/.Rprofile") #' ``` #' -#' In this file, you can set options such as `options(AMR_locale = "pt")` for Portuguese language support of antibiotics. +#' In this file, you can set options such as: +#' +#' ```r +#' options(AMR_locale = "pt") +#' options(AMR_include_PKPD = TRUE) +#' ``` +#' +#' to add Portuguese language support of antibiotics, and allow PK/PD rules when interpreting MIC values with [as.sir()]. #' #' ### Share Options Within Team #' diff --git a/R/get_episode.R b/R/get_episode.R index 398cc210..4c3c5c6b 100755 --- a/R/get_episode.R +++ b/R/get_episode.R @@ -27,20 +27,31 @@ # how to conduct AMR data analysis: https://msberends.github.io/AMR/ # # ==================================================================== # -#' Determine (New) Episodes for Patients +#' Determine (Clinical) Episodes #' #' These functions determine which items in a vector can be considered (the start of) a new episode, based on the argument `episode_days`. This can be used to determine clinical episodes for any epidemiological analysis. The [get_episode()] function returns the index number of the episode per group, while the [is_new_episode()] function returns `TRUE` for every new [get_episode()] index, and is thus equal to `!duplicated(get_episode(...))`. #' @param x vector of dates (class `Date` or `POSIXt`), will be sorted internally to determine episodes #' @param episode_days required episode length in days, can also be less than a day or `Inf`, see *Details* #' @param ... ignored, only in place to allow future extensions -#' @details +#' @details The functions [get_episode()] and [is_new_episode()] differ in this way when setting `episode_days` to 365: +#' +#' +#' | person_id | date | `get_episode()` | `is_new_episode()` | +#' |:---------:|:----------:|:---------------:|:------------------:| +#' | A | 2019-01-01 | 1 | TRUE | +#' | A | 2019-03-01 | 1 | FALSE | +#' | A | 2021-01-01 | 2 | TRUE | +#' | B | 2008-01-01 | 1 | TRUE | +#' | B | 2008-01-01 | 1 | FALSE | +#' | C | 2020-01-01 | 1 | TRUE | +#' #' Dates are first sorted from old to new. The oldest date will mark the start of the first episode. After this date, the next date will be marked that is at least `episode_days` days later than the start of the first episode. From that second marked date on, the next date will be marked that is at least `episode_days` days later than the start of the second episode which will be the start of the third episode, and so on. Before the vector is being returned, the original order will be restored. #' #' The [first_isolate()] function is a wrapper around the [is_new_episode()] function, but is more efficient for data sets containing microorganism codes or names and allows for different isolate selection methods. #' #' The `dplyr` package is not required for these functions to work, but these episode functions do support [variable grouping][dplyr::group_by()] and work conveniently inside `dplyr` verbs such as [`filter()`][dplyr::filter()], [`mutate()`][dplyr::mutate()] and [`summarise()`][dplyr::summarise()]. #' @return -#' * [get_episode()]: a [double] vector +#' * [get_episode()]: an [integer] vector #' * [is_new_episode()]: a [logical] vector #' @seealso [first_isolate()] #' @rdname get_episode @@ -68,12 +79,13 @@ #' df %>% #' mutate(condition = sample( #' x = c("A", "B", "C"), -#' size = 200, +#' size = 100, #' replace = TRUE #' )) %>% -#' group_by(condition) %>% +#' group_by(patient, condition) %>% #' mutate(new_episode = is_new_episode(date, 365)) %>% -#' select(patient, date, condition, new_episode) +#' select(patient, date, condition, new_episode) %>% +#' arrange(patient, condition, date) #' } #' #' if (require("dplyr")) { @@ -128,7 +140,7 @@ get_episode <- function(x, episode_days, ...) { meet_criteria(x, allow_class = c("Date", "POSIXt"), allow_NA = TRUE) meet_criteria(episode_days, allow_class = c("numeric", "integer"), has_length = 1, is_positive = TRUE, is_finite = FALSE) - exec_episode(x, episode_days, ...) + as.integer(exec_episode(x, episode_days, ...)) } #' @rdname get_episode diff --git a/R/sir.R b/R/sir.R index c4e85a1e..abcd2250 100755 --- a/R/sir.R +++ b/R/sir.R @@ -29,16 +29,19 @@ #' Translate MIC and Disk Diffusion to SIR, or Clean Existing SIR Data #' -#' Interpret minimum inhibitory concentration (MIC) values and disk diffusion diameters according to EUCAST or CLSI, or clean up existing SIR values. This transforms the input to a new class [`sir`], which is an ordered [factor] with levels `S < I < R`. +#' @description Interpret minimum inhibitory concentration (MIC) values and disk diffusion diameters according to EUCAST or CLSI, or clean up existing SIR values. This transforms the input to a new class [`sir`], which is an ordered [factor] with levels `S < I < R`. +#' +#' All breakpoints used for interpretation are publicly available in the [clinical_breakpoints] data set. #' @rdname as.sir #' @param x vector of values (for class [`mic`]: MIC values in mg/L, for class [`disk`]: a disk diffusion radius in millimetres) #' @param mo any (vector of) text that can be coerced to valid microorganism codes with [as.mo()], can be left empty to determine it automatically #' @param ab any (vector of) text that can be coerced to a valid antimicrobial drug code with [as.ab()] #' @param uti (Urinary Tract Infection) A vector with [logical]s (`TRUE` or `FALSE`) to specify whether a UTI specific interpretation from the guideline should be chosen. For using [as.sir()] on a [data.frame], this can also be a column containing [logical]s or when left blank, the data set will be searched for a column 'specimen', and rows within this column containing 'urin' (such as 'urine', 'urina') will be regarded isolates from a UTI. See *Examples*. #' @inheritParams first_isolate -#' @param guideline defaults to EUCAST `r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))` (the latest implemented EUCAST guideline in the [clinical_breakpoints] data set), but can be set with the option [`AMR_guideline`][AMR-options]. Currently supports 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)))`), see *Details*. +#' @param guideline defaults to EUCAST `r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))` (the latest implemented EUCAST guideline in the [AMR::clinical_breakpoints] data set), but can be set with the option [`AMR_guideline`][AMR-options]. Currently supports EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`) and CLSI (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`), see *Details*. #' @param conserve_capped_values a [logical] to indicate that MIC values starting with `">"` (but not `">="`) must always return "R" , and that MIC values starting with `"<"` (but not `"<="`) must always return "S" #' @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 include_screening a [logical] to indicate that clinical breakpoints for screening are allowed, defaults to `FALSE`. Can also be set with the option [`AMR_include_screening`][AMR-options]. #' @param include_PKPD a [logical] to indicate that PK/PD clinical breakpoints must be applied as a last resort, defaults to `TRUE`. Can also be set with the option [`AMR_include_PKPD`][AMR-options]. #' @param reference_data a [data.frame] to be used for interpretation, which defaults to the [clinical_breakpoints] data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the [clinical_breakpoints] data set (same column names and column types). Please note that the `guideline` argument will be ignored when `reference_data` is manually set. #' @param threshold maximum fraction of invalid antimicrobial interpretations of `x`, see *Examples* @@ -69,9 +72,9 @@ #' #' ### Supported Guidelines #' -#' For interpreting MIC values as well as disk diffusion diameters, currently implemented guidelines are 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)))`). +#' For interpreting MIC values as well as disk diffusion diameters, currently implemented guidelines are EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`) and CLSI (`r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`). #' -#' Thus, the `guideline` argument must be set to e.g., ``r paste0('"', subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline[1], '"')`` or ``r paste0('"', subset(clinical_breakpoints, guideline %like% "CLSI")$guideline[1], '"')``. By simply using `"EUCAST"` (the default) or `"CLSI"` as input, the latest included version of that guideline will automatically be selected. You can set your own data set using the `reference_data` argument. The `guideline` argument will then be ignored. +#' Thus, the `guideline` argument must be set to e.g., ``r paste0('"', subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline[1], '"')`` or ``r paste0('"', subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline[1], '"')``. By simply using `"EUCAST"` (the default) or `"CLSI"` as input, the latest included version of that guideline will automatically be selected. You can set your own data set using the `reference_data` argument. The `guideline` argument will then be ignored. #' #' You can set the default guideline with the option [`AMR_guideline`][AMR-options] (e.g. in your `.Rprofile` file), such as: #' @@ -87,7 +90,7 @@ #' #' 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. #' -#' ### Machine-Readable Interpretation Guidelines +#' ### Machine-Readable Clinical Breakpoints #' #' The repository of this package [contains a machine-readable version](https://github.com/msberends/AMR/blob/main/data-raw/clinical_breakpoints.txt) of all guidelines. This is a CSV file consisting of `r format(nrow(AMR::clinical_breakpoints), big.mark = " ")` rows and `r ncol(AMR::clinical_breakpoints)` columns. This file is machine-readable, since it contains one row for every unique combination of the test method (MIC or disk diffusion), the antimicrobial drug and the microorganism. **This allows for easy implementation of these rules in laboratory information systems (LIS)**. Note that it only contains interpretation guidelines for humans - interpretation guidelines from CLSI for animals were removed. #' @@ -116,9 +119,9 @@ #' @source #' For interpretations of minimum inhibitory concentration (MIC) values and disk diffusion diameters: #' -#' - **M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data**, `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)))`, *Clinical and Laboratory Standards Institute* (CLSI). . -#' - **M100 Performance Standard for Antimicrobial Susceptibility Testing**, `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)))`, *Clinical and Laboratory Standards Institute* (CLSI). . -#' - **Breakpoint tables for interpretation of MICs and zone diameters**, `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)))`, *European Committee on Antimicrobial Susceptibility Testing* (EUCAST). . +#' - **M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data**, `r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`, *Clinical and Laboratory Standards Institute* (CLSI). . +#' - **M100 Performance Standard for Antimicrobial Susceptibility Testing**, `r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "CLSI")$guideline)))`, *Clinical and Laboratory Standards Institute* (CLSI). . +#' - **Breakpoint tables for interpretation of MICs and zone diameters**, `r min(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(AMR::clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`, *European Committee on Antimicrobial Susceptibility Testing* (EUCAST). . #' @inheritSection AMR Reference Data Publicly Available #' @examples #' example_isolates @@ -418,6 +421,7 @@ as.sir.mic <- function(x, conserve_capped_values = FALSE, add_intrinsic_resistance = FALSE, reference_data = AMR::clinical_breakpoints, + include_screening = getOption("AMR_include_screening", FALSE), include_PKPD = getOption("AMR_include_PKPD", TRUE), ...) { as_sir_method( @@ -431,6 +435,7 @@ as.sir.mic <- function(x, conserve_capped_values = conserve_capped_values, add_intrinsic_resistance = add_intrinsic_resistance, reference_data = reference_data, + include_screening = include_screening, include_PKPD = include_PKPD, ... ) @@ -445,6 +450,7 @@ as.sir.disk <- function(x, uti = NULL, add_intrinsic_resistance = FALSE, reference_data = AMR::clinical_breakpoints, + include_screening = getOption("AMR_include_screening", FALSE), include_PKPD = getOption("AMR_include_PKPD", TRUE), ...) { as_sir_method( @@ -458,6 +464,7 @@ as.sir.disk <- function(x, conserve_capped_values = FALSE, add_intrinsic_resistance = add_intrinsic_resistance, reference_data = reference_data, + include_screening = include_screening, include_PKPD = include_PKPD, ... ) @@ -473,6 +480,7 @@ as.sir.data.frame <- function(x, conserve_capped_values = FALSE, add_intrinsic_resistance = FALSE, reference_data = AMR::clinical_breakpoints, + include_screening = getOption("AMR_include_screening", FALSE), include_PKPD = getOption("AMR_include_PKPD", TRUE)) { meet_criteria(x, allow_class = "data.frame") # will also check for dimensions > 0 meet_criteria(col_mo, allow_class = "character", is_in = colnames(x), allow_NULL = TRUE) @@ -610,6 +618,7 @@ as.sir.data.frame <- function(x, conserve_capped_values = conserve_capped_values, add_intrinsic_resistance = add_intrinsic_resistance, reference_data = reference_data, + include_screening = include_screening, include_PKPD = include_PKPD, is_data.frame = TRUE ) @@ -626,6 +635,7 @@ as.sir.data.frame <- function(x, uti = uti, add_intrinsic_resistance = add_intrinsic_resistance, reference_data = reference_data, + include_screening = include_screening, include_PKPD = include_PKPD, is_data.frame = TRUE ) @@ -694,6 +704,7 @@ as_sir_method <- function(method_short, conserve_capped_values, add_intrinsic_resistance, reference_data, + include_screening, include_PKPD, ...) { meet_criteria(x, allow_NA = TRUE, .call_depth = -2) @@ -704,8 +715,9 @@ as_sir_method <- function(method_short, meet_criteria(conserve_capped_values, allow_class = "logical", has_length = 1, .call_depth = -2) 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(include_screening, allow_class = "logical", has_length = 1, .call_depth = -2) meet_criteria(include_PKPD, allow_class = "logical", has_length = 1, .call_depth = -2) - check_reference_data(reference_data) + check_reference_data(reference_data, .call_depth = -2) # for dplyr's across() cur_column_dplyr <- import_fn("cur_column", "dplyr", error_on_fail = FALSE) @@ -860,6 +872,11 @@ as_sir_method <- function(method_short, subset(method == method_coerced & ab == ab_coerced) } + if (isFALSE(include_screening)) { + # remove screening rules from the breakpoints table + breakpoints <- breakpoints %pm>% + subset(site %unlike% "screen" & ref_tbl %unlike% "screen") + } if (isFALSE(include_PKPD)) { # remove PKPD rules from the breakpoints table breakpoints <- breakpoints %pm>% @@ -969,9 +986,12 @@ as_sir_method <- function(method_short, # then run the rules breakpoints_current <- breakpoints_current[1L, , drop = FALSE] - if (breakpoints_current$mo == "UNKNOWN" | breakpoints_current$ref_tbl %like% "PK.*PD") { + if (any(breakpoints_current$mo == "UNKNOWN", na.rm = TRUE) | any(breakpoints_current$ref_tbl %like% "PK.*PD", na.rm = TRUE)) { msgs <- c(msgs, "(Some) PK/PD breakpoints were applied - use `include_PKPD = FALSE` to prevent this") } + if (any(breakpoints_current$site %like% "screen", na.rm = TRUE) | any(breakpoints_current$ref_tbl %like% "screen", na.rm = TRUE)) { + msgs <- c(msgs, "(Some) screening breakpoints were applied - use `include_screening = FALSE` to prevent this") + } if (method == "mic") { new_sir <- quick_case_when( @@ -1254,16 +1274,15 @@ rep.sir <- function(x, ...) { y } -check_reference_data <- function(reference_data) { +check_reference_data <- function(reference_data, .call_depth) { if (!identical(reference_data, AMR::clinical_breakpoints)) { - class_sir <- vapply(FUN.VALUE = character(1), clinical_breakpoints, function(x) paste0("<", class(x), ">", collapse = " and ")) + class_sir <- vapply(FUN.VALUE = character(1), AMR::clinical_breakpoints, function(x) paste0("<", class(x), ">", collapse = " and ")) class_ref <- vapply(FUN.VALUE = character(1), reference_data, function(x) paste0("<", class(x), ">", collapse = " and ")) if (!all(names(class_sir) == names(class_ref))) { - stop_("`reference_data` must have the same column names as the 'clinical_breakpoints' data set.", call = -2) + stop_("`reference_data` must have the same column names as the 'clinical_breakpoints' data set.", call = .call_depth) } if (!all(class_sir == class_ref)) { - class_sir[class_sir != class_ref][1] - stop_("`reference_data` must be the same structure as the 'clinical_breakpoints' data set. Column '", names(class_ref[class_sir != class_ref][1]), "' is of class ", class_ref[class_sir != class_ref][1], ", but should be of class ", class_sir[class_sir != class_ref][1], ".", call = -2) + stop_("`reference_data` must be the same structure as the 'clinical_breakpoints' data set. Column '", names(class_ref[class_sir != class_ref][1]), "' is of class ", class_ref[class_sir != class_ref][1], ", but should be of class ", class_sir[class_sir != class_ref][1], ".", call = .call_depth) } } } diff --git a/man/AMR-options.Rd b/man/AMR-options.Rd index 5b570d4e..314cecc8 100644 --- a/man/AMR-options.Rd +++ b/man/AMR-options.Rd @@ -15,6 +15,7 @@ This is an overview of all the package-specific \code{\link[=options]{options()} \item \code{AMR_guideline} \cr Used for setting 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 is \code{"EUCAST 2022"}. Supported guideline are currently EUCAST (2013-2022) and CLSI (2013-2022). \item \code{AMR_ignore_pattern} \cr A \link[base:regex]{regular expression} to define input that must be ignored 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, defaults to \code{TRUE}. +\item \code{AMR_include_screening} \cr A \link{logical} to use in \code{\link[=as.sir]{as.sir()}}, to indicate that clinical breakpoints for screening are allowed, defaults to \code{FALSE}. \item \code{AMR_keep_synonyms} \cr A \link{logical} to use in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions, to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. \item \code{AMR_locale} \cr A language to use for the \code{AMR} package, can be one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr) or Ukrainian (uk). \item \code{AMR_mo_source} \cr A file location for a manual code list to be used in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions. This is explained in \code{\link[=set_mo_source]{set_mo_source()}}. @@ -28,7 +29,13 @@ Settings in \R are not saved globally and are thus lost when \R is exited. You c \if{html}{\out{
}}\preformatted{ utils::file.edit("~/.Rprofile") }\if{html}{\out{
}} -In this file, you can set options such as \code{options(AMR_locale = "pt")} for Portuguese language support of antibiotics. +In this file, you can set options such as: + +\if{html}{\out{
}}\preformatted{ options(AMR_locale = "pt") + options(AMR_include_PKPD = TRUE) +}\if{html}{\out{
}} + +to add Portuguese language support of antibiotics, 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. This would work in this way: diff --git a/man/as.sir.Rd b/man/as.sir.Rd index c9059e5c..2d1d74a2 100644 --- a/man/as.sir.Rd +++ b/man/as.sir.Rd @@ -41,6 +41,7 @@ is_sir_eligible(x, threshold = 0.05) conserve_capped_values = FALSE, add_intrinsic_resistance = FALSE, reference_data = AMR::clinical_breakpoints, + include_screening = getOption("AMR_include_screening", FALSE), include_PKPD = getOption("AMR_include_PKPD", TRUE), ... ) @@ -53,6 +54,7 @@ is_sir_eligible(x, threshold = 0.05) uti = NULL, add_intrinsic_resistance = FALSE, reference_data = AMR::clinical_breakpoints, + include_screening = getOption("AMR_include_screening", FALSE), include_PKPD = getOption("AMR_include_PKPD", TRUE), ... ) @@ -66,6 +68,7 @@ is_sir_eligible(x, threshold = 0.05) conserve_capped_values = FALSE, add_intrinsic_resistance = FALSE, reference_data = AMR::clinical_breakpoints, + include_screening = getOption("AMR_include_screening", FALSE), include_PKPD = getOption("AMR_include_PKPD", TRUE) ) @@ -92,6 +95,8 @@ sir_interpretation_history(clean = FALSE) \item{reference_data}{a \link{data.frame} to be used for interpretation, which defaults to the \link{clinical_breakpoints} data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the \link{clinical_breakpoints} data set (same column names and column types). Please note that the \code{guideline} argument will be ignored when \code{reference_data} is manually set.} +\item{include_screening}{a \link{logical} to indicate that clinical breakpoints for screening are allowed, defaults to \code{FALSE}. Can also be set with the option \code{\link[=AMR-options]{AMR_include_screening}}.} + \item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort, defaults to \code{TRUE}. Can also be set with the option \code{\link[=AMR-options]{AMR_include_PKPD}}.} \item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}), defaults to the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.} @@ -103,6 +108,8 @@ Ordered \link{factor} with new class \code{sir} } \description{ Interpret minimum inhibitory concentration (MIC) values and disk diffusion diameters according to EUCAST or CLSI, or clean up existing SIR values. This transforms the input to a new class \code{\link{sir}}, which is an ordered \link{factor} with levels \verb{S < I < R}. + +All breakpoints used for interpretation are publicly available in the \link{clinical_breakpoints} data set. } \details{ \subsection{How it Works}{ @@ -154,7 +161,7 @@ You can set the default guideline with the option \code{\link[=AMR-options]{AMR_ 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. } -\subsection{Machine-Readable Interpretation Guidelines}{ +\subsection{Machine-Readable Clinical Breakpoints}{ The repository of this package \href{https://github.com/msberends/AMR/blob/main/data-raw/clinical_breakpoints.txt}{contains a machine-readable version} of all guidelines. This is a CSV file consisting of 18 308 rows and 11 columns. This file is machine-readable, since it contains one row for every unique combination of the test method (MIC or disk diffusion), the antimicrobial drug and the microorganism. \strong{This allows for easy implementation of these rules in laboratory information systems (LIS)}. Note that it only contains interpretation guidelines for humans - interpretation guidelines from CLSI for animals were removed. } diff --git a/man/get_episode.Rd b/man/get_episode.Rd index 9af782b4..76874194 100644 --- a/man/get_episode.Rd +++ b/man/get_episode.Rd @@ -3,7 +3,7 @@ \name{get_episode} \alias{get_episode} \alias{is_new_episode} -\title{Determine (New) Episodes for Patients} +\title{Determine (Clinical) Episodes} \usage{ get_episode(x, episode_days, ...) @@ -18,7 +18,7 @@ is_new_episode(x, episode_days, ...) } \value{ \itemize{ -\item \code{\link[=get_episode]{get_episode()}}: a \link{double} vector +\item \code{\link[=get_episode]{get_episode()}}: an \link{integer} vector \item \code{\link[=is_new_episode]{is_new_episode()}}: a \link{logical} vector } } @@ -26,6 +26,17 @@ is_new_episode(x, episode_days, ...) These functions determine which items in a vector can be considered (the start of) a new episode, based on the argument \code{episode_days}. This can be used to determine clinical episodes for any epidemiological analysis. The \code{\link[=get_episode]{get_episode()}} function returns the index number of the episode per group, while the \code{\link[=is_new_episode]{is_new_episode()}} function returns \code{TRUE} for every new \code{\link[=get_episode]{get_episode()}} index, and is thus equal to \code{!duplicated(get_episode(...))}. } \details{ +The functions \code{\link[=get_episode]{get_episode()}} and \code{\link[=is_new_episode]{is_new_episode()}} differ in this way when setting \code{episode_days} to 365:\tabular{cccc}{ + person_id \tab date \tab \code{get_episode()} \tab \code{is_new_episode()} \cr + A \tab 2019-01-01 \tab 1 \tab TRUE \cr + A \tab 2019-03-01 \tab 1 \tab FALSE \cr + A \tab 2021-01-01 \tab 2 \tab TRUE \cr + B \tab 2008-01-01 \tab 1 \tab TRUE \cr + B \tab 2008-01-01 \tab 1 \tab FALSE \cr + C \tab 2020-01-01 \tab 1 \tab TRUE \cr +} + + Dates are first sorted from old to new. The oldest date will mark the start of the first episode. After this date, the next date will be marked that is at least \code{episode_days} days later than the start of the first episode. From that second marked date on, the next date will be marked that is at least \code{episode_days} days later than the start of the second episode which will be the start of the third episode, and so on. Before the vector is being returned, the original order will be restored. The \code{\link[=first_isolate]{first_isolate()}} function is a wrapper around the \code{\link[=is_new_episode]{is_new_episode()}} function, but is more efficient for data sets containing microorganism codes or names and allows for different isolate selection methods. @@ -55,12 +66,13 @@ if (require("dplyr")) { df \%>\% mutate(condition = sample( x = c("A", "B", "C"), - size = 200, + size = 100, replace = TRUE )) \%>\% - group_by(condition) \%>\% + group_by(patient, condition) \%>\% mutate(new_episode = is_new_episode(date, 365)) \%>\% - select(patient, date, condition, new_episode) + select(patient, date, condition, new_episode) \%>\% + arrange(patient, condition, date) } if (require("dplyr")) { diff --git a/pkgdown/extra.css b/pkgdown/extra.css index 0995fd15..a84fbe85 100644 --- a/pkgdown/extra.css +++ b/pkgdown/extra.css @@ -62,6 +62,7 @@ pre code { /* never wrap code on smaller screens */ word-wrap: normal !important; white-space: pre !important; + font-size: 0.8em !important; } .ot, .dv, .fl, .cn, .at, .op a {