* Functions `is_gram_negative()` and `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. If you have the `dplyr` package installed, they can even determine the column with microorganisms themselves inside `dplyr` functions:
* 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. If you have the `dplyr` package installed, they can even determine the column with microorganisms themselves when used inside `dplyr` verbs:
```r
example_isolates %>%
filter(is_gram_positive())
#> NOTE: Using column `mo` as input for 'x'
filter(mo_is_gram_positive())
#> NOTE: Using column `mo` as input for mo_is_gram_positive()
```
* 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. As with the new `mo_is_gram_*()` functions, if you have the `dplyr` package installed the column with microorganisms will be automatically determined when used inside `dplyr` verbs:
#> NOTE: Using column `mo` as input for mo_is_intrinsic_resistant()
```
* Functions `%not_like%` and `%not_like_case%` as wrappers around `%like%` and `%like_case%`. The RStudio addin to insert the text " %like% " as provided in this package now iterates over all like variants. So if you have defined the keyboard shortcut Ctrl/Cmd + L to this addin, it will first insert ` %like% ` and by pressing it again it will be replaced with ` %not_like% `, etc.
#' @param property one of the column names of the [microorganisms] data set or `"shortname"`
#' @param language language of the returned text, defaults to system language (see [get_locale()]) and can be overwritten by setting the option `AMR_locale`, e.g. `options(AMR_locale = "de")`, see [translate]. Also used to translate text like "no growth". Use `language = NULL` or `language = ""` to prevent translation.
#' @param ... other parameters passed on to [as.mo()], such as 'allow_uncertain' and 'ignore_pattern'
#' @param ab any (vector of) text that can be coerced to a valid antibiotic code with [as.ab()]
#' @param open browse the URL using [utils::browseURL()]
#' @details All functions will return the most recently known taxonomic property according to the Catalogue of Life, except for [mo_ref()], [mo_authors()] and [mo_year()]. Please refer to this example, knowing that *Escherichia blattae* was renamed to *Shimwellia blattae* in 2010:
#' - `mo_name("Escherichia blattae")` will return `"Shimwellia blattae"` (with a message about the renaming)
@ -41,7 +42,9 @@
#'
#' Since the top-level of the taxonomy is sometimes referred to as 'kingdom' and sometimes as 'domain', the functions [mo_kingdom()] and [mo_domain()] return the exact same results.
#'
#' The Gram stain - [mo_gramstain()] - will be determined based on the taxonomic kingdom and phylum. According to Cavalier-Smith (2002, [PMID 11837318](https://pubmed.ncbi.nlm.nih.gov/11837318)), who defined subkingdoms Negibacteria and Posibacteria, only these phyla are Posibacteria: Actinobacteria, Chloroflexi, Firmicutes and Tenericutes. These bacteria are considered Gram-positive - all other bacteria are considered Gram-negative. Species outside the kingdom of Bacteria will return a value `NA`. Functions [is_gram_negative()] and [is_gram_positive()] 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.
#' The Gram stain - [mo_gramstain()] - will be determined based on the taxonomic kingdom and phylum. According to Cavalier-Smith (2002, [PMID 11837318](https://pubmed.ncbi.nlm.nih.gov/11837318)), who defined subkingdoms Negibacteria and Posibacteria, only these phyla are Posibacteria: Actinobacteria, Chloroflexi, Firmicutes and Tenericutes. These bacteria are considered Gram-positive - all other bacteria are considered Gram-negative. Species outside the kingdom of Bacteria will return a value `NA`. Functions [mo_is_gram_negative()] and [mo_is_gram_positive()] 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.
#'
#' Intrinsic resistance - [mo_is_intrinsic_resistant()] - will be determined based on the [intrinsic_resistant] data set, which is based on `r format_eucast_version_nr(3.2)`. The [mo_is_intrinsic_resistant()] can be vectorised over parameters `x` (input for microorganisms) and over `ab` (input for antibiotics).
#'
#' All output will be [translate]d where possible.
#'
@ -139,13 +142,19 @@
#' Lancefield = TRUE,
#' language = "nl") # "Streptococcus groep A"
#'
#' # gram stains can be used as a filter
#'
#' # other --------------------------------------------------------------------
#'
#' # gram stains and intrinsic resistance can also be used as a filter in dplyr verbs
<ahref="#last-updated-12-november-2020"class="anchor"></a><small>Last updated: 12 November 2020</small>
<ahref="#last-updated-16-november-2020"class="anchor"></a><small>Last updated: 16 November 2020</small>
</h2>
<divid="new"class="section level3">
<h3class="hasAnchor">
<ahref="#new"class="anchor"></a>New</h3>
<ul>
<li>
<p>Functions <code><ahref="../reference/mo_property.html">is_gram_negative()</a></code> and <code><ahref="../reference/mo_property.html">is_gram_positive()</a></code> as wrappers around <code><ahref="../reference/mo_property.html">mo_gramstain()</a></code>. They always return <code>TRUE</code> or <code>FALSE</code> (except when the input is <code>NA</code> or the MO code is <code>UNKNOWN</code>), thus always return <code>FALSE</code> for species outside the taxonomic kingdom of Bacteria. If you have the <code>dplyr</code> package installed, they can even determine the column with microorganisms themselves inside <code>dplyr</code>functions:</p>
<p>Functions <code><ahref="../reference/mo_property.html">mo_is_gram_negative()</a></code> and <code><ahref="../reference/mo_property.html">mo_is_gram_positive()</a></code> as wrappers around <code><ahref="../reference/mo_property.html">mo_gramstain()</a></code>. They always return <code>TRUE</code> or <code>FALSE</code> (except when the input is <code>NA</code> or the MO code is <code>UNKNOWN</code>), thus always return <code>FALSE</code> for species outside the taxonomic kingdom of Bacteria. If you have the <code>dplyr</code> package installed, they can even determine the column with microorganisms themselves when used inside <code>dplyr</code>verbs:</p>
<spanclass="co">#> NOTE: Using column `mo` as input for mo_is_gram_positive()</span></pre></div>
</li>
<li>
<p>Function <code><ahref="../reference/mo_property.html">mo_is_intrinsic_resistant()</a></code> to test for intrinsic resistance, based on <ahref="https://www.eucast.org/expert_rules_and_intrinsic_resistance/">EUCAST Intrinsic Resistance and Unusual Phenotypes v3.2</a> from 2020. As with the new <code>mo_is_gram_*()</code> functions, if you have the <code>dplyr</code> package installed the column with microorganisms will be automatically determined when used inside <code>dplyr</code> verbs:</p>
<spanclass="co">#> NOTE: Using column `mo` as input for mo_is_intrinsic_resistant()</span></pre></div>
</li>
<li><p>Functions <code><ahref="../reference/like.html">%not_like%</a></code> and <code><ahref="../reference/like.html">%not_like_case%</a></code> as wrappers around <code><ahref="../reference/like.html">%like%</a></code> and <code><ahref="../reference/like.html">%like_case%</a></code>. The RStudio addin to insert the text " %like% " as provided in this package now iterates over all like variants. So if you have defined the keyboard shortcut Ctrl/Cmd + L to this addin, it will first insert <code><ahref="../reference/like.html">%like%</a></code> and by pressing it again it will be replaced with <code><ahref="../reference/like.html">%not_like%</a></code>, etc.</p></li>
</ul>
@ -295,7 +302,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>Support for using <code>dplyr</code>’s <code><ahref="https://dplyr.tidyverse.org/reference/across.html">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>
<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">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">dplyr::select()</a></code> and <code><ahref="https://tidyr.tidyverse.org/reference/pivot_longer.html">tidyr::pivot_longer()</a></code>:</p>
<spanclass="co"># Columns 'IPM' and 'MEM' are in the example_isolates data set</span>
@ -582,7 +589,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>Fixed important floating point error for some MIC comparisons in EUCAST 2020 guideline</p></li>
<li>
<p>Interpretation from MIC values (and disk zones) to R/SI can now be used with <code><ahref="https://dplyr.tidyverse.org/reference/mutate_all.html">mutate_at()</a></code> of the <code>dplyr</code> package:</p>
<spanclass="fu"><ahref="https://dplyr.tidyverse.org/reference/mutate_all.html">mutate_at</a></span><spanclass="op">(</span><spanclass="fu"><ahref="https://dplyr.tidyverse.org/reference/vars.html">vars</a></span><spanclass="op">(</span><spanclass="va">antibiotic1</span><spanclass="op">:</span><spanclass="va">antibiotic25</span><spanclass="op">)</span>, <spanclass="va">as.rsi</span>, mo <spanclass="op">=</span><spanclass="st">"E. coli"</span><spanclass="op">)</span>
@ -610,7 +617,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<ul>
<li>
<p>Support for LOINC codes in the <code>antibiotics</code> data set. Use <code><ahref="../reference/ab_property.html">ab_loinc()</a></code> to retrieve LOINC codes, or use a LOINC code for input in any <code>ab_*</code> function:</p>
@ -620,7 +627,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
</li>
<li>
<p>Support for SNOMED CT codes in the <code>microorganisms</code> data set. Use <code><ahref="../reference/mo_property.html">mo_snomed()</a></code> to retrieve SNOMED codes, or use a SNOMED code for input in any <code>mo_*</code> function:</p>
@ -700,7 +707,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<ul>
<li>
<p>Functions <code><ahref="../reference/proportion.html">susceptibility()</a></code> and <code><ahref="../reference/proportion.html">resistance()</a></code> as aliases of <code><ahref="../reference/proportion.html">proportion_SI()</a></code> and <code><ahref="../reference/proportion.html">proportion_R()</a></code>, respectively. These functions were added to make it more clear that “I” should be considered susceptible and not resistant.</p>
@ -728,7 +735,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>More intelligent way of coping with some consonants like “l” and “r”</p></li>
<li>
<p>Added a score (a certainty percentage) to <code><ahref="../reference/as.mo.html">mo_uncertainties()</a></code>, that is calculated using the <ahref="https://en.wikipedia.org/wiki/Levenshtein_distance">Levenshtein distance</a>:</p>
@ -786,13 +793,13 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<ul>
<li>
<p>Determination of first isolates now <strong>excludes</strong> all ‘unknown’ microorganisms at default, i.e.microbial code <code>"UNKNOWN"</code>. They can be included with the new parameter <code>include_unknown</code>:</p>
<p>For WHONET users, this means that all records/isolates with organism code <code>"con"</code> (<em>contamination</em>) will be excluded at default, since <code>as.mo("con") = "UNKNOWN"</code>. The function always shows a note with the number of ‘unknown’ microorganisms that were included or excluded.</p>
</li>
<li>
<p>For code consistency, classes <code>ab</code> and <code>mo</code> will now be preserved in any subsetting or assignment. For the sake of data integrity, this means that invalid assignments will now result in <code>NA</code>:</p>
@ -816,7 +823,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<ul>
<li>
<p>Function <code><ahref="../reference/bug_drug_combinations.html">bug_drug_combinations()</a></code> to quickly get a <code>data.frame</code> with the results of all bug-drug combinations in a data set. The column containing microorganism codes is guessed automatically and its input is transformed with <code><ahref="../reference/mo_property.html">mo_shortname()</a></code> at default:</p>
<spanclass="co">#> NOTE: Use 'format()' on this result to get a publicable/printable format.</span></pre></div>
<p>You can format this to a printable format, ready for reporting or exporting to e.g.Excel with the base R <code><ahref="https://rdrr.io/r/base/format.html">format()</a></code> function:</p>
<p>Additional way to calculate co-resistance, i.e.when using multiple antimicrobials as input for <code>portion_*</code> functions or <code>count_*</code> functions. This can be used to determine the empiric susceptibility of a combination therapy. A new parameter <code>only_all_tested</code> (<strong>which defaults to <code>FALSE</code></strong>) replaces the old <code>also_single_tested</code> 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 <code>portion</code> and <code>count</code> help pages), where the %SI is being determined:</p>
@ -864,7 +871,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
</li>
<li>
<p><code>tibble</code> printing support for classes <code>rsi</code>, <code>mic</code>, <code>disk</code>, <code>ab</code><code>mo</code>. When using <code>tibble</code>s containing antimicrobial columns, values <code>S</code> will print in green, values <code>I</code> will print in yellow and values <code>R</code> will print in red. Microbial IDs (class <code>mo</code>) will emphasise on the genus and species, not on the kingdom.</p>
@ -946,7 +953,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<ul>
<li>
<p>Function <code><ahref="../reference/proportion.html">rsi_df()</a></code> to transform a <code>data.frame</code> to a data set containing only the microbial interpretation (S, I, R), the antibiotic, the percentage of S/I/R and the number of available isolates. This is a convenient combination of the existing functions <code><ahref="../reference/count.html">count_df()</a></code> and <code>portion_df()</code> to immediately show resistance percentages and number of available isolates:</p>
<p>The <code>antibiotics</code> data set will be searched, after which the input data will be checked for column names with a value in any abbreviations, codes or official names found in the <code>antibiotics</code> data set. For example:</p>
@ -1211,19 +1218,19 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>New function <code><ahref="../reference/age_groups.html">age_groups()</a></code> to split ages into custom or predefined groups (like children or elderly). This allows for easier demographic antimicrobial resistance analysis per age group.</p></li>
<li>
<p>New function <code><ahref="../reference/resistance_predict.html">ggplot_rsi_predict()</a></code> as well as the base R <code><ahref="../reference/plot.html">plot()</a></code> function can now be used for resistance prediction calculated with <code><ahref="../reference/resistance_predict.html">resistance_predict()</a></code>:</p>
<p>Functions <code><ahref="../reference/first_isolate.html">filter_first_isolate()</a></code> and <code><ahref="../reference/first_isolate.html">filter_first_weighted_isolate()</a></code> to shorten and fasten filtering on data sets with antimicrobial results, e.g.:</p>
@ -1266,7 +1273,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
</li>
<li>
<p>Uncertainty of the algorithm is now divided into four levels, 0 to 3, where the default <code>allow_uncertain = TRUE</code> is equal to uncertainty level 2. Run <code><ahref="../reference/as.mo.html">?as.mo</a></code> for more info about these levels.</p>
@ -1280,7 +1287,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>All microbial IDs that found are now saved to a local file <code>~/.Rhistory_mo</code>. Use the new function <code>clean_mo_history()</code> to delete this file, which resets the algorithms.</p></li>
<li>
<p>Incoercible results will now be considered ‘unknown’, MO code <code>UNKNOWN</code>. On foreign systems, properties of these will be translated to all languages already previously supported: German, Dutch, French, Italian, Spanish and Portuguese:</p>
<spanclass="fu"><ahref="../reference/mo_property.html">mo_genus</a></span><spanclass="op">(</span><spanclass="st">"qwerty"</span>, language <spanclass="op">=</span><spanclass="st">"es"</span><spanclass="op">)</span>
<spanclass="co"># Warning: </span>
<spanclass="co"># one unique value (^= 100.0%) could not be coerced and is considered 'unknown': "qwerty". Use mo_failures() to review it.</span>
@ -1329,7 +1336,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<ul>
<li>
<p>Support for tidyverse quasiquotation! Now you can create frequency tables of function outcomes:</p>
<spanclass="fu"><ahref="https://dplyr.tidyverse.org/reference/select.html">select</a></span><spanclass="op">(</span><spanclass="op">-</span><spanclass="va">count</span>, <spanclass="op">-</span><spanclass="va">cum_count</span><spanclass="op">)</span><spanclass="co"># only get item, percent, cum_percent</span></pre></div>
@ -1514,7 +1521,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
</li>
</ul>
<p>They also come with support for German, Dutch, French, Italian, Spanish and Portuguese:</p>
<spanclass="fu"><ahref="../reference/mo_property.html">mo_gramstain</a></span><spanclass="op">(</span><spanclass="st">"E. coli"</span>, language <spanclass="op">=</span><spanclass="st">"de"</span><spanclass="op">)</span><spanclass="co"># German</span>
@ -1524,7 +1531,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<spanclass="fu"><ahref="../reference/mo_property.html">mo_fullname</a></span><spanclass="op">(</span><spanclass="st">"S. group A"</span>, language <spanclass="op">=</span><spanclass="st">"pt"</span><spanclass="op">)</span><spanclass="co"># Portuguese</span>
<spanclass="co"># [1] "Streptococcus grupo A"</span></pre></div>
<p>Furthermore, former taxonomic names will give a note about the current taxonomic name:</p>
@ -1538,7 +1545,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>Function <code>is.rsi.eligible</code> to check for columns that have valid antimicrobial results, but do not have the <code>rsi</code> class yet. Transform the columns of your raw data with: <code>data %>% mutate_if(is.rsi.eligible, as.rsi)</code></p></li>
<li>
<p>Functions <code>as.mo</code> and <code>is.mo</code> as replacements for <code>as.bactid</code> and <code>is.bactid</code> (since the <code>microoganisms</code> data set not only contains bacteria). These last two functions are deprecated and will be removed in a future release. The <code>as.mo</code> function determines microbial IDs using intelligent rules:</p>
<spanclass="fu">microbenchmark</span><spanclass="fu">::</span><spanclass="fu"><ahref="https://rdrr.io/pkg/microbenchmark/man/microbenchmark.html">microbenchmark</a></span><spanclass="op">(</span><spanclass="fu"><ahref="../reference/as.mo.html">as.mo</a></span><spanclass="op">(</span><spanclass="va">thousands_of_E_colis</span><spanclass="op">)</span>, unit <spanclass="op">=</span><spanclass="st">"s"</span><spanclass="op">)</span>
<spanclass="co"># Unit: seconds</span>
@ -1579,7 +1586,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>Added three antimicrobial agents to the <code>antibiotics</code> data set: Terbinafine (D01BA02), Rifaximin (A07AA11) and Isoconazole (D01AC05)</p></li>
<li>
<p>Added 163 trade names to the <code>antibiotics</code> data set, it now contains 298 different trade names in total, e.g.:</p>
@ -1595,7 +1602,7 @@ This works for all drug combinations, such as ampicillin/sulbactam, ceftazidime/
<li><p>Added parameters <code>minimum</code> and <code>as_percent</code> to <code>portion_df</code></p></li>
<li>
<p>Support for quasiquotation in the functions series <code>count_*</code> and <code>portions_*</code>, and <code>n_rsi</code>. This allows to check for more than 2 vectors or columns.</p>
<spanclass="version label label-default"data-toggle="tooltip"data-placement="bottom"title="Latest development version">1.4.0.9019</span>
<spanclass="version label label-default"data-toggle="tooltip"data-placement="bottom"title="Latest development version">1.4.0.9020</span>
</span>
</div>
@ -455,8 +455,9 @@ This package contains the complete taxonomic tree of almost all microorganisms (
<spanclass='fu'>as.mo</span><spanclass='op'>(</span><spanclass='st'>"S. pyogenes"</span>, Lancefield <spanclass='op'>=</span><spanclass='cn'>TRUE</span><spanclass='op'>)</span><spanclass='co'># will not remain species: B_STRPT_GRPA</span>
<spanclass='co'># All mo_* functions use as.mo() internally too (see ?mo_property):</span>
