diff --git a/DESCRIPTION b/DESCRIPTION index 1bfeea3a..5449f6f4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 2.1.1.9032 -Date: 2024-05-20 +Version: 2.1.1.9033 +Date: 2024-05-24 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/NAMESPACE b/NAMESPACE index 1dac7af9..b1e7296e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -235,7 +235,6 @@ export(kurtosis) export(labels_sir_count) export(left_join_microorganisms) export(like) -export(limit_mic_range) export(lincosamides) export(lipoglycopeptides) export(macrolides) @@ -302,6 +301,7 @@ export(quinolones) export(random_disk) export(random_mic) export(random_sir) +export(rescale_mic) export(reset_AMR_locale) export(resistance) export(resistance_predict) diff --git a/NEWS.md b/NEWS.md index 12d3dbfb..c685ffb2 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 2.1.1.9032 +# AMR 2.1.1.9033 *(this beta version will eventually become v3.0. We're happy to reach a new major milestone soon, which will be all about the new One Health support!)* @@ -17,14 +17,14 @@ This package now supports not only tools for AMR data analysis in clinical setti * `ab_url()` now supports retrieving the WHOCC url of their ATCvet pages * `as.sir()` now returns additional factor levels "N" for non-interpretable and "SDD" for susceptible dose-dependent. Users can now set their own criteria (using regular expressions) as to what should be considered S, I, R, SDD, and N. * The function group `scale_*_mic()`, namely: `scale_x_mic()`, `scale_y_mic()`, `scale_colour_mic()` and `scale_fill_mic()`. They are advanced ggplot2 extensions to allow easy plotting of MIC values. They allow for manual range definition and plotting missing intermediate log2 levels. -* Function `limit_mic_range()`, which allows to limit MIC values to a manually set range. This is the powerhouse behind the `scale_*_mic()` functions, but it can be used by users directly to e.g. compare equality in MIC distributions by rescaling them to the same range first. -* Function `mo_group_members()` to retrieve the member microorganisms. For example, `mo_group_members("Strep group C")` returns a vector of all microorganisms that are in that group. +* Function `rescale_mic()`, which allows to rescale MIC values to a manually set range. This is the powerhouse behind the `scale_*_mic()` functions, but it can be used by users directly to e.g. compare equality in MIC distributions by rescaling them to the same range first. +* Function `mo_group_members()` to retrieve the member microorganisms of a microorganism group. For example, `mo_group_members("Strep group C")` returns a vector of all microorganisms that are in that group. ## Changed * For SIR interpretation, it is now possible to use column names for argument `ab` and `mo`: `as.sir(..., ab = "column1", mo = "column2")`. This greatly improves the flexibility for users. * For MICs: * Added as valid levels: 4096, 6 powers of 0.0625, and 5 powers of 192 (192, 384, 576, 768, 960) - * Added new argument `keep_operators` to `as.mic()`. This can be `"all"` (default), `"none"`, or `"edges"`. This argument is also available in the new `limit_mic_range()` and `scale_*_mic()` functions. + * Added new argument `keep_operators` to `as.mic()`. This can be `"all"` (default), `"none"`, or `"edges"`. This argument is also available in the new `rescale_mic()` and `scale_*_mic()` functions. * Comparisons of MIC values are now more strict. For example, `>32` is higher than (and never equal to) `32`. Thus, `as.mic(">32") == as.mic(32)` now returns `FALSE`, and `as.mic(">32") > as.mic(32)` now returns `TRUE`. * Updated `italicise_taxonomy()` to support HTML output * `mo_info()` now contains an extra element `group_members`, with the contents of the new `mo_group_members()` function diff --git a/R/mic.R b/R/mic.R index 1ba1b13e..653d64a3 100644 --- a/R/mic.R +++ b/R/mic.R @@ -96,7 +96,7 @@ VALID_MIC_LEVELS <- c(t(vapply(FUN.VALUE = character(length(VALID_MIC_LEVELS)), #' #' Use [droplevels()] to drop unused levels. At default, it will return a plain factor. Use `droplevels(..., as.mic = TRUE)` to maintain the `mic` class. #' -#' With [limit_mic_range()], existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions. +#' With [rescale_mic()], existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions. #' #' For `ggplot2`, use one of the [`scale_*_mic()`][scale_x_mic()] functions to plot MIC values. They allows custom MIC ranges and to plot intermediate log2 levels for missing MIC values. #' @return Ordered [factor] with additional class [`mic`], that in mathematical operations acts as a [numeric] vector. Bear in mind that the outcome of any mathematical operation on MICs will return a [numeric] value. @@ -116,8 +116,8 @@ VALID_MIC_LEVELS <- c(t(vapply(FUN.VALUE = character(length(VALID_MIC_LEVELS)), #' quantile(mic_data) #' all(mic_data < 512) #' -#' # limit MICs using limit_mic_range() -#' limit_mic_range(mic_data, mic_range = c(4, 16)) +#' # limit MICs using rescale_mic() +#' rescale_mic(mic_data, mic_range = c(4, 16)) #' #' # interpret MIC values #' as.sir( @@ -270,7 +270,7 @@ NA_mic_ <- set_clean_class(factor(NA, levels = VALID_MIC_LEVELS, ordered = TRUE) #' @rdname as.mic #' @param mic_range a manual range to limit the MIC values, e.g., `mic_range = c(0.001, 32)`. Use `NA` to set no limit on one side, e.g., `mic_range = c(NA, 32)`. #' @export -limit_mic_range <- function(x, mic_range, keep_operators = "edges", as.mic = TRUE) { +rescale_mic <- function(x, mic_range, keep_operators = "edges", as.mic = TRUE) { meet_criteria(mic_range, allow_class = c("numeric", "integer", "logical"), has_length = 2, allow_NA = TRUE, allow_NULL = TRUE) stop_ifnot(all(mic_range %in% c(VALID_MIC_LEVELS, NA)), "Values in `mic_range` must be valid MIC values. Unvalid: ", vector_and(mic_range[mic_range %in% c(VALID_MIC_LEVELS, NA)])) diff --git a/R/plot.R b/R/plot.R index d4727df3..07e7ac82 100755 --- a/R/plot.R +++ b/R/plot.R @@ -117,7 +117,7 @@ scale_x_mic <- function(keep_operators = "edges", mic_range = NULL, drop = FALSE meet_criteria(drop, allow_class = "logical", has_length = 1) scale <- ggplot2::scale_x_discrete(drop = drop, ...) scale$transform <- function(x, keep_ops = keep_operators, mic_rng = mic_range) { - limit_mic_range(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) + rescale_mic(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) } scale } @@ -130,7 +130,7 @@ scale_y_mic <- function(keep_operators = "edges", mic_range = NULL, drop = FALSE meet_criteria(drop, allow_class = "logical", has_length = 1) scale <- ggplot2::scale_y_discrete(drop = drop, ...) scale$transform <- function(x, keep_ops = keep_operators, mic_rng = mic_range) { - limit_mic_range(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) + rescale_mic(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) } scale } @@ -143,7 +143,7 @@ scale_colour_mic <- function(keep_operators = "edges", mic_range = NULL, drop = meet_criteria(drop, allow_class = "logical", has_length = 1) scale <- ggplot2::scale_colour_discrete(drop = drop, ...) scale$transform <- function(x, keep_ops = keep_operators, mic_rng = mic_range) { - limit_mic_range(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) + rescale_mic(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) } scale } @@ -156,7 +156,7 @@ scale_fill_mic <- function(keep_operators = "edges", mic_range = NULL, drop = FA meet_criteria(drop, allow_class = "logical", has_length = 1) scale <- ggplot2::scale_fill_discrete(drop = drop, ...) scale$transform <- function(x, keep_ops = keep_operators, mic_rng = mic_range) { - limit_mic_range(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) + rescale_mic(x = x, keep_operators = keep_ops, mic_range = mic_rng, as.mic = FALSE) } scale } diff --git a/R/sir.R b/R/sir.R index d5ab34d7..4232e070 100755 --- a/R/sir.R +++ b/R/sir.R @@ -323,7 +323,7 @@ is_sir_eligible <- function(x, threshold = 0.05) { #' @rdname as.sir #' @export -#' @param S,I,R,N,SDD a case-indepdendent [regular expression][base::regex] to translate input to this result. This regular expression will be run *after* all non-letters are removed from the input. +#' @param S,I,R,N,SDD a case-independent [regular expression][base::regex] to translate input to this result. This regular expression will be run *after* all non-letters are removed from the input. # extra param: warn (logical, to never throw a warning) as.sir.default <- function(x, S = "^(S|U)+$", I = "^(I|H)+$", R = "^(R)+$", N = "^(N|V)+$", SDD = "^(SDD|D)+$", ...) { if (inherits(x, "sir")) { diff --git a/man/as.mic.Rd b/man/as.mic.Rd index 20c21bcc..80e6484c 100644 --- a/man/as.mic.Rd +++ b/man/as.mic.Rd @@ -6,7 +6,7 @@ \alias{mic} \alias{is.mic} \alias{NA_mic_} -\alias{limit_mic_range} +\alias{rescale_mic} \alias{droplevels.mic} \title{Transform Input to Minimum Inhibitory Concentrations (MIC)} \usage{ @@ -16,7 +16,7 @@ is.mic(x) NA_mic_ -limit_mic_range(x, mic_range, keep_operators = "edges", as.mic = TRUE) +rescale_mic(x, mic_range, keep_operators = "edges", as.mic = TRUE) \method{droplevels}{mic}(x, as.mic = FALSE, ...) } @@ -82,7 +82,7 @@ Using \code{\link[=as.double]{as.double()}} or \code{\link[=as.numeric]{as.numer Use \code{\link[=droplevels]{droplevels()}} to drop unused levels. At default, it will return a plain factor. Use \code{droplevels(..., as.mic = TRUE)} to maintain the \code{mic} class. -With \code{\link[=limit_mic_range]{limit_mic_range()}}, existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions. +With \code{\link[=rescale_mic]{rescale_mic()}}, existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions. For \code{ggplot2}, use one of the \code{\link[=scale_x_mic]{scale_*_mic()}} functions to plot MIC values. They allows custom MIC ranges and to plot intermediate log2 levels for missing MIC values. @@ -101,8 +101,8 @@ fivenum(mic_data) quantile(mic_data) all(mic_data < 512) -# limit MICs using limit_mic_range() -limit_mic_range(mic_data, mic_range = c(4, 16)) +# limit MICs using rescale_mic() +rescale_mic(mic_data, mic_range = c(4, 16)) # interpret MIC values as.sir( diff --git a/man/as.sir.Rd b/man/as.sir.Rd index 1a468a2a..1a02d1b5 100644 --- a/man/as.sir.Rd +++ b/man/as.sir.Rd @@ -96,7 +96,7 @@ sir_interpretation_history(clean = FALSE) \item{threshold}{maximum fraction of invalid antimicrobial interpretations of \code{x}, see \emph{Examples}} -\item{S, I, R, N, SDD}{a case-indepdendent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters are removed from the input.} +\item{S, I, R, N, SDD}{a case-independent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters are removed from the input.} \item{mo}{a vector (or column name) with \link{character}s that can be coerced to valid microorganism codes with \code{\link[=as.mo]{as.mo()}}, can be left empty to determine it automatically}