* Additional way to calculate co-resistance, i.e. when using multiple antibiotics as input for `portion_*` functions or `count_*` functions. This can be used to determine the empiric susceptibily of a combination therapy. A new parameter `only_all_tested` replaces the old `also_single_tested` and can be used to select one of the two methods to count isolates and calculate portions. The difference can be seen in this example table (which is also on the `portion` and `count` help pages), where the %SI is being determined:
* Fix for `as.mo()` where misspelled input would not be understood
* Fix for `also_single_tested` parameter in `count_*` functions
* Fix for using `mo_*` functions where the coercion uncertainties and failures would not be available through `mo_uncertainties()` and `mo_failures()` anymore
#' The function \code{count_df} takes any variable from \code{data} that has an \code{"rsi"} class (created with \code{\link{as.rsi}}) and counts the amounts of S, I and R. The resulting \emph{tidy data} (see Source) \code{data.frame} will have three rows (S/I/R) and a column for each variable with class \code{"rsi"}.
#'
#' The function \code{rsi_df} works exactly like \code{count_df}, but adds the percentage of S, I and R.
#' @inheritSection portion Combination therapy
#' @source Wickham H. \strong{Tidy Data.} The Journal of Statistical Software, vol. 59, 2014. \url{http://vita.had.co.nz/papers/tidy-data.html}
#' @seealso \code{\link{portion}_*} to calculate microbial resistance and susceptibility.
#' The algorithm can additionally use three different levels of uncertainty to guess valid results. The default is \code{allow_uncertain = TRUE}, which is equal to uncertainty level 2. Using \code{allow_uncertain = FALSE} will skip all of these additional rules:
#' \itemize{
#' \item{(uncertainty level 1): It tries to look for only matching genera}
#' \item{(uncertainty level 1): It tries to look for previously accepted (but now invalid) taxonomic names}
#' \item{(uncertainty level 2): It strips off values between brackets and the brackets itself, and re-evaluates the input with all previous rules}
#' \item{(uncertainty level 2): It strips off words from the end one by one and re-evaluates the input with all previous rules}
#' \item{(uncertainty level 3): It strips off words from the start one by one and re-evaluates the input with all previous rules}
#' \item{(uncertainty level 3): It tries any part of the name}
#' \item{(uncertainty level 1): It tries to look for only matching genera, previously accepted (but now invalid) taxonomic names and misspelled input}
#' \item{(uncertainty level 2): It removed parts between brackets, strips off words from the end one by one and re-evaluates the input with all previous rules}
#' \item{(uncertainty level 3): It strips off words from the start one by one and tries any part of the name}
#' }
#'
#' You can also use e.g. \code{as.mo(..., allow_uncertain = 1)} to only allow up to level 1 uncertainty.
shortnames[shortnames%like%"S. group [ABCDFGHK]"]<-paste0("G",gsub("S. group ([ABCDFGHK])","\\1",shortnames[shortnames%like%"S. group [ABCDFGHK]"]),"S")
#' @param ... one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link{as.rsi}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See Examples.
#' @param minimum the minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see Source.
#' @param as_percent a logical to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.
#' @param also_single_tested a logical to indicate whether for combination therapies also observations should be included where not all antibiotics were tested, but at least one of the tested antibiotics contains a target interpretation (e.g. S in case of \code{portion_S} and R in case of \code{portion_R}). \strong{This could lead to selection bias.}
#' @param only_all_tested (for combination therapies, i.e. using more than one variable for \code{...}) a logical to indicate that isolates must be tested for all antibiotics, see section \emph{Combination therapy} below
#' @param data a \code{data.frame} containing columns with class \code{rsi} (see \code{\link{as.rsi}})
#' @param translate_ab a column name of the \code{\link{antibiotics}} data set to translate the antibiotic abbreviations to, using \code{\link{ab_property}}
#' @inheritParams ab_property
#' @param combine_SI a logical to indicate whether all values of S and I must be merged into one, so the output only consists of S+I vs. R (susceptible vs. resistant). This used to be the parameter \code{combine_IR}, but this now follows the redefinition by EUCAST about the interpretion of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. Default is \code{TRUE}.
#' @param combine_IR a logical to indicate whether all values of I and R must be merged into one, so the output only consists of S vs. I+R (susceptible vs. non-susceptible). This is outdated, see parameter \code{combine_SI}.
#' @inheritSection as.rsi Interpretation of S, I and R
#' @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.
#' @details \strong{Remember that you should filter your table to let it contain only first isolates!} This is needed to exclude duplicates and to reduce selection bias. Use \code{\link{first_isolate}} to determine them in your data set.
#'
#' These functions are not meant to count isolates, but to calculate the portion of resistance/susceptibility. Use the \code{\link[AMR]{count}} functions to count isolates. \emph{Low counts can infuence the outcome - these \code{portion} functions may camouflage this, since they only return the portion albeit being dependent on the \code{minimum} parameter.}
#'
#' The function \code{portion_df} takes any variable from \code{data} that has an \code{"rsi"} class (created with \code{\link{as.rsi}}) and calculates the portions R, I and S. The resulting \emph{tidy data} (see Source) \code{data.frame} will have three rows (S/I/R) and a column for each group and each variable with class \code{"rsi"}.
#'
#' The function \code{rsi_df} works exactly like \code{portion_df}, but adds the number of isolates.
#' \if{html}{
# (created with https://www.latex4technics.com/)
#' \cr\cr
#' To calculate the probability (\emph{p}) of susceptibility of one antibiotic, we use this formula:
#' 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
#' When using more than one variable for \code{...} (= combination therapy)), use \code{only_all_tested} to only count isolates that are tested for all antibiotics/variables that you test them for. See this example for two antibiotics, Antibiotic A and Antibiotic B, about how \code{portion_SI} works to calculate the \%SI:
#' Using \code{only_all_tested} has no impact when only using one antibiotic as input.
#' @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/}.
#'
#' Wickham H. \strong{Tidy Data.} The Journal of Statistical Software, vol. 59, 2014. \url{http://vita.had.co.nz/papers/tidy-data.html}
@ -89,7 +114,7 @@
@@ -89,7 +114,7 @@
#'
#' septic_patients %>%
#' group_by(hospital_id) %>%
#' summarise(p = portion_S(CIP),
#' summarise(p = portion_SI(CIP),
#' n = n_rsi(CIP)) # n_rsi works like n_distinct in dplyr
#'
#' septic_patients %>%
@ -103,32 +128,38 @@
@@ -103,32 +128,38 @@
#'
#' # Calculate co-resistance between amoxicillin/clav acid and gentamicin,
#' # so we can see that combination therapy does a lot more than mono therapy:
#' The function \code{is.rsi.eligible} returns \code{TRUE} when a columns contains at most 5\% invalid antimicrobial interpretations (not S and/or I and/or R), and \code{FALSE} otherwise. The threshold of 5\% can be set with the \code{threshold} parameter.
#' @section Interpretation of S, I and R:
#' In 2019, EUCAST has decided to change the definitions of susceptibility testing categories S, I and R as shown below. Results of several consultations on the new definitions are available on the EUCAST website under "Consultations".
#' In 2019, EUCAST has decided to change the definitions of susceptibility testing categories S, I and R as shown below (\url{http://www.eucast.org/newsiandr/}). Results of several consultations on the new definitions are available on the EUCAST website under "Consultations".
#'
#' \itemize{
#' \item{\strong{S} - }{Susceptible, standard dosing regimen: A microorganism is categorised as "Susceptible, standard dosing regimen", when there is a high likelihood of therapeutic success using a standard dosing regimen of the agent.}
@ -46,9 +46,7 @@
@@ -46,9 +46,7 @@
#'
#' Exposure is a function of how the mode of administration, dose, dosing interval, infusion time, as well as distribution and excretion of the antimicrobial agent will influence the infecting organism at the site of infection.
#' \strong{This AMR package honours this new insight.}
#' This AMR package honours this new insight. Use \code{\link{portion_SI}} to determine antimicrobial susceptibility and \code{\link{count_SI}} to count susceptible isolates.
#' @return Ordered factor with new class \code{rsi}
stop("`also_single_tested` was replaced by `only_all_tested`. Please read Details in the help page (`?portion`) as this may have a considerable impact on your analysis.",call.=FALSE)
<p><strong>Note:</strong> values on this page will change with every website update since they are based on randomly created values and the page was written in <ahref="https://rmarkdown.rstudio.com/">R Markdown</a>. However, the methodology remains unchanged. This page was generated on 23 June 2019.</p>
<p><strong>Note:</strong> values on this page will change with every website update since they are based on randomly created values and the page was written in <ahref="https://rmarkdown.rstudio.com/">R Markdown</a>. However, the methodology remains unchanged. This page was generated on 01 July 2019.</p>
<p>So, we can draw at least two conclusions immediately. From a data scientists perspective, the data looks clean: only values <code>M</code> and <code>F</code>. From a researchers perspective: there are slightly more men. Nothing we didn’t already know.</p>
<p>The data is already quite clean, but we still need to transform some variables. The <code>bacteria</code> column now consists of text, and we want to add more variables based on microbial IDs later on. So, we will transform this column to valid IDs. The <code><ahref="https://dplyr.tidyverse.org/reference/mutate.html">mutate()</a></code> function of the <code>dplyr</code> package makes this really easy:</p>
<aclass="sourceLine"id="cb14-25"title="25"><spanclass="co"># Table 01: Intrinsic resistance in Enterobacteriaceae (1,298 new changes)</span></a>
<aclass="sourceLine"id="cb14-25"title="25"><spanclass="co"># Table 01: Intrinsic resistance in Enterobacteriaceae (1,332 new changes)</span></a>
<aclass="sourceLine"id="cb14-26"title="26"><spanclass="co"># Table 02: Intrinsic resistance in non-fermentative Gram-negative bacteria (no new changes)</span></a>
<aclass="sourceLine"id="cb14-27"title="27"><spanclass="co"># Table 03: Intrinsic resistance in other Gram-negative bacteria (no new changes)</span></a>
<aclass="sourceLine"id="cb14-28"title="28"><spanclass="co"># Table 04: Intrinsic resistance in Gram-positive bacteria (2,747 new changes)</span></a>
<aclass="sourceLine"id="cb14-28"title="28"><spanclass="co"># Table 04: Intrinsic resistance in Gram-positive bacteria (2,723 new changes)</span></a>
<aclass="sourceLine"id="cb14-29"title="29"><spanclass="co"># Table 08: Interpretive rules for B-lactam agents and Gram-positive cocci (no new changes)</span></a>
<aclass="sourceLine"id="cb14-30"title="30"><spanclass="co"># Table 09: Interpretive rules for B-lactam agents and Gram-negative rods (no new changes)</span></a>
<aclass="sourceLine"id="cb14-31"title="31"><spanclass="co"># Table 11: Interpretive rules for macrolides, lincosamides, and streptogramins (no new changes)</span></a>
@ -457,24 +457,24 @@
@@ -457,24 +457,24 @@
<aclass="sourceLine"id="cb14-33"title="33"><spanclass="co"># Table 13: Interpretive rules for quinolones (no new changes)</span></a>
<aclass="sourceLine"id="cb14-35"title="35"><spanclass="co"># Other rules</span></a>
<aclass="sourceLine"id="cb14-36"title="36"><spanclass="co"># Non-EUCAST: amoxicillin/clav acid = S where ampicillin = S (2,176 new changes)</span></a>
<aclass="sourceLine"id="cb14-37"title="37"><spanclass="co"># Non-EUCAST: ampicillin = R where amoxicillin/clav acid = R (121 new changes)</span></a>
<aclass="sourceLine"id="cb14-36"title="36"><spanclass="co"># Non-EUCAST: amoxicillin/clav acid = S where ampicillin = S (2,213 new changes)</span></a>
<aclass="sourceLine"id="cb14-37"title="37"><spanclass="co"># Non-EUCAST: ampicillin = R where amoxicillin/clav acid = R (127 new changes)</span></a>
<aclass="sourceLine"id="cb14-38"title="38"><spanclass="co"># Non-EUCAST: piperacillin = R where piperacillin/tazobactam = R (no new changes)</span></a>
<aclass="sourceLine"id="cb14-39"title="39"><spanclass="co"># Non-EUCAST: piperacillin/tazobactam = S where piperacillin = S (no new changes)</span></a>
<aclass="sourceLine"id="cb14-40"title="40"><spanclass="co"># Non-EUCAST: trimethoprim = R where trimethoprim/sulfa = R (no new changes)</span></a>
<aclass="sourceLine"id="cb14-41"title="41"><spanclass="co"># Non-EUCAST: trimethoprim/sulfa = S where trimethoprim = S (no new changes)</span></a>