documentation

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AMR
-Version: 1.8.2.9074
+Version: 1.8.2.9076
-Date: 2022-12-29
+Date: 2022-12-30
 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

NEWS.md

@@ -1,4 +1,4 @@
-# AMR 1.8.2.9074
+#  1.8.2.9076
 
 *(this beta version will eventually become v2.0! We're happy to reach a new major milestone soon!)*
 
@@ -19,7 +19,7 @@ This is a new major release of the AMR package, with great new additions but als
 
 ### Interpretation of MIC and disk diffusion values
 
-EUCAST 2022 and CLSI 2022 guidelines have been added for `as.rsi()`. 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")`.
+The clinical breakpoints and intrinsic resistance of EUCAST 2022 and CLSI 2022 have been added for `as.rsi()`. 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")`.
  
 Interpretation guidelines older than 10 years were removed, the oldest now included guidelines of EUCAST and CLSI are from 2013.
 
@@ -31,7 +31,7 @@ We are very grateful for the valuable input by our colleagues from other countri
 
 ### Microbiological taxonomy
 
-The `microorganisms` no longer relies on the Catalogue of Life, but on the List of Prokaryotic names with Standing in Nomenclature (LPSN) and is supplemented with the 'backbone taxonomy' from the Global Biodiversity Information Facility (GBIF). The structure of this data set has changed to include separate LPSN and GBIF identifiers. Almost all previous MO codes were retained. It contains over 1,400 taxonomic names from 2022.
+The `microorganisms` data set no longer relies on the Catalogue of Life, but on the List of Prokaryotic names with Standing in Nomenclature (LPSN) and is supplemented with the 'backbone taxonomy' from the Global Biodiversity Information Facility (GBIF). The structure of this data set has changed to include separate LPSN and GBIF identifiers. Almost all previous MO codes were retained. It contains over 1,400 taxonomic names from 2022.
 
 We previously relied on our own experience to categorise species into pathogenic groups, but we were very happy to encounter the very recent work of Bartlett *et al.* (2022, DOI [10.1099/mic.0.001269](https://doi.org/10.1099/mic.0.001269)) who extensively studied medical-scientific literature to categorise all bacterial species into groups. See `mo_matching_score()` on how their work was incorporated into the `prevalence` column of the `microorganisms` data set. Using their results, the `as.mo()` and all `mo_*()` functions are now much better capable of converting user input to valid taxonomic records.
 
@@ -40,7 +40,7 @@ The new function `add_custom_microorganisms()` allows users to add custom microo
 We also made the following changes regarding the included taxonomy or microorganisms functions:
 
 * Updated full microbiological taxonomy according to the latest daily LPSN data set (December 2022) and latest yearly GBIF taxonomy backbone (November 2022)
-* Support for all 1,515 city-like serovars of *Salmonella*, such as *Salmonella* Goldcoast. Formally, these are serovars belonging to the *S. enterica* species, but they are reported with only the name of the genus and the city. For this reason, the serovars are in the `subspecies` column of the `microorganisms` data set and "enterica" is in the `species` column, but the full name does not contain the species name (*enterica*).
+* Support for all 1,516 city-like serovars of *Salmonella*, such as *Salmonella* Goldcoast. Formally, these are serovars belonging to the *S. enterica* species, but they are reported with only the name of the genus and the city. For this reason, the serovars are in the `subspecies` column of the `microorganisms` data set and "enterica" is in the `species` column, but the full name does not contain the species name (*enterica*).
 * All new algorithm for `as.mo()` (and thus all `mo_*()` functions) while still following our original set-up as described in our recently published JSS paper (DOI [10.18637/jss.v104.i03](https://doi.org/10.18637/jss.v104.i03)).
   * A new argument `keep_synonyms` allows to *not* correct for updated taxonomy, in favour of the now deleted argument `allow_uncertain`
   * It has increased tremendously in speed and returns generally more consequent results

R/aa_helper_functions.R

@@ -380,7 +380,7 @@ import_fn <- function(name, pkg, error_on_fail = TRUE) {
     error = function(e) {
       if (isTRUE(error_on_fail)) {
         stop_("function ", name, "() is not an exported object from package '", pkg,
-          "'. Please create an issue at https://github.com/msberends/AMR/issues. Many thanks!",
+          "'. Please create an issue at ", font_url("https://github.com/msberends/AMR/issues"), ". Many thanks!",
           call = FALSE
         )
       } else {
@@ -476,6 +476,7 @@ word_wrap <- function(...,
   # remove extra space that was introduced (e.g. "Smith et al., 2022")
   msg <- gsub(". ,", ".,", msg, fixed = TRUE)
   msg <- gsub("[ ,", "[,", msg, fixed = TRUE)
+  msg <- gsub("/ /", "//", msg, fixed = TRUE)
 
   msg
 }

R/add_custom_antimicrobials.R

@@ -135,7 +135,7 @@ add_custom_antimicrobials <- function(x) {
   x$generalised_name <- generalise_antibiotic_name(x$name)
   x$generalised_all <- as.list(x$generalised_name)
   for (col in colnames(x)) {
-    if (is.list(AMR_env$AB_lookup[, col, drop = TRUE])) {
+    if (is.list(AMR_env$AB_lookup[, col, drop = TRUE]) & !is.list(x[, col, drop = TRUE])) {
       x[, col] <- as.list(x[, col, drop = TRUE])
     }
   }
@@ -155,7 +155,8 @@ add_custom_antimicrobials <- function(x) {
     new_df[, col] <- x[, col, drop = TRUE]
   }
   AMR_env$AB_lookup <- unique(rbind(AMR_env$AB_lookup, new_df))
-  AMR_env$ab_previously_coerced <- AMR_env$ab_previously_coerced[which(!AMR_env$ab_previously_coerced$ab %in% new_df$ab), , drop = FALSE]
+  
+  AMR_env$ab_previously_coerced <- AMR_env$ab_previously_coerced[which(!AMR_env$ab_previously_coerced$ab %in% x$ab), , drop = FALSE]
   class(AMR_env$AB_lookup$ab) <- c("ab", "character")
   message_("Added ", nr2char(nrow(x)), " record", ifelse(nrow(x) > 1, "s", ""), " to the internal `antibiotics` data set.")
 }
@@ -167,5 +168,6 @@ clear_custom_antimicrobials <- function() {
   AMR_env$AB_lookup <- create_AB_lookup()
   n2 <- nrow(AMR_env$AB_lookup)
   AMR_env$custom_ab_codes <- character(0)
+  AMR_env$ab_previously_coerced <- AMR_env$ab_previously_coerced[which(AMR_env$ab_previously_coerced$ab %in% AMR_env$AB_lookup$ab), , drop = FALSE]
   message_("Cleared ", nr2char(n - n2), " custom record", ifelse(n - n2 > 1, "s", ""), " from the internal `antibiotics` data set.")
 }

R/add_custom_microorganisms.R

@@ -185,11 +185,10 @@ add_custom_microorganisms <- function(x) {
   x$mo <- trimws2(x$mo)
   x$mo[x$mo == ""] <- NA_character_
   x$mo[is.na(x$mo)] <- paste0("CUSTOM_",
-                              toupper(abbreviate(gsub(" +", " _ ",
+                              toupper(unname(abbreviate(gsub(" +", " _ ",
-                                                      gsub("[^A-Za-z0-9-]", " ",
+                                                             gsub("[^A-Za-z0-9-]", " ",
-                                                                        trimws2(paste(x$genus, x$species, x$subspecies)))),
+                                                                  trimws2(paste(x$genus, x$species, x$subspecies)))),
-                                                 minlength = 10,
+                                                        minlength = 10))))
-                                                 named = FALSE)))
   
   # add to package ----
   

R/mean_amr_distance.R

@@ -27,11 +27,11 @@
 # how to conduct AMR data analysis: https://msberends.github.io/AMR/   #
 # ==================================================================== #
 
-#' Mean AMR Distance
+#' Calculate the Mean AMR Distance
 #'
-#' This function calculates a normalised mean for antimicrobial resistance between multiple observations.
+#' Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand.
 #' @param x a vector of class [rsi][as.rsi()], [rsi][as.rsi()] or [rsi][as.rsi()], or a [data.frame] containing columns of any of these classes
-#' @param ... variables to select (supports tidy selection such as `column1:column4` and [`where(is.mic)`][tidyselect::language]), and can thus also be [antibiotic selectors][ab_selector()]
+#' @param ... variables to select (supports [tidyselect language][tidyselect::language] such as `column1:column4` and `where(is.mic)`, and can thus also be [antibiotic selectors][ab_selector()]
 #' @param combine_SI 	a [logical] to indicate whether all values of S and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant), defaults to `TRUE`
 #' @details The mean AMR distance is a normalised numeric value to compare AMR test results and can help to identify similar isolates, without comparing antibiograms by hand. For common numeric data this distance is equal to [Z scores](https://en.wikipedia.org/wiki/Standard_score) (the number of standard deviations from the mean).
 #'
@@ -83,20 +83,20 @@ mean_amr_distance <- function(x, ...) {
   UseMethod("mean_amr_distance")
 }
 
-#' @rdname mean_amr_distance
+#' @noRd
 #' @export
 mean_amr_distance.default <- function(x, ...) {
   x <- as.double(x)
   (x - mean(x, na.rm = TRUE)) / stats::sd(x, na.rm = TRUE)
 }
 
-#' @rdname mean_amr_distance
+#' @noRd
 #' @export
 mean_amr_distance.mic <- function(x, ...) {
   mean_amr_distance(log2(x))
 }
 
-#' @rdname mean_amr_distance
+#' @noRd
 #' @export
 mean_amr_distance.disk <- function(x, ...) {
   mean_amr_distance(as.double(x))

R/rsi.R

@@ -804,7 +804,7 @@ as_rsi_method <- function(method_short,
     for (i in seq_len(length(messages))) {
       messages[i] <- word_wrap(extra_indent = 5, messages[i])
     }
-    message(font_green(font_bold(" * NOTE *\n")),
+    message(font_green(font_bold(" Note:\n")),
             paste0("   ", font_black(AMR_env$bullet_icon)," ", font_black(messages, collapse = NULL) , collapse = "\n"))
   }
 

R/translate.R

@@ -230,7 +230,7 @@ translate_into_language <- function(from,
   any_form_in_patterns <- tryCatch(
     any(from_unique %like% paste0("(", paste(gsub(" +\\(.*", "", df_trans$pattern), collapse = "|"), ")")),
     error = function(e) {
-      warning_("Translation not possible. Please open an issue on GitHub (https://github.com/msberends/AMR/issues).")
+      warning_("Translation not possible. Please create an issue at ", font_url("https://github.com/msberends/AMR/issues"), ". Many thanks!")
       return(FALSE)
     }
   )

_pkgdown.yml

@@ -96,13 +96,13 @@ navbar:
       - text: "Apply EUCAST rules"
         icon: "fa-exchange-alt"
         href: "articles/EUCAST.html"
-      - text: "Get properties of a microorganism"
+      - text: "Get taxonomy of a microorganism"
         icon: "fa-bug"
         href: "reference/mo_property.html" # reference instead of an article
-      - text: "Get properties of an antibiotic"
+      - text: "Get properties of an antibiotic drug"
         icon: "fa-capsules"
         href: "reference/ab_property.html" # reference instead of an article
-      - text: "Get properties of an antiviral agent"
+      - text: "Get properties of an antiviral drug"
         icon: "fa-capsules"
         href: "reference/av_property.html" # reference instead of an article
     - text: "Manual"
@@ -118,15 +118,14 @@ navbar:
     - text: "Source Code"
       icon: "fab fa-github"
       href: "https://github.com/msberends/AMR"
-    # - text: "Survey"
-    #   icon: "fa-clipboard-list"
-    #   href: "survey.html"
 
 reference:
   - title: "Preparing data: microorganisms"
     desc: >
-      These functions are meant to get taxonomically valid properties of microorganisms from any input.
+      These functions are meant to get taxonomically valid properties of microorganisms from any input, but
-      Use `mo_source()` to teach this package how to translate your own codes to valid microorganism codes.
+      also properties derived from taxonomy, such as the Gram stain (`mo_gramstain()`) , or `mo_is_yeast()`.
+      Use `mo_source()` to teach this package how to translate your own codes to valid microorganisms, and
+      use `add_custom_microorganisms() to add your own custom microorganisms to this package.
     contents:
     - "`as.mo`"
     - "`mo_property`"

man/g.test.Rd

@@ -21,7 +21,7 @@ g.test(x, y = NULL, p = rep(1/length(x), length(x)), rescale.p = FALSE)
 \item{y}{a numeric vector; ignored if \code{x} is a matrix.  If
     \code{x} is a factor, \code{y} should be a factor of the same length.}
 
-\item{p}{a vector of probabilities of the same length as \code{x}.
+\item{p}{a vector of probabilities of the same length of \code{x}.
     An error is given if any entry of \code{p} is negative.}
 
 \item{rescale.p}{a logical scalar; if TRUE then \code{p} is rescaled

man/mean_amr_distance.Rd

@@ -2,22 +2,13 @@
 % Please edit documentation in R/mean_amr_distance.R
 \name{mean_amr_distance}
 \alias{mean_amr_distance}
-\alias{mean_amr_distance.default}
-\alias{mean_amr_distance.mic}
-\alias{mean_amr_distance.disk}
 \alias{mean_amr_distance.rsi}
 \alias{mean_amr_distance.data.frame}
 \alias{amr_distance_from_row}
-\title{Mean AMR Distance}
+\title{Calculate the Mean AMR Distance}
 \usage{
 mean_amr_distance(x, ...)
 
-\method{mean_amr_distance}{default}(x, ...)
-
-\method{mean_amr_distance}{mic}(x, ...)
-
-\method{mean_amr_distance}{disk}(x, ...)
-
 \method{mean_amr_distance}{rsi}(x, ..., combine_SI = TRUE)
 
 \method{mean_amr_distance}{data.frame}(x, ..., combine_SI = TRUE)
@@ -27,7 +18,7 @@ amr_distance_from_row(amr_distance, row)
 \arguments{
 \item{x}{a vector of class \link[=as.rsi]{rsi}, \link[=as.rsi]{rsi} or \link[=as.rsi]{rsi}, or a \link{data.frame} containing columns of any of these classes}
 
-\item{...}{variables to select (supports tidy selection such as \code{column1:column4} and \code{\link[tidyselect:language]{where(is.mic)}}), and can thus also be \link[=ab_selector]{antibiotic selectors}}
+\item{...}{variables to select (supports \link[tidyselect:language]{tidyselect language} such as \code{column1:column4} and \code{where(is.mic)}, and can thus also be \link[=ab_selector]{antibiotic selectors}}
 
 \item{combine_SI}{a \link{logical} to indicate whether all values of S and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant), defaults to \code{TRUE}}
 
@@ -36,7 +27,7 @@ amr_distance_from_row(amr_distance, row)
 \item{row}{an index, such as a row number}
 }
 \description{
-This function calculates a normalised mean for antimicrobial resistance between multiple observations.
+Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand.
 }
 \details{
 The mean AMR distance is a normalised numeric value to compare AMR test results and can help to identify similar isolates, without comparing antibiograms by hand. For common numeric data this distance is equal to \href{https://en.wikipedia.org/wiki/Standard_score}{Z scores} (the number of standard deviations from the mean).