add `add_custom_antimicrobials()`

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: AMR
-Version: 1.8.2.9009
+Version: 1.8.2.9010
 Date: 2022-10-10
 Title: Antimicrobial Resistance Data Analysis
 Description: Functions to simplify and standardise antimicrobial resistance (AMR)

NAMESPACE

@@ -181,6 +181,7 @@ export(ab_selector)
 export(ab_synonyms)
 export(ab_tradenames)
 export(ab_url)
+export(add_custom_antimicrobials)
 export(administrable_iv)
 export(administrable_per_os)
 export(age)
@@ -212,6 +213,7 @@ export(cephalosporins_2nd)
 export(cephalosporins_3rd)
 export(cephalosporins_4th)
 export(cephalosporins_5th)
+export(clear_custom_antimicrobials)
 export(count_I)
 export(count_IR)
 export(count_R)

NEWS.md

@@ -1,4 +1,4 @@
-# AMR 1.8.2.9009
+# AMR 1.8.2.9010
 
 This version will eventually become v2.0! We're happy to reach a new major milestone soon!
 
@@ -20,6 +20,7 @@ This version will eventually become v2.0! We're happy to reach a new major miles
 * Function `mean_amr_distance()` to calculate the mean AMR distance. 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.
 * Function `rsi_interpretation_history()` to view the history of previous runs of `as.rsi()`. This returns a 'logbook' with the selected guideline, reference table and specific interpretation of each row in a data set on which `as.rsi()` was run.
 * Function `mo_current()` to get the currently valid taxonomic name of a microorganism
+* Function `add_custom_antimicrobials()` to add custom antimicrobial codes and names to the `AMR` package
 * Support for `data.frame`-enhancing R packages, more specifically: `data.table::data.table`, `janitor::tabyl`, `tibble::tibble`, and `tsibble::tsibble`. AMR package functions that have a data set as output (such as `rsi_df()` and `bug_drug_combinations()`), will now return the same data type as the input.
 * All data sets in this package are now exported as `tibble`, instead of base R `data.frame`s. Older R versions are still supported.
 * Support for the following languages: Chinese, Greek, Japanese, Polish, Turkish and Ukrainian. We are very grateful for the valuable input by our colleagues from other countries. The `AMR` package is now available in 16 languages.

R/ab.R

@@ -48,6 +48,8 @@
 #' Use the [`ab_*`][ab_property()] functions to get properties based on the returned antibiotic ID, see *Examples*.
 #'
 #' Note: the [as.ab()] and [`ab_*`][ab_property()] functions may use very long regular expression to match brand names of antimicrobial agents. This may fail on some systems.
+#' 
+#' You can add your own manual codes to be considered by [as.ab()] and all [`ab_*`][ab_property()] functions, see [add_custom_antimicrobials()].
 #' @section Source:
 #' World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: \url{https://www.whocc.no/atc_ddd_index/}
 #'
@@ -218,7 +220,7 @@ as.ab <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) {
       AB_lookup$generalised_loinc,
       function(s) x[i] %in% s
     ))
-    found <- AMR::antibiotics$ab[loinc_found == TRUE]
+    found <- AB_lookup$ab[loinc_found == TRUE]
     if (length(found) > 0) {
       x_new[i] <- note_if_more_than_one_found(found, i, from_text)
       next
@@ -229,7 +231,7 @@ as.ab <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) {
       AB_lookup$generalised_synonyms,
       function(s) x[i] %in% s
     ))
-    found <- AMR::antibiotics$ab[synonym_found == TRUE]
+    found <- AB_lookup$ab[synonym_found == TRUE]
     if (length(found) > 0) {
       x_new[i] <- note_if_more_than_one_found(found, i, from_text)
       next
@@ -241,7 +243,7 @@ as.ab <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) {
       # require at least 2 characters for abbreviations
       function(s) x[i] %in% s && nchar(x[i]) >= 2
     ))
-    found <- AMR::antibiotics$ab[abbr_found == TRUE]
+    found <- AB_lookup$ab[abbr_found == TRUE]
     if (length(found) > 0) {
       x_new[i] <- note_if_more_than_one_found(found, i, from_text)
       next
@@ -288,13 +290,13 @@ as.ab <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) {
     }
 
     # try if name starts with it
-    found <- AMR::antibiotics[which(AB_lookup$generalised_name %like% paste0("^", x_spelling)), "ab", drop = TRUE]
+    found <- AB_lookup[which(AB_lookup$generalised_name %like% paste0("^", x_spelling)), "ab", drop = TRUE]
     if (length(found) > 0) {
       x_new[i] <- note_if_more_than_one_found(found, i, from_text)
       next
     }
     # try if name ends with it
-    found <- AMR::antibiotics[which(AB_lookup$generalised_name %like% paste0(x_spelling, "$")), "ab", drop = TRUE]
+    found <- AB_lookup[which(AB_lookup$generalised_name %like% paste0(x_spelling, "$")), "ab", drop = TRUE]
     if (nchar(x[i]) >= 4 && length(found) > 0) {
       x_new[i] <- note_if_more_than_one_found(found, i, from_text)
       next
@@ -305,7 +307,7 @@ as.ab <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) {
       AB_lookup$generalised_synonyms,
       function(s) any(s %like% paste0("^", x_spelling))
     ))
-    found <- AMR::antibiotics$ab[synonym_found == TRUE]
+    found <- AB_lookup$ab[synonym_found == TRUE]
     if (length(found) > 0) {
       x_new[i] <- note_if_more_than_one_found(found, i, from_text)
       next
@@ -583,7 +585,7 @@ as.data.frame.ab <- function(x, ...) {
 "[<-.ab" <- function(i, j, ..., value) {
   y <- NextMethod()
   attributes(y) <- attributes(i)
-  return_after_integrity_check(y, "antimicrobial code", AMR::antibiotics$ab)
+  return_after_integrity_check(y, "antimicrobial code", AB_lookup$ab)
 }
 #' @method [[<- ab
 #' @export
@@ -591,7 +593,7 @@ as.data.frame.ab <- function(x, ...) {
 "[[<-.ab" <- function(i, j, ..., value) {
   y <- NextMethod()
   attributes(y) <- attributes(i)
-  return_after_integrity_check(y, "antimicrobial code", AMR::antibiotics$ab)
+  return_after_integrity_check(y, "antimicrobial code", AB_lookup$ab)
 }
 #' @method c ab
 #' @export
@@ -600,7 +602,7 @@ c.ab <- function(...) {
   x <- list(...)[[1L]]
   y <- NextMethod()
   attributes(y) <- attributes(x)
-  return_after_integrity_check(y, "antimicrobial code", AMR::antibiotics$ab)
+  return_after_integrity_check(y, "antimicrobial code", AB_lookup$ab)
 }
 
 #' @method unique ab

R/add_custom_antimicrobials.R

@@ -0,0 +1,98 @@
+# ==================================================================== #
+# TITLE                                                                #
+# AMR: An R Package for Working with Antimicrobial Resistance Data     #
+#                                                                      #
+# SOURCE                                                               #
+# https://github.com/msberends/AMR                                     #
+#                                                                      #
+# CITE AS                                                              #
+# Berends MS, Luz CF, Friedrich AW, Sinha BNM, Albers CJ, Glasner C    #
+# (2022). AMR: An R Package for Working with Antimicrobial Resistance  #
+# Data. Journal of Statistical Software, 104(3), 1-31.                 #
+# doi:10.18637/jss.v104.i03                                            #
+#                                                                      #
+# Developed at the University of Groningen, the Netherlands, in        #
+# collaboration with non-profit organisations Certe Medical            #
+# Diagnostics & Advice, and University Medical Center Groningen.       #
+#                                                                      #
+# This R package is free software; you can freely use and distribute   #
+# it for both personal and commercial purposes under the terms of the  #
+# GNU General Public License version 2.0 (GNU GPL-2), as published by  #
+# the Free Software Foundation.                                        #
+# We created this package for both routine data analysis and academic  #
+# research and it was publicly released in the hope that it will be    #
+# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY.              #
+#                                                                      #
+# Visit our website for the full manual and a complete tutorial about  #
+# how to conduct AMR data analysis: https://msberends.github.io/AMR/   #
+# ==================================================================== #
+
+#' Add Manual Antimicrobials to This Package
+#' 
+#' With [add_custom_antimicrobials()] you can add your own manual antimicrobial codes to the `AMR` package.
+#' @param x a [data.frame] resembling the [antibiotics] data set, at least containing columns "ab" and "name"
+#' @details Due to how \R works, the [add_custom_antimicrobials()] function has to be run in every \R session - added antimicrobials are not stored between sessions and are thus lost when \R is exited. It is possible to save the antimicrobial additions to your `.Rprofile` file to circumvent this, for example:
+#' 
+#' ```r
+#' library(AMR)
+#' add_custom_antimicrobials(
+#'   data.frame(ab = "TEST",
+#'              name = "Test Antibiotic",
+#'              group = "Test Group")
+#' )
+#' ```
+#' 
+#' Use [clear_custom_antimicrobials()] to clear the previously added antimicrobials.
+#' @rdname add_custom_antimicrobials
+#' @export
+#' @examples 
+#' \donttest{
+#' 
+#' # returns NA and throws a warning:
+#' as.ab("test")
+#' 
+#' # now a manual entry - it will be considered by as.ab() and
+#' # all ab_*() functions
+#' add_custom_antimicrobials(
+#'   data.frame(ab = "TEST",
+#'              name = "Test Antibiotic",
+#'              group = "Test Group")
+#' )
+#' 
+#' "test" is now a new antibiotic:
+#' as.ab("test")
+#' ab_name("test")
+#' ab_group("test")
+#' }
+add_custom_antimicrobials <- function(x) {
+  meet_criteria(x, allow_class = "data.frame")
+  stop_ifnot(all(c("ab", "name") %in% colnames(x)),
+             "`x` must contain columns \"ab\" and \"name\".")
+  stop_if(any(x$ab %in% AB_lookup$ab),
+          "Antimicrobial code(s) ", vector_and(x$ab[x$ab %in% AB_lookup$ab]), " already exist in the internal `antibiotics` data set.")
+  
+  x <- x[, colnames(AB_lookup)[colnames(AB_lookup) %in% colnames(x)], drop = FALSE]
+  x$generalised_name <- generalise_antibiotic_name(x$name)
+  x$generalised_all <- as.list(x$generalised_name)
+  
+  bind_rows <- import_fn("bind_rows", "dplyr", error_on_fail = FALSE)
+  if (!is.null(bind_rows)) {
+    new_df <- bind_rows(AB_lookup, x)
+  } else {
+    new_df <- rbind(AB_lookup, x, stringsAsFactors = FALSE)
+  }
+  
+  assignInNamespace(x = "AB_lookup",
+                    value = new_df,
+                    ns = asNamespace("AMR"))
+  message_("Added ", nr2char(nrow(x)), " record", ifelse(nrow(x) > 1, "s", ""), " to internal `antibiotics` data set.")
+}
+
+#' @rdname add_custom_antimicrobials
+#' @export
+clear_custom_antimicrobials <- function() {
+  assignInNamespace(x = "AB_lookup",
+                    value = create_AB_lookup(),
+                    ns = asNamespace("AMR"))
+  message_("Manual antimicrobials cleared.")
+}

inst/tinytest/test-add_custom_antimicrobials.R

@@ -0,0 +1,43 @@
+# ==================================================================== #
+# TITLE                                                                #
+# AMR: An R Package for Working with Antimicrobial Resistance Data     #
+#                                                                      #
+# SOURCE                                                               #
+# https://github.com/msberends/AMR                                     #
+#                                                                      #
+# CITE AS                                                              #
+# Berends MS, Luz CF, Friedrich AW, Sinha BNM, Albers CJ, Glasner C    #
+# (2022). AMR: An R Package for Working with Antimicrobial Resistance  #
+# Data. Journal of Statistical Software, 104(3), 1-31.                 #
+# doi:10.18637/jss.v104.i03                                            #
+#                                                                      #
+# Developed at the University of Groningen, the Netherlands, in        #
+# collaboration with non-profit organisations Certe Medical            #
+# Diagnostics & Advice, and University Medical Center Groningen.       #
+#                                                                      #
+# This R package is free software; you can freely use and distribute   #
+# it for both personal and commercial purposes under the terms of the  #
+# GNU General Public License version 2.0 (GNU GPL-2), as published by  #
+# the Free Software Foundation.                                        #
+# We created this package for both routine data analysis and academic  #
+# research and it was publicly released in the hope that it will be    #
+# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY.              #
+#                                                                      #
+# Visit our website for the full manual and a complete tutorial about  #
+# how to conduct AMR data analysis: https://msberends.github.io/AMR/   #
+# ==================================================================== #
+
+expect_warning(as.ab("test"))
+expect_identical(as.character(suppressWarnings(as.ab("test"))), NA_character_)
+
+suppressMessages(
+  add_custom_antimicrobials(
+    data.frame(ab = "TEST",
+               name = "Test Antibiotic",
+               group = "Test Group")
+  )
+)
+
+expect_identical(as.character(as.ab("test")), "TEST")
+expect_identical(ab_name("test"), "Test Antibiotic")
+expect_identical(ab_group("test"), "Test Group")

man/add_custom_antimicrobials.Rd

@@ -0,0 +1,50 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/add_custom_antimicrobials.R
+\name{add_custom_antimicrobials}
+\alias{add_custom_antimicrobials}
+\alias{clear_custom_antimicrobials}
+\title{Add Manual Antimicrobials to This Package}
+\usage{
+add_custom_antimicrobials(x)
+
+clear_custom_antimicrobials()
+}
+\arguments{
+\item{x}{a \link{data.frame} resembling the \link{antibiotics} data set, at least containing columns "ab" and "name"}
+}
+\description{
+With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you can add your own manual antimicrobial codes to the \code{AMR} package.
+}
+\details{
+Due to how \R works, the \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} function has to be run in every \R session - added antimicrobials are not stored between sessions and are thus lost when \R is exited. It is possible to save the antimicrobial additions to your \code{.Rprofile} file to circumvent this, for example:
+
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(AMR)
+add_custom_antimicrobials(
+  data.frame(ab = "TEST",
+             name = "Test Antibiotic",
+             group = "Test Group")
+)
+}\if{html}{\out{</div>}}
+
+Use \code{\link[=clear_custom_antimicrobials]{clear_custom_antimicrobials()}} to clear the previously added antimicrobials.
+}
+\examples{
+\donttest{
+
+# returns NA and throws a warning:
+as.ab("test")
+
+# now a manual entry - it will be considered by as.ab() and
+# all ab_*() functions
+add_custom_antimicrobials(
+  data.frame(ab = "TEST",
+             name = "Test Antibiotic",
+             group = "Test Group")
+)
+
+"test" is now a new antibiotic:
+as.ab("test")
+ab_name("test")
+ab_group("test")
+}
+}

man/as.ab.Rd

@@ -39,6 +39,8 @@ All these properties will be searched for the user input. The \code{\link[=as.ab
 Use the \code{\link[=ab_property]{ab_*}} functions to get properties based on the returned antibiotic ID, see \emph{Examples}.
 
 Note: the \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_property]{ab_*}} functions may use very long regular expression to match brand names of antimicrobial agents. This may fail on some systems.
+
+You can add your own manual codes to be considered by \code{\link[=as.ab]{as.ab()}} and all \code{\link[=ab_property]{ab_*}} functions, see \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}}.
 }
 \section{Source}{