* Added the selector `ab_selector()`, which accepts a filter to be used internally on the `antibiotics` data set, yielding great flexibility on drug properties, such as selecting antibiotic columns with an oral DDD of at least 1 gram:
```r
example_isolates[, ab_selector(oral_ddd > 1 & oral_units == "g")] # base R
* Fix for using selectors multiple times in one call (e.g., using them in `dplyr::filter()` and immediately after in `dplyr::select()`)
* Added argument `only_treatable`, which defaults to `TRUE` and will exclude drugs that are only for laboratory tests and not for treating patients (such as imipenem/EDTA and gentamicin-high)
* Fixed the Gram stain (`mo_gramstain()`) determination of the class Negativicutes within the phylum of Firmicutes - they were considered Gram-positives because of their phylum but are actually Gram-negative. This impacts 137 taxonomic species, genera and families, such as *Negativicoccus* and *Veillonella*.
#' These functions allow for filtering rows and selecting columns based on antibiotic test results that are of a specific antibiotic class or group, without the need to define the columns or antibiotic abbreviations. In short, if you have a column name that resembles an antimicrobial agent, it will be picked up by any of these functions that matches its pharmaceutical class: "cefazolin", "CZO" and "J01DB04" will all be picked up by [cephalosporins()].
#' @inheritSection lifecycle Stable Lifecycle
#' @param ab_class an antimicrobial class, such as `"carbapenems"`. The columns `group`, `atc_group1` and `atc_group2` of the [antibiotics] data set will be searched (case-insensitive) for this value.
#' @param ab_class an antimicrobial class or a part of it, such as `"carba"` and `"carbapenems"`. The columns `group`, `atc_group1` and `atc_group2` of the [antibiotics] data set will be searched (case-insensitive) for this value.
#' @param filter an [expression] to be evaluated in the [antibiotics] data set, such as `name %like% "trim"`
#' @param only_rsi_columns a [logical] to indicate whether only columns of class `<rsi>` must be selected (defaults to `FALSE`), see [as.rsi()]
#' @param only_treatable a [logical] to indicate whether agents that are only for laboratory tests should be excluded (defaults to `TRUE`), such as gentamicin-high (`GEH`) and imipenem/EDTA (`IPE`)
@ -37,7 +37,7 @@
@@ -37,7 +37,7 @@
#'
#' All columns in the data in which these functions are called will be searched for known antibiotic names, abbreviations, brand names, and codes (ATC, EARS-Net, WHO, etc.) according to the [antibiotics] data set. This means that a selector such as [aminoglycosides()] will pick up column names like 'gen', 'genta', 'J01GB03', 'tobra', 'Tobracin', etc.
#'
#' The [ab_class()] function can be used to filter/select on a manually defined antibiotic class. It searches for results in the [antibiotics] data set within the columns `name`, `atc_group1` and `atc_group2`.
#' The [ab_class()] function can be used to filter/select on a manually defined antibiotic class. It searches for results in the [antibiotics] data set within the columns `group`, `atc_group1` and `atc_group2`.
#'
#' The [ab_selector()] function can be used to internally filter the [antibiotics] data set on any results, see *Examples*. It allows for filtering on a (part of) a certain name, and/or a group name or even a minimum of DDDs for oral treatment. This function yields the highest flexibility, but is also the least user-friendly, since it requires a hard-coded filter to set.
#' Gets data from the WHO to determine properties of an ATC (e.g. an antibiotic), such as the name, defined daily dose (DDD) or standard unit.
#' Gets data from the WHOCC website to determine properties of an Anatomical Therapeutic Chemical (ATC) (e.g. an antibiotic), such as the name, defined daily dose (DDD) or standard unit.
#' @inheritSection lifecycle Stable Lifecycle
#' @param atc_code a [character] or [character] vector with ATC code(s) of antibiotic(s)
#' @param atc_code a [character] (vector) with ATC code(s) of antibiotics, will be coerced with [as.ab()] and [ab_atc()] internally if not a valid ATC code
#' @param property property of an ATC code. Valid values are `"ATC"`, `"Name"`, `"DDD"`, `"U"` (`"unit"`), `"Adm.R"`, `"Note"` and `groups`. For this last option, all hierarchical groups of an ATC code will be returned, see *Examples*.
#' @param administration type of administration when using `property = "Adm.R"`, see *Details*
#' @param url url of website of the WHOCC. The sign `%s` can be used as a placeholder for ATC codes.
@ -68,6 +68,7 @@
@@ -68,6 +68,7 @@
#' if (requireNamespace("curl") && requireNamespace("rvest") && requireNamespace("xml2")) {
#' # oral DDD (Defined Daily Dose) of amoxicillin
#' atc_online_property("J01CA04", "DDD", "O")
#' atc_online_ddd(ab_atc("amox"))
#'
#' # parenteral DDD (Defined Daily Dose) of amoxicillin
#' Data Sets with `r format(nrow(antibiotics) + nrow(antivirals), big.mark = ",")` Antimicrobials
#' Data Sets with `r format(nrow(antibiotics) + nrow(antivirals), big.mark = ",")` Antimicrobial Drugs
#'
#' Two data sets containing all antibiotics/antimycotics and antivirals. Use [as.ab()] or one of the [`ab_*`][ab_property()] functions to retrieve values from the [antibiotics] data set. Three identifiers are included in this data set: an antibiotic ID (`ab`, primarily used in this package) as defined by WHONET/EARS-Net, an ATC code (`atc`) as defined by the WHO, and a Compound ID (`cid`) as found in PubChem. Other properties in this data set are derived from one or more of these codes. Note that some drugs have multiple ATC codes.
#' @format
@ -37,9 +37,9 @@
@@ -37,9 +37,9 @@
#' - `atc_group2`\cr Official chemical subgroup (4th level ATC code) as defined by the WHOCC, like `"Macrolides"`
#' - `abbr`\cr List of abbreviations as used in many countries, also for antibiotic susceptibility testing (AST)
#' - `synonyms`\cr Synonyms (often trade names) of a drug, as found in PubChem based on their compound ID
#' - `oral_ddd`\cr Defined Daily Dose (DDD), oral treatment
#' - `oral_ddd`\cr Defined Daily Dose (DDD), oral treatment, currently available for `r sum(!is.na(antibiotics$oral_ddd))` drugs
#' - `oral_units`\cr Units of `oral_ddd`
#' - `iv_ddd`\cr Defined Daily Dose (DDD), parenteral treatment
#' - `iv_ddd`\cr Defined Daily Dose (DDD), parenteral (intravenous) treatment, currently available for `r sum(!is.na(antibiotics$iv_ddd))` drugs
#' - `iv_units`\cr Units of `iv_ddd`
#' - `loinc`\cr All LOINC codes (Logical Observation Identifiers Names and Codes) associated with the name of the antimicrobial agent. Use [ab_loinc()] to retrieve them quickly, see [ab_property()].
#'
@ -55,7 +55,7 @@
@@ -55,7 +55,7 @@
#' - `iv_units`\cr Units of `iv_ddd`
#' @details Properties that are based on an ATC code are only available when an ATC is available. These properties are: `atc_group1`, `atc_group2`, `oral_ddd`, `oral_units`, `iv_ddd` and `iv_units`.
#'
#' Synonyms (i.e. trade names) are derived from the Compound ID (`cid`) and consequently only available where a CID is available.
#' Synonyms (i.e. trade names) were derived from the Compound ID (`cid`) and consequently only available where a CID is available.
#'
#' ## Direct download
#' These data sets are available as 'flat files' for use even without \R - you can find the files here:
"SMF" "Simvastatin/fenofibrate" "Antimycobacterials" "C10BA04" "Drugs for treatment of tuberculosis" "Other drugs for treatment of tuberculosis" "simv" "" 86 ""
"SMF" "Simvastatin/fenofibrate" "Antimycobacterials" "C10BA04" "Drugs for treatment of tuberculosis" "Other drugs for treatment of tuberculosis" "simv" "" ""
@ -495,7 +495,7 @@ If you are reading this page from within R, please <a href="https://msberends.gi
@@ -495,7 +495,7 @@ If you are reading this page from within R, please <a href="https://msberends.gi
<p>A data set with 456 rows and 14 columns, containing the following column names:<br><em>ab</em>, <em>cid</em>, <em>name</em>, <em>group</em>, <em>atc</em>, <em>atc_group1</em>, <em>atc_group2</em>, <em>abbreviations</em>, <em>synonyms</em>, <em>oral_ddd</em>, <em>oral_units</em>, <em>iv_ddd</em>, <em>iv_units</em> and <em>loinc</em>.</p>
<p>This data set is in R available as <code>antibiotics</code>, after you load the <code>AMR</code> package.</p>
<p>It was last updated on 16 August 2021 13:16:15 UTC. Find more info about the structure of this data set <ahref="https://msberends.github.io/AMR/reference/antibiotics.html">here</a>.</p>
<p>It was last updated on 19 August 2021 21:21:57 UTC. Find more info about the structure of this data set <ahref="https://msberends.github.io/AMR/reference/antibiotics.html">here</a>.</p>
<p><strong>Direct download links:</strong></p>
<ul>
<li>Download as <ahref="https://github.com/msberends/AMR/raw/master/data-raw/../data-raw/antibiotics.rds"class="external-link">R file</a> (32 kB)<br>
<ul><li>Removed <code>p_symbol()</code> and all <code>filter_*()</code> functions (except for <code><ahref="../reference/first_isolate.html">filter_first_isolate()</a></code>), which were all deprecated in a previous package version</li>
<ul><li>Removed <code><ahref="https://msberends.github.io/AMR/reference/AMR-deprecated.html">p_symbol()</a></code> and all <code>filter_*()</code> functions (except for <code><ahref="../reference/first_isolate.html">filter_first_isolate()</a></code>), which were all deprecated in a previous package version</li>
<li>Removed the <code>key_antibiotics()</code> and <code>key_antibiotics_equal()</code> functions, which were deprecated and superseded by <code><ahref="../reference/key_antimicrobials.html">key_antimicrobials()</a></code> and <code><ahref="../reference/key_antimicrobials.html">antimicrobials_equal()</a></code>
</li>
<li>Removed all previously implemented <code><ahref="https://ggplot2.tidyverse.org/reference/ggplot.html"class="external-link">ggplot2::ggplot()</a></code> generics for classes <code><mic></code>, <code><disk></code>, <code><rsi></code> and <code><resistance_predict></code> as they did not follow the <code>ggplot2</code> logic. They were replaced with <code><ahref="https://ggplot2.tidyverse.org/reference/autoplot.html"class="external-link">ggplot2::autoplot()</a></code> generics.</li>
@ -269,6 +269,7 @@
@@ -269,6 +269,7 @@
<code>antibiotics$atc</code> is now a <code>list</code> instead of a <code>character</code>, and this <code>atc</code> column was moved to the 5th position of the <code>antibiotics</code> data set</li>
<li>
<code><ahref="../reference/ab_property.html">ab_atc()</a></code> does not always return a character vector with length 1, and returns a <code>list</code> if the input is larger than length 1</li>
<li>Some DDDs (daily defined doses) were added or updated according to newly included ATC codes</li>
</ul></li>
<li>Antibiotic selectors
<ul><li><p>They now also work in R-3.0 and R-3.1, supporting every version of R since 2013</p></li>
@ -280,6 +281,13 @@
@@ -280,6 +281,13 @@
<spanclass="va">example_isolates</span><spanclass="op">[</span>, <spanclass="fu"><ahref="../reference/antibiotic_class_selectors.html">penicillins</a></span><spanclass="op">(</span><spanclass="op">)</span><spanclass="op">&</span><spanclass="fu"><ahref="../reference/antibiotic_class_selectors.html">administrable_per_os</a></span><spanclass="op">(</span><spanclass="op">)</span><spanclass="op">]</span><spanclass="co"># base R</span>
<p>Added the selector <code><ahref="../reference/antibiotic_class_selectors.html">ab_selector()</a></code>, which accepts a filter to be used internally on the <code>antibiotics</code> data set, yielding great flexibility on drug properties, such as selecting antibiotic columns with an oral DDD of at least 1 gram:</p>
<spanclass="va">example_isolates</span><spanclass="op">[</span>, <spanclass="fu"><ahref="../reference/antibiotic_class_selectors.html">ab_selector</a></span><spanclass="op">(</span><spanclass="va">oral_ddd</span><spanclass="op">></span><spanclass="fl">1</span><spanclass="op">&</span><spanclass="va">oral_units</span><spanclass="op">==</span><spanclass="st">"g"</span><spanclass="op">)</span><spanclass="op">]</span><spanclass="co"># base R</span>
<li><p>Fix for using selectors multiple times in one call (e.g., using them in <code><ahref="https://dplyr.tidyverse.org/reference/filter.html"class="external-link">dplyr::filter()</a></code> and immediately after in <code><ahref="https://dplyr.tidyverse.org/reference/select.html"class="external-link">dplyr::select()</a></code>)</p></li>
<li><p>Added argument <code>only_treatable</code>, which defaults to <code>TRUE</code> and will exclude drugs that are only for laboratory tests and not for treating patients (such as imipenem/EDTA and gentamicin-high)</p></li>
<p>All antibiotic class selectors (such as <code><ahref="../reference/antibiotic_class_selectors.html">carbapenems()</a></code>, <code><ahref="../reference/antibiotic_class_selectors.html">aminoglycosides()</a></code>) can now be used for filtering as well, making all their accompanying <code>filter_*()</code> functions redundant (such as <code>filter_carbapenems()</code>, <code>filter_aminoglycosides()</code>). These functions are now deprecated and will be removed in a next release. Examples of how the selectors can be used for filtering:</p>
<spanclass="co"># select columns with results for carbapenems</span>
<spanclass="va">example_isolates</span><spanclass="op">[</span>, <spanclass="fu"><ahref="../reference/antibiotic_class_selectors.html">carbapenems</a></span><spanclass="op">(</span><spanclass="op">)</span><spanclass="op">]</span><spanclass="co"># base R</span>
@ -370,7 +378,7 @@
@@ -370,7 +378,7 @@
<ul><li><p>Now checks if <code>pattern</code> is a <em>valid</em> regular expression</p></li>
<li>
<p>Added <code><ahref="../reference/like.html">%unlike%</a></code> and <code><ahref="../reference/like.html">%unlike_case%</a></code> (as negations of the existing <code><ahref="../reference/like.html">%like%</a></code> and <code><ahref="../reference/like.html">%like_case%</a></code>). This greatly improves readability:</p>
<p>Functions <code><ahref="../reference/antibiotic_class_selectors.html">oxazolidinones()</a></code> (an antibiotic selector function) and <code>filter_oxazolidinones()</code> (an antibiotic filter function) to select/filter on e.g.linezolid and tedizolid</p>
<li><p><code>ggplot()</code> generics for classes <code><mic></code> and <code><disk></code></p></li>
<li>
<p>Function <code><ahref="../reference/mo_property.html">mo_is_yeast()</a></code>, which determines whether a microorganism is a member of the taxonomic class Saccharomycetes or the taxonomic order Saccharomycetales:</p>
<spanclass="va">example_isolates</span><spanclass="op">[</span><spanclass="fu"><ahref="https://rdrr.io/r/base/which.html">which</a></span><spanclass="op">(</span><spanclass="fu"><ahref="../reference/mo_property.html">mo_is_yeast</a></span><spanclass="op">(</span><spanclass="op">)</span><spanclass="op">)</span>, <spanclass="op">]</span><spanclass="co"># base R</span>
<li><p>Added Pretomanid (PMD, J04AK08) to the <code>antibiotics</code> data set</p></li>
<li>
<p>MIC values (see <code><ahref="../reference/as.mic.html">as.mic()</a></code>) can now be used in any mathematical processing, such as usage inside functions <code><ahref="https://rdrr.io/r/base/Extremes.html"class="external-link">min()</a></code>, <code><ahref="https://rdrr.io/r/base/Extremes.html"class="external-link">max()</a></code>, <code><ahref="https://rdrr.io/r/base/range.html"class="external-link">range()</a></code>, and with binary operators (<code><ahref="https://rdrr.io/r/base/Arithmetic.html"class="external-link">+</a></code>, <code><ahref="https://rdrr.io/r/base/Arithmetic.html"class="external-link">-</a></code>, etc.). This allows for easy distribution analysis and fast filtering on MIC values:</p>
<p>Functions <code><ahref="../reference/get_episode.html">get_episode()</a></code> and <code><ahref="../reference/get_episode.html">is_new_episode()</a></code> to determine (patient) episodes which are not necessarily based on microorganisms. The <code><ahref="../reference/get_episode.html">get_episode()</a></code> function returns the index number of the episode per group, while the <code><ahref="../reference/get_episode.html">is_new_episode()</a></code> function returns values <code>TRUE</code>/<code>FALSE</code> to indicate whether an item in a vector is the start of a new episode. They also support <code>dplyr</code>s grouping (i.e.using <code><ahref="https://dplyr.tidyverse.org/reference/group_by.html"class="external-link">group_by()</a></code>):</p>
<spanclass="co"># to select first isolates that are Gram-negative </span>
<spanclass="co"># and view results of cephalosporins and aminoglycosides:</span>
@ -592,7 +600,7 @@
@@ -592,7 +600,7 @@
</li>
<li>
<p>For antibiotic selection functions (such as <code><ahref="../reference/antibiotic_class_selectors.html">cephalosporins()</a></code>, <code><ahref="../reference/antibiotic_class_selectors.html">aminoglycosides()</a></code>) to select columns based on a certain antibiotic group, the dependency on the <code>tidyselect</code> package was removed, meaning that they can now also be used without the need to have this package installed and now also work in base R function calls (they rely on R 3.2 or later):</p>
<li><p>For all function arguments in the code, it is now defined what the exact type of user input should be (inspired by the <ahref="https://github.com/moodymudskipper/typed"class="external-link"><code>typed</code></a> package). If the user input for a certain function does not meet the requirements for a specific argument (such as the class or length), an informative error will be thrown. This makes the package more robust and the use of it more reproducible and reliable. In total, more than 420 arguments were defined.</p></li>
<li><p>Fix for <code><ahref="../reference/mo_source.html">set_mo_source()</a></code>, that previously would not remember the file location of the original file</p></li>
<li><p>Deprecated function <code>p_symbol()</code> that not really fits the scope of this package. It will be removed in a future version. See <ahref="https://github.com/msberends/AMR/blob/v1.4.0/R/p_symbol.R"class="external-link">here</a> for the source code to preserve it.</p></li>
<li><p>Deprecated function <code><ahref="https://msberends.github.io/AMR/reference/AMR-deprecated.html">p_symbol()</a></code> that not really fits the scope of this package. It will be removed in a future version. See <ahref="https://github.com/msberends/AMR/blob/v1.4.0/R/p_symbol.R"class="external-link">here</a> for the source code to preserve it.</p></li>
<li><p>Updated coagulase-negative staphylococci determination with Becker <em>et al.</em> 2020 (PMID 32056452), meaning that the species <em>S. argensis</em>, <em>S. caeli</em>, <em>S. debuckii</em>, <em>S. edaphicus</em> and <em>S. pseudoxylosus</em> are now all considered CoNS</p></li>
<li><p>Fix for using argument <code>reference_df</code> in <code><ahref="../reference/as.mo.html">as.mo()</a></code> and <code>mo_*()</code> functions that contain old microbial codes (from previous package versions)</p></li>
<li><p>Fixed a bug where <code><ahref="../reference/as.mo.html">mo_uncertainties()</a></code> would not return the results based on the MO matching score</p></li>
@ -638,7 +646,7 @@
@@ -638,7 +646,7 @@
<li>
<p>Data set <code>intrinsic_resistant</code>. This data set contains all bug-drug combinations where the ‘bug’ is intrinsic resistant to the ‘drug’ according to the latest EUCAST insights. It contains just two columns: <code>microorganism</code> and <code>antibiotic</code>.</p>
<p>Curious about which enterococci are actually intrinsic resistant to vancomycin?</p>
<p>Improvements for <code><ahref="../reference/as.rsi.html">as.rsi()</a></code>:</p>
<ul><li>
<p>Support for using <code>dplyr</code>’s <code><ahref="https://dplyr.tidyverse.org/reference/across.html"class="external-link">across()</a></code> to interpret MIC values or disk zone diameters, which also automatically determines the column with microorganism names or codes.</p>
<p>Added intelligent data cleaning to <code><ahref="../reference/as.disk.html">as.disk()</a></code>, so numbers can also be extracted from text and decimal numbers will always be rounded up:</p>
<ul><li><p>Function <code><ahref="../reference/ab_from_text.html">ab_from_text()</a></code> to retrieve antimicrobial drug names, doses and forms of administration from clinical texts in e.g.health care records, which also corrects for misspelling since it uses <code><ahref="../reference/as.ab.html">as.ab()</a></code> internally</p></li>
<li>
<p><ahref="https://tidyselect.r-lib.org/reference/language.html"class="external-link">Tidyverse selection helpers</a> for antibiotic classes, that help to select the columns of antibiotics that are of a specific antibiotic class, without the need to define the columns or antibiotic abbreviations. They can be used in any function that allows selection helpers, like <code><ahref="https://dplyr.tidyverse.org/reference/select.html"class="external-link">dplyr::select()</a></code> and <code><ahref="https://tidyr.tidyverse.org/reference/pivot_longer.html"class="external-link">tidyr::pivot_longer()</a></code>:</p>
@ -833,7 +841,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
@@ -833,7 +841,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/