new functions R, RI, SI, S

NAMESPACE

@@ -21,6 +21,7 @@ S3method(print,bactid)
 S3method(print,frequency_tbl)
 S3method(print,mic)
 S3method(print,rsi)
+S3method(pull,bactid)
 S3method(skewness,data.frame)
 S3method(skewness,default)
 S3method(skewness,matrix)
@@ -30,8 +31,12 @@ export("%like%")
 export(BRMO)
 export(EUCAST_exceptional_phenotypes)
 export(EUCAST_rules)
+export(IR)
 export(MDRO)
 export(MRGN)
+export(R)
+export(S)
+export(SI)
 export(abname)
 export(anti_join_microorganisms)
 export(as.bactid)
@@ -94,6 +99,7 @@ exportMethods(print.bactid)
 exportMethods(print.frequency_tbl)
 exportMethods(print.mic)
 exportMethods(print.rsi)
+exportMethods(pull.bactid)
 exportMethods(skewness)
 exportMethods(skewness.data.frame)
 exportMethods(skewness.default)

NEWS.md

@@ -1,6 +1,6 @@
 # 0.2.0.90xx (development version)
 #### New
-* **BREAKING**: `rsi_df` was removed in favour of new functions `resistance` and `susceptibility`. Now, all functions used to calculate resistance (`resistance` and `susceptibility`) use **hybrid evaluation**. This means calculations are not done in R directly but rather in C++ using the `Rcpp` package, making them 25 to 30 times faster. The function `rsi` still works, but is deprecated.
+* **BREAKING**: `rsi_df` was removed in favour of new functions `R`, `IR`, `SI` and `S` to selectively calculate resistance or susceptibility. These functions use **hybrid evaluation**, which means that calculations are not done in R directly but rather in C++ using the `Rcpp` package, making them 20 to 30 times faster. The function `rsi` still works, but is deprecated.
 * **BREAKING**: the methodology for determining first weighted isolates was changed. The antibiotics that are compared between isolates (call *key antibiotics*) to include more first isolates (afterwards called first *weighted* isolates) are now as follows:
   * Universal: amoxicillin, amoxicillin/clavlanic acid, cefuroxime, piperacillin/tazobactam, ciprofloxacin,  trimethoprim/sulfamethoxazole
   * Gram-positive: vancomycin, teicoplanin, tetracycline, erythromycin, oxacillin, rifampicin

R/bactid.R

@@ -101,6 +101,18 @@ as.bactid <- function(x) {
   x <- paste0('^', x, '$')
 
   for (i in 1:length(x)) {
+
+    if (x.fullbackup[i] %in% AMR::microorganisms$bactid) {
+      # is already a valid bactid
+      x[i] <- x.fullbackup[i]
+      next
+    }
+    if (x.backup[i] %in% AMR::microorganisms$bactid) {
+      # is already a valid bactid
+      x[i] <- x.backup[i]
+      next
+    }
+
     if (tolower(x[i]) == '^e.*coli$') {
       # avoid detection of Entamoeba coli in case of E. coli
       x[i] <- 'Escherichia coli'
@@ -255,3 +267,11 @@ as.data.frame.bactid <- function (x, ...) {
     as.data.frame.vector(x, ...)
   }
 }
+
+#' @exportMethod pull.bactid
+#' @export
+#' @importFrom dplyr pull
+#' @noRd
+pull.bactid <- function(.data, ...) {
+  pull(as.data.frame(.data), ...)
+}

R/first_isolate.R

@@ -53,7 +53,7 @@
 #' @export
 #' @importFrom dplyr arrange_at lag between row_number filter mutate arrange
 #' @return A vector to add to table, see Examples.
-#' @source Methodology of this function is based on: "M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition", 2014, Clinical and Laboratory Standards Institute. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
+#' @source Methodology of this function is based on: \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition}, 2014, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
 #' @examples
 #' # septic_patients is a dataset available in the AMR package
 #' ?septic_patients

R/resistance.R

@@ -18,19 +18,22 @@
 
 #' Calculate resistance of isolates
 #'
-#' These functions can be used to calculate the (co-)resistance of microbial isolates (i.e. percentage S, SI, I, IR or R). All functions can be used in \code{dplyr}s \code{\link[dplyr]{summarise}} and support grouped variables, see \emph{Examples}.
+#' These functions can be used to calculate the (co-)resistance of microbial isolates (i.e. percentage S, SI, IR or R). All functions can be used in \code{dplyr}s \code{\link[dplyr]{summarise}} and support grouped variables, see \emph{Examples}. \cr\cr
-#' @param ab,ab1,ab2 vector of antibiotic interpretations, they will be transformed internally with \code{\link{as.rsi}}
+#' \code{R} and \code{IR} can be used to calculate resistance, \code{S} and \code{SI} can be used to calculate susceptibility.\cr
+#' \code{n_rsi} counts all cases where antimicrobial interpretations are available.
+#' @param ab1 vector of antibiotic interpretations, they will be transformed internally with \code{\link{as.rsi}}
+#' @param ab2 like \code{ab}, a vector of antibiotic interpretations. Use this to calculate (the lack of) co-resistance: the probability where one of two drugs have a susceptible result. See Examples.
 #' @param include_I logical to indicate whether antimicrobial interpretations of "I" should be included
-#' @param minimum minimal amount of available isolates. Any number lower than \code{minimum} will return \code{NA}.
+#' @param minimum minimal amount of available isolates. Any number lower than \code{minimum} will return \code{NA}. The default number of \code{30} isolates is advised by the CLSI as best practice, see Source.
 #' @param as_percent logical to indicate whether the output must be returned as percent (text), will else be a double
 #' @param interpretation antimicrobial interpretation
 #' @param info \emph{DEPRECATED} calculate the amount of available isolates and print it, like \code{n = 423}
 #' @param warning \emph{DEPRECATED} show a warning when the available amount of isolates is below \code{minimum}
 #' @details \strong{Remember that you should filter your table to let it contain only first isolates!} Use \code{\link{first_isolate}} to determine them in your data set.
 #'
-#' The functions \code{resistance}, \code{susceptibility} and \code{n_rsi} calculate using hybrid evaluation (i.e. using C++), which makes these functions 25-30 times faster than the old \code{rsi} function. This function is still available for backwards compatibility but is deprecated.
+#' The functions \code{resistance} and \code{susceptibility} are wrappers around \code{IR} and \code{S}, respectively. All functions except \code{rsi} use hybrid evaluation (i.e. using C++), which makes these functions 20-30 times faster than the old \code{rsi} function. This latter function is still available for backwards compatibility but is deprecated.
 #' \if{html}{
-#'   \cr
+#'   \cr\cr
 #'   To calculate the probability (\emph{p}) of susceptibility of one antibiotic, we use this formula:
 #'   \out{<div style="text-align: center">}\figure{mono_therapy.png}\out{</div>}
 #'   To calculate the probability (\emph{p}) of susceptibility of more antibiotics (i.e. combination therapy), we need to check whether one of them has a susceptible result (as numerator) and count all cases where all antibiotics were tested (as denominator). \cr
@@ -41,88 +44,143 @@
 #'   Theoretically for three antibiotics:
 #'   \out{<div style="text-align: center">}\figure{combi_therapy_3.png}\out{</div>}
 #' }
-#' @keywords resistance susceptibility rsi_df antibiotics isolate isolates
+#' @source \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition}, 2014, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
+#' @keywords resistance susceptibility rsi_df rsi antibiotics isolate isolates
 #' @return Double or, when \code{as_percent = TRUE}, a character.
 #' @rdname resistance
 #' @export
 #' @examples
-#' library(dplyr)
-#'
-#' septic_patients %>%
-#'   group_by(hospital_id) %>%
-#'   summarise(p = susceptibility(cipr),
-#'             n = n_rsi(cipr)) # n_rsi works like n_distinct in dplyr
-#'
-#' septic_patients %>%
-#'   group_by(hospital_id) %>%
-#'   summarise(cipro_p = susceptibility(cipr, as_percent = TRUE),
-#'             cipro_n = n_rsi(cipr),
-#'             genta_p = susceptibility(gent, as_percent = TRUE),
-#'             genta_n = n_rsi(gent),
-#'             combination_p = susceptibility(cipr, gent, as_percent = TRUE),
-#'             combination_n = n_rsi(cipr, gent))
-#'
-#'
 #' # Calculate resistance
-#' resistance(septic_patients$amox)
+#' R(septic_patients$amox)
-#' rsi(septic_patients$amox, interpretation = "IR") # deprecated
+#' IR(septic_patients$amox)
 #'
 #' # Or susceptibility
-#' susceptibility(septic_patients$amox)
+#' S(septic_patients$amox)
-#' rsi(septic_patients$amox, interpretation = "S") # deprecated
+#' SI(septic_patients$amox)
 #'
+#' # Since n_rsi counts available isolates (and is used as denominator),
+#' # you can calculate back to e.g. count resistant isolates:
+#' IR(septic_patients$amox) * n_rsi(septic_patients$amox)
+#'
+#' library(dplyr)
+#' septic_patients %>%
+#'   group_by(hospital_id) %>%
+#'   summarise(p = S(cipr),
+#'             n = n_rsi(cipr)) # n_rsi works like n_distinct in dplyr
 #'
 #' # Calculate co-resistance between amoxicillin/clav acid and gentamicin,
 #' # so we can see that combination therapy does a lot more than mono therapy:
-#' susceptibility(septic_patients$amcl) # p = 67.8%
+#' S(septic_patients$amcl)     # p = 67.3%
-#' n_rsi(septic_patients$amcl)          # n = 1641
+#' n_rsi(septic_patients$amcl) # n = 1570
 #'
-#' susceptibility(septic_patients$gent) # p = 69.1%
+#' S(septic_patients$gent)     # p = 74.0%
-#' n_rsi(septic_patients$gent)          # n = 1863
+#' n_rsi(septic_patients$gent) # n = 1842
 #'
 #' with(septic_patients,
-#'      susceptibility(amcl, gent))     # p = 90.6%
+#'      S(amcl, gent))         # p = 92.1%
 #' with(septic_patients,
-#'      n_rsi(amcl, gent))              # n = 1580
+#'      n_rsi(amcl, gent))     # n = 1504
+#'
+#' septic_patients %>%
+#'   group_by(hospital_id) %>%
+#'   summarise(cipro_p = S(cipr, as_percent = TRUE),
+#'             cipro_n = n_rsi(cipr),
+#'             genta_p = S(gent, as_percent = TRUE),
+#'             genta_n = n_rsi(gent),
+#'             combination_p = S(cipr, gent, as_percent = TRUE),
+#'             combination_n = n_rsi(cipr, gent))
 #'
 #' \dontrun{
+#'
 #' # calculate current empiric combination therapy of Helicobacter gastritis:
 #' my_table %>%
 #'   filter(first_isolate == TRUE,
 #'          genus == "Helicobacter") %>%
-#'   summarise(p = susceptibility(amox, metr), # amoxicillin with metronidazole
+#'   summarise(p = S(amox, metr),     # amoxicillin with metronidazole
 #'             n = n_rsi(amox, metr))
-#'
-#'
-#' # How fast is this hybrid evaluation in C++ compared to R?
-#' # In other words: how is the speed improvement of the new `resistance` compared to old `rsi`?
-#'
-#' library(microbenchmark)
-#' df <- septic_patients %>% group_by(hospital_id, bactid) # 317 groups with sizes 1 to 167
-#'
-#' microbenchmark(old_IR = df %>% summarise(p = rsi(amox, minimum = 0, interpretation = "IR")),
-#'                new_IR = df %>% summarise(p = resistance(amox, minimum = 0)),
-#'                old_S = df %>% summarise(p = rsi(amox, minimum = 0, interpretation = "S")),
-#'                new_S = df %>% summarise(p = susceptibility(amox, minimum = 0)),
-#'                times = 5,
-#'                unit = "s")
-#'
-#' # Unit: seconds
-#' #    expr          min         lq       mean     median         uq        max neval
-#' #  old_IR   1.95600230 1.96096857 1.97981537 1.96823318 2.00645711 2.00741568     5
-#' #  new_IR   0.06872808 0.06984932 0.07162866 0.06987306 0.07050094 0.07919192     5
-#' #   old_S   1.68893579 1.69024888 1.72461867 1.69785934 1.70428796 1.84176137     5
-#' #   new_S   0.06737037 0.06838167 0.07431906 0.07745364 0.07827224 0.08011738     5
-#'
-#' # The old function took roughly 2 seconds, the new ones take 0.07 seconds.
 #' }
-resistance <- function(ab,
+#' @rdname resistance
+#' @name resistance
+#' @export
+#' @rdname resistance
+#' @export
+S <- function(ab1,
+              ab2 = NULL,
+              minimum = 30,
+              as_percent = FALSE) {
+  susceptibility(ab1 = ab1,
+                 ab2 = ab2,
+                 include_I = FALSE,
+                 minimum = minimum,
+                 as_percent = as_percent)
+}
+
+#' @rdname resistance
+#' @export
+SI <- function(ab1,
+               ab2 = NULL,
+               minimum = 30,
+               as_percent = FALSE) {
+  susceptibility(ab1 = ab1,
+                 ab2 = ab2,
+                 include_I = TRUE,
+                 minimum = minimum,
+                 as_percent = as_percent)
+}
+
+#' @rdname resistance
+#' @export
+IR <- function(ab1,
+               minimum = 30,
+               as_percent = FALSE) {
+  resistance(ab1 = ab1,
+             include_I = TRUE,
+             minimum = minimum,
+             as_percent = as_percent)
+}
+
+#' @rdname resistance
+#' @export
+R <- function(ab1,
+              minimum = 30,
+              as_percent = FALSE) {
+  resistance(ab1 = ab1,
+             include_I = FALSE,
+             minimum = minimum,
+             as_percent = as_percent)
+}
+
+#' @rdname resistance
+#' @export
+n_rsi <- function(ab1, ab2 = NULL) {
+  if (NCOL(ab1) > 1) {
+    stop('`ab` must be a vector of antimicrobial interpretations', call. = FALSE)
+  }
+  if (!is.rsi(ab1)) {
+    ab1 <- as.rsi(ab1)
+  }
+  if (!is.null(ab2)) {
+    if (NCOL(ab2) > 1) {
+      stop('`ab2` must be a vector of antimicrobial interpretations', call. = FALSE)
+    }
+    if (!is.rsi(ab2)) {
+      ab2 <- as.rsi(ab2)
+    }
+    sum(!is.na(ab1) & !is.na(ab2))
+  } else {
+    sum(!is.na(ab1))
+  }
+}
+
+#' @rdname resistance
+#' @export
+resistance <- function(ab1,
                        include_I = TRUE,
                        minimum = 30,
                        as_percent = FALSE) {
 
-  if (NCOL(ab) > 1) {
+  if (NCOL(ab1) > 1) {
-    stop('`ab` must be a vector of antimicrobial interpretations', call. = FALSE)
+    stop('`ab1` must be a vector of antimicrobial interpretations', call. = FALSE)
   }
   if (!is.logical(include_I)) {
     stop('`include_I` must be logical', call. = FALSE)
@@ -134,14 +192,17 @@ resistance <- function(ab,
     stop('`as_percent` must be logical', call. = FALSE)
   }
 
-  if (!is.rsi(ab)) {
+  # ab_name <- deparse(substitute(ab))
-    x <- as.rsi(ab)
+
+  if (!is.rsi(ab1)) {
+    x <- as.rsi(ab1)
     warning("Increase speed by transforming to class `rsi` on beforehand: df %>% mutate_at(vars(col10:col20), as.rsi)")
   } else {
-    x <- ab
+    x <- ab1
   }
   total <- length(x) - sum(is.na(x)) # faster than C++
   if (total < minimum) {
+    # warning("Too few isolates available for ", ab_name, ": ", total, " < ", minimum, "; returning NA.", call. = FALSE)
     return(NA)
   }
   found <- .Call(`_AMR_rsi_calc_R`, x, include_I)
@@ -180,6 +241,7 @@ susceptibility <- function(ab1,
     print_warning <- TRUE
   }
   if (!is.null(ab2)) {
+    # ab_name <- paste(deparse(substitute(ab1)), "and", deparse(substitute(ab2)))
     if (NCOL(ab2) > 1) {
       stop('`ab2` must be a vector of antimicrobial interpretations', call. = FALSE)
     }
@@ -193,9 +255,11 @@ susceptibility <- function(ab1,
                FUN = min)
   } else {
     x <- ab1
+    # ab_name <- deparse(substitute(ab1))
   }
   total <- length(x) - sum(is.na(x))
   if (total < minimum) {
+    # warning("Too few isolates available for ", ab_name, ": ", total, " < ", minimum, "; returning NA.", call. = FALSE)
     return(NA)
   }
   found <- .Call(`_AMR_rsi_calc_S`, x, include_I)
@@ -211,28 +275,6 @@ susceptibility <- function(ab1,
   }
 }
 
-#' @rdname resistance
-#' @export
-n_rsi <- function(ab1, ab2 = NULL) {
-  if (NCOL(ab1) > 1) {
-    stop('`ab1` must be a vector of antimicrobial interpretations', call. = FALSE)
-  }
-  if (!is.rsi(ab1)) {
-    ab1 <- as.rsi(ab1)
-  }
-  if (!is.null(ab2)) {
-    if (NCOL(ab2) > 1) {
-      stop('`ab2` must be a vector of antimicrobial interpretations', call. = FALSE)
-    }
-    if (!is.rsi(ab2)) {
-      ab2 <- as.rsi(ab2)
-    }
-    sum(!is.na(ab1) & !is.na(ab2))
-  } else {
-    sum(!is.na(ab1))
-  }
-}
-
 #' @rdname resistance
 #' @export
 rsi <- function(ab1,
@@ -242,6 +284,9 @@ rsi <- function(ab1,
                 as_percent = FALSE,
                 info = FALSE,
                 warning = TRUE) {
+
+  .Deprecated()
+
   ab1.name <- deparse(substitute(ab1))
   if (ab1.name %like% '.[$].') {
     ab1.name <- unlist(strsplit(ab1.name, "$", fixed = TRUE))

README.md

@@ -25,7 +25,7 @@ This R package was created for academic research by PhD students of the Faculty
 This R package contains functions to make **microbiological, epidemiological data analysis easier**. It allows the use of some new classes to work with MIC values and antimicrobial interpretations (i.e. values S, I and R).
 
 With `AMR` you can:
-* Calculate the resistance (and even co-resistance) of microbial isolates with the `resistance` and `susceptibility` functions, that can also be used with the `dplyr` package (e.g. in conjunction with `summarise`)
+* Calculate the resistance (and even co-resistance) of microbial isolates with the `R`, `IR`, `SI` and `S` functions, that can also be used with the `dplyr` package (e.g. in conjunction with `summarise`)
 * Predict antimicrobial resistance for the nextcoming years with the `resistance_predict` function
 * Apply [EUCAST rules to isolates](http://www.eucast.org/expert_rules_and_intrinsic_resistance/) with the `EUCAST_rules` function
 * Identify first isolates of every patient [using guidelines from the CLSI](https://clsi.org/standards/products/microbiology/documents/m39/) (Clinical and Laboratory Standards Institute) with the `first_isolate` function
@@ -50,35 +50,21 @@ The functions to calculate microbial resistance use expressions that are not eva
 #### Read all changes and new functions in [NEWS.md](NEWS.md).
 
 ## How to get it?
-This package is available on CRAN and also here on GitHub.
+This package [is published on CRAN](http://cran.r-project.org/package=AMR), the official R network.
 
-### From CRAN (recommended)
+### Install from CRAN (recommended)
-Latest released version on CRAN:
+[![CRAN_Badge](https://img.shields.io/cran/v/AMR.svg?label=CRAN)](http://cran.r-project.org/package=AMR) [![CRAN_Downloads](https://cranlogs.r-pkg.org/badges/grand-total/AMR)](http://cran.r-project.org/package=AMR)
 
-[![CRAN_Badge](https://img.shields.io/cran/v/AMR.svg?label=CRAN&colorB=3679BC)](http://cran.r-project.org/package=AMR)
+(Note: downloads measured only by [cran.rstudio.com](https://cran.rstudio.com/package=AMR), i.e. this excludes the official [cran.r-project.org](https://cran.r-project.org/package=AMR))
 
-Downloads via RStudio CRAN server (downloads by all other CRAN mirrors **not** measured, including the official https://cran.r-project.org):
+- <img src="http://www.rstudio.com/favicon.ico" alt="RStudio favicon" height="20px"> Install using [RStudio](http://www.rstudio.com) (recommended):
-
-[![CRAN_Downloads](https://cranlogs.r-pkg.org/badges/grand-total/AMR)](http://cran.r-project.org/package=AMR)
-[![CRAN_Downloads](https://cranlogs.r-pkg.org/badges/AMR)](https://cranlogs.r-pkg.org/downloads/daily/last-month/AMR)
-  
-- <img src="http://www.rstudio.com/favicon.ico" alt="RStudio favicon" height="20px"> In [RStudio](http://www.rstudio.com) (recommended):
   - Click on `Tools` and then `Install Packages...`
   - Type in `AMR` and press <kbd>Install</kbd>
 
-- <img src="https://cran.r-project.org/favicon.ico" alt="R favicon" height="20px"> In R directly:
+- <img src="https://cran.r-project.org/favicon.ico" alt="R favicon" height="20px"> Install in R directly:
   - `install.packages("AMR")`
 
-- <img src="https://exploratory.io/favicon.ico" alt="Exploratory favicon" height="20px"> In [Exploratory.io](https://exploratory.io):
+### Install from GitHub (latest development version)
-  - (Exploratory.io costs $40/month but the somewhat limited Community Plan is free for students and teachers, [click here to enroll](https://exploratory.io/plan?plan=Community))
-  - Start the software and log in
-  - Click on your username at the right hand side top
-  - Click on `R Packages`
-  - Click on the `Install` tab
-  - Type in `AMR` and press <kbd>Install</kbd>
-  - Once it’s installed it will show up in the `User Packages` section under the `Packages` tab.
-
-### From GitHub (latest development version)
 [![Travis_Build](https://travis-ci.org/msberends/AMR.svg?branch=master)](https://travis-ci.org/msberends/AMR)
 [![Since_Release](https://img.shields.io/github/commits-since/msberends/AMR/latest.svg?colorB=3679BC)](https://github.com/msberends/AMR/commits/master)
 [![Last_Commit](https://img.shields.io/github/last-commit/msberends/AMR.svg)](https://github.com/msberends/AMR/commits/master)

man/first_isolate.Rd

@@ -4,7 +4,7 @@
 \alias{first_isolate}
 \title{Determine first (weighted) isolates}
 \source{
-Methodology of this function is based on: "M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition", 2014, Clinical and Laboratory Standards Institute. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
+Methodology of this function is based on: \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition}, 2014, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
 }
 \usage{
 first_isolate(tbl, col_date, col_patient_id, col_bactid = NA,

man/resistance.Rd

@@ -2,30 +2,47 @@
 % Please edit documentation in R/resistance.R
 \name{resistance}
 \alias{resistance}
-\alias{susceptibility}
+\alias{S}
+\alias{SI}
+\alias{IR}
+\alias{R}
 \alias{n_rsi}
+\alias{susceptibility}
 \alias{rsi}
 \title{Calculate resistance of isolates}
+\source{
+\strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition}, 2014, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
+}
 \usage{
-resistance(ab, include_I = TRUE, minimum = 30, as_percent = FALSE)
+S(ab1, ab2 = NULL, minimum = 30, as_percent = FALSE)
+
+SI(ab1, ab2 = NULL, minimum = 30, as_percent = FALSE)
+
+IR(ab1, minimum = 30, as_percent = FALSE)
+
+R(ab1, minimum = 30, as_percent = FALSE)
+
+n_rsi(ab1, ab2 = NULL)
+
+resistance(ab1, include_I = TRUE, minimum = 30, as_percent = FALSE)
 
 susceptibility(ab1, ab2 = NULL, include_I = FALSE, minimum = 30,
   as_percent = FALSE)
 
-n_rsi(ab1, ab2 = NULL)
-
 rsi(ab1, ab2 = NA, interpretation = "IR", minimum = 30,
   as_percent = FALSE, info = FALSE, warning = TRUE)
 }
 \arguments{
-\item{ab, ab1, ab2}{vector of antibiotic interpretations, they will be transformed internally with \code{\link{as.rsi}}}
+\item{ab1}{vector of antibiotic interpretations, they will be transformed internally with \code{\link{as.rsi}}}
 
-\item{include_I}{logical to indicate whether antimicrobial interpretations of "I" should be included}
+\item{ab2}{like \code{ab}, a vector of antibiotic interpretations. Use this to calculate (the lack of) co-resistance: the probability where one of two drugs have a susceptible result. See Examples.}
 
-\item{minimum}{minimal amount of available isolates. Any number lower than \code{minimum} will return \code{NA}.}
+\item{minimum}{minimal amount of available isolates. Any number lower than \code{minimum} will return \code{NA}. The default number of \code{30} isolates is advised by the CLSI as best practice, see Source.}
 
 \item{as_percent}{logical to indicate whether the output must be returned as percent (text), will else be a double}
 
+\item{include_I}{logical to indicate whether antimicrobial interpretations of "I" should be included}
+
 \item{interpretation}{antimicrobial interpretation}
 
 \item{info}{\emph{DEPRECATED} calculate the amount of available isolates and print it, like \code{n = 423}}
@@ -36,14 +53,16 @@ rsi(ab1, ab2 = NA, interpretation = "IR", minimum = 30,
 Double or, when \code{as_percent = TRUE}, a character.
 }
 \description{
-These functions can be used to calculate the (co-)resistance of microbial isolates (i.e. percentage S, SI, I, IR or R). All functions can be used in \code{dplyr}s \code{\link[dplyr]{summarise}} and support grouped variables, see \emph{Examples}.
+These functions can be used to calculate the (co-)resistance of microbial isolates (i.e. percentage S, SI, IR or R). All functions can be used in \code{dplyr}s \code{\link[dplyr]{summarise}} and support grouped variables, see \emph{Examples}. \cr\cr
+\code{R} and \code{IR} can be used to calculate resistance, \code{S} and \code{SI} can be used to calculate susceptibility.\cr
+\code{n_rsi} counts all cases where antimicrobial interpretations are available.
 }
 \details{
 \strong{Remember that you should filter your table to let it contain only first isolates!} Use \code{\link{first_isolate}} to determine them in your data set.
 
-The functions \code{resistance}, \code{susceptibility} and \code{n_rsi} calculate using hybrid evaluation (i.e. using C++), which makes these functions 25-30 times faster than the old \code{rsi} function. This function is still available for backwards compatibility but is deprecated.
+The functions \code{resistance} and \code{susceptibility} are wrappers around \code{IR} and \code{S}, respectively. All functions except \code{rsi} use hybrid evaluation (i.e. using C++), which makes these functions 20-30 times faster than the old \code{rsi} function. This latter function is still available for backwards compatibility but is deprecated.
 \if{html}{
-  \cr
+  \cr\cr
   To calculate the probability (\emph{p}) of susceptibility of one antibiotic, we use this formula:
   \out{<div style="text-align: center">}\figure{mono_therapy.png}\out{</div>}
   To calculate the probability (\emph{p}) of susceptibility of more antibiotics (i.e. combination therapy), we need to check whether one of them has a susceptible result (as numerator) and count all cases where all antibiotics were tested (as denominator). \cr
@@ -56,80 +75,60 @@ The functions \code{resistance}, \code{susceptibility} and \code{n_rsi} calculat
 }
 }
 \examples{
-library(dplyr)
-
-septic_patients \%>\%
-  group_by(hospital_id) \%>\%
-  summarise(p = susceptibility(cipr),
-            n = n_rsi(cipr)) # n_rsi works like n_distinct in dplyr
-
-septic_patients \%>\%
-  group_by(hospital_id) \%>\%
-  summarise(cipro_p = susceptibility(cipr, as_percent = TRUE),
-            cipro_n = n_rsi(cipr),
-            genta_p = susceptibility(gent, as_percent = TRUE),
-            genta_n = n_rsi(gent),
-            combination_p = susceptibility(cipr, gent, as_percent = TRUE),
-            combination_n = n_rsi(cipr, gent))
-
-
 # Calculate resistance
-resistance(septic_patients$amox)
+R(septic_patients$amox)
-rsi(septic_patients$amox, interpretation = "IR") # deprecated
+IR(septic_patients$amox)
 
 # Or susceptibility
-susceptibility(septic_patients$amox)
+S(septic_patients$amox)
-rsi(septic_patients$amox, interpretation = "S") # deprecated
+SI(septic_patients$amox)
 
+# Since n_rsi counts available isolates (and is used as denominator),
+# you can calculate back to e.g. count resistant isolates:
+IR(septic_patients$amox) * n_rsi(septic_patients$amox)
+
+library(dplyr)
+septic_patients \%>\%
+  group_by(hospital_id) \%>\%
+  summarise(p = S(cipr),
+            n = n_rsi(cipr)) # n_rsi works like n_distinct in dplyr
 
 # Calculate co-resistance between amoxicillin/clav acid and gentamicin,
 # so we can see that combination therapy does a lot more than mono therapy:
-susceptibility(septic_patients$amcl) # p = 67.8\%
+S(septic_patients$amcl)     # p = 67.3\%
-n_rsi(septic_patients$amcl)          # n = 1641
+n_rsi(septic_patients$amcl) # n = 1570
 
-susceptibility(septic_patients$gent) # p = 69.1\%
+S(septic_patients$gent)     # p = 74.0\%
-n_rsi(septic_patients$gent)          # n = 1863
+n_rsi(septic_patients$gent) # n = 1842
 
 with(septic_patients,
-     susceptibility(amcl, gent))     # p = 90.6\%
+     S(amcl, gent))         # p = 92.1\%
 with(septic_patients,
-     n_rsi(amcl, gent))              # n = 1580
+     n_rsi(amcl, gent))     # n = 1504
+
+septic_patients \%>\%
+  group_by(hospital_id) \%>\%
+  summarise(cipro_p = S(cipr, as_percent = TRUE),
+            cipro_n = n_rsi(cipr),
+            genta_p = S(gent, as_percent = TRUE),
+            genta_n = n_rsi(gent),
+            combination_p = S(cipr, gent, as_percent = TRUE),
+            combination_n = n_rsi(cipr, gent))
 
 \dontrun{
+
 # calculate current empiric combination therapy of Helicobacter gastritis:
 my_table \%>\%
   filter(first_isolate == TRUE,
          genus == "Helicobacter") \%>\%
-  summarise(p = susceptibility(amox, metr), # amoxicillin with metronidazole
+  summarise(p = S(amox, metr),     # amoxicillin with metronidazole
             n = n_rsi(amox, metr))
-
-
-# How fast is this hybrid evaluation in C++ compared to R?
-# In other words: how is the speed improvement of the new `resistance` compared to old `rsi`?
-
-library(microbenchmark)
-df <- septic_patients \%>\% group_by(hospital_id, bactid) # 317 groups with sizes 1 to 167
-
-microbenchmark(old_IR = df \%>\% summarise(p = rsi(amox, minimum = 0, interpretation = "IR")),
-               new_IR = df \%>\% summarise(p = resistance(amox, minimum = 0)),
-               old_S = df \%>\% summarise(p = rsi(amox, minimum = 0, interpretation = "S")),
-               new_S = df \%>\% summarise(p = susceptibility(amox, minimum = 0)),
-               times = 5,
-               unit = "s")
-
-# Unit: seconds
-#    expr          min         lq       mean     median         uq        max neval
-#  old_IR   1.95600230 1.96096857 1.97981537 1.96823318 2.00645711 2.00741568     5
-#  new_IR   0.06872808 0.06984932 0.07162866 0.06987306 0.07050094 0.07919192     5
-#   old_S   1.68893579 1.69024888 1.72461867 1.69785934 1.70428796 1.84176137     5
-#   new_S   0.06737037 0.06838167 0.07431906 0.07745364 0.07827224 0.08011738     5
-
-# The old function took roughly 2 seconds, the new ones take 0.07 seconds.
 }
 }
 \keyword{antibiotics}
 \keyword{isolate}
 \keyword{isolates}
 \keyword{resistance}
+\keyword{rsi}
 \keyword{rsi_df}
 \keyword{susceptibility}

tests/testthat/test-bactid.R

@@ -60,5 +60,12 @@ test_that("as.bactid works", {
   expect_identical(as.bactid("ESCCOL"),
                    guess_bactid("ESCCOL"))
 
+  # test pull
+  expect_equal(nrow(septic_patients %>% mutate(bactid = as.bactid(bactid))),
+               2000)
+
+  # test data.frame
+  expect_equal(nrow(data.frame(test = as.bactid("ESCCOL"))),
+               1)
 
 })

tests/testthat/test-resistance.R

@@ -1,6 +1,16 @@
 context("resistance.R")
 
 test_that("resistance works", {
+  # check shortcuts
+  expect_equal(resistance(septic_patients$amox, include_I = TRUE),
+               IR(septic_patients$amox))
+  expect_equal(resistance(septic_patients$amox, include_I = FALSE),
+               R(septic_patients$amox))
+  expect_equal(susceptibility(septic_patients$amox, include_I = TRUE),
+               SI(septic_patients$amox))
+  expect_equal(susceptibility(septic_patients$amox, include_I = FALSE),
+               S(septic_patients$amox))
+
   # amox resistance in `septic_patients` should be around 66.33%
   expect_equal(resistance(septic_patients$amox, include_I = TRUE), 0.6633, tolerance = 0.0001)
   expect_equal(susceptibility(septic_patients$amox, include_I = FALSE), 1 - 0.6633, tolerance = 0.0001)
@@ -37,18 +47,18 @@ test_that("resistance works", {
 
 test_that("old rsi works", {
   # amox resistance in `septic_patients` should be around 66.33%
-  expect_equal(rsi(septic_patients$amox), 0.6633, tolerance = 0.0001)
+  expect_equal(suppressWarnings(rsi(septic_patients$amox)), 0.6633, tolerance = 0.0001)
-  expect_equal(rsi(septic_patients$amox, interpretation = "S"), 1 - 0.6633, tolerance = 0.0001)
+  expect_equal(suppressWarnings(rsi(septic_patients$amox, interpretation = "S")), 1 - 0.6633, tolerance = 0.0001)
   expect_equal(rsi_df(septic_patients,
                       ab = "amox",
                       info = TRUE),
                0.6633,
                tolerance = 0.0001)
   # pita+genta susceptibility around 98.09%
-  expect_equal(rsi(septic_patients$pita,
+  expect_equal(suppressWarnings(rsi(septic_patients$pita,
-                   septic_patients$gent,
+                                    septic_patients$gent,
-                   interpretation = "S",
+                                    interpretation = "S",
-                   info = TRUE),
+                                    info = TRUE)),
                0.9535,
                tolerance = 0.0001)
   expect_equal(rsi_df(septic_patients,
@@ -66,14 +76,14 @@ test_that("old rsi works", {
   # count of cases
   expect_equal(septic_patients %>%
                  group_by(hospital_id) %>%
-                 summarise(cipro_S = rsi(cipr, interpretation = "S",
+                 summarise(cipro_S = suppressWarnings(rsi(cipr, interpretation = "S",
-                                         as_percent = TRUE, warning = FALSE),
+                                                          as_percent = TRUE, warning = FALSE)),
                            cipro_n = n_rsi(cipr),
-                           genta_S = rsi(gent, interpretation = "S",
+                           genta_S = suppressWarnings(rsi(gent, interpretation = "S",
-                                         as_percent = TRUE, warning = FALSE),
+                                                          as_percent = TRUE, warning = FALSE)),
                            genta_n = n_rsi(gent),
-                           combination_S = rsi(cipr, gent, interpretation = "S",
+                           combination_S = suppressWarnings(rsi(cipr, gent, interpretation = "S",
-                                               as_percent = TRUE, warning = FALSE),
+                                                                as_percent = TRUE, warning = FALSE)),
                            combination_n = n_rsi(cipr, gent)) %>%
                  pull(combination_n),
                c(202, 482, 201, 499))