From c8bcecf232668b8f6e78080e2006dc6071ef496d Mon Sep 17 00:00:00 2001 From: "Matthijs S. Berends" Date: Sat, 12 Dec 2020 23:17:29 +0100 Subject: [PATCH] (v1.4.0.9037) random_* functions --- .Rbuildignore | 1 + DESCRIPTION | 4 +- NAMESPACE | 4 + NEWS.md | 7 +- R/ab_property.R | 2 +- R/disk.R | 24 ++ R/is_new_episode.R | 4 +- R/mic.R | 10 +- R/random.R | 133 ++++++++++++ _pkgdown.yml | 1 + docs/404.html | 2 +- docs/LICENSE-text.html | 2 +- docs/articles/index.html | 2 +- docs/authors.html | 2 +- docs/index.html | 85 ++++---- docs/news/index.html | 15 +- docs/pkgdown.yml | 4 +- docs/reference/index.html | 10 +- docs/reference/is_new_episode.html | 10 +- docs/reference/plot.html | 16 +- docs/reference/random.html | 338 +++++++++++++++++++++++++++++ docs/sitemap.xml | 3 + docs/survey.html | 2 +- man/is_new_episode.Rd | 10 +- man/plot.Rd | 12 +- man/random.Rd | 64 ++++++ tests/testthat/test-random.R | 44 ++++ 27 files changed, 731 insertions(+), 80 deletions(-) create mode 100644 R/random.R create mode 100644 docs/reference/random.html create mode 100644 man/random.Rd create mode 100644 tests/testthat/test-random.R diff --git a/.Rbuildignore b/.Rbuildignore index 67cfd832..004dd495 100755 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -21,6 +21,7 @@ ^public$ ^data-raw$ ^\.lintr$ +^tests/testthat/_snaps$ ^vignettes/AMR.Rmd$ ^vignettes/benchmarks.Rmd$ ^vignettes/EUCAST.Rmd$ diff --git a/DESCRIPTION b/DESCRIPTION index bdaa486a..67169e31 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 1.4.0.9036 -Date: 2020-12-11 +Version: 1.4.0.9037 +Date: 2020-12-12 Title: Antimicrobial Resistance Analysis Authors@R: c( person(role = c("aut", "cre"), diff --git a/NAMESPACE b/NAMESPACE index a4750927..803a5fb1 100755 --- a/NAMESPACE +++ b/NAMESPACE @@ -40,6 +40,7 @@ S3method(format,bug_drug_combinations) S3method(kurtosis,data.frame) S3method(kurtosis,default) S3method(kurtosis,matrix) +S3method(plot,disk) S3method(plot,mic) S3method(plot,resistance_predict) S3method(plot,rsi) @@ -203,6 +204,9 @@ export(proportion_R) export(proportion_S) export(proportion_SI) export(proportion_df) +export(random_disk) +export(random_mic) +export(random_rsi) export(resistance) export(resistance_predict) export(right_join_microorganisms) diff --git a/NEWS.md b/NEWS.md index ac7b9e21..9d45e44b 100755 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,5 @@ -# AMR 1.4.0.9036 -## Last updated: 11 December 2020 +# AMR 1.4.0.9037 +## Last updated: 12 December 2020 ### New * Function `is_new_episode()` to determine patient episodes which are not necessarily based on microorganisms. It also supports grouped variables with e.g. `mutate()`, `filter()` and `summarise()` of the `dplyr` package: @@ -11,6 +11,7 @@ ``` * Functions `mo_is_gram_negative()` and `mo_is_gram_positive()` as wrappers around `mo_gramstain()`. They always return `TRUE` or `FALSE` (except when the input is `NA` or the MO code is `UNKNOWN`), thus always return `FALSE` for species outside the taxonomic kingdom of Bacteria. * Function `mo_is_intrinsic_resistant()` to test for intrinsic resistance, based on [EUCAST Intrinsic Resistance and Unusual Phenotypes v3.2](https://www.eucast.org/expert_rules_and_intrinsic_resistance/) from 2020. +* Functions `random_mic()`, `random_disk()` and `random_rsi()` for random number generation. They take microorganism names and antibiotic names as input to make generation more realistic. ### Changed * Reference data used for `as.rsi()` can now be set by the user, using the `reference_data` parameter. This allows for using own interpretation guidelines. The user-set data must have the same structure as `rsi_translation`. @@ -36,6 +37,8 @@ * Fixed a bug where `as.ab()` would sometimes fail * If using `as.rsi()` on MICs or disk diffusion while there is intrinsic antimicrobial resistance, a warning will be thrown to remind about this * Better tibble printing for MIC values +* Fix for plotting MIC values with `plot()` +* Added `plot()` generic to class `` ### Other * All messages and warnings thrown by this package now break sentences on whole words diff --git a/R/ab_property.R b/R/ab_property.R index c6af266f..476d6e3e 100644 --- a/R/ab_property.R +++ b/R/ab_property.R @@ -260,7 +260,7 @@ ab_validate <- function(x, property, ...) { if (!all(x %in% antibiotics[, property])) { x <- data.frame(ab = as.ab(x, ...), stringsAsFactors = FALSE) %pm>% pm_left_join(antibiotics, by = "ab") %pm>% - pm_pull(property) + pm_pull(property) } if (property == "ab") { return(set_clean_class(x, new_class = c("ab", "character"))) diff --git a/R/disk.R b/R/disk.R index eb2fc05f..824052ca 100644 --- a/R/disk.R +++ b/R/disk.R @@ -144,6 +144,30 @@ print.disk <- function(x, ...) { print(as.integer(x), quote = FALSE) } +#' @method plot disk +#' @export +#' @importFrom graphics barplot axis +#' @rdname plot +plot.disk <- function(x, + main = paste("Disk zones values of", deparse(substitute(x))), + ylab = "Frequency", + xlab = "Disk diffusion (mm)", + axes = FALSE, + ...) { + meet_criteria(main, allow_class = "character", has_length = 1) + meet_criteria(ylab, allow_class = "character", has_length = 1) + meet_criteria(xlab, allow_class = "character", has_length = 1) + meet_criteria(axes, allow_class = "logical", has_length = 1) + + barplot(table(x), + ylab = ylab, + xlab = xlab, + axes = axes, + main = main, + ...) + axis(2, seq(0, max(table(x)))) +} + #' @method [ disk #' @export #' @noRd diff --git a/R/is_new_episode.R b/R/is_new_episode.R index 14079031..d07d8141 100644 --- a/R/is_new_episode.R +++ b/R/is_new_episode.R @@ -26,13 +26,15 @@ #' Determine (new) episodes for patients #' #' This function determines which items in a vector can be considered (the start of) a new episode, based on the parameter `episode_days`. This can be used to determine clinical episodes for any epidemiological analysis. -#' @inheritSection lifecycle Experimental lifecycle +#' @inheritSection lifecycle Stable lifecycle #' @param x vector of dates (class `Date` or `POSIXt`) #' @param episode_days length of the required episode in days, defaults to 365. Every element in the input will return `TRUE` after this number of days has passed since the last included date, independent of calendar years. Please see *Details*. #' @param ... arguments passed on to [as.Date()] #' @details #' Dates are first sorted from old to new. The oldest date will mark the start of the first episode. After this date, the next date will be marked that is at least `episode_days` days later than the start of the first episode. From that second marked date on, the next date will be marked that is at least `episode_days` days later than the start of the second episode which will be the start of the third episode, and so on. Before the vector is being returned, the original order will be restored. #' +#' The [first_isolate()] function is a wrapper around the [is_new_episode()] function, but more efficient for data sets containing microorganism codes or names. +#' #' The `dplyr` package is not required for this function to work, but this function works conveniently inside `dplyr` verbs such as [`filter()`][dplyr::filter()], [`mutate()`][dplyr::mutate()] and [`summarise()`][dplyr::summarise()]. #' @return a [logical] vector #' @export diff --git a/R/mic.R b/R/mic.R index 8c8e8ba3..bb192e8f 100755 --- a/R/mic.R +++ b/R/mic.R @@ -223,7 +223,7 @@ summary.mic <- function(object, ...) { #' @method plot mic #' @export -#' @importFrom graphics barplot axis par +#' @importFrom graphics barplot axis #' @rdname plot plot.mic <- function(x, main = paste("MIC values of", deparse(substitute(x))), @@ -236,13 +236,13 @@ plot.mic <- function(x, meet_criteria(xlab, allow_class = "character", has_length = 1) meet_criteria(axes, allow_class = "logical", has_length = 1) - barplot(table(droplevels.factor(x)), + barplot(table(as.double(x)), ylab = ylab, xlab = xlab, axes = axes, main = main, ...) - axis(2, seq(0, max(table(droplevels.factor(x))))) + axis(2, seq(0, max(table(as.double(x))))) } #' @method barplot mic @@ -260,13 +260,13 @@ barplot.mic <- function(height, meet_criteria(xlab, allow_class = "character", has_length = 1) meet_criteria(axes, allow_class = "logical", has_length = 1) - barplot(table(droplevels.factor(height)), + barplot(table(as.double(height)), ylab = ylab, xlab = xlab, axes = axes, main = main, ...) - axis(2, seq(0, max(table(droplevels.factor(height))))) + axis(2, seq(0, max(table(as.double(height))))) } #' @method [ mic diff --git a/R/random.R b/R/random.R new file mode 100644 index 00000000..24d51f73 --- /dev/null +++ b/R/random.R @@ -0,0 +1,133 @@ +# ==================================================================== # +# TITLE # +# Antimicrobial Resistance (AMR) Analysis for R # +# # +# SOURCE # +# https://github.com/msberends/AMR # +# # +# LICENCE # +# (c) 2018-2020 Berends MS, Luz CF et al. # +# 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 analysis: https://msberends.github.io/AMR/ # +# ==================================================================== # + +#' Random MIC values/disk zones/RSI generation +#' +#' These functions can be used for generating random MIC values and disk diffusion diameters, for AMR analysis practice. +#' @inheritSection lifecycle Maturing lifecycle +#' @param size desired size of the returned vector +#' @param mo any character that can be coerced to a valid microorganism code with [as.mo()] +#' @param ab any character that can be coerced to a valid antimicrobial agent code with [as.ab()] +#' @param prob_RSI a vector of length 3: the probabilities for R (1st value), S (2nd value) and I (3rd value) +#' @param ... extension for future versions, not used at the moment +#' @details The base R function [sample()] is used for generating values. +#' +#' Generated values are based on the latest EUCAST guideline implemented in the [rsi_translation] data set. To create specific generated values per bug or drug, set the `mo` and/or `ab` parameter. +#' @return class `` for [random_mic()] (see [as.mic()]) and class `` for [random_disk()] (see [as.disk()]) +#' @name random +#' @rdname random +#' @export +#' @inheritSection AMR Read more on our website! +#' @examples +#' random_mic(100) +#' random_disk(100) +#' random_rsi(100) +#' +#' \donttest{ +#' # make the random generation more realistic by setting a bug and/or drug: +#' random_mic(100, "Klebsiella pneumoniae") # range 0.0625-64 +#' random_mic(100, "Klebsiella pneumoniae", "meropenem") # range 0.0625-16 +#' random_mic(100, "Streptococcus pneumoniae", "meropenem") # range 0.0625-4 +#' +#' random_disk(100, "Klebsiella pneumoniae") # range 11-50 +#' random_disk(100, "Klebsiella pneumoniae", "ampicillin") # range 6-14 +#' random_disk(100, "Streptococcus pneumoniae", "ampicillin") # range 16-22 +#' } +random_mic <- function(size, mo = NULL, ab = NULL, ...) { + random_exec("MIC", size = size, mo = mo, ab = ab) +} + +#' @rdname random +#' @export +random_disk <- function(size, mo = NULL, ab = NULL, ...) { + random_exec("DISK", size = size, mo = mo, ab = ab) +} + +#' @rdname random +#' @export +random_rsi <- function(size, prob_RSI = c(0.33, 0.33, 0.33), ...) { + sample(as.rsi(c("R", "S", "I")), size = size, replace = TRUE, prob = prob_RSI) +} + +random_exec <- function(type, size, mo = NULL, ab = NULL) { + df <- rsi_translation %pm>% + pm_filter(guideline %like% "EUCAST") %pm>% + pm_arrange(pm_desc(guideline)) %pm>% + subset(guideline == max(guideline) & + method == type) + + if (!is.null(mo)) { + mo_coerced <- as.mo(mo) + mo_include <- c(mo_coerced, + as.mo(mo_genus(mo_coerced)), + as.mo(mo_family(mo_coerced)), + as.mo(mo_order(mo_coerced))) + df_new <- df %pm>% + subset(mo %in% mo_include) + if (nrow(df_new) > 0) { + df <- df_new + } else { + warning_("No rows found that match mo '", mo, "', ignoring parameter `mo`", call = FALSE) + } + } + + if (!is.null(ab)) { + ab_coerced <- as.ab(ab) + df_new <- df %pm>% + subset(ab %in% ab_coerced) + if (nrow(df_new) > 0) { + df <- df_new + } else { + warning_("No rows found that match ab '", ab, "', ignoring parameter `ab`", call = FALSE) + } + } + + if (type == "MIC") { + # all valid MIC levels + valid_range <- as.mic(levels(as.mic(1))) + set_range_max <- max(df$breakpoint_R) + if (log(set_range_max, 2) %% 1 == 0) { + # return powers of 2 + valid_range <- unique(as.double(valid_range)) + # add one higher MIC level to set_range_max + set_range_max <- 2 ^ (log(set_range_max, 2) + 1) + set_range <- as.mic(valid_range[log(valid_range, 2) %% 1 == 0 & valid_range <= set_range_max]) + } else { + # no power of 2, return factors of 2 to left and right side + valid_mics <- suppressWarnings(as.mic(set_range_max / (2 ^ c(-3:3)))) + set_range <- valid_mics[!is.na(valid_mics)] + } + return(as.mic(sample(set_range, size = size, replace = TRUE))) + } else if (type == "DISK") { + set_range <- seq(from = as.integer(min(df$breakpoint_R)), + to = as.integer(max(df$breakpoint_S)), + by = 1) + out <- sample(set_range, size = size, replace = TRUE) + out[out < 6] <- sample(c(6:10), length(out[out < 6]), replace = TRUE) + out[out > 50] <- sample(c(40:50), length(out[out > 50]), replace = TRUE) + return(as.disk(out)) + } +} + diff --git a/_pkgdown.yml b/_pkgdown.yml index 82cf48df..d2e1f491 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -179,6 +179,7 @@ reference: - "`like`" - "`mo_matching_score`" - "`pca`" + - "`random`" - title: "Other: statistical tests" desc: > diff --git a/docs/404.html b/docs/404.html index de2032b5..2958537e 100644 --- a/docs/404.html +++ b/docs/404.html @@ -81,7 +81,7 @@ AMR (for R) - 1.4.0.9036 + 1.4.0.9037 diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html index 3d9a21c1..f96252b2 100644 --- a/docs/LICENSE-text.html +++ b/docs/LICENSE-text.html @@ -81,7 +81,7 @@ AMR (for R) - 1.4.0.9036 + 1.4.0.9037 diff --git a/docs/articles/index.html b/docs/articles/index.html index de0b6616..b08ec871 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -81,7 +81,7 @@ AMR (for R) - 1.4.0.9036 + 1.4.0.9037 diff --git a/docs/authors.html b/docs/authors.html index 8ac84045..ce1597da 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -81,7 +81,7 @@ AMR (for R) - 1.4.0.9036 + 1.4.0.9037 diff --git a/docs/index.html b/docs/index.html index 457aa513..0d049f2c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -43,7 +43,7 @@ AMR (for R) - 1.4.0.9036 + 1.4.0.9037 @@ -212,24 +212,24 @@ Since you are one of our users, we would like to know how you use the package an

Used in 135 countries
Since its first public release in early 2018, this package has been downloaded from 135 countries. Click the map to enlarge.

-

+



With AMR (for R), there’s always a knowledgeable microbiologist by your side!
-
# AMR works great with dplyr, but it's not required or neccesary
-library(AMR)
-library(dplyr)
-
-example_isolates %>%
-  mutate(mo = mo_fullname(mo)) %>%
-  filter(mo_is_gram_negative(), mo_is_intrinsic_resistant(ab = "cefotax")) %>%
-  select(mo, aminoglycosides(), carbapenems())
-#> NOTE: Using column 'mo' as input for mo_is_gram_negative()
-#> NOTE: Using column 'mo' as input for mo_is_intrinsic_resistant()
-#> Selecting aminoglycosides: 'AMK' (amikacin), 'GEN' (gentamicin), 
-                              'KAN' (kanamycin), 'TOB' (tobramycin)
-#> Selecting carbapenems: 'IPM' (imipenem), 'MEM' (meropenem)
+
# AMR works great with dplyr, but it's not required or neccesary
+library(AMR)
+library(dplyr)
+
+example_isolates %>%
+  mutate(mo = mo_fullname(mo)) %>%
+  filter(mo_is_gram_negative(), mo_is_intrinsic_resistant(ab = "cefotax")) %>%
+  select(mo, aminoglycosides(), carbapenems())
+#> NOTE: Using column 'mo' as input for mo_is_gram_negative()
+#> NOTE: Using column 'mo' as input for mo_is_intrinsic_resistant()
+#> Selecting aminoglycosides: 'AMK' (amikacin), 'GEN' (gentamicin), 
+                              'KAN' (kanamycin), 'TOB' (tobramycin)
+#> Selecting carbapenems: 'IPM' (imipenem), 'MEM' (meropenem)

With only having defined a row filter on Gram-negative bacteria with intrinsic resistance to cefotaxime (mo_is_gram_positive() and mo_is_intrinsic_resistant()) and a column selection on two antibiotic groups (aminoglycosides() and carbapenems()), the reference data about all microorganisms and all antibiotics in the AMR package make sure you get what you meant:

@@ -317,31 +317,30 @@ Since you are one of our users, we would like to know how you use the package an
- -
-
-
-Download our data sets -
- -
-
-
-Start learning AMR analysis -
- -
-
-
-Interpret MIC/disk values to R/SI -
- -
-
-
-Determine multi-drug resistance (MDR) -
- +
<a href="articles/datasets.html">
+    <div style="background-color: #128f7635;">
+        <div class="fa fa-database"></div>
+        <span>Download our data sets</span>
+    </div>
+</a>
+<a href="articles/AMR.html">
+    <div style="background-color: #138F3865;">
+        <div class="fa fa-chalkboard-teacher"></div>
+        <span>Start learning AMR analysis</span>
+    </div>
+</a>
+<a href="reference/as.rsi.html">
+    <div style="background-color: #128f7650;">
+        <div class="fa fa-language"></div>
+        <span>Interpret MIC/disk values to R/SI</span>
+    </div>
+</a>
+<a href="articles/MDR.html">
+    <div style="background-color: #138F3835;">
+        <div class="fa fa-skull-crossbones"></div>
+        <span>Determine multi-drug resistance (MDR)</span>
+    </div>
+</a>
@@ -349,7 +348,7 @@ Since you are one of our users, we would like to know how you use the package an Partners

The development of this package is part of, related to, or made possible by:

- +

@@ -384,7 +383,7 @@ Since you are one of our users, we would like to know how you use the package an Latest released version

This package is available here on the official R network (CRAN), which has a peer-reviewed submission process. Install this package in R from CRAN by using the command:

-
+
 
It will be downloaded and installed automatically. For RStudio, click on the menu Tools > Install Packages… and then type in “AMR” and press Install.

 
Note: Not all functions on this website may be available in this latest release. To use all functions and data sets mentioned on this website, install the latest development version.

@@ -393,7 +392,7 @@ Since you are one of our users, we would like to know how you use the package an
 

 Latest development version

 
The latest and unpublished development version can be installed from GitHub using:

-
+
 install.packages("remotes") 
 remotes::install_github("msberends/AMR")

 

diff --git a/docs/news/index.html b/docs/news/index.html
index b1991b09..762ca72e 100644
--- a/docs/news/index.html
+++ b/docs/news/index.html
@@ -81,7 +81,7 @@
       
       
         AMR (for R)
-        1.4.0.9036
+        1.4.0.9037
@@ -236,13 +236,13 @@ Source: NEWS.md -
-

-AMR 1.4.0.9036 Unreleased +
+

+AMR 1.4.0.9037 Unreleased

-
+

-Last updated: 11 December 2020 +Last updated: 12 December 2020

@@ -258,6 +258,7 @@

  • Functions mo_is_gram_negative() and mo_is_gram_positive() as wrappers around mo_gramstain(). They always return TRUE or FALSE (except when the input is NA or the MO code is UNKNOWN), thus always return FALSE for species outside the taxonomic kingdom of Bacteria.

  • Function mo_is_intrinsic_resistant() to test for intrinsic resistance, based on EUCAST Intrinsic Resistance and Unusual Phenotypes v3.2 from 2020.

    • +

  • Functions random_mic(), random_disk() and random_rsi() for random number generation. They take microorganism names and antibiotic names as input to make generation more realistic.

    • @@ -288,6 +289,8 @@

  • Fixed a bug where as.ab() would sometimes fail

  • If using as.rsi() on MICs or disk diffusion while there is intrinsic antimicrobial resistance, a warning will be thrown to remind about this

  • Better tibble printing for MIC values

    • +

  • Fix for plotting MIC values with plot()

    • +

  • Added plot() generic to class <disk>

    • diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 528ab994..52f8d833 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -1,4 +1,4 @@ -pandoc: 2.9.2.1 +pandoc: 2.11.2 pkgdown: 1.6.1 pkgdown_sha: ~ articles: @@ -12,7 +12,7 @@ articles: datasets: datasets.html resistance_predict: resistance_predict.html welcome_to_AMR: welcome_to_AMR.html -last_built: 2020-12-11T11:03Z +last_built: 2020-12-12T21:53Z urls: reference: https://msberends.github.io/AMR//reference article: https://msberends.github.io/AMR//articles diff --git a/docs/reference/index.html b/docs/reference/index.html index c388bc3d..e15eee4d 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -81,7 +81,7 @@ AMR (for R) - 1.4.0.9036 + 1.4.0.9037
    @@ -447,7 +447,7 @@ -

    plot(<mic>) barplot(<mic>) plot(<rsi>) barplot(<rsi>)

    +

    plot(<disk>) plot(<mic>) barplot(<mic>) plot(<rsi>) barplot(<rsi>)

    Plotting for classes rsi and disk

    @@ -602,6 +602,12 @@

    pca()

    Principal Component Analysis (for AMR)

    + + + +

    random_mic() random_disk() random_rsi()

    + +

    Random MIC values/disk zones/RSI generation

    diff --git a/docs/reference/is_new_episode.html b/docs/reference/is_new_episode.html index 8f624d66..3ee4124c 100644 --- a/docs/reference/is_new_episode.html +++ b/docs/reference/is_new_episode.html @@ -82,7 +82,7 @@ AMR (for R) - 1.4.0.9034 + 1.4.0.9037
    @@ -267,13 +267,15 @@

    Details

    Dates are first sorted from old to new. The oldest date will mark the start of the first episode. After this date, the next date will be marked that is at least episode_days days later than the start of the first episode. From that second marked date on, the next date will be marked that is at least episode_days days later than the start of the second episode which will be the start of the third episode, and so on. Before the vector is being returned, the original order will be restored.

    +

    The first_isolate() function is a wrapper around the is_new_episode() function, but more efficient for data sets containing microorganism codes or names.

    The dplyr package is not required for this function to work, but this function works conveniently inside dplyr verbs such as filter(), mutate() and summarise().

    -

    Experimental lifecycle

    +

    Stable lifecycle

    -


    -The lifecycle of this function is experimental. An experimental function is in early stages of development. The unlying code might be changing frequently. Experimental functions might be removed without deprecation, so you are generally best off waiting until a function is more mature before you use it in production code. Experimental functions are only available in development versions of this AMR package and will thus not be included in releases that are submitted to CRAN, since such functions have not yet matured enough.

    +


    +The lifecycle of this function is stable. In a stable function, major changes are unlikely. This means that the unlying code will generally evolve by adding new arguments; removing arguments or changing the meaning of existing arguments will be avoided.

    +

    If the unlying code needs breaking changes, they will occur gradually. For example, a parameter will be deprecated and first continue to work, but will emit an message informing you of the change. Next, typically after at least one newly released version on CRAN, the message will be transformed to an error.

    Read more on our website!

    diff --git a/docs/reference/plot.html b/docs/reference/plot.html index 552c612c..cec4d02d 100644 --- a/docs/reference/plot.html +++ b/docs/reference/plot.html @@ -82,7 +82,7 @@ AMR (for R) - 1.4.0.9032 + 1.4.0.9037
    @@ -234,7 +234,7 @@

    Plotting for classes rsi and disk

    - Source: R/amr.R, R/mic.R, R/rsi.R + Source: R/amr.R, R/disk.R, R/mic.R, and 1 more
    @@ -242,7 +242,17 @@

    Functions to print classes of the AMR package.

    - 
    # S3 method for mic
+    
    # S3 method for disk
+plot(
+  x,
+  main = paste("Disk zones values of", deparse(substitute(x))),
+  ylab = "Frequency",
+  xlab = "Disk diffusion (mm)",
+  axes = FALSE,
+  ...
+)
+
+# S3 method for mic
 plot(
   x,
   main = paste("MIC values of", deparse(substitute(x))),
diff --git a/docs/reference/random.html b/docs/reference/random.html
new file mode 100644
index 00000000..86475dc8
--- /dev/null
+++ b/docs/reference/random.html
@@ -0,0 +1,338 @@
+
+
+
+  
+  
+
+
+
+Random MIC values/disk zones/RSI generation — random • AMR (for R)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+  
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+
+  
+    
    
+      
    
+      
+
+      
+
+      
    
+
+
    
+  
    
+    
    
+    
    Random MIC values/disk zones/RSI generation
    
+    Source: R/random.R
+    
+    
    
+
+    
    
+    
    These functions can be used for generating random MIC values and disk diffusion diameters, for AMR analysis practice.
    
+    
    
+
+    
    random_mic(size, mo = NULL, ab = NULL, ...)
+
+random_disk(size, mo = NULL, ab = NULL, ...)
+
+random_rsi(size, prob_RSI = c(0.33, 0.33, 0.33), ...)
    
+
+    
    Arguments
    
+    
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
    size
    desired size of the returned vector
    mo
    any character that can be coerced to a valid microorganism code with as.mo()
    ab
    any character that can be coerced to a valid antimicrobial agent code with as.ab()
    ...
    extension for future versions, not used at the moment
    prob_RSI
    a vector of length 3: the probabilities for R (1st value), S (2nd value) and I (3rd value)
    
+
+    
    Value
    
+
+    
    class <mic> for random_mic() (see as.mic()) and class <disk> for random_disk() (see as.disk())
    
+    
    Details
    
+
+    
    The base R function sample() is used for generating values.
    
+
    Generated values are based on the latest EUCAST guideline implemented in the rsi_translation data set. To create specific generated values per bug or drug, set the mo and/or ab parameter.
    
+    
    Maturing lifecycle
    
+
+    
+
+
     
    
+The lifecycle of this function is maturing. The unlying code of a maturing function has been roughed out, but finer details might still change. Since this function needs wider usage and more extensive testing, you are very welcome to suggest changes at our repository or write us an email (see section 'Contact Us').
    
+    
    Read more on our website!
    
+
+    
+
+
    On our website https://msberends.github.io/AMR/ you can find a comprehensive tutorial about how to conduct AMR analysis, the complete documentation of all functions and an example analysis using WHONET data. As we would like to better understand the backgrounds and needs of our users, please participate in our survey!
    
+
+    
    Examples
    
+    
    random_mic(100)
+random_disk(100)
+random_rsi(100)
+
+# \donttest{
+# make the random generation more realistic by setting a bug and/or drug:
+random_mic(100, "Klebsiella pneumoniae")                 # range 0.0625-64
+random_mic(100, "Klebsiella pneumoniae", "meropenem")    # range 0.0625-16
+random_mic(100, "Streptococcus pneumoniae", "meropenem") # range 0.0625-4
+
+random_disk(100, "Klebsiella pneumoniae")                  # range 11-50
+random_disk(100, "Klebsiella pneumoniae", "ampicillin")    # range 6-14
+random_disk(100, "Streptococcus pneumoniae", "ampicillin") # range 16-22
+# }
+
    
+  
    
+  
+
    
+
+
+      
+   
    
+
+  
+
+
+  
+
+
+
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index aace7d9c..8071036d 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -144,6 +144,9 @@
   
     https://msberends.github.io/AMR//reference/proportion.html
   
+  
+    https://msberends.github.io/AMR//reference/random.html
+  
   
     https://msberends.github.io/AMR//reference/resistance_predict.html
   
diff --git a/docs/survey.html b/docs/survey.html
index 4039473f..ef3156d8 100644
--- a/docs/survey.html
+++ b/docs/survey.html
@@ -81,7 +81,7 @@
       
       
         AMR (for R)
-        1.4.0.9036
+        1.4.0.9037
    diff --git a/man/is_new_episode.Rd b/man/is_new_episode.Rd index 0f4df478..2d9bc08e 100644 --- a/man/is_new_episode.Rd +++ b/man/is_new_episode.Rd @@ -22,12 +22,16 @@ This function determines which items in a vector can be considered (the start of \details{ Dates are first sorted from old to new. The oldest date will mark the start of the first episode. After this date, the next date will be marked that is at least \code{episode_days} days later than the start of the first episode. From that second marked date on, the next date will be marked that is at least \code{episode_days} days later than the start of the second episode which will be the start of the third episode, and so on. Before the vector is being returned, the original order will be restored. +The \code{\link[=first_isolate]{first_isolate()}} function is a wrapper around the \code{\link[=is_new_episode]{is_new_episode()}} function, but more efficient for data sets containing microorganism codes or names. + The \code{dplyr} package is not required for this function to work, but this function works conveniently inside \code{dplyr} verbs such as \code{\link[dplyr:filter]{filter()}}, \code{\link[dplyr:mutate]{mutate()}} and \code{\link[dplyr:summarise]{summarise()}}. } -\section{Experimental lifecycle}{ +\section{Stable lifecycle}{ -\if{html}{\figure{lifecycle_experimental.svg}{options: style=margin-bottom:5px} \cr} -The \link[=lifecycle]{lifecycle} of this function is \strong{experimental}. An experimental function is in early stages of development. The unlying code might be changing frequently. Experimental functions might be removed without deprecation, so you are generally best off waiting until a function is more mature before you use it in production code. Experimental functions are only available in development versions of this \code{AMR} package and will thus not be included in releases that are submitted to CRAN, since such functions have not yet matured enough. +\if{html}{\figure{lifecycle_stable.svg}{options: style=margin-bottom:5px} \cr} +The \link[=lifecycle]{lifecycle} of this function is \strong{stable}. In a stable function, major changes are unlikely. This means that the unlying code will generally evolve by adding new arguments; removing arguments or changing the meaning of existing arguments will be avoided. + +If the unlying code needs breaking changes, they will occur gradually. For example, a parameter will be deprecated and first continue to work, but will emit an message informing you of the change. Next, typically after at least one newly released version on CRAN, the message will be transformed to an error. } \section{Read more on our website!}{ diff --git a/man/plot.Rd b/man/plot.Rd index facd350e..2ca1d5df 100644 --- a/man/plot.Rd +++ b/man/plot.Rd @@ -1,13 +1,23 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/amr.R, R/mic.R, R/rsi.R +% Please edit documentation in R/amr.R, R/disk.R, R/mic.R, R/rsi.R \name{plot} \alias{plot} +\alias{plot.disk} \alias{plot.mic} \alias{barplot.mic} \alias{plot.rsi} \alias{barplot.rsi} \title{Plotting for classes \code{rsi} and \code{disk}} \usage{ +\method{plot}{disk}( + x, + main = paste("Disk zones values of", deparse(substitute(x))), + ylab = "Frequency", + xlab = "Disk diffusion (mm)", + axes = FALSE, + ... +) + \method{plot}{mic}( x, main = paste("MIC values of", deparse(substitute(x))), diff --git a/man/random.Rd b/man/random.Rd new file mode 100644 index 00000000..fc21f042 --- /dev/null +++ b/man/random.Rd @@ -0,0 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/random.R +\name{random} +\alias{random} +\alias{random_mic} +\alias{random_disk} +\alias{random_rsi} +\title{Random MIC values/disk zones/RSI generation} +\usage{ +random_mic(size, mo = NULL, ab = NULL, ...) + +random_disk(size, mo = NULL, ab = NULL, ...) + +random_rsi(size, prob_RSI = c(0.33, 0.33, 0.33), ...) +} +\arguments{ +\item{size}{desired size of the returned vector} + +\item{mo}{any character that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}} + +\item{ab}{any character that can be coerced to a valid antimicrobial agent code with \code{\link[=as.ab]{as.ab()}}} + +\item{...}{extension for future versions, not used at the moment} + +\item{prob_RSI}{a vector of length 3: the probabilities for R (1st value), S (2nd value) and I (3rd value)} +} +\value{ +class \verb{} for \code{\link[=random_mic]{random_mic()}} (see \code{\link[=as.mic]{as.mic()}}) and class \verb{} for \code{\link[=random_disk]{random_disk()}} (see \code{\link[=as.disk]{as.disk()}}) +} +\description{ +These functions can be used for generating random MIC values and disk diffusion diameters, for AMR analysis practice. +} +\details{ +The base R function \code{\link[=sample]{sample()}} is used for generating values. + +Generated values are based on the latest EUCAST guideline implemented in the \link{rsi_translation} data set. To create specific generated values per bug or drug, set the \code{mo} and/or \code{ab} parameter. +} +\section{Maturing lifecycle}{ + +\if{html}{\figure{lifecycle_maturing.svg}{options: style=margin-bottom:5px} \cr} +The \link[=lifecycle]{lifecycle} of this function is \strong{maturing}. The unlying code of a maturing function has been roughed out, but finer details might still change. Since this function needs wider usage and more extensive testing, you are very welcome \href{https://github.com/msberends/AMR/issues}{to suggest changes at our repository} or \link[=AMR]{write us an email (see section 'Contact Us')}. +} + +\section{Read more on our website!}{ + +On our website \url{https://msberends.github.io/AMR/} you can find \href{https://msberends.github.io/AMR/articles/AMR.html}{a comprehensive tutorial} about how to conduct AMR analysis, the \href{https://msberends.github.io/AMR/reference/}{complete documentation of all functions} and \href{https://msberends.github.io/AMR/articles/WHONET.html}{an example analysis using WHONET data}. As we would like to better understand the backgrounds and needs of our users, please \href{https://msberends.github.io/AMR/survey.html}{participate in our survey}! +} + +\examples{ +random_mic(100) +random_disk(100) +random_rsi(100) + +\donttest{ +# make the random generation more realistic by setting a bug and/or drug: +random_mic(100, "Klebsiella pneumoniae") # range 0.0625-64 +random_mic(100, "Klebsiella pneumoniae", "meropenem") # range 0.0625-16 +random_mic(100, "Streptococcus pneumoniae", "meropenem") # range 0.0625-4 + +random_disk(100, "Klebsiella pneumoniae") # range 11-50 +random_disk(100, "Klebsiella pneumoniae", "ampicillin") # range 6-14 +random_disk(100, "Streptococcus pneumoniae", "ampicillin") # range 16-22 +} +} diff --git a/tests/testthat/test-random.R b/tests/testthat/test-random.R new file mode 100644 index 00000000..dd178bbd --- /dev/null +++ b/tests/testthat/test-random.R @@ -0,0 +1,44 @@ +# ==================================================================== # +# TITLE # +# Antimicrobial Resistance (AMR) Analysis for R # +# # +# SOURCE # +# https://github.com/msberends/AMR # +# # +# LICENCE # +# (c) 2018-2020 Berends MS, Luz CF et al. # +# 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 analysis: https://msberends.github.io/AMR/ # +# ==================================================================== # + +context("random.R") + +test_that("random works", { + skip_on_cran() + + expect_s3_class(random_mic(100), "mic") + expect_s3_class(random_mic(100, mo = "Klebsiella pneumoniae"), "mic") + expect_s3_class(random_mic(100, mo = "Klebsiella pneumoniae", ab = "meropenem"), "mic") + expect_s3_class(random_mic(100, ab = "meropenem"), "mic") + # no normal factors of 2 + expect_s3_class(random_mic(100, "Haemophilus influenzae", "ceftaroline"), "mic") + + expect_s3_class(random_disk(100), "disk") + expect_s3_class(random_disk(100, mo = "Klebsiella pneumoniae"), "disk") + expect_s3_class(random_disk(100, mo = "Klebsiella pneumoniae", ab = "meropenem"), "disk") + expect_s3_class(random_disk(100, ab = "meropenem"), "disk") + + expect_s3_class(random_rsi(100), "rsi") +})