From 80cfc503c29ad48806e526b97d4570600bbd5420 Mon Sep 17 00:00:00 2001 From: "Matthijs S. Berends" Date: Sun, 12 Mar 2023 13:02:37 +0100 Subject: [PATCH] check for 2.0 --- DESCRIPTION | 4 +- NEWS.md | 4 +- R/aa_amr-package.R | 6 +-- R/aa_helper_functions.R | 16 ++++---- R/ab.R | 2 +- R/ab_selectors.R | 66 ++++++++++++++++--------------- R/antibiogram.R | 2 +- R/av.R | 2 +- R/bug_drug_combinations.R | 6 +-- R/custom_antimicrobials.R | 6 +-- R/custom_microorganisms.R | 11 ++++-- R/eucast_rules.R | 6 +-- R/mo.R | 4 +- R/mo_source.R | 4 +- R/plot.R | 6 +-- R/proportion.R | 10 ++--- R/sir.R | 6 +-- R/sir_calc.R | 4 +- R/zzz.R | 4 +- README.md | 26 ++---------- man/AMR.Rd | 6 +-- man/add_custom_antimicrobials.Rd | 4 +- man/add_custom_microorganisms.Rd | 6 +-- man/antibiotic_class_selectors.Rd | 44 +++++++++++---------- vignettes/welcome_to_AMR.Rmd | 6 +-- 25 files changed, 127 insertions(+), 134 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index b5c9f931..c1883589 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 1.8.2.9151 -Date: 2023-03-11 +Version: 1.8.2.9152 +Date: 2023-03-12 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 diff --git a/NEWS.md b/NEWS.md index 0b3dec7b..4d811894 100755 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,4 @@ -# AMR 1.8.2.9151 - -*(this beta version will eventually become v2.0! We're happy to reach a new major milestone soon!)* +# AMR 1.8.2.9152 This is a new major release of the AMR package, with great new additions but also some breaking changes for current users. These are all listed below. diff --git a/R/aa_amr-package.R b/R/aa_amr-package.R index 8041b77d..7747627a 100755 --- a/R/aa_amr-package.R +++ b/R/aa_amr-package.R @@ -34,11 +34,11 @@ #' #' The `AMR` package is a [free and open-source](https://msberends.github.io/AMR/#copyright) R package with [zero dependencies](https://en.wikipedia.org/wiki/Dependency_hell) to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. **Our aim is to provide a standard** for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. [Many different researchers](https://msberends.github.io/AMR/authors.html) from around the globe are continually helping us to make this a successful and durable project! #' -#' This work was published in the Journal of Statistical Software (Volume 104(3); [DOI 10.18637/jss.v104.i03](https://doi.org/10.18637/jss.v104.i03)) and formed the basis of two PhD theses ([DOI 10.33612/diss.177417131](https://doi.org/10.33612/diss.177417131) and [DOI 10.33612/diss.192486375](https://doi.org/10.33612/diss.192486375)). +#' This work was published in the Journal of Statistical Software (Volume 104(3); \doi{jss.v104.i03}) and formed the basis of two PhD theses (\doi{10.33612/diss.177417131} and \doi{10.33612/diss.192486375}). #' -#' After installing this package, R knows [**`r format_included_data_number(AMR::microorganisms)`**](https://msberends.github.io/AMR/reference/microorganisms.html) (updated December 2022) and all [**~600 antibiotic, antimycotic and antiviral drugs**](https://msberends.github.io/AMR/reference/antibiotics.html) by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral breakpoint guidelines from CLSI and EUCAST are included from the last 10 years. It supports and can read any data format, including WHONET data. This package works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). **It was designed to work in any setting, including those with very limited resources**. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the [University of Groningen](https://www.rug.nl), in collaboration with non-profit organisations [Certe Medical Diagnostics and Advice Foundation](https://www.certe.nl) and [University Medical Center Groningen](https://www.umcg.nl). +#' After installing this package, R knows [**`r format_included_data_number(AMR::microorganisms)` microorganisms**](https://msberends.github.io/AMR/reference/microorganisms.html) (updated `r format(TAXONOMY_VERSION$GBIF$accessed_date, "%B %Y")`) and all [**`r format_included_data_number(nrow(AMR::antibiotics) + nrow(AMR::antivirals))` antibiotic, antimycotic and antiviral drugs**](https://msberends.github.io/AMR/reference/antibiotics.html) by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral breakpoint guidelines from CLSI and EUCAST are included from the last 10 years. It supports and can read any data format, including WHONET data. This package works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). **It was designed to work in any setting, including those with very limited resources**. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the [University of Groningen](https://www.rug.nl), in collaboration with non-profit organisations [Certe Medical Diagnostics and Advice Foundation](https://www.certe.nl) and [University Medical Center Groningen](https://www.umcg.nl). #' -#' The `AMR` package is available in English, Chinese, Danish, Dutch, French, German, Greek, Italian, Japanese, Polish, Portuguese, Russian, Spanish, Swedish, Turkish and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages. +#' The `AMR` package is available in `r vector_and(vapply(FUN.VALUE = character(1), LANGUAGES_SUPPORTED_NAMES, function(x) x$exonym), quotes = FALSE, sort = FALSE)`. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages. #' @section Reference Data Publicly Available: #' All data sets in this `AMR` package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit [our website for the download links](https://msberends.github.io/AMR/articles/datasets.html). The actual files are of course available on [our GitHub repository](https://github.com/msberends/AMR/tree/main/data-raw). #' @source diff --git a/R/aa_helper_functions.R b/R/aa_helper_functions.R index be75542b..65c0c6b8 100755 --- a/R/aa_helper_functions.R +++ b/R/aa_helper_functions.R @@ -63,9 +63,9 @@ pm_left_join <- function(x, y, by = NULL, suffix = c(".x", ".y")) { merged } -# support where() like tidyverse: +# support where() like tidyverse (this function will also be used when running `antibiogram()`): where <- function(fn) { - # adapted from https://github.com/nathaneastwood/poorman/blob/52eb6947e0b4430cd588976ed8820013eddf955f/R/where.R#L17-L32 + # based on https://github.com/nathaneastwood/poorman/blob/52eb6947e0b4430cd588976ed8820013eddf955f/R/where.R#L17-L32 if (!is.function(fn)) { stop_("`", deparse(substitute(fn)), "()` is not a valid predicate function.") } @@ -90,7 +90,7 @@ where <- function(fn) { # copied and slightly rewritten from {poorman} under permissive license (2021-10-15) # https://github.com/nathaneastwood/poorman, MIT licensed, Nathan Eastwood, 2020 -quick_case_when <- function(...) { +case_when_AMR <- function(...) { fs <- list(...) lapply(fs, function(x) { if (!inherits(x, "formula")) { @@ -163,8 +163,8 @@ quick_case_when <- function(...) { out } -rbind2 <- function(...) { - # this is just rbind(), but then with the functionality of dplyr::bind_rows(), +rbind_AMR <- function(...) { + # this is just rbind(), but with the functionality of dplyr::bind_rows(), # to allow differences in available columns l <- list(...) l_names <- unique(unlist(lapply(l, names))) @@ -633,7 +633,9 @@ documentation_date <- function(d) { } format_included_data_number <- function(data) { - if (is.data.frame(data)) { + if (is.numeric(data) && length(data) == 1) { + n <- data + } else if (is.data.frame(data)) { n <- nrow(data) } else { n <- length(unique(data)) @@ -1502,7 +1504,7 @@ trimws2 <- function(..., whitespace = "[\u0009\u000A\u000B\u000C\u000D\u0020\u00 trimws(..., whitespace = whitespace) } -readRDS2 <- function(file, refhook = NULL) { +readRDS_AMR <- function(file, refhook = NULL) { # this is readRDS with remote file support con <- file(file) on.exit(close(con)) diff --git a/R/ab.R b/R/ab.R index 71074808..c3d35ae5 100755 --- a/R/ab.R +++ b/R/ab.R @@ -495,7 +495,7 @@ as.ab <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) { # save to package env to save time for next time if (isTRUE(initial_search)) { AMR_env$ab_previously_coerced <- AMR_env$ab_previously_coerced[which(!AMR_env$ab_previously_coerced$x %in% x), , drop = FALSE] - AMR_env$ab_previously_coerced <- unique(rbind2( + AMR_env$ab_previously_coerced <- unique(rbind_AMR( AMR_env$ab_previously_coerced, data.frame( x = x, diff --git a/R/ab_selectors.R b/R/ab_selectors.R index 7c042b26..3efc4635 100755 --- a/R/ab_selectors.R +++ b/R/ab_selectors.R @@ -30,7 +30,7 @@ #' Antibiotic Selectors #' #' @description These functions allow for filtering rows and selecting columns based on antibiotic test results that are of a specific antibiotic class or group (according to the [antibiotics] data set), without the need to define the columns or antibiotic abbreviations. -#' +#' #' In short, if you have a column name that resembles an antimicrobial drug, it will be picked up by any of these functions that matches its pharmaceutical class: "cefazolin", "kefzol", "CZO" and "J01DB04" will all be picked up by [cephalosporins()]. #' @param ab_class an antimicrobial class or a part of it, such as `"carba"` and `"carbapenems"`. The columns `group`, `atc_group1` and `atc_group2` of the [antibiotics] data set will be searched (case-insensitive) for this value. #' @param filter an [expression] to be evaluated in the [antibiotics] data set, such as `name %like% "trim"` @@ -55,8 +55,8 @@ #' # `example_isolates` is a data set available in the AMR package. #' # See ?example_isolates. #' example_isolates -#' -#' +#' +#' #' # Examples sections below are split into 'base R', 'dplyr', and 'data.table': #' #' @@ -96,15 +96,15 @@ #' # very flexible. For instance, to select antibiotic columns with an oral DDD #' # of at least 1 gram: #' example_isolates[, ab_selector(oral_ddd > 1 & oral_units == "g")] -#' +#' #' \donttest{ #' # dplyr ------------------------------------------------------------------- -#' +#' #' if (require("dplyr")) { #' tibble(kefzol = random_sir(5)) %>% #' select(cephalosporins()) #' } -#' +#' #' if (require("dplyr")) { #' # get AMR for all aminoglycosides e.g., per ward: #' example_isolates %>% @@ -179,40 +179,44 @@ #' select(penicillins()) # only the 'J01CA01' column will be selected #' } #' if (require("dplyr")) { -#' # with recent versions of dplyr this is all equal: +#' # with recent versions of dplyr, this is all equal: #' x <- example_isolates[carbapenems() == "R", ] #' y <- example_isolates %>% filter(carbapenems() == "R") #' z <- example_isolates %>% filter(if_all(carbapenems(), ~ .x == "R")) #' identical(x, y) && identical(y, z) #' } -#' -#' +#' +#' #' # data.table -------------------------------------------------------------- -#' +#' #' # data.table is supported as well, just use it in the same way as with -#' # base R, but add `with = FALSE` if using a single AB selector: -#' +#' # base R, but add `with = FALSE` if using a single AB selector. +#' #' if (require("data.table")) { #' dt <- as.data.table(example_isolates) -#' -#' print( -#' dt[, carbapenems()] # incorrect, returns column *names* -#' ) -#' print( -#' dt[, carbapenems(), with = FALSE] # so `with = FALSE` is required -#' ) -#' -#' # for multiple selections or AB selectors, `with = FALSE` is not needed: -#' print( -#' dt[, c("mo", aminoglycosides())] -#' ) -#' print( -#' dt[, c(carbapenems(), aminoglycosides())] -#' ) -#' -#' # row filters are also supported: -#' print(dt[any(carbapenems() == "S"), ]) -#' print(dt[any(carbapenems() == "S"), penicillins(), with = FALSE]) +#' +#' # this does not work, it returns column *names* +#' dt[, carbapenems()] +#' } +#' if (require("data.table")) { +#' # so `with = FALSE` is required +#' dt[, carbapenems(), with = FALSE] +#' } +#' +#' # for multiple selections or AB selectors, `with = FALSE` is not needed: +#' if (require("data.table")) { +#' dt[, c("mo", aminoglycosides())] +#' } +#' if (require("data.table")) { +#' dt[, c(carbapenems(), aminoglycosides())] +#' } +#' +#' # row filters are also supported: +#' if (require("data.table")) { +#' dt[any(carbapenems() == "S"), ] +#' } +#' if (require("data.table")) { +#' dt[any(carbapenems() == "S"), penicillins(), with = FALSE] #' } #' } ab_class <- function(ab_class, diff --git a/R/antibiogram.R b/R/antibiogram.R index ba951043..f8911de4 100755 --- a/R/antibiogram.R +++ b/R/antibiogram.R @@ -458,7 +458,7 @@ antibiogram <- function(x, if (i == 1) { new_df <- long_to_wide(out[which(out$syndromic_group == grp), , drop = FALSE], digs = digits) } else { - new_df <- rbind2( + new_df <- rbind_AMR( new_df, long_to_wide(out[which(out$syndromic_group == grp), , drop = FALSE], digs = digits) ) diff --git a/R/av.R b/R/av.R index 505637ea..26f53338 100755 --- a/R/av.R +++ b/R/av.R @@ -461,7 +461,7 @@ as.av <- function(x, flag_multiple_results = TRUE, info = interactive(), ...) { # save to package env to save time for next time if (isTRUE(initial_search)) { AMR_env$av_previously_coerced <- AMR_env$av_previously_coerced[which(!AMR_env$av_previously_coerced$x %in% x), , drop = FALSE] - AMR_env$av_previously_coerced <- unique(rbind2( + AMR_env$av_previously_coerced <- unique(rbind_AMR( AMR_env$av_previously_coerced, data.frame( x = x, diff --git a/R/bug_drug_combinations.R b/R/bug_drug_combinations.R index 5e9ef885..3b38842c 100755 --- a/R/bug_drug_combinations.R +++ b/R/bug_drug_combinations.R @@ -124,7 +124,7 @@ bug_drug_combinations <- function(x, m <- as.matrix(table(x)) data.frame(S = m["S", ], I = m["I", ], R = m["R", ], stringsAsFactors = FALSE) }) - merged <- do.call(rbind2, pivot) + merged <- do.call(rbind_AMR, pivot) out_group <- data.frame( mo = rep(unique_mo[i], NROW(merged)), ab = rownames(merged), @@ -144,14 +144,14 @@ bug_drug_combinations <- function(x, } out_group <- cbind(group_values, out_group) } - out <- rbind2(out, out_group) + out <- rbind_AMR(out, out_group) } out } # based on pm_apply_grouped_function apply_group <- function(.data, fn, groups, drop = FALSE, ...) { grouped <- pm_split_into_groups(.data, groups, drop) - res <- do.call(rbind2, unname(lapply(grouped, fn, ...))) + res <- do.call(rbind_AMR, unname(lapply(grouped, fn, ...))) if (any(groups %in% colnames(res))) { class(res) <- c("grouped_data", class(res)) res <- pm_set_groups(res, groups[groups %in% colnames(res)]) diff --git a/R/custom_antimicrobials.R b/R/custom_antimicrobials.R index bd7d8bc0..c233ffbc 100755 --- a/R/custom_antimicrobials.R +++ b/R/custom_antimicrobials.R @@ -33,7 +33,7 @@ #' @param x a [data.frame] resembling the [antibiotics] data set, at least containing columns "ab" and "name" #' @details **Important:** 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. #' -#' There are two ways to automate this process: +#' There are two ways to circumvent this and automate the process of adding antimicrobials: #' #' **Method 1:** Using the [package option][AMR-options] [`AMR_custom_ab`][AMR-options], which is the preferred method. To use this method: #' @@ -48,7 +48,7 @@ #' #' Upon package load, this file will be loaded and run through the [add_custom_antimicrobials()] function. #' -#' **Method 2:** Loading the antimicrobial additions directly from your `.Rprofile` file. An important downside is that this requires the `AMR` package to be installed or else this method will fail. To use this method: +#' **Method 2:** Loading the antimicrobial additions directly from your `.Rprofile` file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method: #' #' 1. Edit the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`. #' @@ -153,7 +153,7 @@ add_custom_antimicrobials <- function(x) { # assign new values new_df[, col] <- x[, col, drop = TRUE] } - AMR_env$AB_lookup <- unique(rbind2(AMR_env$AB_lookup, new_df)) + AMR_env$AB_lookup <- unique(rbind_AMR(AMR_env$AB_lookup, new_df)) 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") diff --git a/R/custom_microorganisms.R b/R/custom_microorganisms.R index ff9c9b72..69e26ea3 100755 --- a/R/custom_microorganisms.R +++ b/R/custom_microorganisms.R @@ -35,7 +35,7 @@ #' #' **Important:** Due to how \R works, the [add_custom_microorganisms()] function has to be run in every \R session - added microorganisms are not stored between sessions and are thus lost when \R is exited. #' -#' There are two ways to automate this process: +#' There are two ways to circumvent this and automate the process of adding microorganisms: #' #' **Method 1:** Using the [package option][AMR-options] [`AMR_custom_mo`][AMR-options], which is the preferred method. To use this method: #' @@ -50,7 +50,7 @@ #' #' Upon package load, this file will be loaded and run through the [add_custom_microorganisms()] function. #' -#' **Method 2:** Loading the microorganism directly from your `.Rprofile` file. An important downside is that this requires the `AMR` package to be installed or else this method will fail. To use this method: +#' **Method 2:** Loading the microorganism directly from your `.Rprofile` file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method: #' #' 1. Edit the `.Rprofile` file using e.g. `utils::file.edit("~/.Rprofile")`. #' @@ -64,7 +64,7 @@ #' ) #' ``` #' -#' Use [clear_custom_microorganisms()] to clear the previously added antimicrobials. +#' Use [clear_custom_microorganisms()] to clear the previously added microorganisms. #' @seealso [add_custom_antimicrobials()] to add custom antimicrobials. #' @rdname add_custom_microorganisms #' @export @@ -279,7 +279,7 @@ add_custom_microorganisms <- function(x) { # clear previous coercions suppressMessages(mo_reset_session()) - AMR_env$MO_lookup <- unique(rbind2(AMR_env$MO_lookup, new_df)) + AMR_env$MO_lookup <- unique(rbind_AMR(AMR_env$MO_lookup, new_df)) class(AMR_env$MO_lookup$mo) <- c("mo", "character") if (nrow(x) <= 3) { message_("Added ", vector_and(italicise(x$fullname), quotes = FALSE), " to the internal `microorganisms` data set.") @@ -297,6 +297,9 @@ clear_custom_microorganisms <- function() { AMR_env$MO_lookup <- NULL add_MO_lookup_to_AMR_env() + # clear previous coercions + suppressMessages(mo_reset_session()) + n2 <- nrow(AMR_env$MO_lookup) AMR_env$custom_mo_codes <- character(0) AMR_env$mo_previously_coerced <- AMR_env$mo_previously_coerced[which(AMR_env$mo_previously_coerced$mo %in% AMR_env$MO_lookup$mo), , drop = FALSE] diff --git a/R/eucast_rules.R b/R/eucast_rules.R index 2c238def..7ce81629 100755 --- a/R/eucast_rules.R +++ b/R/eucast_rules.R @@ -476,7 +476,7 @@ eucast_rules <- function(x, amox$base_ab <- "AMX" amox$base_name <- ab_name("AMX", language = NULL) # merge and sort - ab_enzyme <- rbind2(ab_enzyme, ampi, amox) + ab_enzyme <- rbind_AMR(ab_enzyme, ampi, amox) ab_enzyme <- ab_enzyme[order(ab_enzyme$enzyme_name), , drop = FALSE] for (i in seq_len(nrow(ab_enzyme))) { @@ -1162,7 +1162,7 @@ edit_sir <- function(x, ) verbose_new <- verbose_new %pm>% pm_filter(old != new | is.na(old) | is.na(new) & !is.na(old)) # save changes to data set 'verbose_info' - track_changes$verbose_info <- rbind2( + track_changes$verbose_info <- rbind_AMR( track_changes$verbose_info, verbose_new ) @@ -1216,7 +1216,7 @@ eucast_dosage <- function(ab, administration = "iv", version_breakpoints = 12.0) ) ) } - out <- do.call(rbind2, lapply(lst, as.data.frame, stringsAsFactors = FALSE)) + out <- do.call(rbind_AMR, lapply(lst, as.data.frame, stringsAsFactors = FALSE)) rownames(out) <- NULL out$ab <- ab out$name <- ab_name(ab, language = NULL) diff --git a/R/mo.R b/R/mo.R index 534ab86d..ada3d440 100755 --- a/R/mo.R +++ b/R/mo.R @@ -329,7 +329,7 @@ as.mo <- function(x, result_mo <- NA_character_ } else { result_mo <- AMR_env$MO_lookup$mo[match(top_hits[1], AMR_env$MO_lookup$fullname)] - AMR_env$mo_uncertainties <- rbind2( + AMR_env$mo_uncertainties <- rbind_AMR( AMR_env$mo_uncertainties, data.frame( original_input = x_search, @@ -343,7 +343,7 @@ as.mo <- function(x, ) ) # save to package env to save time for next time - AMR_env$mo_previously_coerced <- unique(rbind2( + AMR_env$mo_previously_coerced <- unique(rbind_AMR( AMR_env$mo_previously_coerced, data.frame( x = paste(x_search, minimum_matching_score), diff --git a/R/mo_source.R b/R/mo_source.R index 99f550f7..b743e863 100755 --- a/R/mo_source.R +++ b/R/mo_source.R @@ -149,7 +149,7 @@ set_mo_source <- function(path, destination = getOption("AMR_mo_source", "~/mo_s df <- NULL if (path %like% "[.]rds$") { - df <- readRDS2(path) + df <- readRDS_AMR(path) } else if (path %like% "[.]xlsx?$") { # is Excel file (old or new) stop_ifnot_installed("readxl") @@ -248,7 +248,7 @@ get_mo_source <- function(destination = getOption("AMR_mo_source", "~/mo_source. return(NULL) } if (is.null(AMR_env$mo_source)) { - AMR_env$mo_source <- readRDS2(path.expand(destination)) + AMR_env$mo_source <- readRDS_AMR(path.expand(destination)) } old_time <- attributes(AMR_env$mo_source)$mo_source_timestamp diff --git a/R/plot.R b/R/plot.R index 32d6ab90..176bd284 100755 --- a/R/plot.R +++ b/R/plot.R @@ -567,13 +567,13 @@ plot.sir <- function(x, data$s <- round((data$n / sum(data$n)) * 100, 1) if (!"S" %in% data$x) { - data <- rbind2(data, data.frame(x = "S", n = 0, s = 0, stringsAsFactors = FALSE)) + data <- rbind_AMR(data, data.frame(x = "S", n = 0, s = 0, stringsAsFactors = FALSE)) } if (!"I" %in% data$x) { - data <- rbind2(data, data.frame(x = "I", n = 0, s = 0, stringsAsFactors = FALSE)) + data <- rbind_AMR(data, data.frame(x = "I", n = 0, s = 0, stringsAsFactors = FALSE)) } if (!"R" %in% data$x) { - data <- rbind2(data, data.frame(x = "R", n = 0, s = 0, stringsAsFactors = FALSE)) + data <- rbind_AMR(data, data.frame(x = "R", n = 0, s = 0, stringsAsFactors = FALSE)) } data$x <- factor(data$x, levels = c("S", "I", "R"), ordered = TRUE) diff --git a/R/proportion.R b/R/proportion.R index 3598322e..3492b4ae 100755 --- a/R/proportion.R +++ b/R/proportion.R @@ -274,7 +274,7 @@ sir_confidence_interval <- function(..., meet_criteria(confidence_level, allow_class = "numeric", is_positive = TRUE, has_length = 1) meet_criteria(side, allow_class = "character", has_length = 1, is_in = c("both", "b", "left", "l", "lower", "lowest", "less", "min", "right", "r", "higher", "highest", "greater", "g", "max")) meet_criteria(collapse, allow_class = c("logical", "character"), has_length = 1) - + x <- tryCatch( sir_calc(..., ab_result = ab_result, @@ -313,9 +313,9 @@ sir_confidence_interval <- function(..., if (n < minimum) { warning_("Introducing NA: ", - ifelse(n == 0, "no", paste("only", n)), - " results available for `sir_confidence_interval()` (`minimum` = ", minimum, ").", - call = FALSE + ifelse(n == 0, "no", paste("only", n)), + " results available for `sir_confidence_interval()` (`minimum` = ", minimum, ").", + call = FALSE ) if (is.character(out)) { return(NA_character_) @@ -323,7 +323,7 @@ sir_confidence_interval <- function(..., return(NA_real_) } } - + out } diff --git a/R/sir.R b/R/sir.R index 93f1b4fa..06c07e2d 100755 --- a/R/sir.R +++ b/R/sir.R @@ -999,7 +999,7 @@ as_sir_method <- function(method_short, } if (method == "mic") { - new_sir <- quick_case_when( + new_sir <- case_when_AMR( is.na(values) ~ NA_sir_, values <= breakpoints_current$breakpoint_S ~ as.sir("S"), guideline_coerced %like% "EUCAST" & values > breakpoints_current$breakpoint_R ~ as.sir("R"), @@ -1010,7 +1010,7 @@ as_sir_method <- function(method_short, TRUE ~ NA_sir_ ) } else if (method == "disk") { - new_sir <- quick_case_when( + new_sir <- case_when_AMR( is.na(values) ~ NA_sir_, as.double(values) >= as.double(breakpoints_current$breakpoint_S) ~ as.sir("S"), guideline_coerced %like% "EUCAST" & as.double(values) < as.double(breakpoints_current$breakpoint_R) ~ as.sir("R"), @@ -1023,7 +1023,7 @@ as_sir_method <- function(method_short, } # write to verbose output - AMR_env$sir_interpretation_history <- rbind2( + AMR_env$sir_interpretation_history <- rbind_AMR( AMR_env$sir_interpretation_history, # recycling 1 to 2 rows does not seem to work, which is why rep() was added data.frame( diff --git a/R/sir_calc.R b/R/sir_calc.R index d5545ec9..24f0fd1e 100755 --- a/R/sir_calc.R +++ b/R/sir_calc.R @@ -322,7 +322,7 @@ sir_calc_df <- function(type, # "proportion", "count" or "both" } out_new <- cbind(group_values, out_new) } - out <- rbind2(out, out_new) + out <- rbind_AMR(out, out_new) } } out @@ -331,7 +331,7 @@ sir_calc_df <- function(type, # "proportion", "count" or "both" # based on pm_apply_grouped_function apply_group <- function(.data, fn, groups, drop = FALSE, ...) { grouped <- pm_split_into_groups(.data, groups, drop) - res <- do.call(rbind2, unname(lapply(grouped, fn, ...))) + res <- do.call(rbind_AMR, unname(lapply(grouped, fn, ...))) if (any(groups %in% colnames(res))) { class(res) <- c("grouped_data", class(res)) res <- pm_set_groups(res, groups[groups %in% colnames(res)]) diff --git a/R/zzz.R b/R/zzz.R index e8ebeb7a..ec593c3f 100755 --- a/R/zzz.R +++ b/R/zzz.R @@ -195,7 +195,7 @@ if (utf8_supported && !is_latex) { # if custom ab option is available, load it if (!is.null(getOption("AMR_custom_ab")) && file.exists(getOption("AMR_custom_ab", default = ""))) { packageStartupMessage("Adding custom antimicrobials from '", getOption("AMR_custom_ab"), "'...", appendLF = FALSE) - x <- readRDS2(getOption("AMR_custom_ab")) + x <- readRDS_AMR(getOption("AMR_custom_ab")) tryCatch( { suppressWarnings(suppressMessages(add_custom_antimicrobials(x))) @@ -207,7 +207,7 @@ if (utf8_supported && !is_latex) { # if custom mo option is available, load it if (!is.null(getOption("AMR_custom_mo")) && file.exists(getOption("AMR_custom_mo", default = ""))) { packageStartupMessage("Adding custom microorganisms from '", getOption("AMR_custom_mo"), "'...", appendLF = FALSE) - x <- readRDS2(getOption("AMR_custom_mo")) + x <- readRDS_AMR(getOption("AMR_custom_mo")) tryCatch( { suppressWarnings(suppressMessages(add_custom_microorganisms(x))) diff --git a/README.md b/README.md index 88c9f3ce..20b9545e 100755 --- a/README.md +++ b/README.md @@ -27,26 +27,8 @@ install.packages("AMR") It will be downloaded and installed automatically. For RStudio, click on the menu *Tools* > *Install Packages...* and then type in "AMR" and press Install. -### Copyright +---- -This R package is licensed under the [GNU General Public License (GPL) v2.0](https://github.com/msberends/AMR/blob/main/LICENSE). In a nutshell, this means that this package: - -- May be used for commercial purposes - -- May be used for private purposes - -- May **not** be used for patent purposes - -- May be modified, although: - - - Modifications **must** be released under the same license when distributing the package - - Changes made to the code **must** be documented - -- May be distributed, although: - - - Source code **must** be made available when the package is distributed - - A copy of the license and copyright notice **must** be included with the package. - -- Comes with a LIMITATION of liability - -- Comes with NO warranty + +This AMR package for R is free, open-source software and licensed under the [GNU General Public License v2.0 (GPL-2)](https://msberends.github.io/AMR/LICENSE-text.html). These requirements are consequently legally binding: modifications must be released under the same license when distributing the package, changes made to the code must be documented, source code must be made available when the package is distributed, and a copy of the license and copyright notice must be included with the package. + diff --git a/man/AMR.Rd b/man/AMR.Rd index 818bf5bf..5163ffd2 100644 --- a/man/AMR.Rd +++ b/man/AMR.Rd @@ -30,11 +30,11 @@ Welcome to the \code{AMR} package. The \code{AMR} package is a \href{https://msberends.github.io/AMR/#copyright}{free and open-source} R package with \href{https://en.wikipedia.org/wiki/Dependency_hell}{zero dependencies} to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. \strong{Our aim is to provide a standard} for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. \href{https://msberends.github.io/AMR/authors.html}{Many different researchers} from around the globe are continually helping us to make this a successful and durable project! -This work was published in the Journal of Statistical Software (Volume 104(3); \href{https://doi.org/10.18637/jss.v104.i03}{DOI 10.18637/jss.v104.i03}) and formed the basis of two PhD theses (\href{https://doi.org/10.33612/diss.177417131}{DOI 10.33612/diss.177417131} and \href{https://doi.org/10.33612/diss.192486375}{DOI 10.33612/diss.192486375}). +This work was published in the Journal of Statistical Software (Volume 104(3); \doi{jss.v104.i03}) and formed the basis of two PhD theses (\doi{10.33612/diss.177417131} and \doi{10.33612/diss.192486375}). -After installing this package, R knows \href{https://msberends.github.io/AMR/reference/microorganisms.html}{\strong{~52 000}} (updated December 2022) and all \href{https://msberends.github.io/AMR/reference/antibiotics.html}{\strong{~600 antibiotic, antimycotic and antiviral drugs}} by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral breakpoint guidelines from CLSI and EUCAST are included from the last 10 years. It supports and can read any data format, including WHONET data. This package works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). \strong{It was designed to work in any setting, including those with very limited resources}. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the \href{https://www.rug.nl}{University of Groningen}, in collaboration with non-profit organisations \href{https://www.certe.nl}{Certe Medical Diagnostics and Advice Foundation} and \href{https://www.umcg.nl}{University Medical Center Groningen}. +After installing this package, R knows \href{https://msberends.github.io/AMR/reference/microorganisms.html}{\strong{~52 000 microorganisms}} (updated December 2022) and all \href{https://msberends.github.io/AMR/reference/antibiotics.html}{\strong{~600 antibiotic, antimycotic and antiviral drugs}} by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral breakpoint guidelines from CLSI and EUCAST are included from the last 10 years. It supports and can read any data format, including WHONET data. This package works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). \strong{It was designed to work in any setting, including those with very limited resources}. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the \href{https://www.rug.nl}{University of Groningen}, in collaboration with non-profit organisations \href{https://www.certe.nl}{Certe Medical Diagnostics and Advice Foundation} and \href{https://www.umcg.nl}{University Medical Center Groningen}. -The \code{AMR} package is available in English, Chinese, Danish, Dutch, French, German, Greek, Italian, Japanese, Polish, Portuguese, Russian, Spanish, Swedish, Turkish and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages. +The \code{AMR} package is available in English, Chinese, Czech, Danish, Dutch, Finnish, French, German, Greek, Italian, Japanese, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish, and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages. } \section{Reference Data Publicly Available}{ diff --git a/man/add_custom_antimicrobials.Rd b/man/add_custom_antimicrobials.Rd index 962c20ed..f9c32f9e 100644 --- a/man/add_custom_antimicrobials.Rd +++ b/man/add_custom_antimicrobials.Rd @@ -18,7 +18,7 @@ With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you c \details{ \strong{Important:} 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. -There are two ways to automate this process: +There are two ways to circumvent this and automate the process of adding antimicrobials: \strong{Method 1:} Using the \link[=AMR-options]{package option} \code{\link[=AMR-options]{AMR_custom_ab}}, which is the preferred method. To use this method: \enumerate{ @@ -32,7 +32,7 @@ options(AMR_custom_ab = "~/my_custom_ab.rds") Upon package load, this file will be loaded and run through the \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} function. } -\strong{Method 2:} Loading the antimicrobial additions directly from your \code{.Rprofile} file. An important downside is that this requires the \code{AMR} package to be installed or else this method will fail. To use this method: +\strong{Method 2:} Loading the antimicrobial additions directly from your \code{.Rprofile} file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method: \enumerate{ \item Edit the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}. \item Add a text like below and save the file: diff --git a/man/add_custom_microorganisms.Rd b/man/add_custom_microorganisms.Rd index 3e716237..aaf76e1b 100644 --- a/man/add_custom_microorganisms.Rd +++ b/man/add_custom_microorganisms.Rd @@ -20,7 +20,7 @@ This function will fill in missing taxonomy for you, if specific taxonomic colum \strong{Important:} Due to how \R works, the \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} function has to be run in every \R session - added microorganisms are not stored between sessions and are thus lost when \R is exited. -There are two ways to automate this process: +There are two ways to circumvent this and automate the process of adding microorganisms: \strong{Method 1:} Using the \link[=AMR-options]{package option} \code{\link[=AMR-options]{AMR_custom_mo}}, which is the preferred method. To use this method: \enumerate{ @@ -34,7 +34,7 @@ options(AMR_custom_mo = "~/my_custom_mo.rds") Upon package load, this file will be loaded and run through the \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} function. } -\strong{Method 2:} Loading the microorganism directly from your \code{.Rprofile} file. An important downside is that this requires the \code{AMR} package to be installed or else this method will fail. To use this method: +\strong{Method 2:} Loading the microorganism directly from your \code{.Rprofile} file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method: \enumerate{ \item Edit the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}. \item Add a text like below and save the file: @@ -47,7 +47,7 @@ Upon package load, this file will be loaded and run through the \code{\link[=add }\if{html}{\out{}} } -Use \code{\link[=clear_custom_microorganisms]{clear_custom_microorganisms()}} to clear the previously added antimicrobials. +Use \code{\link[=clear_custom_microorganisms]{clear_custom_microorganisms()}} to clear the previously added microorganisms. } \examples{ \donttest{ diff --git a/man/antibiotic_class_selectors.Rd b/man/antibiotic_class_selectors.Rd index b34605d2..dda6eba5 100644 --- a/man/antibiotic_class_selectors.Rd +++ b/man/antibiotic_class_selectors.Rd @@ -299,7 +299,7 @@ if (require("dplyr")) { select(penicillins()) # only the 'J01CA01' column will be selected } if (require("dplyr")) { - # with recent versions of dplyr this is all equal: + # with recent versions of dplyr, this is all equal: x <- example_isolates[carbapenems() == "R", ] y <- example_isolates \%>\% filter(carbapenems() == "R") z <- example_isolates \%>\% filter(if_all(carbapenems(), ~ .x == "R")) @@ -310,29 +310,33 @@ if (require("dplyr")) { # data.table -------------------------------------------------------------- # data.table is supported as well, just use it in the same way as with -# base R, but add `with = FALSE` if using a single AB selector: +# base R, but add `with = FALSE` if using a single AB selector. if (require("data.table")) { dt <- as.data.table(example_isolates) - print( - dt[, carbapenems()] # incorrect, returns column *names* - ) - print( - dt[, carbapenems(), with = FALSE] # so `with = FALSE` is required - ) - - # for multiple selections or AB selectors, `with = FALSE` is not needed: - print( - dt[, c("mo", aminoglycosides())] - ) - print( - dt[, c(carbapenems(), aminoglycosides())] - ) - - # row filters are also supported: - print(dt[any(carbapenems() == "S"), ]) - print(dt[any(carbapenems() == "S"), penicillins(), with = FALSE]) + # this does not work, it returns column *names* + dt[, carbapenems()] +} +if (require("data.table")) { + # so `with = FALSE` is required + dt[, carbapenems(), with = FALSE] +} + +# for multiple selections or AB selectors, `with = FALSE` is not needed: +if (require("data.table")) { + dt[, c("mo", aminoglycosides())] +} +if (require("data.table")) { + dt[, c(carbapenems(), aminoglycosides())] +} + +# row filters are also supported: +if (require("data.table")) { + dt[any(carbapenems() == "S"), ] +} +if (require("data.table")) { + dt[any(carbapenems() == "S"), penicillins(), with = FALSE] } } } diff --git a/vignettes/welcome_to_AMR.Rmd b/vignettes/welcome_to_AMR.Rmd index e2d33b3b..aee13786 100644 --- a/vignettes/welcome_to_AMR.Rmd +++ b/vignettes/welcome_to_AMR.Rmd @@ -26,13 +26,13 @@ Note: to keep the package size as small as possible, we only included this vigne ---- -The `AMR` package is a [free and open-source](https://msberends.github.io/AMR/#copyright) R package with [zero dependencies](https://en.wikipedia.org/wiki/Dependency_hell) to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. **Our aim is to provide a standard** for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. +The `AMR` package is a [free and open-source](https://msberends.github.io/AMR/#copyright) R package with [zero dependencies](https://en.wikipedia.org/wiki/Dependency_hell) to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. **Our aim is to provide a standard** for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. [Many different researchers](https://msberends.github.io/AMR/authors.html) from around the globe are continually helping us to make this a successful and durable project! This work was published in the Journal of Statistical Software (Volume 104(3); [DOI 10.18637/jss.v104.i03](https://doi.org/10.18637/jss.v104.i03)) and formed the basis of two PhD theses ([DOI 10.33612/diss.177417131](https://doi.org/10.33612/diss.177417131) and [DOI 10.33612/diss.192486375](https://doi.org/10.33612/diss.192486375)). After installing this package, R knows `r AMR:::format_included_data_number(AMR::microorganisms)` distinct microbial species and all `r AMR:::format_included_data_number(rbind(AMR::antibiotics[, "atc", drop = FALSE], AMR::antivirals[, "atc", drop = FALSE]))` antibiotic, antimycotic and antiviral drugs by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral breakpoint guidelines from CLSI and EUCAST are included from the last 10 years. It supports and can read any data format, including WHONET data. -The `AMR` package is available in English, Chinese, Danish, Dutch, French, German, Greek, Italian, Japanese, Polish, Portuguese, Russian, Spanish, Swedish, Turkish and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages. +With the help of contributors from all corners of the world, the `AMR` package is available in English, Czech, Chinese, Danish, Dutch, Finnish, French, German, Greek, Italian, Japanese, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish, and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages. This package is fully independent of any other R package and works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). **It was designed to work in any setting, including those with very limited resources**. Since its first public release in early 2018, this package has been downloaded from more than 175 countries. @@ -57,7 +57,7 @@ This package can be used for: All reference data sets (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) in this `AMR` package are publicly and freely available. We continually export our data sets to formats for use in R, SPSS, SAS, Stata and Excel. We also supply flat files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please find [all download links on our website](https://msberends.github.io/AMR/articles/datasets.html), which is automatically updated with every code change. -This R package was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the [University of Groningen](https://www.rug.nl), in collaboration with non-profit organisations [Certe Medical Diagnostics and Advice Foundation](https://www.certe.nl) and [University Medical Center Groningen](https://www.umcg.nl), and is being [actively and durably maintained](./news) by two public healthcare organisations in the Netherlands. +This R package was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the [University of Groningen](https://www.rug.nl), in collaboration with non-profit organisations [Certe Medical Diagnostics and Advice Foundation](https://www.certe.nl) and [University Medical Center Groningen](https://www.umcg.nl), and is being [actively and durably maintained](https://msberends.github.io/AMR/news) by two public healthcare organisations in the Netherlands. ----