(v0.9.0.9026) update documentation

R/amr.R

@@ -38,15 +38,17 @@
 #' - Getting properties for any microorganism (like Gram stain, species, genus or family)
 #' - Getting properties for any antibiotic (like name, EARS-Net code, ATC code, PubChem code, defined daily dose or trade name)
 #' - Plotting antimicrobial resistance
-#' - Applying EUCAST expert rules
+#' - Getting SNOMED codes of a microorganism, or get its name associated with a SNOMED code
+#' - Getting LOINC codes of an antibiotic, or get its name associated with a LOINC code
+#' - Machine reading the EUCAST and CLSI guidelines from 2011-2020 to translate MIC values and disk diffusion diameters to R/SI
 
 #' @section Read more on our website!:
-#' On our website <https://msberends.gitlab.io/AMR> you can find [a tutorial](https://msberends.gitlab.io/AMR/articles/AMR.html) about how to conduct AMR analysis, the [complete documentation of all functions](https://msberends.gitlab.io/AMR/reference) (which reads a lot easier than here in R) and [an example analysis using WHONET data](https://msberends.gitlab.io/AMR/articles/WHONET.html).
+#' On our website <https://msberends.gitlab.io/AMR> you can find [a comprehensive tutorial](https://msberends.gitlab.io/AMR/articles/AMR.html) about how to conduct AMR analysis, the [complete documentation of all functions](https://msberends.gitlab.io/AMR/reference) (which reads a lot easier than here in R) and [an example analysis using WHONET data](https://msberends.gitlab.io/AMR/articles/WHONET.html).
 #' @section Contact us:
 #' For suggestions, comments or questions, please contact us at:
 #'
 #' Matthijs S. Berends \cr
-#' m.s.berends at umcg dot nl \cr
+#' m.s.berends \[at\] umcg \[dot\] nl \cr
 #' Department of Medical Microbiology, University of Groningen \cr
 #' University Medical Center Groningen \cr
 #' Post Office Box 30001 \cr

R/data.R

@@ -205,8 +205,8 @@ catalogue_of_life <- list(
 #' - `ab`\cr Antibiotic ID, see [as.ab()]
 #' - `ref_tbl`\cr Info about where the guideline rule can be found
 #' - `disk_dose`\cr Dose of the used disk diffusion method
-#' - `breakpoint_S`\cr Lowest MIC value or highest number of millimeters that leads to "S"
-#' - `breakpoint_R`\cr Highest MIC value or lowest number of millimeters that leads to "R"
+#' - `breakpoint_S`\cr Lowest MIC value or highest number of millimetres that leads to "S"
+#' - `breakpoint_R`\cr Highest MIC value or lowest number of millimetres that leads to "R"
 #' @details The repository of this `AMR` package contains a file comprising this exact data set: <https://gitlab.com/msberends/AMR/blob/master/data-raw/rsi_translation.txt>. This file **allows for machine reading EUCAST and CLSI guidelines**, which is almost impossible with the Excel and PDF files distributed by EUCAST and CLSI. This file is updated automatically.
 #' @inheritSection AMR Read more on our website!
 "rsi_translation"

R/disk.R

@@ -21,7 +21,7 @@
 
 #' Class 'disk'
 #'
-#' This transforms a vector to a new class [`disk`], which is a growth zone size (around an antibiotic disk) in millimeters between 6 and 50.
+#' This transforms a vector to a new class [`disk`], which is a growth zone size (around an antibiotic disk) in millimetres between 6 and 50.
 #' @inheritSection lifecycle Stable lifecycle
 #' @rdname as.disk
 #' @param x vector
@@ -33,15 +33,22 @@
 #' @seealso [as.rsi()]
 #' @inheritSection AMR Read more on our website!
 #' @examples
-#' # interpret disk values
-#' as.rsi(x = 12,
-#'        mo = as.mo("S. pneumoniae"),
-#'        ab = "AMX",
+#' # transform existing disk zones to the `disk` class
+#' df <- data.frame(microorganism = "E. coli",
+#'                  AMP = 20,
+#'                  CIP = 14,
+#'                  GEN = 18,
+#'                  TOB = 16)
+#' df <- df %>% mutate_at(vars(AMP:TOB, as.disk))
+#' df
+#' 
+#' # interpret disk values, see ?as.rsi
+#' as.rsi(x = as.disk(18),
+#'        mo = "Strep pneu",  # `mo` will be coerced with as.mo()
+#'        ab = "ampicillin",  # and `ab` with as.ab()
 #'        guideline = "EUCAST")
-#' as.rsi(x = 12,
-#'        mo = as.mo("S. pneumoniae"),
-#'        ab = "AMX",
-#'        guideline = "CLSI")
+#'        
+#' as.rsi(df)
 as.disk <- function(x, na.rm = FALSE) {
   if (is.disk(x)) {
     x

R/eucast_rules.R

@@ -20,7 +20,7 @@
 # ==================================================================== #
 
 # global variables
-EUCAST_VERSION_BREAKPOINTS <- "9.0, 2019"
+EUCAST_VERSION_BREAKPOINTS <- "10.0, 2020"
 EUCAST_VERSION_EXPERT_RULES <- "3.1, 2016"
 
 #' Apply EUCAST rules
@@ -655,9 +655,11 @@ eucast_rules <- function(x,
         cat(bold(
           case_when(
             rule_group_current %like% "breakpoint" ~
-              paste0("\nEUCAST Clinical Breakpoints (v", EUCAST_VERSION_BREAKPOINTS, ")\n"),
+              paste0("\nEUCAST Clinical Breakpoints (",
+                     red(paste0("v", EUCAST_VERSION_BREAKPOINTS)), ")\n"),
             rule_group_current %like% "expert" ~
-              paste0("\nEUCAST Expert Rules, Intrinsic Resistance and Exceptional Phenotypes (v", EUCAST_VERSION_EXPERT_RULES, ")\n"),
+              paste0("\nEUCAST Expert Rules, Intrinsic Resistance and Exceptional Phenotypes (", 
+                     red(paste0("v", EUCAST_VERSION_EXPERT_RULES)), ")\n"),
             TRUE ~
               "\nOther rules by this AMR package\n"
           )

R/proportion.R

@@ -21,7 +21,7 @@
 
 #' Calculate microbial resistance
 #'
-#' @description These functions can be used to calculate the (co-)resistance or susceptibility of microbial isolates (i.e. percentage of S, SI, I, IR or R). All functions support quasiquotation with pipes, can be used in [dplyr::summarise()] and support grouped variables, please see *Examples*.
+#' @description These functions can be used to calculate the (co-)resistance or susceptibility of microbial isolates (i.e. percentage of S, SI, I, IR or R). All functions support quasiquotation with pipes, can be used in `summarise()`][dplyr::summarise()] and also support grouped variables, please see *Examples*.
 #'
 #' [resistance()] should be used to calculate resistance, [susceptibility()] should be used to calculate susceptibility.\cr
 #' @inheritSection lifecycle Stable lifecycle
@@ -40,11 +40,11 @@
 #'  
 #' **Remember that you should filter your table to let it contain only first isolates!** This is needed to exclude duplicates and to reduce selection bias. Use [first_isolate()] to determine them in your data set.
 #'
-#' These functions are not meant to count isolates, but to calculate the proportion of resistance/susceptibility. Use the [AMR::count()] functions to count isolates. The function [susceptibility()] is essentially equal to `count_susceptible() / count_all()`. *Low counts can infuence the outcome - the `proportion` functions may camouflage this, since they only return the proportion (albeit being dependent on the `minimum` parameter).*
+#' These functions are not meant to count isolates, but to calculate the proportion of resistance/susceptibility. Use the `count()`][AMR::count()] functions to count isolates. The function [susceptibility()] is essentially equal to `count_susceptible() / count_all()`. *Low counts can influence the outcome - the `proportion` functions may camouflage this, since they only return the proportion (albeit being dependent on the `minimum` parameter).*
 #'
 #' The function [proportion_df()] takes any variable from `data` that has an [`rsi`] class (created with [as.rsi()]) and calculates the proportions R, I and S. The function [rsi_df()] works exactly like [proportion_df()], but adds the number of isolates.
 #' @section Combination therapy:
-#' When using more than one variable for `...` (= combination therapy)), use `only_all_tested` to only count isolates that are tested for all antibiotics/variables that you test them for. See this example for two antibiotics, Antibiotic A and Antibiotic B, about how [susceptibility()] works to calculate the %SI:
+#' When using more than one variable for `...` (= combination therapy)), use `only_all_tested` to only count isolates that are tested for all antibiotics/variables that you test them for. See this example for two antibiotics, Drug A and Drug B, about how [susceptibility()] works to calculate the %SI:
 #'
 #' ```
 #' --------------------------------------------------------------------

R/rsi.R

@@ -24,9 +24,9 @@
 #' Interpret MIC values and disk diffusion diameters according to EUCAST or CLSI, or clean up existing R/SI values. This transforms the input to a new class [`rsi`], which is an ordered factor with levels `S < I < R`. Invalid antimicrobial interpretations will be translated as `NA` with a warning.
 #' @inheritSection lifecycle Stable lifecycle
 #' @rdname as.rsi
-#' @param x vector of values (for class [`mic`]: an MIC value in mg/L, for class [`disk`]: a disk diffusion radius in millimeters)
-#' @param mo a microorganism code, generated with [as.mo()]
-#' @param ab an antimicrobial code, generated with [as.ab()]
+#' @param x vector of values (for class [`mic`]: an MIC value in mg/L, for class [`disk`]: a disk diffusion radius in millimetres)
+#' @param mo any (vector of) text that can be coerced to a valid microorganism code with [as.mo()]
+#' @param ab any (vector of) text that can be coerced to a valid antimicrobial code with [as.ab()]
 #' @inheritParams first_isolate
 #' @param guideline defaults to the latest included EUCAST guideline, run `unique(rsi_translation$guideline)` for all options
 #' @param threshold maximum fraction of invalid antimicrobial interpretations of `x`, please see *Examples*
@@ -71,8 +71,10 @@
 #'        
 #' # a whole data set, even with combined MIC values and disk zones
 #' df <- data.frame(microorganism = "E. coli",
-#'                  AMP = as.mic(12),
-#'                  GEN = as.disk(18))
+#'                  AMP = as.mic(8),
+#'                  CIP = as.mic(0.256),
+#'                  GEN = as.disk(18),
+#'                  TOB = as.disk(16))
 #' as.rsi(df)
 #'
 #'
@@ -239,12 +241,12 @@ exec_as.rsi <- function(method, x, mo, ab, guideline) {
   if (guideline_coerced != guideline) {
     message(blue(paste0("Note: Using guideline ", bold(guideline_coerced), " as input for `guideline`.")))
   }
-
+  
   new_rsi <- rep(NA_character_, length(x))
   trans <- rsi_translation %>%
     filter(guideline == guideline_coerced & method == method_param) %>%
     mutate(lookup = paste(mo, ab))
-
+  
   lookup_mo <- paste(mo, ab)
   lookup_genus <- paste(mo_genus, ab)
   lookup_family <- paste(mo_family, ab)