P281424/AMR
1
0
Fork 0
mirror of https://github.com/msberends/AMR.git synced 2024-12-26 07:26:13 +01:00
Code Releases Activity
175a6777f3
AMR/data-raw/gpt_training_text_v2.1.1.9116.txt

10134 lines
561 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This files contains all context you must know about the AMR package for R.
First and foremost, you are trained on version 2.1.1.9116. Remember this whenever someone asks which AMR package version you’re at.
--------------------------------
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'NAMESPACE':
# Generated by roxygen2: do not edit by hand
S3method("!=",ab_selector)
S3method("&",ab_selector)
S3method("==",ab_selector)
S3method("[",ab)
S3method("[",av)
S3method("[",disk)
S3method("[",mic)
S3method("[",mo)
S3method("[<-",ab)
S3method("[<-",av)
S3method("[<-",disk)
S3method("[<-",mic)
S3method("[<-",mo)
S3method("[<-",sir)
S3method("[[",ab)
S3method("[[",av)
S3method("[[",disk)
S3method("[[",mic)
S3method("[[",mo)
S3method("[[<-",ab)
S3method("[[<-",av)
S3method("[[<-",disk)
S3method("[[<-",mic)
S3method("[[<-",mo)
S3method("[[<-",sir)
S3method("|",ab_selector)
S3method(Complex,mic)
S3method(Math,mic)
S3method(Ops,mic)
S3method(Summary,mic)
S3method(all,ab_selector)
S3method(all,ab_selector_any_all)
S3method(any,ab_selector)
S3method(any,ab_selector_any_all)
S3method(as.data.frame,ab)
S3method(as.data.frame,av)
S3method(as.data.frame,mic)
S3method(as.data.frame,mo)
S3method(as.double,mic)
S3method(as.double,sir)
S3method(as.list,custom_eucast_rules)
S3method(as.list,custom_mdro_guideline)
S3method(as.list,mic)
S3method(as.matrix,mic)
S3method(as.numeric,mic)
S3method(as.sir,data.frame)
S3method(as.sir,default)
S3method(as.sir,disk)
S3method(as.sir,mic)
S3method(as.vector,mic)
S3method(barplot,antibiogram)
S3method(barplot,disk)
S3method(barplot,mic)
S3method(barplot,sir)
S3method(c,ab)
S3method(c,ab_selector)
S3method(c,av)
S3method(c,custom_eucast_rules)
S3method(c,custom_mdro_guideline)
S3method(c,disk)
S3method(c,mic)
S3method(c,mo)
S3method(c,sir)
S3method(close,progress_bar)
S3method(droplevels,mic)
S3method(droplevels,sir)
S3method(format,bug_drug_combinations)
S3method(hist,mic)
S3method(kurtosis,data.frame)
S3method(kurtosis,default)
S3method(kurtosis,matrix)
S3method(mean,mic)
S3method(mean_amr_distance,data.frame)
S3method(mean_amr_distance,default)
S3method(mean_amr_distance,disk)
S3method(mean_amr_distance,mic)
S3method(mean_amr_distance,sir)
S3method(median,mic)
S3method(plot,antibiogram)
S3method(plot,disk)
S3method(plot,mic)
S3method(plot,resistance_predict)
S3method(plot,sir)
S3method(print,ab)
S3method(print,ab_selector)
S3method(print,av)
S3method(print,bug_drug_combinations)
S3method(print,custom_eucast_rules)
S3method(print,custom_mdro_guideline)
S3method(print,disk)
S3method(print,mic)
S3method(print,mo)
S3method(print,mo_renamed)
S3method(print,mo_uncertainties)
S3method(print,pca)
S3method(print,sir)
S3method(print,sir_log)
S3method(quantile,mic)
S3method(rep,ab)
S3method(rep,av)
S3method(rep,disk)
S3method(rep,mic)
S3method(rep,mo)
S3method(rep,sir)
S3method(skewness,data.frame)
S3method(skewness,default)
S3method(skewness,matrix)
S3method(sort,mic)
S3method(summary,mic)
S3method(summary,mo)
S3method(summary,pca)
S3method(summary,sir)
S3method(unique,ab)
S3method(unique,av)
S3method(unique,disk)
S3method(unique,mic)
S3method(unique,mo)
S3method(unique,sir)
export("%like%")
export("%like_case%")
export("%unlike%")
export("%unlike_case%")
export(NA_disk_)
export(NA_mic_)
export(NA_sir_)
export(ab_atc)
export(ab_atc_group1)
export(ab_atc_group2)
export(ab_cid)
export(ab_class)
export(ab_ddd)
export(ab_ddd_units)
export(ab_from_text)
export(ab_group)
export(ab_info)
export(ab_loinc)
export(ab_name)
export(ab_property)
export(ab_selector)
export(ab_synonyms)
export(ab_tradenames)
export(ab_url)
export(add_custom_antimicrobials)
export(add_custom_microorganisms)
export(administrable_iv)
export(administrable_per_os)
export(age)
export(age_groups)
export(all_antimicrobials)
export(aminoglycosides)
export(aminopenicillins)
export(amr_distance_from_row)
export(anti_join_microorganisms)
export(antibiogram)
export(antifungals)
export(antimicrobials_equal)
export(antimycobacterials)
export(as.ab)
export(as.av)
export(as.disk)
export(as.mic)
export(as.mo)
export(as.sir)
export(atc_online_ddd)
export(atc_online_ddd_units)
export(atc_online_groups)
export(atc_online_property)
export(av_atc)
export(av_cid)
export(av_ddd)
export(av_ddd_units)
export(av_from_text)
export(av_group)
export(av_info)
export(av_loinc)
export(av_name)
export(av_property)
export(av_synonyms)
export(av_tradenames)
export(av_url)
export(availability)
export(betalactams)
export(betalactams_with_inhibitor)
export(brmo)
export(bug_drug_combinations)
export(carbapenems)
export(cephalosporins)
export(cephalosporins_1st)
export(cephalosporins_2nd)
export(cephalosporins_3rd)
export(cephalosporins_4th)
export(cephalosporins_5th)
export(clear_custom_antimicrobials)
export(clear_custom_microorganisms)
export(count_I)
export(count_IR)
export(count_R)
export(count_S)
export(count_SI)
export(count_all)
export(count_df)
export(count_resistant)
export(count_susceptible)
export(custom_eucast_rules)
export(custom_mdro_guideline)
export(eucast_dosage)
export(eucast_exceptional_phenotypes)
export(eucast_rules)
export(facet_sir)
export(filter_first_isolate)
export(first_isolate)
export(fluoroquinolones)
export(full_join_microorganisms)
export(g.test)
export(geom_sir)
export(get_AMR_locale)
export(get_episode)
export(get_mo_source)
export(ggplot_pca)
export(ggplot_sir)
export(ggplot_sir_predict)
export(glycopeptides)
export(guess_ab_col)
export(inner_join_microorganisms)
export(is.ab)
export(is.av)
export(is.disk)
export(is.mic)
export(is.mo)
export(is.sir)
export(is_new_episode)
export(is_sir_eligible)
export(italicise_taxonomy)
export(italicize_taxonomy)
export(key_antimicrobials)
export(kurtosis)
export(labels_sir_count)
export(left_join_microorganisms)
export(like)
export(lincosamides)
export(lipoglycopeptides)
export(macrolides)
export(mdr_cmi2012)
export(mdr_tb)
export(mdro)
export(mean_amr_distance)
export(mo_authors)
export(mo_class)
export(mo_cleaning_regex)
export(mo_current)
export(mo_domain)
export(mo_failures)
export(mo_family)
export(mo_fullname)
export(mo_gbif)
export(mo_genus)
export(mo_gramstain)
export(mo_group_members)
export(mo_info)
export(mo_is_anaerobic)
export(mo_is_gram_negative)
export(mo_is_gram_positive)
export(mo_is_intrinsic_resistant)
export(mo_is_yeast)
export(mo_kingdom)
export(mo_lpsn)
export(mo_matching_score)
export(mo_mycobank)
export(mo_name)
export(mo_order)
export(mo_oxygen_tolerance)
export(mo_pathogenicity)
export(mo_phylum)
export(mo_property)
export(mo_rank)
export(mo_ref)
export(mo_renamed)
export(mo_reset_session)
export(mo_shortname)
export(mo_snomed)
export(mo_species)
export(mo_status)
export(mo_subspecies)
export(mo_synonyms)
export(mo_taxonomy)
export(mo_type)
export(mo_uncertainties)
export(mo_url)
export(mo_year)
export(mrgn)
export(n_sir)
export(nitrofurans)
export(not_intrinsic_resistant)
export(oxazolidinones)
export(pca)
export(penicillins)
export(polymyxins)
export(proportion_I)
export(proportion_IR)
export(proportion_R)
export(proportion_S)
export(proportion_SI)
export(proportion_df)
export(quinolones)
export(random_disk)
export(random_mic)
export(random_sir)
export(rescale_mic)
export(reset_AMR_locale)
export(resistance)
export(resistance_predict)
export(rifamycins)
export(right_join_microorganisms)
export(scale_colour_mic)
export(scale_fill_mic)
export(scale_sir_colours)
export(scale_x_mic)
export(scale_y_mic)
export(scale_y_percent)
export(semi_join_microorganisms)
export(set_AMR_locale)
export(set_ab_names)
export(set_mo_source)
export(sir_confidence_interval)
export(sir_df)
export(sir_interpretation_history)
export(sir_predict)
export(skewness)
export(streptogramins)
export(susceptibility)
export(tetracyclines)
export(theme_sir)
export(translate_AMR)
export(trimethoprims)
export(ureidopenicillins)
importFrom(graphics,arrows)
importFrom(graphics,axis)
importFrom(graphics,barplot)
importFrom(graphics,hist)
importFrom(graphics,legend)
importFrom(graphics,mtext)
importFrom(graphics,plot)
importFrom(graphics,points)
importFrom(graphics,text)
importFrom(stats,complete.cases)
importFrom(stats,glm)
importFrom(stats,lm)
importFrom(stats,median)
importFrom(stats,pchisq)
importFrom(stats,prcomp)
importFrom(stats,predict)
importFrom(stats,qchisq)
importFrom(stats,quantile)
importFrom(stats,var)
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'index.md':
# The `AMR` Package for R <a href="https://msberends.github.io/AMR/"><img src="./logo.svg" align="right" height="139" /></a>
* Provides an **all-in-one solution** for antimicrobial resistance (AMR) data analysis in a One Health approach
* Used in over 175 countries, available in 20 languages
* Generates **antibiograms** - traditional, combined, syndromic, and even WISCA
* Provides the **full microbiological taxonomy** and extensive info on **all antimicrobial drugs**
* Applies all recent **CLSI** and **EUCAST** clinical and veterinary breakpoints for MICs, disk zones and ECOFFs
* Corrects for duplicate isolates, **calculates** and **predicts** AMR per antibiotic class
* Integrates with **WHONET**, ATC, **EARS-Net**, PubChem, **LOINC**, **SNOMED CT**, and **NCBI**
* 100% free of costs and dependencies, highly suitable for places with **limited resources**
> Now available for Python too! [Click here](./articles/AMR_for_Python.html) to read more.
<div style="display: flex; font-size: 0.8em;">
<p style="text-align:left; width: 50%;"><small><a href="https://msberends.github.io/AMR/">https://msberends.github.io/AMR</a></small></p>
<p style="text-align:right; width: 50%;"><small><a href="https://doi.org/10.18637/jss.v104.i03" target="_blank">https://doi.org/10.18637/jss.v104.i03</a></small></p>
</div>
<a href="./reference/clinical_breakpoints.html#response-from-clsi-and-eucast"><img src="./endorsement_clsi_eucast.jpg" class="endorse_img" align="right" height="120" /></a>
----
### Introduction
The `AMR` package is a [free and open-source](#copyright) R package with [zero dependencies](https://en.wikipedia.org/wiki/Dependency_hell) to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. **Our aim is to provide a standard** for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. [Many different researchers](./authors.html) from around the globe are continually helping us to make this a successful and durable project!
This work was published in the Journal of Statistical Software (Volume 104(3); [DOI 10.18637/jss.v104.i03](https://doi.org/10.18637/jss.v104.i03)) and formed the basis of two PhD theses ([DOI 10.33612/diss.177417131](https://doi.org/10.33612/diss.177417131) and [DOI 10.33612/diss.192486375](https://doi.org/10.33612/diss.192486375)).
After installing this package, R knows [**~52,000 distinct microbial species**](./reference/microorganisms.html) (updated December 2022) and all [**~600 antibiotic, antimycotic and antiviral drugs**](./reference/antibiotics.html) by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral clinical breakpoint guidelines from CLSI and EUCAST are included, even with epidemiological cut-off (ECOFF) values. It supports and can read any data format, including WHONET data. This package works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). **It was designed to work in any setting, including those with very limited resources**. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the [University of Groningen](https://www.rug.nl), in collaboration with non-profit organisations [Certe Medical Diagnostics and Advice Foundation](https://www.certe.nl) and [University Medical Center Groningen](https://www.umcg.nl).
##### Used in over 175 countries, available in 20 languages
<a href="./countries_large.png" target="_blank"><img src="./countries.png" align="right" style="max-width: 300px;" /></a>
Since its first public release in early 2018, this R package has been used in almost all countries in the world. Click the map to enlarge and to see the country names.
With the help of contributors from all corners of the world, the `AMR` package is available in <img src="lang_en.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> English, <img src="lang_cs.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Czech, <img src="lang_zh.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Chinese, <img src="lang_da.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Danish, <img src="lang_nl.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Dutch, <img src="lang_fi.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Finnish, <img src="lang_fr.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> French, <img src="lang_de.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> German, <img src="lang_el.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Greek, <img src="lang_it.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Italian, <img src="lang_ja.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Japanese, <img src="lang_no.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Norwegian, <img src="lang_pl.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Polish, <img src="lang_pt.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Portuguese, <img src="lang_ro.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Romanian, <img src="lang_ru.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Russian, <img src="lang_es.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Spanish, <img src="lang_sv.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Swedish, <img src="lang_tr.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Turkish, and <img src="lang_uk.svg" style="height: 13px !important; border: 1px solid #cccccc; vertical-align: initial !important;"> Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages.
### Practical examples
#### Filtering and selecting data
One of the most powerful functions of this package, aside from calculating and plotting AMR, is selecting and filtering based on antibiotic columns. This can be done using the so-called [antibiotic class selectors](https://msberends.github.io/AMR/reference/antibiotic_class_selectors.html) that work in base R, `dplyr` and `data.table`:
```r
# AMR works great with dplyr, but it's not required or neccesary
library(AMR)
library(dplyr)
example_isolates %>%
mutate(bacteria = mo_fullname()) %>%
# filtering functions for microorganisms:
filter(mo_is_gram_negative(),
mo_is_intrinsic_resistant(ab = "cefotax")) %>%
# antibiotic selectors:
select(bacteria,
aminoglycosides(),
carbapenems())
```
With only having defined a row filter on Gram-negative bacteria with intrinsic resistance to cefotaxime (`mo_is_gram_negative()` and `mo_is_intrinsic_resistant()`) and a column selection on two antibiotic groups (`aminoglycosides()` and `carbapenems()`), the reference data about [all microorganisms](./reference/microorganisms.html) and [all antibiotics](./reference/antibiotics.html) in the `AMR` package make sure you get what you meant:
|bacteria | GEN | TOB | AMK | KAN | IPM | MEM |
|:------------------------------|:---:|:---:|:---:|:---:|:---:|:---:|
|*Pseudomonas aeruginosa* | I | S | | R | S | |
|*Pseudomonas aeruginosa* | I | S | | R | S | |
|*Pseudomonas aeruginosa* | I | S | | R | S | |
|*Pseudomonas aeruginosa* | S | S | S | R | | S |
|*Pseudomonas aeruginosa* | S | S | S | R | S | S |
|*Pseudomonas aeruginosa* | S | S | S | R | S | S |
|*Stenotrophomonas maltophilia* | R | R | R | R | R | R |
|*Pseudomonas aeruginosa* | S | S | S | R | | S |
|*Pseudomonas aeruginosa* | S | S | S | R | | S |
|*Pseudomonas aeruginosa* | S | S | S | R | S | S |
A base R equivalent would be:
```r
library(AMR)
example_isolates$bacteria <- mo_fullname(example_isolates$mo)
example_isolates[which(mo_is_gram_negative() &
mo_is_intrinsic_resistant(ab = "cefotax")),
c("bacteria", aminoglycosides(), carbapenems())]
```
This base R code will work in any version of R since April 2013 (R-3.0). Moreover, this code works identically with the `data.table` package, only by starting with:
```r
example_isolates <- data.table::as.data.table(example_isolates)
```
#### Generating antibiograms
The `AMR` package supports generating traditional, combined, syndromic, and even weighted-incidence syndromic combination antibiograms (WISCA).
If used inside R Markdown or Quarto, the table will be printed in the right output format automatically (such as markdown, LaTeX, HTML, etc.).
```r
antibiogram(example_isolates,
antibiotics = c(aminoglycosides(), carbapenems()))
```
| Pathogen | Amikacin | Gentamicin | Imipenem | Kanamycin | Meropenem | Tobramycin |
|:------------------------|:----------------:|:---------------:|:----------------:|:----------------:|:----------------:|:----------------:|
| CoNS | 0% (0/43) | 86% (267/309) | 52% (25/48) | 0% (0/43) | 52% (25/48) | 22% (12/55) |
| *E. coli* | 100% (171/171) | 98% (451/460) | 100% (422/422) | | 100% (418/418) | 97% (450/462) |
| *E. faecalis* | 0% (0/39) | 0% (0/39) | 100% (38/38) | 0% (0/39) | | 0% (0/39) |
| *K. pneumoniae* | | 90% (52/58) | 100% (51/51) | | 100% (53/53) | 90% (52/58) |
| *P. aeruginosa* | | 100% (30/30) | | 0% (0/30) | | 100% (30/30) |
| *P. mirabilis* | | 94% (32/34) | 94% (30/32) | | | 94% (32/34) |
| *S. aureus* | | 99% (231/233) | | | | 98% (84/86) |
| *S. epidermidis* | 0% (0/44) | 79% (128/163) | | 0% (0/44) | | 51% (45/89) |
| *S. hominis* | | 92% (74/80) | | | | 85% (53/62) |
| *S. pneumoniae* | 0% (0/117) | 0% (0/117) | | 0% (0/117) | | 0% (0/117) |
In combination antibiograms, it is clear that combined antibiotics yield higher empiric coverage:
```r
antibiogram(example_isolates,
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
mo_transform = "gramstain")
```
| Pathogen | Piperacillin/tazobactam | Piperacillin/tazobactam + Gentamicin | Piperacillin/tazobactam + Tobramycin |
|:--------------|:-----------------------:|:-------------------------------------:|:------------------------------------:|
| Gram-negative | 88% (565/641) | 99% (681/691) | 98% (679/693) |
| Gram-positive | 86% (296/345) | 98% (1018/1044) | 95% (524/550) |
Like many other functions in this package, `antibiogram()` comes with support for 20 languages that are often detected automatically based on system language:
```r
antibiogram(example_isolates,
antibiotics = c("cipro", "tobra", "genta"), # any arbitrary name or code will work
mo_transform = "gramstain",
ab_transform = "name",
language = "uk") # Ukrainian
```
| Збудник | Гентаміцин | Тобраміцин | Ципрофлоксацин |
|:---------------|:--------------------:|:-------------------:|:------------------:|
| Грамнегативні | 96% (659/684) | 96% (658/686) | 91% (621/684) |
| Грампозитивні | 63% (740/1170) | 34% (228/665) | 77% (560/724) |
#### Calculating resistance per group
For a manual approach, you can use the `resistance` or `susceptibility()` function:
```r
example_isolates %>%
# group by ward:
group_by(ward) %>%
# calculate AMR using resistance() for gentamicin and tobramycin
# and get their 95% confidence intervals using sir_confidence_interval():
summarise(across(c(GEN, TOB),
list(total_R = resistance,
conf_int = function(x) sir_confidence_interval(x, collapse = "-"))))
```
|ward | GEN_total_R|GEN_conf_int | TOB_total_R|TOB_conf_int |
|:---------:|:----------:|:-----------:|:----------:|:-----------:|
|Clinical | 0.229 |0.205-0.254 | 0.315 |0.284-0.347 |
|ICU | 0.290 |0.253-0.330 | 0.400 |0.353-0.449 |
|Outpatient | 0.200 |0.131-0.285 | 0.368 |0.254-0.493 |
Or use [antibiotic class selectors](https://msberends.github.io/AMR/reference/antibiotic_class_selectors.html) to select a series of antibiotic columns:
```r
library(AMR)
library(dplyr)
out <- example_isolates %>%
# group by ward:
group_by(ward) %>%
# calculate AMR using resistance(), over all aminoglycosides and polymyxins:
summarise(across(c(aminoglycosides(), polymyxins()),
resistance))
out
```
| ward | GEN | TOB | AMK | KAN | COL |
|:-----------|------:|------:|------:|------:|------:|
| Clinical | 0.229 | 0.315 | 0.626 | 1 | 0.780 |
| ICU | 0.290 | 0.400 | 0.662 | 1 | 0.857 |
| Outpatient | 0.200 | 0.368 | 0.605 | | 0.889 |
```r
# transform the antibiotic columns to names:
out %>% set_ab_names()
```
| ward | gentamicin | tobramycin | amikacin | kanamycin | colistin |
|:-----------|-----------:|-----------:|----------|----------:|----------:|
| Clinical | 0.229 | 0.315 | 0.626 | 1 | 0.780 |
| ICU | 0.290 | 0.400 | 0.662 | 1 | 0.857 |
| Outpatient | 0.200 | 0.368 | 0.605 | | 0.889 |
```r
# transform the antibiotic column to ATC codes:
out %>% set_ab_names(property = "atc")
```
| ward | J01GB03 | J01GB01 | J01GB06 | J01GB04 | J01XB01 |
|:-----------|-----------:|-----------:|----------|----------:|----------:|
| Clinical | 0.229 | 0.315 | 0.626 | 1 | 0.780 |
| ICU | 0.290 | 0.400 | 0.662 | 1 | 0.857 |
| Outpatient | 0.200 | 0.368 | 0.605 | | 0.889 |
### What else can you do with this package?
This package was intended as a comprehensive toolbox for integrated AMR data analysis. This package can be used for:
* Reference for the taxonomy of microorganisms, since the package contains all microbial (sub)species from the List of Prokaryotic names with Standing in Nomenclature ([LPSN]((https://lpsn.dsmz.de))) and the Global Biodiversity Information Facility ([GBIF](https://www.gbif.org)) ([manual](./reference/mo_property.html))
* Interpreting raw MIC and disk diffusion values, based on any CLSI or EUCAST guideline ([manual](./reference/as.sir.html))
* Retrieving antimicrobial drug names, doses and forms of administration from clinical health care records ([manual](./reference/ab_from_text.html))
* Determining first isolates to be used for AMR data analysis ([manual](./reference/first_isolate.html))
* Calculating antimicrobial resistance ([tutorial](./articles/AMR.html))
* Determining multi-drug resistance (MDR) / multi-drug resistant organisms (MDRO) ([tutorial](./articles/MDR.html))
* Calculating (empirical) susceptibility of both mono therapy and combination therapies ([tutorial](./articles/AMR.html))
* Predicting future antimicrobial resistance using regression models ([tutorial](./articles/resistance_predict.html))
* Getting properties for any microorganism (like Gram stain, species, genus or family) ([manual](./reference/mo_property.html))
* Getting properties for any antibiotic (like name, code of EARS-Net/ATC/LOINC/PubChem, defined daily dose or trade name) ([manual](./reference/ab_property.html))
* Plotting antimicrobial resistance ([tutorial](./articles/AMR.html))
* Applying EUCAST expert rules ([manual](./reference/eucast_rules.html))
* Getting SNOMED codes of a microorganism, or getting properties of a microorganism based on a SNOMED code ([manual](./reference/mo_property.html))
* Getting LOINC codes of an antibiotic, or getting properties of an antibiotic based on a LOINC code ([manual](./reference/ab_property.html))
* Machine reading the EUCAST and CLSI guidelines from 2011-2021 to translate MIC values and disk diffusion diameters to SIR ([link](./articles/datasets.html))
* Principal component analysis for AMR ([tutorial](./articles/PCA.html))
### Get this package
#### Latest official version
[![CRAN](https://www.r-pkg.org/badges/version-ago/AMR)](https://cran.r-project.org/package=AMR)
[![CRANlogs](https://cranlogs.r-pkg.org/badges/grand-total/AMR)](https://cran.r-project.org/package=AMR)
This package is available [here on the official R network (CRAN)](https://cran.r-project.org/package=AMR). Install this package in R from CRAN by using the command:
```r
install.packages("AMR")
```
It will be downloaded and installed automatically. For RStudio, click on the menu *Tools* > *Install Packages...* and then type in "AMR" and press <kbd>Install</kbd>.
**Note:** Not all functions on this website may be available in this latest release. To use all functions and data sets mentioned on this website, install the latest development version.
#### Latest development version
[![check-old](https://github.com/msberends/AMR/actions/workflows/check-old.yaml/badge.svg?branch=main)](https://github.com/msberends/AMR/actions/workflows/check-old.yaml?query=branch%3Amain)
[![check-recent](https://github.com/msberends/AMR/actions/workflows/check-recent.yaml/badge.svg?branch=main)](https://github.com/msberends/AMR/actions/workflows/check-recent.yaml?query=branch%3Amain)
[![CodeFactor](https://www.codefactor.io/repository/github/msberends/amr/badge)](https://www.codefactor.io/repository/github/msberends/amr)
[![Codecov](https://codecov.io/gh/msberends/AMR/branch/main/graph/badge.svg)](https://codecov.io/gh/msberends/AMR?branch=main)
Please read our [Developer Guideline here](https://github.com/msberends/AMR/wiki/Developer-Guideline).
The latest and unpublished development version can be installed from GitHub in two ways:
1. Manually, using:
```r
install.packages("remotes") # if you haven't already
remotes::install_github("msberends/AMR")
```
2. Automatically, using the [rOpenSci R-universe platform](https://ropensci.org/r-universe/), by adding [our R-universe address](https://msberends.r-universe.dev) to your list of repositories ('repos'):
```r
options(repos = c(getOption("repos"),
msberends = "https://msberends.r-universe.dev"))
```
After this, you can install and update this `AMR` package like any official release (e.g., using `install.packages("AMR")` or in RStudio via *Tools* > *Check for Package Updates...*).
### Get started
To find out how to conduct AMR data analysis, please [continue reading here to get started](./articles/AMR.html) or click a link in the ['How to' menu](https://msberends.github.io/AMR/articles/).
### Partners
The development of this package is part of, related to, or made possible by the following non-profit organisations and initiatives:
<div align="center">
<a href="https://www.rug.nl" title="University of Groningen"><img src="./logo_rug.svg" style="max-width: 200px;"></a>
<a href="https://www.umcg.nl" title="University Medical Center Groningen"><img src="./logo_umcg.svg" style="max-width: 200px;"></a>
<a href="https://www.certe.nl" title="Certe Medical Diagnostics and Advice Foundation"><img src="./logo_certe.svg" style="max-width: 200px;"></a>
<a href="https://www.deutschland-nederland.eu" title="EurHealth-1-Health"><img src="./logo_eh1h.png" style="max-width: 200px;"></a>
<a href="https://www.deutschland-nederland.eu" title="INTERREG"><img src="./logo_interreg.png" style="max-width: 200px;"></a>
</div>
### Copyright
This R package is free, open-source software and licensed under the [GNU General Public License v2.0 (GPL-2)](./LICENSE-text.html). In a nutshell, this means that this package:
- May be used for commercial purposes
- May be used for private purposes
- May **not** be used for patent purposes
- May be modified, although:
- Modifications **must** be released under the same license when distributing the package
- Changes made to the code **must** be documented
- May be distributed, although:
- Source code **must** be made available when the package is distributed
- A copy of the license and copyright notice **must** be included with the package.
- Comes with a LIMITATION of liability
- Comes with NO warranty
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/AMR-options.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aa_options.R
\name{AMR-options}
\alias{AMR-options}
\title{Options for the AMR package}
\description{
This is an overview of all the package-specific \code{\link[=options]{options()}} you can set in the \code{AMR} package.
}
\section{Options}{
\itemize{
\item \code{AMR_antibiogram_formatting_type} \cr A \link{numeric} (1-12) to use in \code{\link[=antibiogram]{antibiogram()}}, to indicate which formatting type to use.
\item \code{AMR_breakpoint_type} \cr A \link{character} to use in \code{\link[=as.sir]{as.sir()}}, to indicate which breakpoint type to use. This must be either "ECOFF", "animal", or "human".
\item \code{AMR_cleaning_regex} \cr A \link[base:regex]{regular expression} (case-insensitive) to use in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions, to clean the user input. The default is the outcome of \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}, which removes texts between brackets and texts such as "species" and "serovar".
\item \code{AMR_custom_ab} \cr A file location to an RDS file, to use custom antimicrobial drugs with this package. This is explained in \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}}.
\item \code{AMR_custom_mo} \cr A file location to an RDS file, to use custom microorganisms with this package. This is explained in \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}}.
\item \code{AMR_eucastrules} \cr A \link{character} to set the default types of rules for \code{\link[=eucast_rules]{eucast_rules()}} function, must be one or more of: \code{"breakpoints"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expert")}.
\item \code{AMR_guideline} \cr A \link{character} to set the default guideline for interpreting MIC values and disk diffusion diameters with \code{\link[=as.sir]{as.sir()}}. Can be only the guideline name (e.g., \code{"CLSI"}) or the name with a year (e.g. \code{"CLSI 2019"}). The default to the latest implemented EUCAST guideline, currently \code{"EUCAST 2024"}. Supported guideline are currently EUCAST (2011-2024) and CLSI (2011-2024).
\item \code{AMR_ignore_pattern} \cr A \link[base:regex]{regular expression} to ignore (i.e., make \code{NA}) any match given in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions.
\item \code{AMR_include_PKPD} \cr A \link{logical} to use in \code{\link[=as.sir]{as.sir()}}, to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}.
\item \code{AMR_include_screening} \cr A \link{logical} to use in \code{\link[=as.sir]{as.sir()}}, to indicate that clinical breakpoints for screening are allowed - the default is \code{FALSE}.
\item \code{AMR_keep_synonyms} \cr A \link{logical} to use in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions, to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}.
\item \code{AMR_locale} \cr A \link{character} to set the language for the \code{AMR} package, can be one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), or Ukrainian (uk). The default is the current system language (if supported, English otherwise).
\item \code{AMR_mo_source} \cr A file location for a manual code list to be used in \code{\link[=as.mo]{as.mo()}} and all \code{\link[=mo_property]{mo_*}} functions. This is explained in \code{\link[=set_mo_source]{set_mo_source()}}.
}
}
\section{Saving Settings Between Sessions}{
Settings in \R are not saved globally and are thus lost when \R is exited. You can save your options to your own \code{.Rprofile} file, which is a user-specific file. You can edit it using:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{ utils::file.edit("~/.Rprofile")
}\if{html}{\out{</div>}}
In this file, you can set options such as...
\if{html}{\out{<div class="sourceCode r">}}\preformatted{ options(AMR_locale = "pt")
options(AMR_include_PKPD = TRUE)
}\if{html}{\out{</div>}}
...to add Portuguese language support of antibiotics, and allow PK/PD rules when interpreting MIC values with \code{\link[=as.sir]{as.sir()}}.
\subsection{Share Options Within Team}{
For a more global approach, e.g. within a (data) team, save an options file to a remote file location, such as a shared network drive, and have each user read in this file automatically at start-up. This would work in this way:
\enumerate{
\item Save a plain text file to e.g. "X:/team_folder/R_options.R" and fill it with preferred settings.
\item For each user, open the \code{.Rprofile} file using \code{utils::file.edit("~/.Rprofile")} and put in there:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{ source("X:/team_folder/R_options.R")
}\if{html}{\out{</div>}}
\item Reload R/RStudio and check the settings with \code{\link[=getOption]{getOption()}}, e.g. \code{getOption("AMR_locale")} if you have set that value.
}
Now the team settings are configured in only one place, and can be maintained there.
}
}
\keyword{internal}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/AMR.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aa_amr-package.R
\docType{package}
\name{AMR}
\alias{AMR-package}
\alias{AMR}
\title{The \code{AMR} Package}
\source{
To cite AMR in publications use:
Berends MS, Luz CF, Friedrich AW, Sinha BNM, Albers CJ, Glasner C (2022). "AMR: An R Package for Working with Antimicrobial Resistance Data." \emph{Journal of Statistical Software}, \emph{104}(3), 1-31. \doi{10.18637/jss.v104.i03}
A BibTeX entry for LaTeX users is:
\preformatted{
@Article{,
title = {{AMR}: An {R} Package for Working with Antimicrobial Resistance Data},
author = {Matthijs S. Berends and Christian F. Luz and Alexander W. Friedrich and Bhanu N. M. Sinha and Casper J. Albers and Corinna Glasner},
journal = {Journal of Statistical Software},
year = {2022},
volume = {104},
number = {3},
pages = {1--31},
doi = {10.18637/jss.v104.i03},
}
}
}
\description{
Welcome to the \code{AMR} package.
The \code{AMR} package is a \href{https://msberends.github.io/AMR/#copyright}{free and open-source} R package with \href{https://en.wikipedia.org/wiki/Dependency_hell}{zero dependencies} to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. \strong{Our aim is to provide a standard} for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. \href{https://msberends.github.io/AMR/authors.html}{Many different researchers} from around the globe are continually helping us to make this a successful and durable project!
This work was published in the Journal of Statistical Software (Volume 104(3); \doi{10.18637/jss.v104.i03}) and formed the basis of two PhD theses (\doi{10.33612/diss.177417131} and \doi{10.33612/diss.192486375}).
After installing this package, R knows \href{https://msberends.github.io/AMR/reference/microorganisms.html}{\strong{~79 000 microorganisms}} (updated June 2024) and all \href{https://msberends.github.io/AMR/reference/antibiotics.html}{\strong{~600 antibiotic, antimycotic and antiviral drugs}} by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral clinical breakpoint guidelines from CLSI and EUCAST are included, even with epidemiological cut-off (ECOFF) values. It supports and can read any data format, including WHONET data. This package works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). \strong{It was designed to work in any setting, including those with very limited resources}. It was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the public \href{https://www.rug.nl}{University of Groningen}, in collaboration with non-profit organisations \href{https://www.certe.nl}{Certe Medical Diagnostics and Advice Foundation} and \href{https://www.umcg.nl}{University Medical Center Groningen}.
The \code{AMR} package is available in English, Chinese, Czech, Danish, Dutch, Finnish, French, German, Greek, Italian, Japanese, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish, and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages.
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\seealso{
Useful links:
\itemize{
\item \url{https://msberends.github.io/AMR/}
\item \url{https://github.com/msberends/AMR}
\item Report bugs at \url{https://github.com/msberends/AMR/issues}
}
}
\author{
\strong{Maintainer}: Matthijs S. Berends \email{m.s.berends@umcg.nl} (\href{https://orcid.org/0000-0001-7620-1800}{ORCID})
Authors:
\itemize{
\item Dennis Souverein (\href{https://orcid.org/0000-0003-0455-0336}{ORCID}) [contributor]
\item Erwin E. A. Hassing [contributor]
}
Other contributors:
\itemize{
\item Andrew P. Norgan (\href{https://orcid.org/0000-0002-2955-2066}{ORCID}) [contributor]
\item Anita Williams (\href{https://orcid.org/0000-0002-5295-8451}{ORCID}) [contributor]
\item Annick Lenglet (\href{https://orcid.org/0000-0003-2013-8405}{ORCID}) [contributor]
\item Anthony Underwood (\href{https://orcid.org/0000-0002-8547-4277}{ORCID}) [contributor]
\item Anton Mymrikov [contributor]
\item Bart C. Meijer [contributor]
\item Christian F. Luz (\href{https://orcid.org/0000-0001-5809-5995}{ORCID}) [contributor]
\item Dmytro Mykhailenko [contributor]
\item Eric H. L. C. M. Hazenberg [contributor]
\item Gwen Knight (\href{https://orcid.org/0000-0002-7263-9896}{ORCID}) [contributor]
\item Jason Stull (\href{https://orcid.org/0000-0002-9028-8153}{ORCID}) [contributor]
\item Javier Sanchez (\href{https://orcid.org/0000-0003-2605-8094}{ORCID}) [contributor]
\item Jonas Salm [contributor]
\item Judith M. Fonville [contributor]
\item Larisse Bolton (\href{https://orcid.org/0000-0001-7879-2173}{ORCID}) [contributor]
\item Matthew Saab [contributor]
\item Peter Dutey-Magni (\href{https://orcid.org/0000-0002-8942-9836}{ORCID}) [contributor]
\item Rogier P. Schade [contributor]
\item Sofia Ny (\href{https://orcid.org/0000-0002-2017-1363}{ORCID}) [contributor]
\item Alex W. Friedrich (\href{https://orcid.org/0000-0003-4881-038X}{ORCID}) [thesis advisor]
\item Bhanu N. M. Sinha (\href{https://orcid.org/0000-0003-1634-0010}{ORCID}) [thesis advisor]
\item Casper J. Albers (\href{https://orcid.org/0000-0002-9213-6743}{ORCID}) [thesis advisor]
\item Corinna Glasner (\href{https://orcid.org/0000-0003-1241-1328}{ORCID}) [thesis advisor]
}
}
\keyword{internal}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/WHOCC.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/whocc.R
\name{WHOCC}
\alias{WHOCC}
\title{WHOCC: WHO Collaborating Centre for Drug Statistics Methodology}
\description{
All antimicrobial drugs and their official names, ATC codes, ATC groups and defined daily dose (DDD) are included in this package, using the WHO Collaborating Centre for Drug Statistics Methodology.
}
\section{WHOCC}{
This package contains \strong{all ~550 antibiotic, antimycotic and antiviral drugs} and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, \url{https://atcddd.fhi.no}) and the Pharmaceuticals Community Register of the European Commission (\url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}).
These have become the gold standard for international drug utilisation monitoring and research.
The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.
\strong{NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package.} See \url{https://atcddd.fhi.no/copyright_disclaimer/.}
}
\examples{
as.ab("meropenem")
ab_name("J01DH02")
ab_tradenames("flucloxacillin")
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/WHONET.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{WHONET}
\alias{WHONET}
\title{Data Set with 500 Isolates - WHONET Example}
\format{
A \link[tibble:tibble]{tibble} with 500 observations and 53 variables:
\itemize{
\item \verb{Identification number}\cr ID of the sample
\item \verb{Specimen number}\cr ID of the specimen
\item \code{Organism}\cr Name of the microorganism. Before analysis, you should transform this to a valid microbial class, using \code{\link[=as.mo]{as.mo()}}.
\item \code{Country}\cr Country of origin
\item \code{Laboratory}\cr Name of laboratory
\item \verb{Last name}\cr Fictitious last name of patient
\item \verb{First name}\cr Fictitious initial of patient
\item \code{Sex}\cr Fictitious gender of patient
\item \code{Age}\cr Fictitious age of patient
\item \verb{Age category}\cr Age group, can also be looked up using \code{\link[=age_groups]{age_groups()}}
\item \verb{Date of admission}\cr \link{Date} of hospital admission
\item \verb{Specimen date}\cr \link{Date} when specimen was received at laboratory
\item \verb{Specimen type}\cr Specimen type or group
\item \verb{Specimen type (Numeric)}\cr Translation of \code{"Specimen type"}
\item \code{Reason}\cr Reason of request with Differential Diagnosis
\item \verb{Isolate number}\cr ID of isolate
\item \verb{Organism type}\cr Type of microorganism, can also be looked up using \code{\link[=mo_type]{mo_type()}}
\item \code{Serotype}\cr Serotype of microorganism
\item \code{Beta-lactamase}\cr Microorganism produces beta-lactamase?
\item \code{ESBL}\cr Microorganism produces extended spectrum beta-lactamase?
\item \code{Carbapenemase}\cr Microorganism produces carbapenemase?
\item \verb{MRSA screening test}\cr Microorganism is possible MRSA?
\item \verb{Inducible clindamycin resistance}\cr Clindamycin can be induced?
\item \code{Comment}\cr Other comments
\item \verb{Date of data entry}\cr \link{Date} this data was entered in WHONET
\item \code{AMP_ND10:CIP_EE}\cr 28 different antibiotics. You can lookup the abbreviations in the \link{antibiotics} data set, or use e.g. \code{\link[=ab_name]{ab_name("AMP")}} to get the official name immediately. Before analysis, you should transform this to a valid antibiotic class, using \code{\link[=as.sir]{as.sir()}}.
}
}
\usage{
WHONET
}
\description{
This example data set has the exact same structure as an export file from WHONET. Such files can be used with this package, as this example data set shows. The antibiotic results are from our \link{example_isolates} data set. All patient names were created using online surname generators and are only in place for practice purposes.
}
\details{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
WHONET
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/ab_from_text.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ab_from_text.R
\name{ab_from_text}
\alias{ab_from_text}
\title{Retrieve Antimicrobial Drug Names and Doses from Clinical Text}
\usage{
ab_from_text(
text,
type = c("drug", "dose", "administration"),
collapse = NULL,
translate_ab = FALSE,
thorough_search = NULL,
info = interactive(),
...
)
}
\arguments{
\item{text}{text to analyse}
\item{type}{type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}}
\item{collapse}{a \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}}
\item{translate_ab}{if \code{type = "drug"}: a column name of the \link{antibiotics} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".}
\item{thorough_search}{a \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.}
\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode}
\item{...}{arguments passed on to \code{\link[=as.ab]{as.ab()}}}
}
\value{
A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL}
}
\description{
Use this function on e.g. clinical texts from health care records. It returns a \link{list} with all antimicrobial drugs, doses and forms of administration found in the texts.
}
\details{
This function is also internally used by \code{\link[=as.ab]{as.ab()}}, although it then only searches for the first drug name and will throw a note if more drug names could have been returned. Note: the \code{\link[=as.ab]{as.ab()}} function may use very long regular expression to match brand names of antimicrobial drugs. This may fail on some systems.
\subsection{Argument \code{type}}{
At default, the function will search for antimicrobial drug names. All text elements will be searched for official names, ATC codes and brand names. As it uses \code{\link[=as.ab]{as.ab()}} internally, it will correct for misspelling.
With \code{type = "dose"} (or similar, like "dosing", "doses"), all text elements will be searched for \link{numeric} values that are higher than 100 and do not resemble years. The output will be \link{numeric}. It supports any unit (g, mg, IE, etc.) and multiple values in one clinical text, see \emph{Examples}.
With \code{type = "administration"} (or abbreviations, like "admin", "adm"), all text elements will be searched for a form of drug administration. It supports the following forms (including common abbreviations): buccal, implant, inhalation, instillation, intravenous, nasal, oral, parenteral, rectal, sublingual, transdermal and vaginal. Abbreviations for oral (such as 'po', 'per os') will become "oral", all values for intravenous (such as 'iv', 'intraven') will become "iv". It supports multiple values in one clinical text, see \emph{Examples}.
}
\subsection{Argument \code{collapse}}{
Without using \code{collapse}, this function will return a \link{list}. This can be convenient to use e.g. inside a \code{mutate()}):\cr
\code{df \%>\% mutate(abx = ab_from_text(clinical_text))}
The returned AB codes can be transformed to official names, groups, etc. with all \code{\link[=ab_property]{ab_*}} functions such as \code{\link[=ab_name]{ab_name()}} and \code{\link[=ab_group]{ab_group()}}, or by using the \code{translate_ab} argument.
With using \code{collapse}, this function will return a \link{character}:\cr
\code{df \%>\% mutate(abx = ab_from_text(clinical_text, collapse = "|"))}
}
}
\examples{
# mind the bad spelling of amoxicillin in this line,
# straight from a true health care record:
ab_from_text("28/03/2020 regular amoxicilliin 500mg po tid")
ab_from_text("500 mg amoxi po and 400mg cipro iv")
ab_from_text("500 mg amoxi po and 400mg cipro iv", type = "dose")
ab_from_text("500 mg amoxi po and 400mg cipro iv", type = "admin")
ab_from_text("500 mg amoxi po and 400mg cipro iv", collapse = ", ")
\donttest{
# if you want to know which antibiotic groups were administered, do e.g.:
abx <- ab_from_text("500 mg amoxi po and 400mg cipro iv")
ab_group(abx[[1]])
if (require("dplyr")) {
tibble(clinical_text = c(
"given 400mg cipro and 500 mg amox",
"started on doxy iv today"
)) \%>\%
mutate(
abx_codes = ab_from_text(clinical_text),
abx_doses = ab_from_text(clinical_text, type = "doses"),
abx_admin = ab_from_text(clinical_text, type = "admin"),
abx_coll = ab_from_text(clinical_text, collapse = "|"),
abx_coll_names = ab_from_text(clinical_text,
collapse = "|",
translate_ab = "name"
),
abx_coll_doses = ab_from_text(clinical_text,
type = "doses",
collapse = "|"
),
abx_coll_admin = ab_from_text(clinical_text,
type = "admin",
collapse = "|"
)
)
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/ab_property.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ab_property.R
\name{ab_property}
\alias{ab_property}
\alias{ab_name}
\alias{ab_cid}
\alias{ab_synonyms}
\alias{ab_tradenames}
\alias{ab_group}
\alias{ab_atc}
\alias{ATC}
\alias{ab_atc_group1}
\alias{ab_atc_group2}
\alias{ab_loinc}
\alias{ab_ddd}
\alias{ab_ddd_units}
\alias{ab_info}
\alias{ab_url}
\alias{set_ab_names}
\title{Get Properties of an Antibiotic}
\usage{
ab_name(x, language = get_AMR_locale(), tolower = FALSE, ...)
ab_cid(x, ...)
ab_synonyms(x, ...)
ab_tradenames(x, ...)
ab_group(x, language = get_AMR_locale(), ...)
ab_atc(x, only_first = FALSE, ...)
ab_atc_group1(x, language = get_AMR_locale(), ...)
ab_atc_group2(x, language = get_AMR_locale(), ...)
ab_loinc(x, ...)
ab_ddd(x, administration = "oral", ...)
ab_ddd_units(x, administration = "oral", ...)
ab_info(x, language = get_AMR_locale(), ...)
ab_url(x, open = FALSE, ...)
ab_property(x, property = "name", language = get_AMR_locale(), ...)
set_ab_names(
data,
...,
property = "name",
language = get_AMR_locale(),
snake_case = NULL
)
}
\arguments{
\item{x}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}}
\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{tolower}{a \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}. This will lead to e.g. "polymyxin B" and not "polymyxin b".}
\item{...}{in case of \code{\link[=set_ab_names]{set_ab_names()}} and \code{data} is a \link{data.frame}: columns to select (supports tidy selection such as \code{column1:column4}), otherwise other arguments passed on to \code{\link[=as.ab]{as.ab()}}}
\item{only_first}{a \link{logical} to indicate whether only the first ATC code must be returned, with giving preference to J0-codes (i.e., the antimicrobial drug group)}
\item{administration}{way of administration, either \code{"oral"} or \code{"iv"}}
\item{open}{browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}}
\item{property}{one of the column names of one of the \link{antibiotics} data set: \code{vector_or(colnames(antibiotics), sort = FALSE)}.}
\item{data}{a \link{data.frame} of which the columns need to be renamed, or a \link{character} vector of column names}
\item{snake_case}{a \link{logical} to indicate whether the names should be in so-called \href{https://en.wikipedia.org/wiki/Snake_case}{snake case}: in lower case and all spaces/slashes replaced with an underscore (\verb{_})}
}
\value{
\itemize{
\item An \link{integer} in case of \code{\link[=ab_cid]{ab_cid()}}
\item A named \link{list} in case of \code{\link[=ab_info]{ab_info()}} and multiple \code{\link[=ab_atc]{ab_atc()}}/\code{\link[=ab_synonyms]{ab_synonyms()}}/\code{\link[=ab_tradenames]{ab_tradenames()}}
\item A \link{double} in case of \code{\link[=ab_ddd]{ab_ddd()}}
\item A \link{data.frame} in case of \code{\link[=set_ab_names]{set_ab_names()}}
\item A \link{character} in all other cases
}
}
\description{
Use these functions to return a specific property of an antibiotic from the \link{antibiotics} data set. All input values will be evaluated internally with \code{\link[=as.ab]{as.ab()}}.
}
\details{
All output \link[=translate]{will be translated} where possible.
The function \code{\link[=ab_url]{ab_url()}} will return the direct URL to the official WHO website. A warning will be returned if the required ATC code is not available.
The function \code{\link[=set_ab_names]{set_ab_names()}} is a special column renaming function for \link{data.frame}s. It renames columns names that resemble antimicrobial drugs. It always makes sure that the new column names are unique. If \code{property = "atc"} is set, preference is given to ATC codes from the J-group.
}
\section{Source}{
World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: \url{https://atcddd.fhi.no/atc_ddd_index/}
European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: \url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
# all properties:
ab_name("AMX")
ab_atc("AMX")
ab_cid("AMX")
ab_synonyms("AMX")
ab_tradenames("AMX")
ab_group("AMX")
ab_atc_group1("AMX")
ab_atc_group2("AMX")
ab_url("AMX")
# smart lowercase transformation
ab_name(x = c("AMC", "PLB"))
ab_name(x = c("AMC", "PLB"), tolower = TRUE)
# defined daily doses (DDD)
ab_ddd("AMX", "oral")
ab_ddd_units("AMX", "oral")
ab_ddd("AMX", "iv")
ab_ddd_units("AMX", "iv")
ab_info("AMX") # all properties as a list
# all ab_* functions use as.ab() internally, so you can go from 'any' to 'any':
ab_atc("AMP")
ab_group("J01CA01")
ab_loinc("ampicillin")
ab_name("21066-6")
ab_name(6249)
ab_name("J01CA01")
# spelling from different languages and dyslexia are no problem
ab_atc("ceftriaxon")
ab_atc("cephtriaxone")
ab_atc("cephthriaxone")
ab_atc("seephthriaaksone")
# use set_ab_names() for renaming columns
colnames(example_isolates)
colnames(set_ab_names(example_isolates))
colnames(set_ab_names(example_isolates, NIT:VAN))
\donttest{
if (require("dplyr")) {
example_isolates \%>\%
set_ab_names()
# this does the same:
example_isolates \%>\%
rename_with(set_ab_names)
# set_ab_names() works with any AB property:
example_isolates \%>\%
set_ab_names(property = "atc")
example_isolates \%>\%
set_ab_names(where(is.sir)) \%>\%
colnames()
example_isolates \%>\%
set_ab_names(NIT:VAN) \%>\%
colnames()
}
}
}
\seealso{
\link{antibiotics}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/add_custom_antimicrobials.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/custom_antimicrobials.R
\name{add_custom_antimicrobials}
\alias{add_custom_antimicrobials}
\alias{clear_custom_antimicrobials}
\title{Add Custom Antimicrobials}
\usage{
add_custom_antimicrobials(x)
clear_custom_antimicrobials()
}
\arguments{
\item{x}{a \link{data.frame} resembling the \link{antibiotics} data set, at least containing columns "ab" and "name"}
}
\description{
With \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} you can add your own custom antimicrobial drug names and codes.
}
\details{
\strong{Important:} Due to how \R works, the \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} function has to be run in every \R session - added antimicrobials are not stored between sessions and are thus lost when \R is exited.
There are two ways to circumvent this and automate the process of adding antimicrobials:
\strong{Method 1:} Using the package option \code{\link[=AMR-options]{AMR_custom_ab}}, which is the preferred method. To use this method:
\enumerate{
\item Create a data set in the structure of the \link{antibiotics} data set (containing at the very least columns "ab" and "name") and save it with \code{\link[=saveRDS]{saveRDS()}} to a location of choice, e.g. \code{"~/my_custom_ab.rds"}, or any remote location.
\item Set the file location to the package option \code{\link[=AMR-options]{AMR_custom_ab}}: \code{options(AMR_custom_ab = "~/my_custom_ab.rds")}. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the \code{.Rprofile} file so that it will be loaded on start-up of \R. To do this, open the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}, add this text and save the file:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Add custom antimicrobial codes:
options(AMR_custom_ab = "~/my_custom_ab.rds")
}\if{html}{\out{</div>}}
Upon package load, this file will be loaded and run through the \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} function.
}
\strong{Method 2:} Loading the antimicrobial additions directly from your \code{.Rprofile} file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method:
\enumerate{
\item Edit the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}.
\item Add a text like below and save the file:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{ # Add custom antibiotic drug codes:
AMR::add_custom_antimicrobials(
data.frame(ab = "TESTAB",
name = "Test Antibiotic",
group = "Test Group")
)
}\if{html}{\out{</div>}}
}
Use \code{\link[=clear_custom_antimicrobials]{clear_custom_antimicrobials()}} to clear the previously added antimicrobials.
}
\examples{
\donttest{
# returns NA and throws a warning (which is suppressed here):
suppressWarnings(
as.ab("testab")
)
# now add a custom entry - it will be considered by as.ab() and
# all ab_*() functions
add_custom_antimicrobials(
data.frame(
ab = "TESTAB",
name = "Test Antibiotic",
# you can add any property present in the
# 'antibiotics' data set, such as 'group':
group = "Test Group"
)
)
# "testab" is now a new antibiotic:
as.ab("testab")
ab_name("testab")
ab_group("testab")
ab_info("testab")
# Add Co-fluampicil, which is one of the many J01CR50 codes, see
# https://atcddd.fhi.no/ddd/list_of_ddds_combined_products/
add_custom_antimicrobials(
data.frame(
ab = "COFLU",
name = "Co-fluampicil",
atc = "J01CR50",
group = "Beta-lactams/penicillins"
)
)
ab_atc("Co-fluampicil")
ab_name("J01CR50")
# even antibiotic selectors work
x <- data.frame(
random_column = "some value",
coflu = as.sir("S"),
ampicillin = as.sir("R")
)
x
x[, betalactams()]
}
}
\seealso{
\code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} to add custom microorganisms.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/add_custom_microorganisms.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/custom_microorganisms.R
\name{add_custom_microorganisms}
\alias{add_custom_microorganisms}
\alias{clear_custom_microorganisms}
\title{Add Custom Microorganisms}
\usage{
add_custom_microorganisms(x)
clear_custom_microorganisms()
}
\arguments{
\item{x}{a \link{data.frame} resembling the \link{microorganisms} data set, at least containing column "genus" (case-insensitive)}
}
\description{
With \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} you can add your own custom microorganisms, such the non-taxonomic outcome of laboratory analysis.
}
\details{
This function will fill in missing taxonomy for you, if specific taxonomic columns are missing, see \emph{Examples}.
\strong{Important:} Due to how \R works, the \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} function has to be run in every \R session - added microorganisms are not stored between sessions and are thus lost when \R is exited.
There are two ways to circumvent this and automate the process of adding microorganisms:
\strong{Method 1:} Using the package option \code{\link[=AMR-options]{AMR_custom_mo}}, which is the preferred method. To use this method:
\enumerate{
\item Create a data set in the structure of the \link{microorganisms} data set (containing at the very least column "genus") and save it with \code{\link[=saveRDS]{saveRDS()}} to a location of choice, e.g. \code{"~/my_custom_mo.rds"}, or any remote location.
\item Set the file location to the package option \code{\link[=AMR-options]{AMR_custom_mo}}: \code{options(AMR_custom_mo = "~/my_custom_mo.rds")}. This can even be a remote file location, such as an https URL. Since options are not saved between \R sessions, it is best to save this option to the \code{.Rprofile} file so that it will be loaded on start-up of \R. To do this, open the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}, add this text and save the file:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Add custom microorganism codes:
options(AMR_custom_mo = "~/my_custom_mo.rds")
}\if{html}{\out{</div>}}
Upon package load, this file will be loaded and run through the \code{\link[=add_custom_microorganisms]{add_custom_microorganisms()}} function.
}
\strong{Method 2:} Loading the microorganism directly from your \code{.Rprofile} file. Note that the definitions will be stored in a user-specific \R file, which is a suboptimal workflow. To use this method:
\enumerate{
\item Edit the \code{.Rprofile} file using e.g. \code{utils::file.edit("~/.Rprofile")}.
\item Add a text like below and save the file:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{ # Add custom antibiotic drug codes:
AMR::add_custom_microorganisms(
data.frame(genus = "Enterobacter",
species = "asburiae/cloacae")
)
}\if{html}{\out{</div>}}
}
Use \code{\link[=clear_custom_microorganisms]{clear_custom_microorganisms()}} to clear the previously added microorganisms.
}
\examples{
\donttest{
# a combination of species is not formal taxonomy, so
# this will result in "Enterobacter cloacae cloacae",
# since it resembles the input best:
mo_name("Enterobacter asburiae/cloacae")
# now add a custom entry - it will be considered by as.mo() and
# all mo_*() functions
add_custom_microorganisms(
data.frame(
genus = "Enterobacter",
species = "asburiae/cloacae"
)
)
# E. asburiae/cloacae is now a new microorganism:
mo_name("Enterobacter asburiae/cloacae")
# its code:
as.mo("Enterobacter asburiae/cloacae")
# all internal algorithms will work as well:
mo_name("Ent asburia cloacae")
# and even the taxonomy was added based on the genus!
mo_family("E. asburiae/cloacae")
mo_gramstain("Enterobacter asburiae/cloacae")
mo_info("Enterobacter asburiae/cloacae")
# the function tries to be forgiving:
add_custom_microorganisms(
data.frame(
GENUS = "BACTEROIDES / PARABACTEROIDES SLASHLINE",
SPECIES = "SPECIES"
)
)
mo_name("BACTEROIDES / PARABACTEROIDES")
mo_rank("BACTEROIDES / PARABACTEROIDES")
# taxonomy still works, even though a slashline genus was given as input:
mo_family("Bacteroides/Parabacteroides")
# for groups and complexes, set them as species or subspecies:
add_custom_microorganisms(
data.frame(
genus = "Citrobacter",
species = c("freundii", "braakii complex"),
subspecies = c("complex", "")
)
)
mo_name(c("C. freundii complex", "C. braakii complex"))
mo_species(c("C. freundii complex", "C. braakii complex"))
mo_gramstain(c("C. freundii complex", "C. braakii complex"))
}
}
\seealso{
\code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}} to add custom antimicrobials.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/age.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/age.R
\name{age}
\alias{age}
\title{Age in Years of Individuals}
\usage{
age(x, reference = Sys.Date(), exact = FALSE, na.rm = FALSE, ...)
}
\arguments{
\item{x}{date(s), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}}
\item{reference}{reference date(s) (default is today), \link{character} (vectors) will be coerced with \code{\link[=as.POSIXlt]{as.POSIXlt()}}}
\item{exact}{a \link{logical} to indicate whether age calculation should be exact, i.e. with decimals. It divides the number of days of \href{https://en.wikipedia.org/wiki/Year-to-date}{year-to-date} (YTD) of \code{x} by the number of days in the year of \code{reference} (either 365 or 366).}
\item{na.rm}{a \link{logical} to indicate whether missing values should be removed}
\item{...}{arguments passed on to \code{\link[=as.POSIXlt]{as.POSIXlt()}}, such as \code{origin}}
}
\value{
An \link{integer} (no decimals) if \code{exact = FALSE}, a \link{double} (with decimals) otherwise
}
\description{
Calculates age in years based on a reference date, which is the system date at default.
}
\details{
Ages below 0 will be returned as \code{NA} with a warning. Ages above 120 will only give a warning.
This function vectorises over both \code{x} and \code{reference}, meaning that either can have a length of 1 while the other argument has a larger length.
}
\examples{
# 10 random pre-Y2K birth dates
df <- data.frame(birth_date = as.Date("2000-01-01") - runif(10) * 25000)
# add ages
df$age <- age(df$birth_date)
# add exact ages
df$age_exact <- age(df$birth_date, exact = TRUE)
# add age at millenium switch
df$age_at_y2k <- age(df$birth_date, "2000-01-01")
df
}
\seealso{
To split ages into groups, use the \code{\link[=age_groups]{age_groups()}} function.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/age_groups.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/age.R
\name{age_groups}
\alias{age_groups}
\title{Split Ages into Age Groups}
\usage{
age_groups(x, split_at = c(12, 25, 55, 75), na.rm = FALSE)
}
\arguments{
\item{x}{age, e.g. calculated with \code{\link[=age]{age()}}}
\item{split_at}{values to split \code{x} at - the default is age groups 0-11, 12-24, 25-54, 55-74 and 75+. See \emph{Details}.}
\item{na.rm}{a \link{logical} to indicate whether missing values should be removed}
}
\value{
Ordered \link{factor}
}
\description{
Split ages into age groups defined by the \code{split} argument. This allows for easier demographic (antimicrobial resistance) analysis.
}
\details{
To split ages, the input for the \code{split_at} argument can be:
\itemize{
\item A \link{numeric} vector. A value of e.g. \code{c(10, 20)} will split \code{x} on 0-9, 10-19 and 20+. A value of only \code{50} will split \code{x} on 0-49 and 50+.
The default is to split on young children (0-11), youth (12-24), young adults (25-54), middle-aged adults (55-74) and elderly (75+).
\item A character:
\itemize{
\item \code{"children"} or \code{"kids"}, equivalent of: \code{c(0, 1, 2, 4, 6, 13, 18)}. This will split on 0, 1, 2-3, 4-5, 6-12, 13-17 and 18+.
\item \code{"elderly"} or \code{"seniors"}, equivalent of: \code{c(65, 75, 85)}. This will split on 0-64, 65-74, 75-84, 85+.
\item \code{"fives"}, equivalent of: \code{1:20 * 5}. This will split on 0-4, 5-9, ..., 95-99, 100+.
\item \code{"tens"}, equivalent of: \code{1:10 * 10}. This will split on 0-9, 10-19, ..., 90-99, 100+.
}
}
}
\examples{
ages <- c(3, 8, 16, 54, 31, 76, 101, 43, 21)
# split into 0-49 and 50+
age_groups(ages, 50)
# split into 0-19, 20-49 and 50+
age_groups(ages, c(20, 50))
# split into groups of ten years
age_groups(ages, 1:10 * 10)
age_groups(ages, split_at = "tens")
# split into groups of five years
age_groups(ages, 1:20 * 5)
age_groups(ages, split_at = "fives")
# split specifically for children
age_groups(ages, c(1, 2, 4, 6, 13, 18))
age_groups(ages, "children")
\donttest{
# resistance of ciprofloxacin per age group
if (require("dplyr") && require("ggplot2")) {
example_isolates \%>\%
filter_first_isolate() \%>\%
filter(mo == as.mo("Escherichia coli")) \%>\%
group_by(age_group = age_groups(age)) \%>\%
select(age_group, CIP) \%>\%
ggplot_sir(
x = "age_group",
minimum = 0,
x.title = "Age Group",
title = "Ciprofloxacin resistance per age group"
)
}
}
}
\seealso{
To determine ages, based on one or more reference dates, use the \code{\link[=age]{age()}} function.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/antibiogram.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/antibiogram.R
\name{antibiogram}
\alias{antibiogram}
\alias{plot.antibiogram}
\alias{autoplot.antibiogram}
\alias{knit_print.antibiogram}
\title{Generate Traditional, Combination, Syndromic, or WISCA Antibiograms}
\source{
\itemize{
\item Bielicki JA \emph{et al.} (2016). \strong{Selecting appropriate empirical antibiotic regimens for paediatric bloodstream infections: application of a Bayesian decision model to local and pooled antimicrobial resistance surveillance data} \emph{Journal of Antimicrobial Chemotherapy} 71(3); \doi{10.1093/jac/dkv397}
\item Klinker KP \emph{et al.} (2021). \strong{Antimicrobial stewardship and antibiograms: importance of moving beyond traditional antibiograms}. \emph{Therapeutic Advances in Infectious Disease}, May 5;8:20499361211011373; \doi{10.1177/20499361211011373}
\item Barbieri E \emph{et al.} (2021). \strong{Development of a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) to guide the choice of the empiric antibiotic treatment for urinary tract infection in paediatric patients: a Bayesian approach} \emph{Antimicrobial Resistance & Infection Control} May 1;10(1):74; \doi{10.1186/s13756-021-00939-2}
\item \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 5th Edition}, 2022, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
}
}
\usage{
antibiogram(
x,
antibiotics = where(is.sir),
mo_transform = "shortname",
ab_transform = "name",
syndromic_group = NULL,
add_total_n = FALSE,
only_all_tested = FALSE,
digits = 0,
formatting_type = getOption("AMR_antibiogram_formatting_type", 10),
col_mo = NULL,
language = get_AMR_locale(),
minimum = 30,
combine_SI = TRUE,
sep = " + ",
info = interactive()
)
\method{plot}{antibiogram}(x, ...)
\method{autoplot}{antibiogram}(object, ...)
\method{knit_print}{antibiogram}(
x,
italicise = TRUE,
na = getOption("knitr.kable.NA", default = ""),
...
)
}
\arguments{
\item{x}{a \link{data.frame} containing at least a column with microorganisms and columns with antibiotic results (class 'sir', see \code{\link[=as.sir]{as.sir()}})}
\item{antibiotics}{vector of any antibiotic name or code (will be evaluated with \code{\link[=as.ab]{as.ab()}}, column name of \code{x}, or (any combinations of) \link[=antibiotic_class_selectors]{antibiotic selectors} such as \code{\link[=aminoglycosides]{aminoglycosides()}} or \code{\link[=carbapenems]{carbapenems()}}. For combination antibiograms, this can also be set to values separated with \code{"+"}, such as "TZP+TOB" or "cipro + genta", given that columns resembling such antibiotics exist in \code{x}. See \emph{Examples}.}
\item{mo_transform}{a character to transform microorganism input - must be \code{"name"}, \code{"shortname"} (default), \code{"gramstain"}, or one of the column names of the \link{microorganisms} data set: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "oxygen_tolerance", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "mycobank", "mycobank_parent", "mycobank_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence", or "snomed". Can also be \code{NULL} to not transform the input.}
\item{ab_transform}{a character to transform antibiotic input - must be one of the column names of the \link{antibiotics} data set (defaults to \code{"name"}): "ab", "cid", "name", "group", "atc", "atc_group1", "atc_group2", "abbreviations", "synonyms", "oral_ddd", "oral_units", "iv_ddd", "iv_units", or "loinc". Can also be \code{NULL} to not transform the input.}
\item{syndromic_group}{a column name of \code{x}, or values calculated to split rows of \code{x}, e.g. by using \code{\link[=ifelse]{ifelse()}} or \code{\link[dplyr:case_when]{case_when()}}. See \emph{Examples}.}
\item{add_total_n}{a \link{logical} to indicate whether total available numbers per pathogen should be added to the table (default is \code{TRUE}). This will add the lowest and highest number of available isolate per antibiotic (e.g, if for \emph{E. coli} 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200").}
\item{only_all_tested}{(for combination antibiograms): a \link{logical} to indicate that isolates must be tested for all antibiotics, see \emph{Details}}
\item{digits}{number of digits to use for rounding the susceptibility percentage}
\item{formatting_type}{numeric value (1–12) indicating how the 'cells' of the antibiogram table should be formatted. See \emph{Details} > \emph{Formatting Type} for a list of options.}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{language}{language to translate text, which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})}
\item{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 \emph{Source}.}
\item{combine_SI}{a \link{logical} to indicate whether all susceptibility should be determined by results of either S, SDD, or I, instead of only S (default is \code{TRUE})}
\item{sep}{a separating character for antibiotic columns in combination antibiograms}
\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode}
\item{...}{when used in \link[knitr:kable]{R Markdown or Quarto}: arguments passed on to \code{\link[knitr:kable]{knitr::kable()}} (otherwise, has no use)}
\item{object}{an \code{\link[=antibiogram]{antibiogram()}} object}
\item{italicise}{a \link{logical} to indicate whether the microorganism names in the \link[knitr:kable]{knitr} table should be made italic, using \code{\link[=italicise_taxonomy]{italicise_taxonomy()}}.}
\item{na}{character to use for showing \code{NA} values}
}
\description{
Create detailed antibiograms with options for traditional, combination, syndromic, and Bayesian WISCA methods. Based on the approaches of Klinker \emph{et al.}, Barbieri \emph{et al.}, and the Bayesian WISCA model (Weighted-Incidence Syndromic Combination Antibiogram) by Bielicki \emph{et al.}, this function provides flexible output formats including plots and tables, ideal for integration with R Markdown and Quarto reports.
}
\details{
This function returns a table with values between 0 and 100 for \emph{susceptibility}, not resistance.
\strong{Remember that you should filter your data to let it contain only first isolates!} This is needed to exclude duplicates and to reduce selection bias. Use \code{\link[=first_isolate]{first_isolate()}} to determine them in your data set with one of the four available algorithms.
\subsection{Formatting Type}{
The formatting of the 'cells' of the table can be set with the argument \code{formatting_type}. In these examples, \code{5} is the susceptibility percentage, \code{15} the numerator, and \code{300} the denominator:
\enumerate{
\item 5
\item 15
\item 300
\item 15/300
\item 5 (300)
\item 5\% (300)
\item 5 (N=300)
\item 5\% (N=300)
\item 5 (15/300)
\item 5\% (15/300)
\item 5 (N=15/300)
\item 5\% (N=15/300)
}
The default is \code{10}, which can be set globally with the package option \code{\link[=AMR-options]{AMR_antibiogram_formatting_type}}, e.g. \code{options(AMR_antibiogram_formatting_type = 5)}.
Set \code{digits} (defaults to \code{0}) to alter the rounding of the susceptibility percentage.
}
\subsection{Antibiogram Types}{
There are four antibiogram types, as summarised by Klinker \emph{et al.} (2021, \doi{10.1177/20499361211011373}), and they are all supported by \code{\link[=antibiogram]{antibiogram()}}. Use WISCA whenever possible, since it provides precise coverage estimates by accounting for pathogen incidence and antimicrobial susceptibility. See the section \emph{Why Use WISCA?} on this page.
The four antibiogram types:
\enumerate{
\item \strong{Traditional Antibiogram}
Case example: Susceptibility of \emph{Pseudomonas aeruginosa} to piperacillin/tazobactam (TZP)
Code example:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{antibiogram(your_data,
antibiotics = "TZP")
}\if{html}{\out{</div>}}
\item \strong{Combination Antibiogram}
Case example: Additional susceptibility of \emph{Pseudomonas aeruginosa} to TZP + tobramycin versus TZP alone
Code example:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{antibiogram(your_data,
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"))
}\if{html}{\out{</div>}}
\item \strong{Syndromic Antibiogram}
Case example: Susceptibility of \emph{Pseudomonas aeruginosa} to TZP among respiratory specimens (obtained among ICU patients only)
Code example:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{antibiogram(your_data,
antibiotics = penicillins(),
syndromic_group = "ward")
}\if{html}{\out{</div>}}
\item \strong{Weighted-Incidence Syndromic Combination Antibiogram (WISCA)}
WISCA enhances empirical antibiotic selection by weighting the incidence of pathogens in specific clinical syndromes and combining them with their susceptibility data. It provides an estimation of regimen coverage by aggregating pathogen incidences and susceptibilities across potential causative organisms. See also the section \emph{Why Use WISCA?} on this page.
Case example: Susceptibility of \emph{Pseudomonas aeruginosa} to TZP among respiratory specimens (obtained among ICU patients only) for male patients age >=65 years with heart failure
Code example:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(dplyr)
your_data \%>\%
filter(ward == "ICU" & specimen_type == "Respiratory") \%>\%
antibiogram(antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
syndromic_group = ifelse(.$age >= 65 &
.$gender == "Male" &
.$condition == "Heart Disease",
"Study Group", "Control Group"))
}\if{html}{\out{</div>}}
WISCA uses a sophisticated Bayesian decision model to combine both local and pooled antimicrobial resistance data. This approach not only evaluates local patterns but can also draw on multi-centre datasets to improve regimen accuracy, even in low-incidence infections like paediatric bloodstream infections (BSIs).
}
}
\subsection{Inclusion in Combination Antibiogram and Syndromic Antibiogram}{
Note that for types 2 and 3 (Combination Antibiogram and Syndromic Antibiogram), it is important to realise that susceptibility can be calculated in two ways, which can be set with the \code{only_all_tested} argument (default is \code{FALSE}). See this example for two antibiotics, Drug A and Drug B, about how \code{\link[=antibiogram]{antibiogram()}} works to calculate the \%SI:
\if{html}{\out{<div class="sourceCode">}}\preformatted{--------------------------------------------------------------------
only_all_tested = FALSE only_all_tested = TRUE
----------------------- -----------------------
Drug A Drug B include as include as include as include as
numerator denominator numerator denominator
-------- -------- ---------- ----------- ---------- -----------
S or I S or I X X X X
R S or I X X X X
<NA> S or I X X - -
S or I R X X X X
R R - X - X
<NA> R - - - -
S or I <NA> X X - -
R <NA> - - - -
<NA> <NA> - - - -
--------------------------------------------------------------------
}\if{html}{\out{</div>}}
}
\subsection{Plotting}{
All types of antibiograms as listed above can be plotted (using \code{\link[ggplot2:autoplot]{ggplot2::autoplot()}} or base \R's \code{\link[=plot]{plot()}} and \code{\link[=barplot]{barplot()}}).
THe outcome of \code{\link[=antibiogram]{antibiogram()}} can also be used directly in R Markdown / Quarto (i.e., \code{knitr}) for reports. In this case, \code{\link[knitr:kable]{knitr::kable()}} will be applied automatically and microorganism names will even be printed in italics at default (see argument \code{italicise}).
You can also use functions from specific 'table reporting' packages to transform the output of \code{\link[=antibiogram]{antibiogram()}} to your needs, e.g. with \code{flextable::as_flextable()} or \code{gt::gt()}.
}
}
\section{Why Use WISCA?}{
WISCA is a powerful tool for guiding empirical antibiotic therapy because it provides precise coverage estimates by accounting for pathogen incidence and antimicrobial susceptibility. This is particularly important in empirical treatment, where the causative pathogen is often unknown at the outset. Traditional antibiograms do not reflect the weighted likelihood of specific pathogens based on clinical syndromes, which can lead to suboptimal treatment choices.
The Bayesian WISCA, as described by Bielicki \emph{et al.} (2016), improves on earlier methods by handling uncertainties common in smaller datasets, such as low-incidence infections. This method offers a significant advantage by:
\enumerate{
\item Pooling Data from Multiple Sources:\cr WISCA uses pooled data from multiple hospitals or surveillance sources to overcome limitations of small sample sizes at individual institutions, allowing for more confident selection of narrow-spectrum antibiotics or combinations.
\item Bayesian Framework:\cr The Bayesian decision tree model accounts for both local data and prior knowledge (such as inherent resistance patterns) to estimate regimen coverage. It allows for a more precise estimation of coverage, even in cases where susceptibility data is missing or incomplete.
\item Incorporating Pathogen and Regimen Uncertainty:\cr WISCA allows clinicians to see the likelihood that an empirical regimen will be effective against all relevant pathogens, taking into account uncertainties related to both pathogen prevalence and antimicrobial resistance. This leads to better-informed, data-driven clinical decisions.
\item Scenarios for Optimising Treatment:\cr For hospitals or settings with low-incidence infections, WISCA helps determine whether local data is sufficient or if pooling with external data is necessary. It also identifies statistically significant differences or similarities between antibiotic regimens, enabling clinicians to choose optimal therapies with greater confidence.
}
WISCA is essential in optimising empirical treatment by shifting away from broad-spectrum antibiotics, which are often overused in empirical settings. By offering precise estimates based on syndromic patterns and pooled data, WISCA supports antimicrobial stewardship by guiding more targeted therapy, reducing unnecessary broad-spectrum use, and combating the rise of antimicrobial resistance.
}
\examples{
# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.
example_isolates
\donttest{
# Traditional antibiogram ----------------------------------------------
antibiogram(example_isolates,
antibiotics = c(aminoglycosides(), carbapenems())
)
antibiogram(example_isolates,
antibiotics = aminoglycosides(),
ab_transform = "atc",
mo_transform = "gramstain"
)
antibiogram(example_isolates,
antibiotics = carbapenems(),
ab_transform = "name",
mo_transform = "name"
)
# Combined antibiogram -------------------------------------------------
# combined antibiotics yield higher empiric coverage
antibiogram(example_isolates,
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
mo_transform = "gramstain"
)
# names of antibiotics do not need to resemble columns exactly:
antibiogram(example_isolates,
antibiotics = c("Cipro", "cipro + genta"),
mo_transform = "gramstain",
ab_transform = "name",
sep = " & "
)
# Syndromic antibiogram ------------------------------------------------
# the data set could contain a filter for e.g. respiratory specimens
antibiogram(example_isolates,
antibiotics = c(aminoglycosides(), carbapenems()),
syndromic_group = "ward"
)
# now define a data set with only E. coli
ex1 <- example_isolates[which(mo_genus() == "Escherichia"), ]
# with a custom language, though this will be determined automatically
# (i.e., this table will be in Spanish on Spanish systems)
antibiogram(ex1,
antibiotics = aminoglycosides(),
ab_transform = "name",
syndromic_group = ifelse(ex1$ward == "ICU",
"UCI", "No UCI"
),
language = "es"
)
# Weighted-incidence syndromic combination antibiogram (WISCA) ---------
# the data set could contain a filter for e.g. respiratory specimens/ICU
antibiogram(example_isolates,
antibiotics = c("AMC", "AMC+CIP", "TZP", "TZP+TOB"),
mo_transform = "gramstain",
minimum = 10, # this should be >=30, but now just as example
syndromic_group = ifelse(example_isolates$age >= 65 &
example_isolates$gender == "M",
"WISCA Group 1", "WISCA Group 2"
)
)
# Print the output for R Markdown / Quarto -----------------------------
ureido <- antibiogram(example_isolates,
antibiotics = ureidopenicillins(),
ab_transform = "name"
)
# in an Rmd file, you would just need to return `ureido` in a chunk,
# but to be explicit here:
if (requireNamespace("knitr")) {
cat(knitr::knit_print(ureido))
}
# Generate plots with ggplot2 or base R --------------------------------
ab1 <- antibiogram(example_isolates,
antibiotics = c("AMC", "CIP", "TZP", "TZP+TOB"),
mo_transform = "gramstain"
)
ab2 <- antibiogram(example_isolates,
antibiotics = c("AMC", "CIP", "TZP", "TZP+TOB"),
mo_transform = "gramstain",
syndromic_group = "ward"
)
if (requireNamespace("ggplot2")) {
ggplot2::autoplot(ab1)
}
if (requireNamespace("ggplot2")) {
ggplot2::autoplot(ab2)
}
plot(ab1)
plot(ab2)
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/antibiotic_class_selectors.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ab_selectors.R
\name{antibiotic_class_selectors}
\alias{antibiotic_class_selectors}
\alias{ab_class}
\alias{ab_selector}
\alias{aminoglycosides}
\alias{aminopenicillins}
\alias{antifungals}
\alias{antimycobacterials}
\alias{betalactams}
\alias{betalactams_with_inhibitor}
\alias{carbapenems}
\alias{cephalosporins}
\alias{cephalosporins_1st}
\alias{cephalosporins_2nd}
\alias{cephalosporins_3rd}
\alias{cephalosporins_4th}
\alias{cephalosporins_5th}
\alias{fluoroquinolones}
\alias{glycopeptides}
\alias{lincosamides}
\alias{lipoglycopeptides}
\alias{macrolides}
\alias{nitrofurans}
\alias{oxazolidinones}
\alias{penicillins}
\alias{polymyxins}
\alias{quinolones}
\alias{rifamycins}
\alias{streptogramins}
\alias{tetracyclines}
\alias{trimethoprims}
\alias{ureidopenicillins}
\alias{administrable_per_os}
\alias{administrable_iv}
\alias{not_intrinsic_resistant}
\title{Antibiotic Selectors}
\usage{
ab_class(ab_class, only_sir_columns = FALSE, only_treatable = TRUE, ...)
ab_selector(filter, only_sir_columns = FALSE, only_treatable = TRUE, ...)
aminoglycosides(only_sir_columns = FALSE, only_treatable = TRUE, ...)
aminopenicillins(only_sir_columns = FALSE, ...)
antifungals(only_sir_columns = FALSE, ...)
antimycobacterials(only_sir_columns = FALSE, ...)
betalactams(only_sir_columns = FALSE, only_treatable = TRUE, ...)
betalactams_with_inhibitor(only_sir_columns = FALSE, ...)
carbapenems(only_sir_columns = FALSE, only_treatable = TRUE, ...)
cephalosporins(only_sir_columns = FALSE, ...)
cephalosporins_1st(only_sir_columns = FALSE, ...)
cephalosporins_2nd(only_sir_columns = FALSE, ...)
cephalosporins_3rd(only_sir_columns = FALSE, ...)
cephalosporins_4th(only_sir_columns = FALSE, ...)
cephalosporins_5th(only_sir_columns = FALSE, ...)
fluoroquinolones(only_sir_columns = FALSE, ...)
glycopeptides(only_sir_columns = FALSE, ...)
lincosamides(only_sir_columns = FALSE, only_treatable = TRUE, ...)
lipoglycopeptides(only_sir_columns = FALSE, ...)
macrolides(only_sir_columns = FALSE, ...)
nitrofurans(only_sir_columns = FALSE, ...)
oxazolidinones(only_sir_columns = FALSE, ...)
penicillins(only_sir_columns = FALSE, ...)
polymyxins(only_sir_columns = FALSE, only_treatable = TRUE, ...)
quinolones(only_sir_columns = FALSE, ...)
rifamycins(only_sir_columns = FALSE, ...)
streptogramins(only_sir_columns = FALSE, ...)
tetracyclines(only_sir_columns = FALSE, ...)
trimethoprims(only_sir_columns = FALSE, ...)
ureidopenicillins(only_sir_columns = FALSE, ...)
administrable_per_os(only_sir_columns = FALSE, ...)
administrable_iv(only_sir_columns = FALSE, ...)
not_intrinsic_resistant(
only_sir_columns = FALSE,
col_mo = NULL,
version_expertrules = 3.3,
...
)
}
\arguments{
\item{ab_class}{an antimicrobial class or a part of it, such as \code{"carba"} and \code{"carbapenems"}. The columns \code{group}, \code{atc_group1} and \code{atc_group2} of the \link{antibiotics} data set will be searched (case-insensitive) for this value.}
\item{only_sir_columns}{a \link{logical} to indicate whether only columns of class \code{sir} must be selected (default is \code{FALSE}), see \code{\link[=as.sir]{as.sir()}}}
\item{only_treatable}{a \link{logical} to indicate whether antimicrobial drugs should be excluded that are only for laboratory tests (default is \code{TRUE}), such as gentamicin-high (\code{GEH}) and imipenem/EDTA (\code{IPE})}
\item{...}{ignored, only in place to allow future extensions}
\item{filter}{an \link{expression} to be evaluated in the \link{antibiotics} data set, such as \code{name \%like\% "trim"}}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{version_expertrules}{the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".}
}
\value{
When used inside selecting or filtering, this returns a \link{character} vector of column names, with additional class \code{"ab_selector"}. When used individually, this returns an \link[=as.ab]{'ab' vector} with all possible antimicrobial that the function would be able to select or filter.
}
\description{
These functions allow for filtering rows and selecting columns based on antibiotic test results that are of a specific antibiotic class or group (according to the \link{antibiotics} data set), without the need to define the columns or antibiotic abbreviations.
In short, if you have a column name that resembles an antimicrobial drug, it will be picked up by any of these functions that matches its pharmaceutical class: "cefazolin", "kefzol", "CZO" and "J01DB04" will all be picked up by \code{\link[=cephalosporins]{cephalosporins()}}.
}
\details{
These functions can be used in data set calls for selecting columns and filtering rows. They work with base \R, the Tidyverse, and \code{data.table}. They are heavily inspired by the \link[tidyselect:language]{Tidyverse selection helpers} such as \code{\link[tidyselect:everything]{everything()}}, but are not limited to \code{dplyr} verbs. Nonetheless, they are very convenient to use with \code{dplyr} functions such as \code{\link[dplyr:select]{select()}}, \code{\link[dplyr:filter]{filter()}} and \code{\link[dplyr:summarise]{summarise()}}, see \emph{Examples}.
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 \link{antibiotics} data set. This means that a selector such as \code{\link[=aminoglycosides]{aminoglycosides()}} will pick up column names like 'gen', 'genta', 'J01GB03', 'tobra', 'Tobracin', etc.
The \code{\link[=ab_class]{ab_class()}} function can be used to filter/select on a manually defined antibiotic class. It searches for results in the \link{antibiotics} data set within the columns \code{group}, \code{atc_group1} and \code{atc_group2}.
The \code{\link[=ab_selector]{ab_selector()}} function can be used to internally filter the \link{antibiotics} data set on any results, see \emph{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.
The \code{\link[=administrable_per_os]{administrable_per_os()}} and \code{\link[=administrable_iv]{administrable_iv()}} functions also rely on the \link{antibiotics} data set - antibiotic columns will be matched where a DDD (defined daily dose) for resp. oral and IV treatment is available in the \link{antibiotics} data set.
The \code{\link[=not_intrinsic_resistant]{not_intrinsic_resistant()}} function can be used to only select antibiotic columns that pose no intrinsic resistance for the microorganisms in the data set. For example, if a data set contains only microorganism codes or names of \emph{E. coli} and \emph{K. pneumoniae} and contains a column "vancomycin", this column will be removed (or rather, unselected) using this function. It currently applies \href{https://www.eucast.org/expert_rules_and_expected_phenotypes}{'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3} (2021) to determine intrinsic resistance, using the \code{\link[=eucast_rules]{eucast_rules()}} function internally. Because of this determination, this function is quite slow in terms of performance.
}
\section{Full list of supported (antibiotic) classes}{
\itemize{
\item \code{\link[=aminoglycosides]{aminoglycosides()}} can select: \cr amikacin (AMK), amikacin/fosfomycin (AKF), apramycin (APR), arbekacin (ARB), astromicin (AST), bekanamycin (BEK), dibekacin (DKB), framycetin (FRM), gentamicin (GEN), gentamicin-high (GEH), habekacin (HAB), hygromycin (HYG), isepamicin (ISE), kanamycin (KAN), kanamycin-high (KAH), kanamycin/cephalexin (KAC), micronomicin (MCR), neomycin (NEO), netilmicin (NET), pentisomicin (PIM), plazomicin (PLZ), propikacin (PKA), ribostamycin (RST), sisomicin (SIS), streptoduocin (STR), streptomycin (STR1), streptomycin-high (STH), tobramycin (TOB), and tobramycin-high (TOH)
\item \code{\link[=aminopenicillins]{aminopenicillins()}} can select: \cr amoxicillin (AMX) and ampicillin (AMP)
\item \code{\link[=antifungals]{antifungals()}} can select: \cr amorolfine (AMO), amphotericin B (AMB), amphotericin B-high (AMH), anidulafungin (ANI), butoconazole (BUT), caspofungin (CAS), ciclopirox (CIX), clotrimazole (CTR), econazole (ECO), fluconazole (FLU), flucytosine (FCT), fosfluconazole (FFL), griseofulvin (GRI), hachimycin (HCH), ibrexafungerp (IBX), isavuconazole (ISV), isoconazole (ISO), itraconazole (ITR), ketoconazole (KET), manogepix (MGX), micafungin (MIF), miconazole (MCZ), nystatin (NYS), oteseconazole (OTE), pimaricin (PMR), posaconazole (POS), rezafungin (RZF), ribociclib (RBC), sulconazole (SUC), terbinafine (TRB), terconazole (TRC), and voriconazole (VOR)
\item \code{\link[=antimycobacterials]{antimycobacterials()}} can select: \cr 4-aminosalicylic acid (AMA), calcium aminosalicylate (CLA), capreomycin (CAP), clofazimine (CLF), delamanid (DLM), enviomycin (ENV), ethambutol (ETH), ethambutol/isoniazid (ETI), ethionamide (ETI1), isoniazid (INH), isoniazid/sulfamethoxazole/trimethoprim/pyridoxine (IST), morinamide (MRN), p-aminosalicylic acid (PAS), pretomanid (PMD), protionamide (PTH), pyrazinamide (PZA), rifabutin (RIB), rifampicin (RIF), rifampicin/ethambutol/isoniazid (REI), rifampicin/isoniazid (RFI), rifampicin/pyrazinamide/ethambutol/isoniazid (RPEI), rifampicin/pyrazinamide/isoniazid (RPI), rifamycin (RFM), rifapentine (RFP), simvastatin/fenofibrate (SMF), sodium aminosalicylate (SDA), streptomycin/isoniazid (STI), terizidone (TRZ), thioacetazone (TAT), thioacetazone/isoniazid (THI1), tiocarlide (TCR), and viomycin (VIO)
\item \code{\link[=betalactams]{betalactams()}} can select: \cr amoxicillin (AMX), amoxicillin/clavulanic acid (AMC), amoxicillin/sulbactam (AXS), ampicillin (AMP), ampicillin/sulbactam (SAM), apalcillin (APL), aspoxicillin (APX), avibactam (AVB), azidocillin (AZD), azlocillin (AZL), aztreonam (ATM), aztreonam/avibactam (AZA), aztreonam/nacubactam (ANC), bacampicillin (BAM), benzathine benzylpenicillin (BNB), benzathine phenoxymethylpenicillin (BNP), benzylpenicillin (PEN), biapenem (BIA), carbenicillin (CRB), carindacillin (CRN), cefacetrile (CAC), cefaclor (CEC), cefadroxil (CFR), cefalexin (LEX), cefaloridine (RID), cefalotin (CEP), cefamandole (MAN), cefapirin (HAP), cefatrizine (CTZ), cefazedone (CZD), cefazolin (CZO), cefcapene (CCP), cefcapene pivoxil (CCX), cefdinir (CDR), cefditoren (DIT), cefditoren pivoxil (DIX), cefepime (FEP), cefepime/clavulanic acid (CPC), cefepime/nacubactam (FNC), cefepime/tazobactam (FPT), cefetamet (CAT), cefetamet pivoxil (CPI), cefetecol (CCL), cefetrizole (CZL), cefiderocol (FDC), cefixime (CFM), cefmenoxime (CMX), cefmetazole (CMZ), cefodizime (DIZ), cefonicid (CID), cefoperazone (CFP), cefoperazone/sulbactam (CSL), ceforanide (CND), cefoselis (CSE), cefotaxime (CTX), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefotetan (CTT), cefotiam (CTF), cefotiam hexetil (CHE), cefovecin (FOV), cefoxitin (FOX), cefoxitin screening (FOX1), cefozopran (ZOP), cefpimizole (CFZ), cefpiramide (CPM), cefpirome (CPO), cefpodoxime (CPD), cefpodoxime proxetil (CPX), cefpodoxime/clavulanic acid (CDC), cefprozil (CPR), cefquinome (CEQ), cefroxadine (CRD), cefsulodin (CFS), cefsumide (CSU), ceftaroline (CPT), ceftaroline/avibactam (CPA), ceftazidime (CAZ), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), cefteram (CEM), cefteram pivoxil (CPL), ceftezole (CTL), ceftibuten (CTB), ceftiofur (TIO), ceftizoxime (CZX), ceftizoxime alapivoxil (CZP), ceftobiprole (BPR), ceftobiprole medocaril (CFM1), ceftolozane/tazobactam (CZT), ceftriaxone (CRO), ceftriaxone/beta-lactamase inhibitor (CEB), cefuroxime (CXM), cefuroxime axetil (CXA), cephradine (CED), ciclacillin (CIC), clometocillin (CLM), cloxacillin (CLO), dicloxacillin (DIC), doripenem (DOR), epicillin (EPC), ertapenem (ETP), flucloxacillin (FLC), hetacillin (HET), imipenem (IPM), imipenem/EDTA (IPE), imipenem/relebactam (IMR), latamoxef (LTM), lenampicillin (LEN), loracarbef (LOR), mecillinam (MEC), meropenem (MEM), meropenem/nacubactam (MNC), meropenem/vaborbactam (MEV), metampicillin (MTM), meticillin (MET), mezlocillin (MEZ), mezlocillin/sulbactam (MSU), nacubactam (NAC), nafcillin (NAF), oxacillin (OXA), panipenem (PAN), penamecillin (PNM), penicillin/novobiocin (PNO), penicillin/sulbactam (PSU), pheneticillin (PHE), phenoxymethylpenicillin (PHN), piperacillin (PIP), piperacillin/sulbactam (PIS), piperacillin/tazobactam (TZP), piridicillin (PRC), pivampicillin (PVM), pivmecillinam (PME), procaine benzylpenicillin (PRB), propicillin (PRP), razupenem (RZM), ritipenem (RIT), ritipenem acoxil (RIA), sarmoxicillin (SRX), sulbactam (SUL), sulbenicillin (SBC), sultamicillin (SLT6), talampicillin (TAL), tazobactam (TAZ), tebipenem (TBP), temocillin (TEM), ticarcillin (TIC), and ticarcillin/clavulanic acid (TCC)
\item \code{\link[=betalactams_with_inhibitor]{betalactams_with_inhibitor()}} can select: \cr amoxicillin/clavulanic acid (AMC), amoxicillin/sulbactam (AXS), ampicillin/sulbactam (SAM), aztreonam/avibactam (AZA), aztreonam/nacubactam (ANC), cefepime/clavulanic acid (CPC), cefepime/nacubactam (FNC), cefepime/tazobactam (FPT), cefoperazone/sulbactam (CSL), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefpodoxime/clavulanic acid (CDC), ceftaroline/avibactam (CPA), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), ceftolozane/tazobactam (CZT), ceftriaxone/beta-lactamase inhibitor (CEB), imipenem/relebactam (IMR), meropenem/nacubactam (MNC), meropenem/vaborbactam (MEV), mezlocillin/sulbactam (MSU), penicillin/novobiocin (PNO), penicillin/sulbactam (PSU), piperacillin/sulbactam (PIS), piperacillin/tazobactam (TZP), and ticarcillin/clavulanic acid (TCC)
\item \code{\link[=carbapenems]{carbapenems()}} can select: \cr biapenem (BIA), doripenem (DOR), ertapenem (ETP), imipenem (IPM), imipenem/EDTA (IPE), imipenem/relebactam (IMR), meropenem (MEM), meropenem/nacubactam (MNC), meropenem/vaborbactam (MEV), panipenem (PAN), razupenem (RZM), ritipenem (RIT), ritipenem acoxil (RIA), and tebipenem (TBP)
\item \code{\link[=cephalosporins]{cephalosporins()}} can select: \cr cefacetrile (CAC), cefaclor (CEC), cefadroxil (CFR), cefalexin (LEX), cefaloridine (RID), cefalotin (CEP), cefamandole (MAN), cefapirin (HAP), cefatrizine (CTZ), cefazedone (CZD), cefazolin (CZO), cefcapene (CCP), cefcapene pivoxil (CCX), cefdinir (CDR), cefditoren (DIT), cefditoren pivoxil (DIX), cefepime (FEP), cefepime/clavulanic acid (CPC), cefepime/tazobactam (FPT), cefetamet (CAT), cefetamet pivoxil (CPI), cefetecol (CCL), cefetrizole (CZL), cefiderocol (FDC), cefixime (CFM), cefmenoxime (CMX), cefmetazole (CMZ), cefodizime (DIZ), cefonicid (CID), cefoperazone (CFP), cefoperazone/sulbactam (CSL), ceforanide (CND), cefoselis (CSE), cefotaxime (CTX), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefotetan (CTT), cefotiam (CTF), cefotiam hexetil (CHE), cefovecin (FOV), cefoxitin (FOX), cefoxitin screening (FOX1), cefozopran (ZOP), cefpimizole (CFZ), cefpiramide (CPM), cefpirome (CPO), cefpodoxime (CPD), cefpodoxime proxetil (CPX), cefpodoxime/clavulanic acid (CDC), cefprozil (CPR), cefquinome (CEQ), cefroxadine (CRD), cefsulodin (CFS), cefsumide (CSU), ceftaroline (CPT), ceftaroline/avibactam (CPA), ceftazidime (CAZ), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), cefteram (CEM), cefteram pivoxil (CPL), ceftezole (CTL), ceftibuten (CTB), ceftiofur (TIO), ceftizoxime (CZX), ceftizoxime alapivoxil (CZP), ceftobiprole (BPR), ceftobiprole medocaril (CFM1), ceftolozane/tazobactam (CZT), ceftriaxone (CRO), ceftriaxone/beta-lactamase inhibitor (CEB), cefuroxime (CXM), cefuroxime axetil (CXA), cephradine (CED), latamoxef (LTM), and loracarbef (LOR)
\item \code{\link[=cephalosporins_1st]{cephalosporins_1st()}} can select: \cr cefacetrile (CAC), cefadroxil (CFR), cefalexin (LEX), cefaloridine (RID), cefalotin (CEP), cefapirin (HAP), cefatrizine (CTZ), cefazedone (CZD), cefazolin (CZO), cefroxadine (CRD), ceftezole (CTL), and cephradine (CED)
\item \code{\link[=cephalosporins_2nd]{cephalosporins_2nd()}} can select: \cr cefaclor (CEC), cefamandole (MAN), cefmetazole (CMZ), cefonicid (CID), ceforanide (CND), cefotetan (CTT), cefotiam (CTF), cefoxitin (FOX), cefoxitin screening (FOX1), cefprozil (CPR), cefuroxime (CXM), cefuroxime axetil (CXA), and loracarbef (LOR)
\item \code{\link[=cephalosporins_3rd]{cephalosporins_3rd()}} can select: \cr cefcapene (CCP), cefcapene pivoxil (CCX), cefdinir (CDR), cefditoren (DIT), cefditoren pivoxil (DIX), cefetamet (CAT), cefetamet pivoxil (CPI), cefixime (CFM), cefmenoxime (CMX), cefodizime (DIZ), cefoperazone (CFP), cefoperazone/sulbactam (CSL), cefotaxime (CTX), cefotaxime/clavulanic acid (CTC), cefotaxime/sulbactam (CTS), cefotiam hexetil (CHE), cefovecin (FOV), cefpimizole (CFZ), cefpiramide (CPM), cefpodoxime (CPD), cefpodoxime proxetil (CPX), cefpodoxime/clavulanic acid (CDC), cefsulodin (CFS), ceftazidime (CAZ), ceftazidime/avibactam (CZA), ceftazidime/clavulanic acid (CCV), cefteram (CEM), cefteram pivoxil (CPL), ceftibuten (CTB), ceftiofur (TIO), ceftizoxime (CZX), ceftizoxime alapivoxil (CZP), ceftriaxone (CRO), ceftriaxone/beta-lactamase inhibitor (CEB), and latamoxef (LTM)
\item \code{\link[=cephalosporins_4th]{cephalosporins_4th()}} can select: \cr cefepime (FEP), cefepime/clavulanic acid (CPC), cefepime/tazobactam (FPT), cefetecol (CCL), cefoselis (CSE), cefozopran (ZOP), cefpirome (CPO), and cefquinome (CEQ)
\item \code{\link[=cephalosporins_5th]{cephalosporins_5th()}} can select: \cr ceftaroline (CPT), ceftaroline/avibactam (CPA), ceftobiprole (BPR), ceftobiprole medocaril (CFM1), and ceftolozane/tazobactam (CZT)
\item \code{\link[=fluoroquinolones]{fluoroquinolones()}} can select: \cr besifloxacin (BES), ciprofloxacin (CIP), clinafloxacin (CLX), danofloxacin (DAN), delafloxacin (DFX), difloxacin (DIF), enoxacin (ENX), enrofloxacin (ENR), finafloxacin (FIN), fleroxacin (FLE), garenoxacin (GRN), gatifloxacin (GAT), gemifloxacin (GEM), grepafloxacin (GRX), lascufloxacin (LSC), levofloxacin (LVX), levonadifloxacin (LND), lomefloxacin (LOM), marbofloxacin (MAR), metioxate (MXT), miloxacin (MIL), moxifloxacin (MFX), nadifloxacin (NAD), nifuroquine (NIF), norfloxacin (NOR), ofloxacin (OFX), orbifloxacin (ORB), pazufloxacin (PAZ), pefloxacin (PEF), pradofloxacin (PRA), premafloxacin (PRX), prulifloxacin (PRU), rufloxacin (RFL), sarafloxacin (SAR), sitafloxacin (SIT), sparfloxacin (SPX), temafloxacin (TMX), tilbroquinol (TBQ), tioxacin (TXC), tosufloxacin (TFX), and trovafloxacin (TVA)
\item \code{\link[=glycopeptides]{glycopeptides()}} can select: \cr avoparcin (AVO), dalbavancin (DAL), norvancomycin (NVA), oritavancin (ORI), ramoplanin (RAM), teicoplanin (TEC), teicoplanin-macromethod (TCM), telavancin (TLV), vancomycin (VAN), and vancomycin-macromethod (VAM)
\item \code{\link[=lincosamides]{lincosamides()}} can select: \cr acetylmidecamycin (ACM), acetylspiramycin (ASP), clindamycin (CLI), clindamycin inducible screening (CLI1), gamithromycin (GAM), kitasamycin (KIT), lincomycin (LIN), meleumycin (MEL), nafithromycin (ZWK), pirlimycin (PRL), primycin (PRM), solithromycin (SOL), tildipirosin (TIP), tilmicosin (TIL), tulathromycin (TUL), tylosin (TYL), and tylvalosin (TYL1)
\item \code{\link[=lipoglycopeptides]{lipoglycopeptides()}} can select: \cr dalbavancin (DAL), oritavancin (ORI), and telavancin (TLV)
\item \code{\link[=macrolides]{macrolides()}} can select: \cr acetylmidecamycin (ACM), acetylspiramycin (ASP), azithromycin (AZM), clarithromycin (CLR), dirithromycin (DIR), erythromycin (ERY), flurithromycin (FLR1), gamithromycin (GAM), josamycin (JOS), kitasamycin (KIT), meleumycin (MEL), midecamycin (MID), miocamycin (MCM), nafithromycin (ZWK), oleandomycin (OLE), pirlimycin (PRL), primycin (PRM), rokitamycin (ROK), roxithromycin (RXT), solithromycin (SOL), spiramycin (SPI), telithromycin (TLT), tildipirosin (TIP), tilmicosin (TIL), troleandomycin (TRL), tulathromycin (TUL), tylosin (TYL), and tylvalosin (TYL1)
\item \code{\link[=nitrofurans]{nitrofurans()}} can select: \cr furazidin (FUR), furazolidone (FRZ), nifurtoinol (NFR), nitrofurantoin (NIT), and nitrofurazone (NIZ)
\item \code{\link[=oxazolidinones]{oxazolidinones()}} can select: \cr cadazolid (CDZ), cycloserine (CYC), linezolid (LNZ), tedizolid (TZD), and thiacetazone (THA)
\item \code{\link[=penicillins]{penicillins()}} can select: \cr amoxicillin (AMX), amoxicillin/clavulanic acid (AMC), amoxicillin/sulbactam (AXS), ampicillin (AMP), ampicillin/sulbactam (SAM), apalcillin (APL), aspoxicillin (APX), avibactam (AVB), azidocillin (AZD), azlocillin (AZL), aztreonam (ATM), aztreonam/avibactam (AZA), aztreonam/nacubactam (ANC), bacampicillin (BAM), benzathine benzylpenicillin (BNB), benzathine phenoxymethylpenicillin (BNP), benzylpenicillin (PEN), carbenicillin (CRB), carindacillin (CRN), cefepime/nacubactam (FNC), ciclacillin (CIC), clometocillin (CLM), cloxacillin (CLO), dicloxacillin (DIC), epicillin (EPC), flucloxacillin (FLC), hetacillin (HET), lenampicillin (LEN), mecillinam (MEC), metampicillin (MTM), meticillin (MET), mezlocillin (MEZ), mezlocillin/sulbactam (MSU), nacubactam (NAC), nafcillin (NAF), oxacillin (OXA), penamecillin (PNM), penicillin/novobiocin (PNO), penicillin/sulbactam (PSU), pheneticillin (PHE), phenoxymethylpenicillin (PHN), piperacillin (PIP), piperacillin/sulbactam (PIS), piperacillin/tazobactam (TZP), piridicillin (PRC), pivampicillin (PVM), pivmecillinam (PME), procaine benzylpenicillin (PRB), propicillin (PRP), sarmoxicillin (SRX), sulbactam (SUL), sulbenicillin (SBC), sultamicillin (SLT6), talampicillin (TAL), tazobactam (TAZ), temocillin (TEM), ticarcillin (TIC), and ticarcillin/clavulanic acid (TCC)
\item \code{\link[=polymyxins]{polymyxins()}} can select: \cr colistin (COL), polymyxin B (PLB), and polymyxin B/polysorbate 80 (POP)
\item \code{\link[=quinolones]{quinolones()}} can select: \cr besifloxacin (BES), cinoxacin (CIN), ciprofloxacin (CIP), ciprofloxacin/metronidazole (CIM), ciprofloxacin/ornidazole (CIO), ciprofloxacin/tinidazole (CIT), clinafloxacin (CLX), danofloxacin (DAN), delafloxacin (DFX), difloxacin (DIF), enoxacin (ENX), enrofloxacin (ENR), finafloxacin (FIN), fleroxacin (FLE), flumequine (FLM), garenoxacin (GRN), gatifloxacin (GAT), gemifloxacin (GEM), grepafloxacin (GRX), lascufloxacin (LSC), levofloxacin (LVX), levonadifloxacin (LND), lomefloxacin (LOM), marbofloxacin (MAR), metioxate (MXT), miloxacin (MIL), moxifloxacin (MFX), nadifloxacin (NAD), nalidixic acid (NAL), nemonoxacin (NEM), nifuroquine (NIF), nitroxoline (NTR), norfloxacin (NOR), ofloxacin (OFX), orbifloxacin (ORB), oxolinic acid (OXO), pazufloxacin (PAZ), pefloxacin (PEF), pipemidic acid (PPA), piromidic acid (PIR), pradofloxacin (PRA), premafloxacin (PRX), prulifloxacin (PRU), rosoxacin (ROS), rufloxacin (RFL), sarafloxacin (SAR), sitafloxacin (SIT), sparfloxacin (SPX), temafloxacin (TMX), tilbroquinol (TBQ), tioxacin (TXC), tosufloxacin (TFX), and trovafloxacin (TVA)
\item \code{\link[=rifamycins]{rifamycins()}} can select: \cr rifabutin (RIB), rifampicin (RIF), rifampicin/ethambutol/isoniazid (REI), rifampicin/isoniazid (RFI), rifampicin/pyrazinamide/ethambutol/isoniazid (RPEI), rifampicin/pyrazinamide/isoniazid (RPI), rifamycin (RFM), and rifapentine (RFP)
\item \code{\link[=streptogramins]{streptogramins()}} can select: \cr pristinamycin (PRI) and quinupristin/dalfopristin (QDA)
\item \code{\link[=tetracyclines]{tetracyclines()}} can select: \cr cetocycline (CTO), chlortetracycline (CTE), clomocycline (CLM1), demeclocycline (DEM), doxycycline (DOX), eravacycline (ERV), lymecycline (LYM), metacycline (MTC), minocycline (MNO), omadacycline (OMC), oxytetracycline (OXY), penimepicycline (PNM1), rolitetracycline (RLT), sarecycline (SRC), tetracycline (TCY), and tigecycline (TGC)
\item \code{\link[=trimethoprims]{trimethoprims()}} can select: \cr brodimoprim (BDP), sulfadiazine (SDI), sulfadiazine/tetroxoprim (SLT), sulfadiazine/trimethoprim (SLT1), sulfadimethoxine (SUD), sulfadimidine (SDM), sulfadimidine/trimethoprim (SLT2), sulfafurazole (SLF), sulfaisodimidine (SLF1), sulfalene (SLF2), sulfamazone (SZO), sulfamerazine (SLF3), sulfamerazine/trimethoprim (SLT3), sulfamethizole (SLF4), sulfamethoxazole (SMX), sulfamethoxypyridazine (SLF5), sulfametomidine (SLF6), sulfametoxydiazine (SLF7), sulfametrole/trimethoprim (SLT4), sulfamoxole (SLF8), sulfamoxole/trimethoprim (SLT5), sulfanilamide (SLF9), sulfaperin (SLF10), sulfaphenazole (SLF11), sulfapyridine (SLF12), sulfathiazole (SUT), sulfathiourea (SLF13), trimethoprim (TMP), and trimethoprim/sulfamethoxazole (SXT)
\item \code{\link[=ureidopenicillins]{ureidopenicillins()}} can select: \cr azlocillin (AZL), mezlocillin (MEZ), piperacillin (PIP), and piperacillin/tazobactam (TZP)
}
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates.
example_isolates
# you can use the selectors separately to retrieve all possible antimicrobials:
carbapenems()
# Though they are primarily intended to use for selections and filters.
# Examples sections below are split into 'dplyr', 'base R', and 'data.table':
\donttest{
\dontrun{
# dplyr -------------------------------------------------------------------
library(dplyr, warn.conflicts = FALSE)
example_isolates \%>\% select(carbapenems())
# select columns 'mo', 'AMK', 'GEN', 'KAN' and 'TOB'
example_isolates \%>\% select(mo, aminoglycosides())
# you can combine selectors like you are used with tidyverse
# e.g., for betalactams, but not the ones with an enzyme inhibitor:
example_isolates \%>\% select(betalactams(), -betalactams_with_inhibitor())
# select only antibiotic columns with DDDs for oral treatment
example_isolates \%>\% select(administrable_per_os())
# get AMR for all aminoglycosides e.g., per ward:
example_isolates \%>\%
group_by(ward) \%>\%
summarise(across(aminoglycosides(),
resistance))
# You can combine selectors with '&' to be more specific:
example_isolates \%>\%
select(penicillins() & administrable_per_os())
# get AMR for only drugs that matter - no intrinsic resistance:
example_isolates \%>\%
filter(mo_genus() \%in\% c("Escherichia", "Klebsiella")) \%>\%
group_by(ward) \%>\%
summarise_at(not_intrinsic_resistant(),
resistance)
# get susceptibility for antibiotics whose name contains "trim":
example_isolates \%>\%
filter(first_isolate()) \%>\%
group_by(ward) \%>\%
summarise(across(ab_selector(name \%like\% "trim"), susceptibility))
# this will select columns 'IPM' (imipenem) and 'MEM' (meropenem):
example_isolates \%>\%
select(carbapenems())
# this will select columns 'mo', 'AMK', 'GEN', 'KAN' and 'TOB':
example_isolates \%>\%
select(mo, aminoglycosides())
# any() and all() work in dplyr's filter() too:
example_isolates \%>\%
filter(
any(aminoglycosides() == "R"),
all(cephalosporins_2nd() == "R")
)
# also works with c():
example_isolates \%>\%
filter(any(c(carbapenems(), aminoglycosides()) == "R"))
# not setting any/all will automatically apply all():
example_isolates \%>\%
filter(aminoglycosides() == "R")
# this will select columns 'mo' and all antimycobacterial drugs ('RIF'):
example_isolates \%>\%
select(mo, ab_class("mycobact"))
# get bug/drug combinations for only glycopeptides in Gram-positives:
example_isolates \%>\%
filter(mo_is_gram_positive()) \%>\%
select(mo, glycopeptides()) \%>\%
bug_drug_combinations() \%>\%
format()
data.frame(
some_column = "some_value",
J01CA01 = "S"
) \%>\% # ATC code of ampicillin
select(penicillins()) # only the 'J01CA01' column will be selected
# with recent versions of dplyr, this is all equal:
x <- example_isolates[carbapenems() == "R", ]
y <- example_isolates \%>\% filter(carbapenems() == "R")
z <- example_isolates \%>\% filter(if_all(carbapenems(), ~ .x == "R"))
identical(x, y) && identical(y, z)
}
# base R ------------------------------------------------------------------
# select columns 'IPM' (imipenem) and 'MEM' (meropenem)
example_isolates[, carbapenems()]
# select columns 'mo', 'AMK', 'GEN', 'KAN' and 'TOB'
example_isolates[, c("mo", aminoglycosides())]
# select only antibiotic columns with DDDs for oral treatment
example_isolates[, administrable_per_os()]
# filter using any() or all()
example_isolates[any(carbapenems() == "R"), ]
subset(example_isolates, any(carbapenems() == "R"))
# filter on any or all results in the carbapenem columns (i.e., IPM, MEM):
example_isolates[any(carbapenems()), ]
example_isolates[all(carbapenems()), ]
# filter with multiple antibiotic selectors using c()
example_isolates[all(c(carbapenems(), aminoglycosides()) == "R"), ]
# filter + select in one go: get penicillins in carbapenem-resistant strains
example_isolates[any(carbapenems() == "R"), penicillins()]
# You can combine selectors with '&' to be more specific. For example,
# penicillins() would select benzylpenicillin ('peni G') and
# administrable_per_os() would select erythromycin. Yet, when combined these
# drugs are both omitted since benzylpenicillin is not administrable per os
# and erythromycin is not a penicillin:
example_isolates[, penicillins() & administrable_per_os()]
# ab_selector() applies a filter in the `antibiotics` data set and is thus
# very flexible. For instance, to select antibiotic columns with an oral DDD
# of at least 1 gram:
example_isolates[, ab_selector(oral_ddd > 1 & oral_units == "g")]
# data.table --------------------------------------------------------------
# data.table is supported as well, just use it in the same way as with
# base R, but add `with = FALSE` if using a single AB selector.
if (require("data.table")) {
dt <- as.data.table(example_isolates)
# this does not work, it returns column *names*
dt[, carbapenems()]
}
if (require("data.table")) {
# so `with = FALSE` is required
dt[, carbapenems(), with = FALSE]
}
# for multiple selections or AB selectors, `with = FALSE` is not needed:
if (require("data.table")) {
dt[, c("mo", aminoglycosides())]
}
if (require("data.table")) {
dt[, c(carbapenems(), aminoglycosides())]
}
# row filters are also supported:
if (require("data.table")) {
dt[any(carbapenems() == "S"), ]
}
if (require("data.table")) {
dt[any(carbapenems() == "S"), penicillins(), with = FALSE]
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/antibiotics.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{antibiotics}
\alias{antibiotics}
\alias{antivirals}
\title{Data Sets with 605 Antimicrobial Drugs}
\format{
\subsection{For the \link{antibiotics} data set: a \link[tibble:tibble]{tibble} with 485 observations and 14 variables:}{
\itemize{
\item \code{ab}\cr Antibiotic ID as used in this package (such as \code{AMC}), using the official EARS-Net (European Antimicrobial Resistance Surveillance Network) codes where available. \emph{\strong{This is a unique identifier.}}
\item \code{cid}\cr Compound ID as found in PubChem. \emph{\strong{This is a unique identifier.}}
\item \code{name}\cr Official name as used by WHONET/EARS-Net or the WHO. \emph{\strong{This is a unique identifier.}}
\item \code{group}\cr A short and concise group name, based on WHONET and WHOCC definitions
\item \code{atc}\cr ATC codes (Anatomical Therapeutic Chemical) as defined by the WHOCC, like \code{J01CR02}
\item \code{atc_group1}\cr Official pharmacological subgroup (3rd level ATC code) as defined by the WHOCC, like \code{"Macrolides, lincosamides and streptogramins"}
\item \code{atc_group2}\cr Official chemical subgroup (4th level ATC code) as defined by the WHOCC, like \code{"Macrolides"}
\item \code{abbr}\cr List of abbreviations as used in many countries, also for antibiotic susceptibility testing (AST)
\item \code{synonyms}\cr Synonyms (often trade names) of a drug, as found in PubChem based on their compound ID
\item \code{oral_ddd}\cr Defined Daily Dose (DDD), oral treatment, currently available for 179 drugs
\item \code{oral_units}\cr Units of \code{oral_ddd}
\item \code{iv_ddd}\cr Defined Daily Dose (DDD), parenteral (intravenous) treatment, currently available for 153 drugs
\item \code{iv_units}\cr Units of \code{iv_ddd}
\item \code{loinc}\cr All codes associated with the name of the antimicrobial drug from Logical Observation Identifiers Names and Codes (LOINC), Version 2.76 (18 September, 2023). Use \code{\link[=ab_loinc]{ab_loinc()}} to retrieve them quickly, see \code{\link[=ab_property]{ab_property()}}.
}
}
\subsection{For the \link{antivirals} data set: a \link[tibble:tibble]{tibble} with 120 observations and 11 variables:}{
\itemize{
\item \code{av}\cr Antiviral ID as used in this package (such as \code{ACI}), using the official EARS-Net (European Antimicrobial Resistance Surveillance Network) codes where available. \emph{\strong{This is a unique identifier.}} Combinations are codes that contain a \code{+} to indicate this, such as \code{ATA+COBI} for atazanavir/cobicistat.
\item \code{name}\cr Official name as used by WHONET/EARS-Net or the WHO. \emph{\strong{This is a unique identifier.}}
\item \code{atc}\cr ATC codes (Anatomical Therapeutic Chemical) as defined by the WHOCC
\item \code{cid}\cr Compound ID as found in PubChem. \emph{\strong{This is a unique identifier.}}
\item \code{atc_group}\cr Official pharmacological subgroup (3rd level ATC code) as defined by the WHOCC
\item \code{synonyms}\cr Synonyms (often trade names) of a drug, as found in PubChem based on their compound ID
\item \code{oral_ddd}\cr Defined Daily Dose (DDD), oral treatment
\item \code{oral_units}\cr Units of \code{oral_ddd}
\item \code{iv_ddd}\cr Defined Daily Dose (DDD), parenteral treatment
\item \code{iv_units}\cr Units of \code{iv_ddd}
\item \code{loinc}\cr All codes associated with the name of the antiviral drug from Logical Observation Identifiers Names and Codes (LOINC), Version 2.76 (18 September, 2023). Use \code{\link[=av_loinc]{av_loinc()}} to retrieve them quickly, see \code{\link[=av_property]{av_property()}}.
}
}
An object of class \code{tbl_df} (inherits from \code{tbl}, \code{data.frame}) with 120 rows and 11 columns.
}
\source{
\itemize{
\item World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology (WHOCC): \url{https://atcddd.fhi.no/atc_ddd_index/}
\item Logical Observation Identifiers Names and Codes (LOINC), Version 2.76 (18 September, 2023). Accessed from \url{https://loinc.org} on October 19th, 2023.
\item European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: \url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}
}
}
\usage{
antibiotics
antivirals
}
\description{
Two data sets containing all antibiotics/antimycotics and antivirals. Use \code{\link[=as.ab]{as.ab()}} or one of the \code{\link[=ab_property]{ab_*}} functions to retrieve values from the \link{antibiotics} data set. Three identifiers are included in this data set: an antibiotic ID (\code{ab}, primarily used in this package) as defined by WHONET/EARS-Net, an ATC code (\code{atc}) as defined by the WHO, and a Compound ID (\code{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.
}
\details{
Properties that are based on an ATC code are only available when an ATC is available. These properties are: \code{atc_group1}, \code{atc_group2}, \code{oral_ddd}, \code{oral_units}, \code{iv_ddd} and \code{iv_units}.
Synonyms (i.e. trade names) were derived from the PubChem Compound ID (column \code{cid}) and consequently only available where a CID is available.
\subsection{Direct download}{
Like all data sets in this package, these data sets are publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
}
\section{WHOCC}{
This package contains \strong{all ~550 antibiotic, antimycotic and antiviral drugs} and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, \url{https://atcddd.fhi.no}) and the Pharmaceuticals Community Register of the European Commission (\url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}).
These have become the gold standard for international drug utilisation monitoring and research.
The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.
\strong{NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package.} See \url{https://atcddd.fhi.no/copyright_disclaimer/.}
}
\examples{
antibiotics
antivirals
}
\seealso{
\link{microorganisms}, \link{intrinsic_resistant}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/as.ab.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ab.R
\name{as.ab}
\alias{as.ab}
\alias{ab}
\alias{is.ab}
\title{Transform Input to an Antibiotic ID}
\usage{
as.ab(x, flag_multiple_results = TRUE, info = interactive(), ...)
is.ab(x)
}
\arguments{
\item{x}{a \link{character} vector to determine to antibiotic ID}
\item{flag_multiple_results}{a \link{logical} to indicate whether a note should be printed to the console that probably more than one antibiotic drug code or name can be retrieved from a single input value.}
\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode}
\item{...}{arguments passed on to internal functions}
}
\value{
A \link{character} \link{vector} with additional class \code{\link{ab}}
}
\description{
Use this function to determine the antibiotic drug code of one or more antibiotics. The data set \link{antibiotics} will be searched for abbreviations, official names and synonyms (brand names).
}
\details{
All entries in the \link{antibiotics} data set have three different identifiers: a human readable EARS-Net code (column \code{ab}, used by ECDC and WHONET), an ATC code (column \code{atc}, used by WHO), and a CID code (column \code{cid}, Compound ID, used by PubChem). The data set contains more than 5,000 official brand names from many different countries, as found in PubChem. Not that some drugs contain multiple ATC codes.
All these properties will be searched for the user input. The \code{\link[=as.ab]{as.ab()}} can correct for different forms of misspelling:
\itemize{
\item Wrong spelling of drug names (such as "tobramicin" or "gentamycin"), which corrects for most audible similarities such as f/ph, x/ks, c/z/s, t/th, etc.
\item Too few or too many vowels or consonants
\item Switching two characters (such as "mreopenem", often the case in clinical data, when doctors typed too fast)
\item Digitalised paper records, leaving artefacts like 0/o/O (zero and O's), B/8, n/r, etc.
}
Use the \code{\link[=ab_property]{ab_*}} functions to get properties based on the returned antibiotic ID, see \emph{Examples}.
Note: the \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_property]{ab_*}} functions may use very long regular expression to match brand names of antimicrobial drugs. This may fail on some systems.
You can add your own manual codes to be considered by \code{\link[=as.ab]{as.ab()}} and all \code{\link[=ab_property]{ab_*}} functions, see \code{\link[=add_custom_antimicrobials]{add_custom_antimicrobials()}}.
}
\section{Source}{
World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: \url{https://atcddd.fhi.no/atc_ddd_index/}
European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: \url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}
}
\section{WHOCC}{
This package contains \strong{all ~550 antibiotic, antimycotic and antiviral drugs} and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, \url{https://atcddd.fhi.no}) and the Pharmaceuticals Community Register of the European Commission (\url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}).
These have become the gold standard for international drug utilisation monitoring and research.
The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.
\strong{NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package.} See \url{https://atcddd.fhi.no/copyright_disclaimer/.}
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
# these examples all return "ERY", the ID of erythromycin:
as.ab("J01FA01")
as.ab("J 01 FA 01")
as.ab("Erythromycin")
as.ab("eryt")
as.ab(" eryt 123")
as.ab("ERYT")
as.ab("ERY")
as.ab("eritromicine") # spelled wrong, yet works
as.ab("Erythrocin") # trade name
as.ab("Romycin") # trade name
# spelling from different languages and dyslexia are no problem
ab_atc("ceftriaxon")
ab_atc("cephtriaxone") # small spelling error
ab_atc("cephthriaxone") # or a bit more severe
ab_atc("seephthriaaksone") # and even this works
# use ab_* functions to get a specific properties (see ?ab_property);
# they use as.ab() internally:
ab_name("J01FA01")
ab_name("eryt")
\donttest{
if (require("dplyr")) {
# you can quickly rename 'sir' columns using set_ab_names() with dplyr:
example_isolates \%>\%
set_ab_names(where(is.sir), property = "atc")
}
}
}
\seealso{
\itemize{
\item \link{antibiotics} for the \link{data.frame} that is being used to determine ATCs
\item \code{\link[=ab_from_text]{ab_from_text()}} for a function to retrieve antimicrobial drugs from clinical text (from health care records)
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/as.av.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/av.R
\name{as.av}
\alias{as.av}
\alias{av}
\alias{is.av}
\title{Transform Input to an Antiviral Drug ID}
\usage{
as.av(x, flag_multiple_results = TRUE, info = interactive(), ...)
is.av(x)
}
\arguments{
\item{x}{a \link{character} vector to determine to antiviral drug ID}
\item{flag_multiple_results}{a \link{logical} to indicate whether a note should be printed to the console that probably more than one antiviral drug code or name can be retrieved from a single input value.}
\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode}
\item{...}{arguments passed on to internal functions}
}
\value{
A \link{character} \link{vector} with additional class \code{\link{ab}}
}
\description{
Use this function to determine the antiviral drug code of one or more antiviral drugs. The data set \link{antivirals} will be searched for abbreviations, official names and synonyms (brand names).
}
\details{
All entries in the \link{antivirals} data set have three different identifiers: a human readable EARS-Net code (column \code{ab}, used by ECDC and WHONET), an ATC code (column \code{atc}, used by WHO), and a CID code (column \code{cid}, Compound ID, used by PubChem). The data set contains more than 5,000 official brand names from many different countries, as found in PubChem. Not that some drugs contain multiple ATC codes.
All these properties will be searched for the user input. The \code{\link[=as.av]{as.av()}} can correct for different forms of misspelling:
\itemize{
\item Wrong spelling of drug names (such as "acyclovir"), which corrects for most audible similarities such as f/ph, x/ks, c/z/s, t/th, etc.
\item Too few or too many vowels or consonants
\item Switching two characters (such as "aycclovir", often the case in clinical data, when doctors typed too fast)
\item Digitalised paper records, leaving artefacts like 0/o/O (zero and O's), B/8, n/r, etc.
}
Use the \code{\link[=av_property]{av_*}} functions to get properties based on the returned antiviral drug ID, see \emph{Examples}.
Note: the \code{\link[=as.av]{as.av()}} and \code{\link[=av_property]{av_*}} functions may use very long regular expression to match brand names of antimicrobial drugs. This may fail on some systems.
}
\section{Source}{
World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: \url{https://atcddd.fhi.no/atc_ddd_index/}
European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: \url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}
}
\section{WHOCC}{
This package contains \strong{all ~550 antibiotic, antimycotic and antiviral drugs} and their Anatomical Therapeutic Chemical (ATC) codes, ATC groups and Defined Daily Dose (DDD) from the World Health Organization Collaborating Centre for Drug Statistics Methodology (WHOCC, \url{https://atcddd.fhi.no}) and the Pharmaceuticals Community Register of the European Commission (\url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}).
These have become the gold standard for international drug utilisation monitoring and research.
The WHOCC is located in Oslo at the Norwegian Institute of Public Health and funded by the Norwegian government. The European Commission is the executive of the European Union and promotes its general interest.
\strong{NOTE: The WHOCC copyright does not allow use for commercial purposes, unlike any other info from this package.} See \url{https://atcddd.fhi.no/copyright_disclaimer/.}
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
# these examples all return "ACI", the ID of aciclovir:
as.av("J05AB01")
as.av("J 05 AB 01")
as.av("Aciclovir")
as.av("aciclo")
as.av(" aciclo 123")
as.av("ACICL")
as.av("ACI")
as.av("Virorax") # trade name
as.av("Zovirax") # trade name
as.av("acyklofir") # severe spelling error, yet works
# use av_* functions to get a specific properties (see ?av_property);
# they use as.av() internally:
av_name("J05AB01")
av_name("acicl")
}
\seealso{
\itemize{
\item \link{antivirals} for the \link{data.frame} that is being used to determine ATCs
\item \code{\link[=av_from_text]{av_from_text()}} for a function to retrieve antimicrobial drugs from clinical text (from health care records)
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/as.disk.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/disk.R
\docType{data}
\name{as.disk}
\alias{as.disk}
\alias{disk}
\alias{NA_disk_}
\alias{is.disk}
\title{Transform Input to Disk Diffusion Diameters}
\format{
An object of class \code{disk} (inherits from \code{integer}) of length 1.
}
\usage{
as.disk(x, na.rm = FALSE)
NA_disk_
is.disk(x)
}
\arguments{
\item{x}{vector}
\item{na.rm}{a \link{logical} indicating whether missing values should be removed}
}
\value{
An \link{integer} with additional class \code{\link{disk}}
}
\description{
This transforms a vector to a new class \code{\link{disk}}, which is a disk diffusion growth zone size (around an antibiotic disk) in millimetres between 0 and 50.
}
\details{
Interpret disk values as SIR values with \code{\link[=as.sir]{as.sir()}}. It supports guidelines from EUCAST and CLSI.
Disk diffusion growth zone sizes must be between 0 and 50 millimetres. Values higher than 50 but lower than 100 will be maximised to 50. All others input values outside the 0-50 range will return \code{NA}.
\code{NA_disk_} is a missing value of the new \code{disk} class.
}
\examples{
# transform existing disk zones to the `disk` class (using base R)
df <- data.frame(
microorganism = "Escherichia coli",
AMP = 20,
CIP = 14,
GEN = 18,
TOB = 16
)
df[, 2:5] <- lapply(df[, 2:5], as.disk)
str(df)
\donttest{
# transforming is easier with dplyr:
if (require("dplyr")) {
df \%>\% mutate(across(AMP:TOB, as.disk))
}
}
# interpret disk values, see ?as.sir
as.sir(
x = as.disk(18),
mo = "Strep pneu", # `mo` will be coerced with as.mo()
ab = "ampicillin", # and `ab` with as.ab()
guideline = "EUCAST"
)
# interpret whole data set, pretend to be all from urinary tract infections:
as.sir(df, uti = TRUE)
}
\seealso{
\code{\link[=as.sir]{as.sir()}}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/as.mic.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mic.R
\docType{data}
\name{as.mic}
\alias{as.mic}
\alias{mic}
\alias{is.mic}
\alias{NA_mic_}
\alias{rescale_mic}
\alias{droplevels.mic}
\title{Transform Input to Minimum Inhibitory Concentrations (MIC)}
\usage{
as.mic(x, na.rm = FALSE, keep_operators = "all")
is.mic(x)
NA_mic_
rescale_mic(x, mic_range, keep_operators = "edges", as.mic = TRUE)
\method{droplevels}{mic}(x, as.mic = FALSE, ...)
}
\arguments{
\item{x}{a \link{character} or \link{numeric} vector}
\item{na.rm}{a \link{logical} indicating whether missing values should be removed}
\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.}
\item{mic_range}{a manual range to limit the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to set no limit on one side, e.g., \code{mic_range = c(NA, 32)}.}
\item{as.mic}{a \link{logical} to indicate whether the \code{mic} class should be kept - the default is \code{FALSE}}
\item{...}{arguments passed on to methods}
}
\value{
Ordered \link{factor} with additional class \code{\link{mic}}, that in mathematical operations acts as a \link{numeric} vector. Bear in mind that the outcome of any mathematical operation on MICs will return a \link{numeric} value.
}
\description{
This transforms vectors to a new class \code{\link{mic}}, which treats the input as decimal numbers, while maintaining operators (such as ">=") and only allowing valid MIC values known to the field of (medical) microbiology.
}
\details{
To interpret MIC values as SIR values, use \code{\link[=as.sir]{as.sir()}} on MIC values. It supports guidelines from EUCAST (2011-2024) and CLSI (2011-2024).
This class for MIC values is a quite a special data type: formally it is an ordered \link{factor} with valid MIC values as \link{factor} levels (to make sure only valid MIC values are retained), but for any mathematical operation it acts as decimal numbers:
\if{html}{\out{<div class="sourceCode">}}\preformatted{x <- random_mic(10)
x
#> Class 'mic'
#> [1] 16 1 8 8 64 >=128 0.0625 32 32 16
is.factor(x)
#> [1] TRUE
x[1] * 2
#> [1] 32
median(x)
#> [1] 26
}\if{html}{\out{</div>}}
This makes it possible to maintain operators that often come with MIC values, such ">=" and "<=", even when filtering using \link{numeric} values in data analysis, e.g.:
\if{html}{\out{<div class="sourceCode">}}\preformatted{x[x > 4]
#> Class 'mic'
#> [1] 16 8 8 64 >=128 32 32 16
df <- data.frame(x, hospital = "A")
subset(df, x > 4) # or with dplyr: df \%>\% filter(x > 4)
#> x hospital
#> 1 16 A
#> 5 64 A
#> 6 >=128 A
#> 8 32 A
#> 9 32 A
#> 10 16 A
}\if{html}{\out{</div>}}
All so-called \link[=groupGeneric]{group generic functions} are implemented for the MIC class (such as \code{!}, \code{!=}, \code{<}, \code{>=}, \code{\link[=exp]{exp()}}, \code{\link[=log2]{log2()}}). Some functions of the \code{stats} package are also implemented (such as \code{\link[=quantile]{quantile()}}, \code{\link[=median]{median()}}, \code{\link[=fivenum]{fivenum()}}). Since \code{\link[=sd]{sd()}} and \code{\link[=var]{var()}} are non-generic functions, these could not be extended. Use \code{\link[=mad]{mad()}} as an alternative, or use e.g. \code{sd(as.numeric(x))} where \code{x} is your vector of MIC values.
Using \code{\link[=as.double]{as.double()}} or \code{\link[=as.numeric]{as.numeric()}} on MIC values will remove the operators and return a numeric vector. Do \strong{not} use \code{\link[=as.integer]{as.integer()}} on MIC values as by the \R convention on \link{factor}s, it will return the index of the factor levels (which is often useless for regular users).
Use \code{\link[=droplevels]{droplevels()}} to drop unused levels. At default, it will return a plain factor. Use \code{droplevels(..., as.mic = TRUE)} to maintain the \code{mic} class.
With \code{\link[=rescale_mic]{rescale_mic()}}, existing MIC ranges can be limited to a defined range of MIC values. This can be useful to better compare MIC distributions.
For \code{ggplot2}, use one of the \code{\link[=scale_x_mic]{scale_*_mic()}} functions to plot MIC values. They allows custom MIC ranges and to plot intermediate log2 levels for missing MIC values.
\code{NA_mic_} is a missing value of the new \code{mic} class, analogous to e.g. base \R's \code{\link[base:NA]{NA_character_}}.
}
\examples{
mic_data <- as.mic(c(">=32", "1.0", "1", "1.00", 8, "<=0.128", "8", "16", "16"))
mic_data
is.mic(mic_data)
# this can also coerce combined MIC/SIR values:
as.mic("<=0.002; S")
# mathematical processing treats MICs as numeric values
fivenum(mic_data)
quantile(mic_data)
all(mic_data < 512)
# rescale MICs using rescale_mic()
rescale_mic(mic_data, mic_range = c(4, 16))
# interpret MIC values
as.sir(
x = as.mic(2),
mo = as.mo("Streptococcus pneumoniae"),
ab = "AMX",
guideline = "EUCAST"
)
as.sir(
x = as.mic(c(0.01, 2, 4, 8)),
mo = as.mo("Streptococcus pneumoniae"),
ab = "AMX",
guideline = "EUCAST"
)
# plot MIC values, see ?plot
plot(mic_data)
plot(mic_data, mo = "E. coli", ab = "cipro")
if (require("ggplot2")) {
autoplot(mic_data, mo = "E. coli", ab = "cipro")
}
if (require("ggplot2")) {
autoplot(mic_data, mo = "E. coli", ab = "cipro", language = "nl") # Dutch
}
}
\seealso{
\code{\link[=as.sir]{as.sir()}}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/as.mo.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mo.R
\name{as.mo}
\alias{as.mo}
\alias{mo}
\alias{is.mo}
\alias{mo_uncertainties}
\alias{mo_renamed}
\alias{mo_failures}
\alias{mo_reset_session}
\alias{mo_cleaning_regex}
\title{Transform Arbitrary Input to Valid Microbial Taxonomy}
\usage{
as.mo(
x,
Becker = FALSE,
Lancefield = FALSE,
minimum_matching_score = NULL,
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
reference_df = get_mo_source(),
ignore_pattern = getOption("AMR_ignore_pattern", NULL),
cleaning_regex = getOption("AMR_cleaning_regex", mo_cleaning_regex()),
only_fungi = getOption("AMR_only_fungi", FALSE),
language = get_AMR_locale(),
info = interactive(),
...
)
is.mo(x)
mo_uncertainties()
mo_renamed()
mo_failures()
mo_reset_session()
mo_cleaning_regex()
}
\arguments{
\item{x}{a \link{character} vector or a \link{data.frame} with one or two columns}
\item{Becker}{a \link{logical} to indicate whether staphylococci should be categorised into coagulase-negative staphylococci ("CoNS") and coagulase-positive staphylococci ("CoPS") instead of their own species, according to Karsten Becker \emph{et al.} (see \emph{Source}). Please see \emph{Details} for a full list of staphylococcal species that will be converted.
This excludes \emph{Staphylococcus aureus} at default, use \code{Becker = "all"} to also categorise \emph{S. aureus} as "CoPS".}
\item{Lancefield}{a \link{logical} to indicate whether a beta-haemolytic \emph{Streptococcus} should be categorised into Lancefield groups instead of their own species, according to Rebecca C. Lancefield (see \emph{Source}). These streptococci will be categorised in their first group, e.g. \emph{Streptococcus dysgalactiae} will be group C, although officially it was also categorised into groups G and L. . Please see \emph{Details} for a full list of streptococcal species that will be converted.
This excludes enterococci at default (who are in group D), use \code{Lancefield = "all"} to also categorise all enterococci as group D.}
\item{minimum_matching_score}{a numeric value to set as the lower limit for the \link[=mo_matching_score]{MO matching score}. When left blank, this will be determined automatically based on the character length of \code{x}, its \link[=microorganisms]{taxonomic kingdom} and \link[=mo_matching_score]{human pathogenicity}.}
\item{keep_synonyms}{a \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.}
\item{reference_df}{a \link{data.frame} to be used for extra reference when translating \code{x} to a valid \code{\link{mo}}. See \code{\link[=set_mo_source]{set_mo_source()}} and \code{\link[=get_mo_source]{get_mo_source()}} to automate the usage of your own codes (e.g. used in your analysis or organisation).}
\item{ignore_pattern}{a Perl-compatible \link[base:regex]{regular expression} (case-insensitive) of which all matches in \code{x} must return \code{NA}. This can be convenient to exclude known non-relevant input and can also be set with the package option \code{\link[=AMR-options]{AMR_ignore_pattern}}, e.g. \code{options(AMR_ignore_pattern = "(not reported|contaminated flora)")}.}
\item{cleaning_regex}{a Perl-compatible \link[base:regex]{regular expression} (case-insensitive) to clean the input of \code{x}. Every matched part in \code{x} will be removed. At default, this is the outcome of \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}, which removes texts between brackets and texts such as "species" and "serovar". The default can be set with the package option \code{\link[=AMR-options]{AMR_cleaning_regex}}.}
\item{only_fungi}{a \link{logical} to indicate if only fungi must be found, making sure that e.g. misspellings always return records from the kingdom of Fungi. This can be set globally for \link[=mo_property]{all microorganism functions} with the package option \code{\link[=AMR-options]{AMR_only_fungi}}, i.e. \code{options(AMR_only_fungi = TRUE)}.}
\item{language}{language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})}
\item{info}{a \link{logical} to indicate that info must be printed, e.g. a progress bar when more than 25 items are to be coerced, or a list with old taxonomic names. The default is \code{TRUE} only in interactive mode.}
\item{...}{other arguments passed on to functions}
}
\value{
A \link{character} \link{vector} with additional class \code{\link{mo}}
}
\description{
Use this function to get a valid microorganism code (\code{\link{mo}}) based on arbitrary user input. Determination is done using intelligent rules and the complete taxonomic tree of the kingdoms Animalia, Archaea, Bacteria, Chromista, and Protozoa, and most microbial species from the kingdom Fungi (see \emph{Source}). The input can be almost anything: a full name (like \code{"Staphylococcus aureus"}), an abbreviated name (such as \code{"S. aureus"}), an abbreviation known in the field (such as \code{"MRSA"}), or just a genus. See \emph{Examples}.
}
\details{
A microorganism (MO) code from this package (class: \code{\link{mo}}) is human-readable and typically looks like these examples:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ Code Full name
--------------- --------------------------------------
B_KLBSL Klebsiella
B_KLBSL_PNMN Klebsiella pneumoniae
B_KLBSL_PNMN_RHNS Klebsiella pneumoniae rhinoscleromatis
| | | |
| | | |
| | | \\---> subspecies, a 3-5 letter acronym
| | \\----> species, a 3-6 letter acronym
| \\----> genus, a 4-8 letter acronym
\\----> kingdom: A (Archaea), AN (Animalia), B (Bacteria),
C (Chromista), F (Fungi), PL (Plantae),
P (Protozoa)
}\if{html}{\out{</div>}}
Values that cannot be coerced will be considered 'unknown' and will return the MO code \code{UNKNOWN} with a warning.
Use the \code{\link[=mo_property]{mo_*}} functions to get properties based on the returned code, see \emph{Examples}.
The \code{\link[=as.mo]{as.mo()}} function uses a novel and scientifically validated (\doi{10.18637/jss.v104.i03}) matching score algorithm (see \emph{Matching Score for Microorganisms} below) to match input against the \link[=microorganisms]{available microbial taxonomy} in this package. This implicates that e.g. \code{"E. coli"} (a microorganism highly prevalent in humans) will return the microbial ID of \emph{Escherichia coli} and not \emph{Entamoeba coli} (a microorganism less prevalent in humans), although the latter would alphabetically come first.
\subsection{Coping with Uncertain Results}{
Results of non-exact taxonomic input are based on their \link[=mo_matching_score]{matching score}. The lowest allowed score can be set with the \code{minimum_matching_score} argument. At default this will be determined based on the character length of the input, the \link[=microorganisms]{taxonomic kingdom}, and the \link[=mo_matching_score]{human pathogenicity} of the taxonomic outcome. If values are matched with uncertainty, a message will be shown to suggest the user to inspect the results with \code{\link[=mo_uncertainties]{mo_uncertainties()}}, which returns a \link{data.frame} with all specifications.
To increase the quality of matching, the \code{cleaning_regex} argument is used to clean the input. This must be a \link[base:regex]{regular expression} that matches parts of the input that should be removed before the input is matched against the \link[=microorganisms]{available microbial taxonomy}. It will be matched Perl-compatible and case-insensitive. The default value of \code{cleaning_regex} is the outcome of the helper function \code{\link[=mo_cleaning_regex]{mo_cleaning_regex()}}.
There are three helper functions that can be run after using the \code{\link[=as.mo]{as.mo()}} function:
\itemize{
\item Use \code{\link[=mo_uncertainties]{mo_uncertainties()}} to get a \link{data.frame} that prints in a pretty format with all taxonomic names that were guessed. The output contains the matching score for all matches (see \emph{Matching Score for Microorganisms} below).
\item Use \code{\link[=mo_failures]{mo_failures()}} to get a \link{character} \link{vector} with all values that could not be coerced to a valid value.
\item Use \code{\link[=mo_renamed]{mo_renamed()}} to get a \link{data.frame} with all values that could be coerced based on old, previously accepted taxonomic names.
}
}
\subsection{For Mycologists}{
The \link[=mo_matching_score]{matching score algorithm} gives precedence to bacteria over fungi. If you are only analysing fungi, be sure to use \code{only_fungi = TRUE}, or better yet, add this to your code and run it once every session:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{options(AMR_only_fungi = TRUE)
}\if{html}{\out{</div>}}
This will make sure that no bacteria or other 'non-fungi' will be returned by \code{\link[=as.mo]{as.mo()}}, or any of the \code{\link[=mo_property]{mo_*}} functions.
}
\subsection{Coagulase-negative and Coagulase-positive Staphylococci}{
With \code{Becker = TRUE}, the following staphylococci will be converted to their corresponding coagulase group:
\itemize{
\item Coagulase-negative: \emph{S. americanisciuri}, \emph{S. argensis}, \emph{S. arlettae}, \emph{S. auricularis}, \emph{S. borealis}, \emph{S. brunensis}, \emph{S. caeli}, \emph{S. caledonicus}, \emph{S. canis}, \emph{S. capitis}, \emph{S. capitis capitis}, \emph{S. capitis urealyticus}, \emph{S. capitis ureolyticus}, \emph{S. caprae}, \emph{S. carnosus}, \emph{S. carnosus carnosus}, \emph{S. carnosus utilis}, \emph{S. casei}, \emph{S. caseolyticus}, \emph{S. chromogenes}, \emph{S. cohnii}, \emph{S. cohnii cohnii}, \emph{S. cohnii urealyticum}, \emph{S. cohnii urealyticus}, \emph{S. condimenti}, \emph{S. croceilyticus}, \emph{S. debuckii}, \emph{S. devriesei}, \emph{S. durrellii}, \emph{S. edaphicus}, \emph{S. epidermidis}, \emph{S. equorum}, \emph{S. equorum equorum}, \emph{S. equorum linens}, \emph{S. felis}, \emph{S. fleurettii}, \emph{S. gallinarum}, \emph{S. haemolyticus}, \emph{S. hominis}, \emph{S. hominis hominis}, \emph{S. hominis novobiosepticus}, \emph{S. jettensis}, \emph{S. kloosii}, \emph{S. lentus}, \emph{S. lloydii}, \emph{S. lugdunensis}, \emph{S. marylandisciuri}, \emph{S. massiliensis}, \emph{S. microti}, \emph{S. muscae}, \emph{S. nepalensis}, \emph{S. pasteuri}, \emph{S. petrasii}, \emph{S. petrasii croceilyticus}, \emph{S. petrasii jettensis}, \emph{S. petrasii petrasii}, \emph{S. petrasii pragensis}, \emph{S. pettenkoferi}, \emph{S. piscifermentans}, \emph{S. pragensis}, \emph{S. pseudoxylosus}, \emph{S. pulvereri}, \emph{S. ratti}, \emph{S. rostri}, \emph{S. saccharolyticus}, \emph{S. saprophyticus}, \emph{S. saprophyticus bovis}, \emph{S. saprophyticus saprophyticus}, \emph{S. schleiferi}, \emph{S. schleiferi schleiferi}, \emph{S. sciuri}, \emph{S. sciuri carnaticus}, \emph{S. sciuri lentus}, \emph{S. sciuri rodentium}, \emph{S. sciuri sciuri}, \emph{S. shinii}, \emph{S. simulans}, \emph{S. stepanovicii}, \emph{S. succinus}, \emph{S. succinus casei}, \emph{S. succinus succinus}, \emph{S. taiwanensis}, \emph{S. urealyticus}, \emph{S. ureilyticus}, \emph{S. veratri}, \emph{S. vitulinus}, \emph{S. vitulus}, \emph{S. warneri}, and \emph{S. xylosus}
\item Coagulase-positive: \emph{S. agnetis}, \emph{S. argenteus}, \emph{S. coagulans}, \emph{S. cornubiensis}, \emph{S. delphini}, \emph{S. hyicus}, \emph{S. hyicus chromogenes}, \emph{S. hyicus hyicus}, \emph{S. intermedius}, \emph{S. lutrae}, \emph{S. pseudintermedius}, \emph{S. roterodami}, \emph{S. schleiferi coagulans}, \emph{S. schweitzeri}, \emph{S. simiae}, and \emph{S. singaporensis}
}
This is based on:
\itemize{
\item Becker K \emph{et al.} (2014). \strong{Coagulase-Negative Staphylococci.} \emph{Clin Microbiol Rev.} 27(4): 870-926; \doi{10.1128/CMR.00109-13}
\item Becker K \emph{et al.} (2019). \strong{Implications of identifying the recently defined members of the \emph{S. aureus} complex, \emph{S. argenteus} and \emph{S. schweitzeri}: A position paper of members of the ESCMID Study Group for staphylococci and Staphylococcal Diseases (ESGS).} \emph{Clin Microbiol Infect}; \doi{10.1016/j.cmi.2019.02.028}
\item Becker K \emph{et al.} (2020). \strong{Emergence of coagulase-negative staphylococci.} \emph{Expert Rev Anti Infect Ther.} 18(4):349-366; \doi{10.1080/14787210.2020.1730813}
}
For newly named staphylococcal species, such as \emph{S. brunensis} (2024) and \emph{S. shinii} (2023), we looked up the scientific reference to make sure the species are considered for the correct coagulase group.
}
\subsection{Lancefield Groups in Streptococci}{
With \code{Lancefield = TRUE}, the following streptococci will be converted to their corresponding Lancefield group:
\itemize{
\item Streptococcus Group A: \emph{S. pyogenes}
\item Streptococcus Group B: \emph{S. agalactiae}
\item Streptococcus Group C: \emph{S. dysgalactiae}, \emph{S. dysgalactiae dysgalactiae}, \emph{S. dysgalactiae equisimilis}, \emph{S. equi}, \emph{S. equi equi}, \emph{S. equi ruminatorum}, and \emph{S. equi zooepidemicus}
\item Streptococcus Group F: \emph{S. anginosus}, \emph{S. anginosus anginosus}, \emph{S. anginosus whileyi}, \emph{S. constellatus}, \emph{S. constellatus constellatus}, \emph{S. constellatus pharyngis}, \emph{S. constellatus viborgensis}, and \emph{S. intermedius}
\item Streptococcus Group G: \emph{S. canis}, \emph{S. dysgalactiae}, \emph{S. dysgalactiae dysgalactiae}, and \emph{S. dysgalactiae equisimilis}
\item Streptococcus Group H: \emph{S. sanguinis}
\item Streptococcus Group K: \emph{S. salivarius}, \emph{S. salivarius salivarius}, and \emph{S. salivarius thermophilus}
\item Streptococcus Group L: \emph{S. dysgalactiae}, \emph{S. dysgalactiae dysgalactiae}, and \emph{S. dysgalactiae equisimilis}
}
This is based on:
\itemize{
\item Lancefield RC (1933). \strong{A serological differentiation of human and other groups of hemolytic streptococci.} \emph{J Exp Med.} 57(4): 571-95; \doi{10.1084/jem.57.4.571}
}
}
}
\section{Source}{
\itemize{
\item Berends MS \emph{et al.} (2022). \strong{AMR: An R Package for Working with Antimicrobial Resistance Data}. \emph{Journal of Statistical Software}, 104(3), 1-31; \doi{10.18637/jss.v104.i03}
\item Parte, AC \emph{et al.} (2020). \strong{List of Prokaryotic names with Standing in Nomenclature (LPSN) moves to the DSMZ.} International Journal of Systematic and Evolutionary Microbiology, 70, 5607-5612; \doi{10.1099/ijsem.0.004332}. Accessed from \url{https://lpsn.dsmz.de} on June 24th, 2024.
\item Vincent, R \emph{et al} (2013). \strong{MycoBank gearing up for new horizons.} IMA Fungus, 4(2), 371-9; \doi{10.5598/imafungus.2013.04.02.16}. Accessed from \url{https://www.mycobank.org} on June 24th, 2024.
\item GBIF Secretariat (2023). GBIF Backbone Taxonomy. Checklist dataset \doi{10.15468/39omei}. Accessed from \url{https://www.gbif.org} on June 24th, 2024.
\item Reimer, LC \emph{et al.} (2022). \strong{\emph{BacDive} in 2022: the knowledge base for standardized bacterial and archaeal data.} Nucleic Acids Res., 50(D1):D741-D74; \doi{10.1093/nar/gkab961}. Accessed from \url{https://bacdive.dsmz.de} on July 16th, 2024.
\item Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS). US Edition of SNOMED CT from 1 September 2020. Value Set Name 'Microorganism', OID 2.16.840.1.114222.4.11.1009 (v12). URL: \url{https://phinvads.cdc.gov}
\item Bartlett A \emph{et al.} (2022). \strong{A comprehensive list of bacterial pathogens infecting humans} \emph{Microbiology} 168:001269; \doi{10.1099/mic.0.001269}
}
}
\section{Matching Score for Microorganisms}{
With ambiguous user input in \code{\link[=as.mo]{as.mo()}} and all the \code{\link[=mo_property]{mo_*}} functions, the returned results are chosen based on their matching score using \code{\link[=mo_matching_score]{mo_matching_score()}}. This matching score \eqn{m}, is calculated as:
\ifelse{latex}{\deqn{m_{(x, n)} = \frac{l_{n} - 0.5 \cdot \min \begin{cases}l_{n} \\ \textrm{lev}(x, n)\end{cases}}{l_{n} \cdot p_{n} \cdot k_{n}}}}{
\ifelse{html}{\figure{mo_matching_score.png}{options: width="300" alt="mo matching score"}}{m(x, n) = ( l_n * min(l_n, lev(x, n) ) ) / ( l_n * p_n * k_n )}}
where:
\itemize{
\item \eqn{x} is the user input;
\item \eqn{n} is a taxonomic name (genus, species, and subspecies);
\item \eqn{l_n} is the length of \eqn{n};
\item \eqn{lev} is the \href{https://en.wikipedia.org/wiki/Levenshtein_distance}{Levenshtein distance function} (counting any insertion as 1, and any deletion or substitution as 2) that is needed to change \eqn{x} into \eqn{n};
\item \eqn{p_n} is the human pathogenic prevalence group of \eqn{n}, as described below;
\item \eqn{k_n} is the taxonomic kingdom of \eqn{n}, set as Bacteria = 1, Fungi = 1.25, Protozoa = 1.5, Chromista = 1.75, Archaea = 2, others = 3.
}
The grouping into human pathogenic prevalence \eqn{p} is based on recent work from Bartlett \emph{et al.} (2022, \doi{10.1099/mic.0.001269}) who extensively studied medical-scientific literature to categorise all bacterial species into these groups:
\itemize{
\item \strong{Established}, if a taxonomic species has infected at least three persons in three or more references. These records have \code{prevalence = 1.15} in the \link{microorganisms} data set;
\item \strong{Putative}, if a taxonomic species has fewer than three known cases. These records have \code{prevalence = 1.25} in the \link{microorganisms} data set.
}
Furthermore,
\itemize{
\item Genera from the World Health Organization's (WHO) Priority Pathogen List have \code{prevalence = 1.0} in the \link{microorganisms} data set;
\item Any genus present in the \strong{established} list also has \code{prevalence = 1.15} in the \link{microorganisms} data set;
\item Any other genus present in the \strong{putative} list has \code{prevalence = 1.25} in the \link{microorganisms} data set;
\item Any other species or subspecies of which the genus is present in the two aforementioned groups, has \code{prevalence = 1.5} in the \link{microorganisms} data set;
\item Any \emph{non-bacterial} genus, species or subspecies of which the genus is present in the following list, has \code{prevalence = 1.25} in the \link{microorganisms} data set: \emph{Absidia}, \emph{Acanthamoeba}, \emph{Acremonium}, \emph{Actinomucor}, \emph{Aedes}, \emph{Alternaria}, \emph{Amoeba}, \emph{Ancylostoma}, \emph{Angiostrongylus}, \emph{Anisakis}, \emph{Anopheles}, \emph{Apophysomyces}, \emph{Arthroderma}, \emph{Aspergillus}, \emph{Aureobasidium}, \emph{Basidiobolus}, \emph{Beauveria}, \emph{Bipolaris}, \emph{Blastobotrys}, \emph{Blastocystis}, \emph{Blastomyces}, \emph{Candida}, \emph{Capillaria}, \emph{Chaetomium}, \emph{Chilomastix}, \emph{Chrysonilia}, \emph{Chrysosporium}, \emph{Cladophialophora}, \emph{Cladosporium}, \emph{Clavispora}, \emph{Coccidioides}, \emph{Cokeromyces}, \emph{Conidiobolus}, \emph{Coniochaeta}, \emph{Contracaecum}, \emph{Cordylobia}, \emph{Cryptococcus}, \emph{Cryptosporidium}, \emph{Cunninghamella}, \emph{Curvularia}, \emph{Cyberlindnera}, \emph{Debaryozyma}, \emph{Demodex}, \emph{Dermatobia}, \emph{Dientamoeba}, \emph{Diphyllobothrium}, \emph{Dirofilaria}, \emph{Echinostoma}, \emph{Entamoeba}, \emph{Enterobius}, \emph{Epidermophyton}, \emph{Exidia}, \emph{Exophiala}, \emph{Exserohilum}, \emph{Fasciola}, \emph{Fonsecaea}, \emph{Fusarium}, \emph{Geotrichum}, \emph{Giardia}, \emph{Graphium}, \emph{Haloarcula}, \emph{Halobacterium}, \emph{Halococcus}, \emph{Hansenula}, \emph{Hendersonula}, \emph{Heterophyes}, \emph{Histomonas}, \emph{Histoplasma}, \emph{Hortaea}, \emph{Hymenolepis}, \emph{Hypomyces}, \emph{Hysterothylacium}, \emph{Kloeckera}, \emph{Kluyveromyces}, \emph{Kodamaea}, \emph{Lacazia}, \emph{Leishmania}, \emph{Lichtheimia}, \emph{Lodderomyces}, \emph{Lomentospora}, \emph{Madurella}, \emph{Malassezia}, \emph{Malbranchea}, \emph{Metagonimus}, \emph{Meyerozyma}, \emph{Microsporidium}, \emph{Microsporum}, \emph{Millerozyma}, \emph{Mortierella}, \emph{Mucor}, \emph{Mycocentrospora}, \emph{Nannizzia}, \emph{Necator}, \emph{Nectria}, \emph{Ochroconis}, \emph{Oesophagostomum}, \emph{Oidiodendron}, \emph{Opisthorchis}, \emph{Paecilomyces}, \emph{Paracoccidioides}, \emph{Pediculus}, \emph{Penicillium}, \emph{Phaeoacremonium}, \emph{Phaeomoniella}, \emph{Phialophora}, \emph{Phlebotomus}, \emph{Phoma}, \emph{Pichia}, \emph{Piedraia}, \emph{Pithomyces}, \emph{Pityrosporum}, \emph{Pneumocystis}, \emph{Pseudallescheria}, \emph{Pseudoscopulariopsis}, \emph{Pseudoterranova}, \emph{Pulex}, \emph{Purpureocillium}, \emph{Quambalaria}, \emph{Rhinocladiella}, \emph{Rhizomucor}, \emph{Rhizopus}, \emph{Rhodotorula}, \emph{Saccharomyces}, \emph{Saksenaea}, \emph{Saprochaete}, \emph{Sarcoptes}, \emph{Scedosporium}, \emph{Schistosoma}, \emph{Schizosaccharomyces}, \emph{Scolecobasidium}, \emph{Scopulariopsis}, \emph{Scytalidium}, \emph{Spirometra}, \emph{Sporobolomyces}, \emph{Sporopachydermia}, \emph{Sporothrix}, \emph{Sporotrichum}, \emph{Stachybotrys}, \emph{Strongyloides}, \emph{Syncephalastrum}, \emph{Syngamus}, \emph{Taenia}, \emph{Talaromyces}, \emph{Teleomorph}, \emph{Toxocara}, \emph{Trichinella}, \emph{Trichobilharzia}, \emph{Trichoderma}, \emph{Trichomonas}, \emph{Trichophyton}, \emph{Trichosporon}, \emph{Trichostrongylus}, \emph{Trichuris}, \emph{Tritirachium}, \emph{Trombicula}, \emph{Trypanosoma}, \emph{Tunga}, \emph{Ulocladium}, \emph{Ustilago}, \emph{Verticillium}, \emph{Wallemia}, \emph{Wangiella}, \emph{Wickerhamomyces}, \emph{Wuchereria}, \emph{Yarrowia}, or \emph{Zygosaccharomyces};
\item All other records have \code{prevalence = 2.0} in the \link{microorganisms} data set.
}
When calculating the matching score, all characters in \eqn{x} and \eqn{n} are ignored that are other than A-Z, a-z, 0-9, spaces and parentheses.
All matches are sorted descending on their matching score and for all user input values, the top match will be returned. This will lead to the effect that e.g., \code{"E. coli"} will return the microbial ID of \emph{Escherichia coli} (\eqn{m = 0.688}, a highly prevalent microorganism found in humans) and not \emph{Entamoeba coli} (\eqn{m = 0.381}, a less prevalent microorganism in humans), although the latter would alphabetically come first.
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
\donttest{
# These examples all return "B_STPHY_AURS", the ID of S. aureus:
as.mo(c(
"sau", # WHONET code
"stau",
"STAU",
"staaur",
"S. aureus",
"S aureus",
"Sthafilokkockus aureus", # handles incorrect spelling
"Staphylococcus aureus (MRSA)",
"MRSA", # Methicillin Resistant S. aureus
"VISA", # Vancomycin Intermediate S. aureus
"VRSA", # Vancomycin Resistant S. aureus
115329001 # SNOMED CT code
))
# Dyslexia is no problem - these all work:
as.mo(c(
"Ureaplasma urealyticum",
"Ureaplasma urealyticus",
"Ureaplasmium urealytica",
"Ureaplazma urealitycium"
))
# input will get cleaned up with the input given in the `cleaning_regex` argument,
# which defaults to `mo_cleaning_regex()`:
cat(mo_cleaning_regex(), "\n")
as.mo("Streptococcus group A")
as.mo("S. epidermidis") # will remain species: B_STPHY_EPDR
as.mo("S. epidermidis", Becker = TRUE) # will not remain species: B_STPHY_CONS
as.mo("S. pyogenes") # will remain species: B_STRPT_PYGN
as.mo("S. pyogenes", Lancefield = TRUE) # will not remain species: B_STRPT_GRPA
# All mo_* functions use as.mo() internally too (see ?mo_property):
mo_genus("E. coli")
mo_gramstain("ESCO")
mo_is_intrinsic_resistant("ESCCOL", ab = "vanco")
}
}
\seealso{
\link{microorganisms} for the \link{data.frame} that is being used to determine ID's.
The \code{\link[=mo_property]{mo_*}} functions (such as \code{\link[=mo_genus]{mo_genus()}}, \code{\link[=mo_gramstain]{mo_gramstain()}}) to get properties based on the returned code.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/as.sir.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sir.R
\docType{data}
\name{as.sir}
\alias{as.sir}
\alias{sir}
\alias{NA_sir_}
\alias{is.sir}
\alias{is_sir_eligible}
\alias{as.sir.default}
\alias{as.sir.mic}
\alias{as.sir.disk}
\alias{as.sir.data.frame}
\alias{sir_interpretation_history}
\title{Translate MIC and Disk Diffusion to SIR, or Clean Existing SIR Data}
\source{
For interpretations of minimum inhibitory concentration (MIC) values and disk diffusion diameters:
\itemize{
\item \strong{CLSI M39: Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data}, 2011-2024, \emph{Clinical and Laboratory Standards Institute} (CLSI). \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
\item \strong{CLSI M100: Performance Standard for Antimicrobial Susceptibility Testing}, 2011-2024, \emph{Clinical and Laboratory Standards Institute} (CLSI). \url{https://clsi.org/standards/products/microbiology/documents/m100/}.
\item \strong{CLSI VET01: Performance Standards for Antimicrobial Disk and Dilution Susceptibility Tests for Bacteria Isolated From Animals}, 2019-2024, \emph{Clinical and Laboratory Standards Institute} (CLSI). \url{https://clsi.org/standards/products/veterinary-medicine/documents/vet01/}.
\item \strong{CLSI VET09: Understanding Susceptibility Test Data as a Component of Antimicrobial Stewardship in Veterinary Settings}, 2019-2024, \emph{Clinical and Laboratory Standards Institute} (CLSI). \url{https://clsi.org/standards/products/veterinary-medicine/documents/vet09/}.
\item \strong{EUCAST Breakpoint tables for interpretation of MICs and zone diameters}, 2011-2024, \emph{European Committee on Antimicrobial Susceptibility Testing} (EUCAST). \url{https://www.eucast.org/clinical_breakpoints}.
\item \strong{WHONET} as a source for machine-reading the clinical breakpoints (\href{https://msberends.github.io/AMR/reference/clinical_breakpoints.html#imported-from-whonet}{read more here}), 1989-2024, \emph{WHO Collaborating Centre for Surveillance of Antimicrobial Resistance}. \url{https://whonet.org/}.
}
}
\usage{
as.sir(x, ...)
NA_sir_
is.sir(x)
is_sir_eligible(x, threshold = 0.05)
\method{as.sir}{default}(
x,
S = "^(S|U)+$",
I = "^(I)+$",
R = "^(R)+$",
NI = "^(N|NI|V)+$",
SDD = "^(SDD|D|H)+$",
...
)
\method{as.sir}{mic}(
x,
mo = NULL,
ab = deparse(substitute(x)),
guideline = getOption("AMR_guideline", "EUCAST"),
uti = NULL,
conserve_capped_values = FALSE,
add_intrinsic_resistance = FALSE,
reference_data = AMR::clinical_breakpoints,
include_screening = getOption("AMR_include_screening", FALSE),
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
host = NULL,
verbose = FALSE,
...
)
\method{as.sir}{disk}(
x,
mo = NULL,
ab = deparse(substitute(x)),
guideline = getOption("AMR_guideline", "EUCAST"),
uti = NULL,
add_intrinsic_resistance = FALSE,
reference_data = AMR::clinical_breakpoints,
include_screening = getOption("AMR_include_screening", FALSE),
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
host = NULL,
verbose = FALSE,
...
)
\method{as.sir}{data.frame}(
x,
...,
col_mo = NULL,
guideline = getOption("AMR_guideline", "EUCAST"),
uti = NULL,
conserve_capped_values = FALSE,
add_intrinsic_resistance = FALSE,
reference_data = AMR::clinical_breakpoints,
include_screening = getOption("AMR_include_screening", FALSE),
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
host = NULL,
verbose = FALSE
)
sir_interpretation_history(clean = FALSE)
}
\arguments{
\item{x}{vector of values (for class \code{\link{mic}}: MIC values in mg/L, for class \code{\link{disk}}: a disk diffusion radius in millimetres)}
\item{...}{for using on a \link{data.frame}: names of columns to apply \code{\link[=as.sir]{as.sir()}} on (supports tidy selection such as \code{column1:column4}). Otherwise: arguments passed on to methods.}
\item{threshold}{maximum fraction of invalid antimicrobial interpretations of \code{x}, see \emph{Examples}}
\item{S, I, R, NI, SDD}{a case-independent \link[base:regex]{regular expression} to translate input to this result. This regular expression will be run \emph{after} all non-letters and whitespaces are removed from the input.}
\item{mo}{a vector (or column name) with \link{character}s that can be coerced to valid microorganism codes with \code{\link[=as.mo]{as.mo()}}, can be left empty to determine it automatically}
\item{ab}{a vector (or column name) with \link{character}s that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}}
\item{guideline}{defaults to EUCAST 2024 (the latest implemented EUCAST guideline in the \link{clinical_breakpoints} data set), but can be set with the package option \code{\link[=AMR-options]{AMR_guideline}}. Currently supports EUCAST (2011-2024) and CLSI (2011-2024), see \emph{Details}.}
\item{uti}{(Urinary Tract Infection) a vector (or column name) with \link{logical}s (\code{TRUE} or \code{FALSE}) to specify whether a UTI specific interpretation from the guideline should be chosen. For using \code{\link[=as.sir]{as.sir()}} on a \link{data.frame}, this can also be a column containing \link{logical}s or when left blank, the data set will be searched for a column 'specimen', and rows within this column containing 'urin' (such as 'urine', 'urina') will be regarded isolates from a UTI. See \emph{Examples}.}
\item{conserve_capped_values}{a \link{logical} to indicate that MIC values starting with \code{">"} (but not \code{">="}) must always return "R" , and that MIC values starting with \code{"<"} (but not \code{"<="}) must always return "S"}
\item{add_intrinsic_resistance}{\emph{(only useful when using a EUCAST guideline)} a \link{logical} to indicate whether intrinsic antibiotic resistance must also be considered for applicable bug-drug combinations, meaning that e.g. ampicillin will always return "R" in \emph{Klebsiella} species. Determination is based on the \link{intrinsic_resistant} data set, that itself is based on \href{https://www.eucast.org/expert_rules_and_expected_phenotypes}{'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3} (2021).}
\item{reference_data}{a \link{data.frame} to be used for interpretation, which defaults to the \link{clinical_breakpoints} data set. Changing this argument allows for using own interpretation guidelines. This argument must contain a data set that is equal in structure to the \link{clinical_breakpoints} data set (same column names and column types). Please note that the \code{guideline} argument will be ignored when \code{reference_data} is manually set.}
\item{include_screening}{a \link{logical} to indicate that clinical breakpoints for screening are allowed - the default is \code{FALSE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_screening}}.}
\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.}
\item{breakpoint_type}{the type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.}
\item{host}{a vector (or column name) with \link{character}s to indicate the host. Only useful for veterinary breakpoints, as it requires \code{breakpoint_type = "animal"}. The values can be any text resembling the animal species, even in any of the 20 supported languages of this package. For foreign languages, be sure to set the language with \code{\link[=set_AMR_locale]{set_AMR_locale()}} (though it will be automatically guessed based on the system language).}
\item{verbose}{a \link{logical} to indicate that all notes should be printed during interpretation of MIC values or disk diffusion values.}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{clean}{a \link{logical} to indicate whether previously stored results should be forgotten after returning the 'logbook' with results}
}
\value{
Ordered \link{factor} with new class \code{sir}
}
\description{
Clean up existing SIR values, or interpret minimum inhibitory concentration (MIC) values and disk diffusion diameters according to EUCAST or CLSI. \code{\link[=as.sir]{as.sir()}} transforms the input to a new class \code{\link{sir}}, which is an ordered \link{factor} containing the levels \code{S}, \code{SDD}, \code{I}, \code{R}, \code{NI}.
These breakpoints are currently implemented:
\itemize{
\item For \strong{clinical microbiology}: EUCAST 2011-2024 and CLSI 2011-2024;
\item For \strong{veterinary microbiology}: EUCAST 2021-2024 and CLSI 2019-2024;
\item For \strong{ECOFFs} (Epidemiological Cut-off Values): EUCAST 2020-2024 and CLSI 2022-2024.
}
All breakpoints used for interpretation are available in our \link{clinical_breakpoints} data set.
}
\details{
\emph{Note: The clinical breakpoints in this package were validated through, and imported from, \href{https://whonet.org}{WHONET}. The public use of this \code{AMR} package has been endorsed by both CLSI and EUCAST. See \link{clinical_breakpoints} for more information.}
\subsection{How it Works}{
The \code{\link[=as.sir]{as.sir()}} function can work in four ways:
\enumerate{
\item For \strong{cleaning raw / untransformed data}. The data will be cleaned to only contain valid values, namely: \strong{S} for susceptible, \strong{I} for intermediate or 'susceptible, increased exposure', \strong{R} for resistant, \strong{NI} for non-interpretable, and \strong{SDD} for susceptible dose-dependent. Each of these can be set using a \link[base:regex]{regular expression}. Furthermore, \code{\link[=as.sir]{as.sir()}} will try its best to clean with some intelligence. For example, mixed values with SIR interpretations and MIC values such as \code{"<0.25; S"} will be coerced to \code{"S"}. Combined interpretations for multiple test methods (as seen in laboratory records) such as \code{"S; S"} will be coerced to \code{"S"}, but a value like \code{"S; I"} will return \code{NA} with a warning that the input is invalid.
\item For \strong{interpreting minimum inhibitory concentration (MIC) values} according to EUCAST or CLSI. You must clean your MIC values first using \code{\link[=as.mic]{as.mic()}}, that also gives your columns the new data class \code{\link{mic}}. Also, be sure to have a column with microorganism names or codes. It will be found automatically, but can be set manually using the \code{mo} argument.
\itemize{
\item Using \code{dplyr}, SIR interpretation can be done very easily with either:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{your_data \%>\% mutate_if(is.mic, as.sir)
your_data \%>\% mutate(across(where(is.mic), as.sir))
your_data \%>\% mutate_if(is.mic, as.sir, ab = "column_with_antibiotics", mo = "column_with_microorganisms")
your_data \%>\% mutate_if(is.mic, as.sir, ab = c("cipro", "ampicillin", ...), mo = c("E. coli", "K. pneumoniae", ...))
# for veterinary breakpoints, also set `host`:
your_data \%>\% mutate_if(is.mic, as.sir, host = "column_with_animal_species", guideline = "CLSI")
}\if{html}{\out{</div>}}
\item Operators like "<=" will be stripped before interpretation. When using \code{conserve_capped_values = TRUE}, an MIC value of e.g. ">2" will always return "R", even if the breakpoint according to the chosen guideline is ">=4". This is to prevent that capped values from raw laboratory data would not be treated conservatively. The default behaviour (\code{conserve_capped_values = FALSE}) considers ">2" to be lower than ">=4" and might in this case return "S" or "I".
}
\item For \strong{interpreting disk diffusion diameters} according to EUCAST or CLSI. You must clean your disk zones first using \code{\link[=as.disk]{as.disk()}}, that also gives your columns the new data class \code{\link{disk}}. Also, be sure to have a column with microorganism names or codes. It will be found automatically, but can be set manually using the \code{mo} argument.
\itemize{
\item Using \code{dplyr}, SIR interpretation can be done very easily with either:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{your_data \%>\% mutate_if(is.disk, as.sir)
your_data \%>\% mutate(across(where(is.disk), as.sir))
your_data \%>\% mutate_if(is.disk, as.sir, ab = "column_with_antibiotics", mo = "column_with_microorganisms")
your_data \%>\% mutate_if(is.disk, as.sir, ab = c("cipro", "ampicillin", ...), mo = c("E. coli", "K. pneumoniae", ...))
# for veterinary breakpoints, also set `host`:
your_data \%>\% mutate_if(is.disk, as.sir, host = "column_with_animal_species", guideline = "CLSI")
}\if{html}{\out{</div>}}
}
\item For \strong{interpreting a complete data set}, with automatic determination of MIC values, disk diffusion diameters, microorganism names or codes, and antimicrobial test results. This is done very simply by running \code{as.sir(your_data)}.
}
\strong{For points 2, 3 and 4: Use \code{\link[=sir_interpretation_history]{sir_interpretation_history()}}} to retrieve a \link{data.frame} (or \link[tibble:tibble]{tibble} if the \code{tibble} package is installed) with all results of the last \code{\link[=as.sir]{as.sir()}} call.
}
\subsection{Supported Guidelines}{
For interpreting MIC values as well as disk diffusion diameters, currently implemented guidelines are for \strong{clinical microbiology}: EUCAST 2011-2024 and CLSI 2011-2024, and for \strong{veterinary microbiology}: EUCAST 2021-2024 and CLSI 2019-2024.
Thus, the \code{guideline} argument must be set to e.g., \code{"EUCAST 2024"} or \code{"CLSI 2024"}. By simply using \code{"EUCAST"} (the default) or \code{"CLSI"} as input, the latest included version of that guideline will automatically be selected. You can set your own data set using the \code{reference_data} argument. The \code{guideline} argument will then be ignored.
You can set the default guideline with the package option \code{\link[=AMR-options]{AMR_guideline}} (e.g. in your \code{.Rprofile} file), such as:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ options(AMR_guideline = "CLSI")
options(AMR_guideline = "CLSI 2018")
options(AMR_guideline = "EUCAST 2020")
# or to reset:
options(AMR_guideline = NULL)
}\if{html}{\out{</div>}}
For veterinary guidelines, these might be the best options:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ options(AMR_guideline = "CLSI")
options(AMR_breakpoint_type = "animal")
}\if{html}{\out{</div>}}
When applying veterinary breakpoints (by setting \code{host} or by setting \code{breakpoint_type = "animal"}), the \href{https://clsi.org/standards/products/veterinary-medicine/documents/vet09/}{CLSI VET09 guideline} will be applied to cope with missing animal species-specific breakpoints.
}
\subsection{After Interpretation}{
After using \code{\link[=as.sir]{as.sir()}}, you can use the \code{\link[=eucast_rules]{eucast_rules()}} defined by EUCAST to (1) apply inferred susceptibility and resistance based on results of other antimicrobials and (2) apply intrinsic resistance based on taxonomic properties of a microorganism.
To determine which isolates are multi-drug resistant, be sure to run \code{\link[=mdro]{mdro()}} (which applies the MDR/PDR/XDR guideline from 2012 at default) on a data set that contains S/I/R values. Read more about \link[=mdro]{interpreting multidrug-resistant organisms here}.
}
\subsection{Machine-Readable Clinical Breakpoints}{
The repository of this package \href{https://github.com/msberends/AMR/blob/main/data-raw/clinical_breakpoints.txt}{contains a machine-readable version} of all guidelines. This is a CSV file consisting of 34 063 rows and 14 columns. This file is machine-readable, since it contains one row for every unique combination of the test method (MIC or disk diffusion), the antimicrobial drug and the microorganism. \strong{This allows for easy implementation of these rules in laboratory information systems (LIS)}. Note that it only contains interpretation guidelines for humans - interpretation guidelines from CLSI for animals were removed.
}
\subsection{Other}{
The function \code{\link[=is.sir]{is.sir()}} detects if the input contains class \code{sir}. If the input is a \link{data.frame}, it iterates over all columns and returns a \link{logical} vector.
The base R function \code{\link[=as.double]{as.double()}} can be used to retrieve quantitative values from a \code{sir} object: \code{"S"} = 1, \code{"I"}/\code{"SDD"} = 2, \code{"R"} = 3. All other values are rendered \code{NA} . \strong{Note:} Do not use \code{as.integer()}, since that (because of how R works internally) will return the factor level indices, and not these aforementioned quantitative values.
The function \code{\link[=is_sir_eligible]{is_sir_eligible()}} returns \code{TRUE} when a column contains at most 5\% invalid antimicrobial interpretations (not S and/or I and/or R and/or NI and/or SDD), and \code{FALSE} otherwise. The threshold of 5\% can be set with the \code{threshold} argument. If the input is a \link{data.frame}, it iterates over all columns and returns a \link{logical} vector.
}
\code{NA_sir_} is a missing value of the new \code{sir} class, analogous to e.g. base \R's \code{\link[base:NA]{NA_character_}}.
}
\section{Interpretation of SIR}{
In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (\url{https://www.eucast.org/newsiandr}):
\itemize{
\item \strong{S - Susceptible, standard dosing regimen}\cr
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.
\item \strong{I - Susceptible, increased exposure} \emph{\cr
A microorganism is categorised as "Susceptible, Increased exposure}" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.
\item \strong{R = Resistant}\cr
A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.
\itemize{
\item \emph{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.
}
}
This AMR package honours this insight. Use \code{\link[=susceptibility]{susceptibility()}} (equal to \code{\link[=proportion_SI]{proportion_SI()}}) to determine antimicrobial susceptibility and \code{\link[=count_susceptible]{count_susceptible()}} (equal to \code{\link[=count_SI]{count_SI()}}) to count susceptible isolates.
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
example_isolates
summary(example_isolates) # see all SIR results at a glance
# For INTERPRETING disk diffusion and MIC values -----------------------
# example data sets, with combined MIC values and disk zones
df_wide <- data.frame(
microorganism = "Escherichia coli",
amoxicillin = as.mic(8),
cipro = as.mic(0.256),
tobra = as.disk(16),
genta = as.disk(18),
ERY = "R"
)
df_long <- data.frame(
bacteria = rep("Escherichia coli", 4),
antibiotic = c("amoxicillin", "cipro", "tobra", "genta"),
mics = as.mic(c(0.01, 1, 4, 8)),
disks = as.disk(c(6, 10, 14, 18))
)
\donttest{
## Using dplyr -------------------------------------------------
if (require("dplyr")) {
# approaches that all work without additional arguments:
df_wide \%>\% mutate_if(is.mic, as.sir)
df_wide \%>\% mutate_if(function(x) is.mic(x) | is.disk(x), as.sir)
df_wide \%>\% mutate(across(where(is.mic), as.sir))
df_wide \%>\% mutate_at(vars(amoxicillin:tobra), as.sir)
df_wide \%>\% mutate(across(amoxicillin:tobra, as.sir))
# approaches that all work with additional arguments:
df_long \%>\%
# given a certain data type, e.g. MIC values
mutate_if(is.mic, as.sir,
mo = "bacteria",
ab = "antibiotic",
guideline = "CLSI")
df_long \%>\%
mutate(across(where(is.mic),
function(x) as.sir(x,
mo = "bacteria",
ab = "antibiotic",
guideline = "CLSI")))
df_wide \%>\%
# given certain columns, e.g. from 'cipro' to 'genta'
mutate_at(vars(cipro:genta), as.sir,
mo = "bacteria",
guideline = "CLSI")
df_wide \%>\%
mutate(across(cipro:genta,
function(x) as.sir(x,
mo = "bacteria",
guideline = "CLSI")))
# for veterinary breakpoints, add 'host':
df_long$animal_species <- c("cats", "dogs", "horses", "cattle")
df_long \%>\%
# given a certain data type, e.g. MIC values
mutate_if(is.mic, as.sir,
mo = "bacteria",
ab = "antibiotic",
host = "animal_species",
guideline = "CLSI")
df_long \%>\%
mutate(across(where(is.mic),
function(x) as.sir(x,
mo = "bacteria",
ab = "antibiotic",
host = "animal_species",
guideline = "CLSI")))
df_wide \%>\%
mutate_at(vars(cipro:genta), as.sir,
mo = "bacteria",
ab = "antibiotic",
host = "animal_species",
guideline = "CLSI")
df_wide \%>\%
mutate(across(cipro:genta,
function(x) as.sir(x,
mo = "bacteria",
host = "animal_species",
guideline = "CLSI")))
# to include information about urinary tract infections (UTI)
data.frame(mo = "E. coli",
nitrofuratoin = c("<= 2", 32),
from_the_bladder = c(TRUE, FALSE)) \%>\%
as.sir(uti = "from_the_bladder")
data.frame(mo = "E. coli",
nitrofuratoin = c("<= 2", 32),
specimen = c("urine", "blood")) \%>\%
as.sir() # automatically determines urine isolates
df_wide \%>\%
mutate_at(vars(cipro:genta), as.sir, mo = "E. coli", uti = TRUE)
}
## Using base R ------------------------------------------------
as.sir(df_wide)
# return a 'logbook' about the results:
sir_interpretation_history()
# for single values
as.sir(
x = as.mic(2),
mo = as.mo("S. pneumoniae"),
ab = "AMP",
guideline = "EUCAST"
)
as.sir(
x = as.disk(18),
mo = "Strep pneu", # `mo` will be coerced with as.mo()
ab = "ampicillin", # and `ab` with as.ab()
guideline = "EUCAST"
)
# For CLEANING existing SIR values ------------------------------------
as.sir(c("S", "SDD", "I", "R", "NI", "A", "B", "C"))
as.sir("<= 0.002; S") # will return "S"
sir_data <- as.sir(c(rep("S", 474), rep("I", 36), rep("R", 370)))
is.sir(sir_data)
plot(sir_data) # for percentages
barplot(sir_data) # for frequencies
# as common in R, you can use as.integer() to return factor indices:
as.integer(as.sir(c("S", "SDD", "I", "R", "NI", NA)))
# but for computational use, as.double() will return 1 for S, 2 for I/SDD, and 3 for R:
as.double(as.sir(c("S", "SDD", "I", "R", "NI", NA)))
# the dplyr way
if (require("dplyr")) {
example_isolates \%>\%
mutate_at(vars(PEN:RIF), as.sir)
# same:
example_isolates \%>\%
as.sir(PEN:RIF)
# fastest way to transform all columns with already valid AMR results to class `sir`:
example_isolates \%>\%
mutate_if(is_sir_eligible, as.sir)
# since dplyr 1.0.0, this can also be:
# example_isolates \%>\%
# mutate(across(where(is_sir_eligible), as.sir))
}
}
}
\seealso{
\code{\link[=as.mic]{as.mic()}}, \code{\link[=as.disk]{as.disk()}}, \code{\link[=as.mo]{as.mo()}}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/atc_online.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/atc_online.R
\name{atc_online_property}
\alias{atc_online_property}
\alias{atc_online_groups}
\alias{atc_online_ddd}
\alias{atc_online_ddd_units}
\title{Get ATC Properties from WHOCC Website}
\source{
\url{https://atcddd.fhi.no/atc_ddd_alterations__cumulative/ddd_alterations/abbrevations/}
}
\usage{
atc_online_property(
atc_code,
property,
administration = "O",
url = "https://atcddd.fhi.no/atc_ddd_index/?code=\%s&showdescription=no",
url_vet = "https://atcddd.fhi.no/atcvet/atcvet_index/?code=\%s&showdescription=no"
)
atc_online_groups(atc_code, ...)
atc_online_ddd(atc_code, ...)
atc_online_ddd_units(atc_code, ...)
}
\arguments{
\item{atc_code}{a \link{character} (vector) with ATC code(s) of antibiotics, will be coerced with \code{\link[=as.ab]{as.ab()}} and \code{\link[=ab_atc]{ab_atc()}} internally if not a valid ATC code}
\item{property}{property of an ATC code. Valid values are \code{"ATC"}, \code{"Name"}, \code{"DDD"}, \code{"U"} (\code{"unit"}), \code{"Adm.R"}, \code{"Note"} and \code{groups}. For this last option, all hierarchical groups of an ATC code will be returned, see \emph{Examples}.}
\item{administration}{type of administration when using \code{property = "Adm.R"}, see \emph{Details}}
\item{url}{url of website of the WHOCC. The sign \verb{\%s} can be used as a placeholder for ATC codes.}
\item{url_vet}{url of website of the WHOCC for veterinary medicine. The sign \verb{\%s} can be used as a placeholder for ATC_vet codes (that all start with "Q").}
\item{...}{arguments to pass on to \code{atc_property}}
}
\description{
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.
}
\details{
Options for argument \code{administration}:
\itemize{
\item \code{"Implant"} = Implant
\item \code{"Inhal"} = Inhalation
\item \code{"Instill"} = Instillation
\item \code{"N"} = nasal
\item \code{"O"} = oral
\item \code{"P"} = parenteral
\item \code{"R"} = rectal
\item \code{"SL"} = sublingual/buccal
\item \code{"TD"} = transdermal
\item \code{"V"} = vaginal
}
Abbreviations of return values when using \code{property = "U"} (unit):
\itemize{
\item \code{"g"} = gram
\item \code{"mg"} = milligram
\item \code{"mcg"} = microgram
\item \code{"U"} = unit
\item \code{"TU"} = thousand units
\item \code{"MU"} = million units
\item \code{"mmol"} = millimole
\item \code{"ml"} = millilitre (e.g. eyedrops)
}
\strong{N.B. This function requires an internet connection and only works if the following packages are installed: \code{curl}, \code{rvest}, \code{xml2}.}
}
\examples{
\donttest{
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
atc_online_property("J01CA04", "DDD", "P")
atc_online_property("J01CA04", property = "groups") # search hierarchical groups of amoxicillin
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/av_from_text.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/av_from_text.R
\name{av_from_text}
\alias{av_from_text}
\title{Retrieve Antiviral Drug Names and Doses from Clinical Text}
\usage{
av_from_text(
text,
type = c("drug", "dose", "administration"),
collapse = NULL,
translate_av = FALSE,
thorough_search = NULL,
info = interactive(),
...
)
}
\arguments{
\item{text}{text to analyse}
\item{type}{type of property to search for, either \code{"drug"}, \code{"dose"} or \code{"administration"}, see \emph{Examples}}
\item{collapse}{a \link{character} to pass on to \code{paste(, collapse = ...)} to only return one \link{character} per element of \code{text}, see \emph{Examples}}
\item{translate_av}{if \code{type = "drug"}: a column name of the \link{antivirals} data set to translate the antibiotic abbreviations to, using \code{\link[=av_property]{av_property()}}. The default is \code{FALSE}. Using \code{TRUE} is equal to using "name".}
\item{thorough_search}{a \link{logical} to indicate whether the input must be extensively searched for misspelling and other faulty input values. Setting this to \code{TRUE} will take considerably more time than when using \code{FALSE}. At default, it will turn \code{TRUE} when all input elements contain a maximum of three words.}
\item{info}{a \link{logical} to indicate whether a progress bar should be printed - the default is \code{TRUE} only in interactive mode}
\item{...}{arguments passed on to \code{\link[=as.av]{as.av()}}}
}
\value{
A \link{list}, or a \link{character} if \code{collapse} is not \code{NULL}
}
\description{
Use this function on e.g. clinical texts from health care records. It returns a \link{list} with all antiviral drugs, doses and forms of administration found in the texts.
}
\details{
This function is also internally used by \code{\link[=as.av]{as.av()}}, although it then only searches for the first drug name and will throw a note if more drug names could have been returned. Note: the \code{\link[=as.av]{as.av()}} function may use very long regular expression to match brand names of antiviral drugs. This may fail on some systems.
\subsection{Argument \code{type}}{
At default, the function will search for antiviral drug names. All text elements will be searched for official names, ATC codes and brand names. As it uses \code{\link[=as.av]{as.av()}} internally, it will correct for misspelling.
With \code{type = "dose"} (or similar, like "dosing", "doses"), all text elements will be searched for \link{numeric} values that are higher than 100 and do not resemble years. The output will be \link{numeric}. It supports any unit (g, mg, IE, etc.) and multiple values in one clinical text, see \emph{Examples}.
With \code{type = "administration"} (or abbreviations, like "admin", "adm"), all text elements will be searched for a form of drug administration. It supports the following forms (including common abbreviations): buccal, implant, inhalation, instillation, intravenous, nasal, oral, parenteral, rectal, sublingual, transdermal and vaginal. Abbreviations for oral (such as 'po', 'per os') will become "oral", all values for intravenous (such as 'iv', 'intraven') will become "iv". It supports multiple values in one clinical text, see \emph{Examples}.
}
\subsection{Argument \code{collapse}}{
Without using \code{collapse}, this function will return a \link{list}. This can be convenient to use e.g. inside a \code{mutate()}):\cr
\code{df \%>\% mutate(avx = av_from_text(clinical_text))}
The returned AV codes can be transformed to official names, groups, etc. with all \code{\link[=av_property]{av_*}} functions such as \code{\link[=av_name]{av_name()}} and \code{\link[=av_group]{av_group()}}, or by using the \code{translate_av} argument.
With using \code{collapse}, this function will return a \link{character}:\cr
\code{df \%>\% mutate(avx = av_from_text(clinical_text, collapse = "|"))}
}
}
\examples{
av_from_text("28/03/2020 valaciclovir po tid")
av_from_text("28/03/2020 valaciclovir po tid", type = "admin")
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/av_property.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/av_property.R
\name{av_property}
\alias{av_property}
\alias{av_name}
\alias{av_cid}
\alias{av_synonyms}
\alias{av_tradenames}
\alias{av_group}
\alias{av_atc}
\alias{av_loinc}
\alias{av_ddd}
\alias{av_ddd_units}
\alias{av_info}
\alias{av_url}
\title{Get Properties of an Antiviral Drug}
\usage{
av_name(x, language = get_AMR_locale(), tolower = FALSE, ...)
av_cid(x, ...)
av_synonyms(x, ...)
av_tradenames(x, ...)
av_group(x, language = get_AMR_locale(), ...)
av_atc(x, ...)
av_loinc(x, ...)
av_ddd(x, administration = "oral", ...)
av_ddd_units(x, administration = "oral", ...)
av_info(x, language = get_AMR_locale(), ...)
av_url(x, open = FALSE, ...)
av_property(x, property = "name", language = get_AMR_locale(), ...)
}
\arguments{
\item{x}{any (vector of) text that can be coerced to a valid antiviral drug code with \code{\link[=as.av]{as.av()}}}
\item{language}{language of the returned text - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{tolower}{a \link{logical} to indicate whether the first \link{character} of every output should be transformed to a lower case \link{character}.}
\item{...}{other arguments passed on to \code{\link[=as.av]{as.av()}}}
\item{administration}{way of administration, either \code{"oral"} or \code{"iv"}}
\item{open}{browse the URL using \code{\link[utils:browseURL]{utils::browseURL()}}}
\item{property}{one of the column names of one of the \link{antivirals} data set: \code{vector_or(colnames(antivirals), sort = FALSE)}.}
}
\value{
\itemize{
\item An \link{integer} in case of \code{\link[=av_cid]{av_cid()}}
\item A named \link{list} in case of \code{\link[=av_info]{av_info()}} and multiple \code{\link[=av_atc]{av_atc()}}/\code{\link[=av_synonyms]{av_synonyms()}}/\code{\link[=av_tradenames]{av_tradenames()}}
\item A \link{double} in case of \code{\link[=av_ddd]{av_ddd()}}
\item A \link{character} in all other cases
}
}
\description{
Use these functions to return a specific property of an antiviral drug from the \link{antivirals} data set. All input values will be evaluated internally with \code{\link[=as.av]{as.av()}}.
}
\details{
All output \link[=translate]{will be translated} where possible.
The function \code{\link[=av_url]{av_url()}} will return the direct URL to the official WHO website. A warning will be returned if the required ATC code is not available.
}
\section{Source}{
World Health Organization (WHO) Collaborating Centre for Drug Statistics Methodology: \url{https://atcddd.fhi.no/atc_ddd_index/}
European Commission Public Health PHARMACEUTICALS - COMMUNITY REGISTER: \url{https://ec.europa.eu/health/documents/community-register/html/reg_hum_atc.htm}
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
# all properties:
av_name("ACI")
av_atc("ACI")
av_cid("ACI")
av_synonyms("ACI")
av_tradenames("ACI")
av_group("ACI")
av_url("ACI")
# lowercase transformation
av_name(x = c("ACI", "VALA"))
av_name(x = c("ACI", "VALA"), tolower = TRUE)
# defined daily doses (DDD)
av_ddd("ACI", "oral")
av_ddd_units("ACI", "oral")
av_ddd("ACI", "iv")
av_ddd_units("ACI", "iv")
av_info("ACI") # all properties as a list
# all av_* functions use as.av() internally, so you can go from 'any' to 'any':
av_atc("ACI")
av_group("J05AB01")
av_loinc("abacavir")
av_name("29113-8")
av_name(135398513)
av_name("J05AB01")
}
\seealso{
\link{antivirals}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/availability.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/availability.R
\name{availability}
\alias{availability}
\title{Check Availability of Columns}
\usage{
availability(tbl, width = NULL)
}
\arguments{
\item{tbl}{a \link{data.frame} or \link{list}}
\item{width}{number of characters to present the visual availability - the default is filling the width of the console}
}
\value{
\link{data.frame} with column names of \code{tbl} as row names
}
\description{
Easy check for data availability of all columns in a data set. This makes it easy to get an idea of which antimicrobial combinations can be used for calculation with e.g. \code{\link[=susceptibility]{susceptibility()}} and \code{\link[=resistance]{resistance()}}.
}
\details{
The function returns a \link{data.frame} with columns \code{"resistant"} and \code{"visual_resistance"}. The values in that columns are calculated with \code{\link[=resistance]{resistance()}}.
}
\examples{
availability(example_isolates)
\donttest{
if (require("dplyr")) {
example_isolates \%>\%
filter(mo == as.mo("Escherichia coli")) \%>\%
select_if(is.sir) \%>\%
availability()
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/bug_drug_combinations.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bug_drug_combinations.R
\name{bug_drug_combinations}
\alias{bug_drug_combinations}
\alias{format.bug_drug_combinations}
\title{Determine Bug-Drug Combinations}
\usage{
bug_drug_combinations(x, col_mo = NULL, FUN = mo_shortname, ...)
\method{format}{bug_drug_combinations}(
x,
translate_ab = "name (ab, atc)",
language = get_AMR_locale(),
minimum = 30,
combine_SI = TRUE,
add_ab_group = TRUE,
remove_intrinsic_resistant = FALSE,
decimal.mark = getOption("OutDec"),
big.mark = ifelse(decimal.mark == ",", ".", ","),
...
)
}
\arguments{
\item{x}{a data set with antibiotic columns, such as \code{amox}, \code{AMX} and \code{AMC}}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{FUN}{the function to call on the \code{mo} column to transform the microorganism codes - the default is \code{\link[=mo_shortname]{mo_shortname()}}}
\item{...}{arguments passed on to \code{FUN}}
\item{translate_ab}{a \link{character} of length 1 containing column names of the \link{antibiotics} data set}
\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{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 \emph{Source}.}
\item{combine_SI}{a \link{logical} to indicate whether values S, SDD, and I should be summed, so resistance will be based on only R - the default is \code{TRUE}}
\item{add_ab_group}{a \link{logical} to indicate where the group of the antimicrobials must be included as a first column}
\item{remove_intrinsic_resistant}{\link{logical} to indicate that rows and columns with 100\% resistance for all tested antimicrobials must be removed from the table}
\item{decimal.mark}{the character to be used to indicate the numeric
decimal point.}
\item{big.mark}{character; if not empty used as mark between every
\code{big.interval} decimals \emph{before} (hence \code{big}) the
decimal point.}
}
\value{
The function \code{\link[=bug_drug_combinations]{bug_drug_combinations()}} returns a \link{data.frame} with columns "mo", "ab", "S", "SDD", "I", "R", and "total".
}
\description{
Determine antimicrobial resistance (AMR) of all bug-drug combinations in your data set where at least 30 (default) isolates are available per species. Use \code{\link[=format]{format()}} on the result to prettify it to a publishable/printable format, see \emph{Examples}.
}
\details{
The function \code{\link[=format]{format()}} calculates the resistance per bug-drug combination and returns a table ready for reporting/publishing. Use \code{combine_SI = TRUE} (default) to test R vs. S+I and \code{combine_SI = FALSE} to test R+I vs. S. This table can also directly be used in R Markdown / Quarto without the need for e.g. \code{\link[knitr:kable]{knitr::kable()}}.
}
\examples{
# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.
example_isolates
\donttest{
x <- bug_drug_combinations(example_isolates)
head(x)
format(x, translate_ab = "name (atc)")
# Use FUN to change to transformation of microorganism codes
bug_drug_combinations(example_isolates,
FUN = mo_gramstain
)
bug_drug_combinations(example_isolates,
FUN = function(x) {
ifelse(x == as.mo("Escherichia coli"),
"E. coli",
"Others"
)
}
)
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/clinical_breakpoints.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{clinical_breakpoints}
\alias{clinical_breakpoints}
\title{Data Set with Clinical Breakpoints for SIR Interpretation}
\format{
A \link[tibble:tibble]{tibble} with 34 063 observations and 14 variables:
\itemize{
\item \code{guideline}\cr Name of the guideline
\item \code{type}\cr Breakpoint type, either "ECOFF", "animal", or "human"
\item \code{host}\cr Host of infectious agent. This is mostly useful for veterinary breakpoints and is either "ECOFF", "aquatic", "cats", "cattle", "dogs", "horse", "human", "poultry", or "swine"
\item \code{method}\cr Testing method, either "DISK" or "MIC"
\item \code{site}\cr Body site for which the breakpoint must be applied, e.g. "Oral" or "Respiratory"
\item \code{mo}\cr Microbial ID, see \code{\link[=as.mo]{as.mo()}}
\item \code{rank_index}\cr Taxonomic rank index of \code{mo} from 1 (subspecies/infraspecies) to 5 (unknown microorganism)
\item \code{ab}\cr Antibiotic code as used by this package, EARS-Net and WHONET, see \code{\link[=as.ab]{as.ab()}}
\item \code{ref_tbl}\cr Info about where the guideline rule can be found
\item \code{disk_dose}\cr Dose of the used disk diffusion method
\item \code{breakpoint_S}\cr Lowest MIC value or highest number of millimetres that leads to "S"
\item \code{breakpoint_R}\cr Highest MIC value or lowest number of millimetres that leads to "R"
\item \code{uti}\cr A \link{logical} value (\code{TRUE}/\code{FALSE}) to indicate whether the rule applies to a urinary tract infection (UTI)
\item \code{is_SDD}\cr A \link{logical} value (\code{TRUE}/\code{FALSE}) to indicate whether the intermediate range between "S" and "R" should be interpreted as "SDD", instead of "I". This currently applies to 24 breakpoints.
}
}
\usage{
clinical_breakpoints
}
\description{
Data set containing clinical breakpoints to interpret MIC and disk diffusion to SIR values, according to international guidelines. This dataset contain breakpoints for humans, 7 different animal groups, and ECOFFs.
These breakpoints are currently implemented:
\itemize{
\item For \strong{clinical microbiology}: EUCAST 2011-2024 and CLSI 2011-2024;
\item For \strong{veterinary microbiology}: EUCAST 2021-2024 and CLSI 2019-2024;
\item For \strong{ECOFFs} (Epidemiological Cut-off Values): EUCAST 2020-2024 and CLSI 2022-2024.
}
Use \code{\link[=as.sir]{as.sir()}} to transform MICs or disks measurements to SIR values.
}
\details{
\subsection{Different types of breakpoints}{
Supported types of breakpoints are ECOFF, animal, and human. ECOFF (Epidemiological cut-off) values are used in antimicrobial susceptibility testing to differentiate between wild-type and non-wild-type strains of bacteria or fungi.
The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. Use \code{\link[=as.sir]{as.sir(..., breakpoint_type = ...)}} to interpret raw data using a specific breakpoint type, e.g. \code{as.sir(..., breakpoint_type = "ECOFF")} to use ECOFFs.
}
\subsection{Imported from WHONET}{
Clinical breakpoints in this package were validated through and imported from \href{https://whonet.org}{WHONET}, a free desktop Windows application developed and supported by the WHO Collaborating Centre for Surveillance of Antimicrobial Resistance. More can be read on \href{https://whonet.org}{their website}. The developers of WHONET and this \code{AMR} package have been in contact about sharing their work. We highly appreciate their great development on the WHONET software.
}
\subsection{Response from CLSI and EUCAST}{
The CEO of CLSI and the chairman of EUCAST have endorsed the work and public use of this \code{AMR} package (and consequently the use of their breakpoints) in June 2023, when future development of distributing clinical breakpoints was discussed in a meeting between CLSI, EUCAST, WHO, developers of WHONET software, and developers of this \code{AMR} package.
}
\subsection{Download}{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}. They allow for machine reading EUCAST and CLSI guidelines, which is almost impossible with the MS Excel and PDF files distributed by EUCAST and CLSI, though initiatives have started to overcome these burdens.
\strong{NOTE:} this \code{AMR} package (and the WHONET software as well) contains rather complex internal methods to apply the guidelines. For example, some breakpoints must be applied on certain species groups (which are in case of this package available through the \link{microorganisms.groups} data set). It is important that this is considered when using the breakpoints for own use.
}
}
\examples{
clinical_breakpoints
}
\seealso{
\link{intrinsic_resistant}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/count.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/count.R
\name{count}
\alias{count}
\alias{count_resistant}
\alias{count_susceptible}
\alias{count_S}
\alias{count_SI}
\alias{count_I}
\alias{count_IR}
\alias{count_R}
\alias{count_all}
\alias{n_sir}
\alias{count_df}
\title{Count Available Isolates}
\usage{
count_resistant(..., only_all_tested = FALSE)
count_susceptible(..., only_all_tested = FALSE)
count_S(..., only_all_tested = FALSE)
count_SI(..., only_all_tested = FALSE)
count_I(..., only_all_tested = FALSE)
count_IR(..., only_all_tested = FALSE)
count_R(..., only_all_tested = FALSE)
count_all(..., only_all_tested = FALSE)
n_sir(..., only_all_tested = FALSE)
count_df(
data,
translate_ab = "name",
language = get_AMR_locale(),
combine_SI = TRUE
)
}
\arguments{
\item{...}{one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed.}
\item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antibiotics, see section \emph{Combination Therapy} below}
\item{data}{a \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})}
\item{translate_ab}{a column name of the \link{antibiotics} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}}
\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}}
}
\value{
An \link{integer}
}
\description{
These functions can be used to count resistant/susceptible microbial isolates. All functions support quasiquotation with pipes, can be used in \code{summarise()} from the \code{dplyr} package and also support grouped variables, see \emph{Examples}.
\code{\link[=count_resistant]{count_resistant()}} should be used to count resistant isolates, \code{\link[=count_susceptible]{count_susceptible()}} should be used to count susceptible isolates.
}
\details{
These functions are meant to count isolates. Use the \code{\link[=resistance]{resistance()}}/\code{\link[=susceptibility]{susceptibility()}} functions to calculate microbial resistance/susceptibility.
The function \code{\link[=count_resistant]{count_resistant()}} is equal to the function \code{\link[=count_R]{count_R()}}. The function \code{\link[=count_susceptible]{count_susceptible()}} is equal to the function \code{\link[=count_SI]{count_SI()}}.
The function \code{\link[=n_sir]{n_sir()}} is an alias of \code{\link[=count_all]{count_all()}}. They can be used to count all available isolates, i.e. where all input antibiotics have an available result (S, I or R). Their use is equal to \code{n_distinct()}. Their function is equal to \code{count_susceptible(...) + count_resistant(...)}.
The function \code{\link[=count_df]{count_df()}} takes any variable from \code{data} that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) and counts the number of S's, I's and R's. It also supports grouped variables. The function \code{\link[=sir_df]{sir_df()}} works exactly like \code{\link[=count_df]{count_df()}}, but adds the percentage of S, I and R.
}
\section{Interpretation of SIR}{
In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (\url{https://www.eucast.org/newsiandr}):
\itemize{
\item \strong{S - Susceptible, standard dosing regimen}\cr
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.
\item \strong{I - Susceptible, increased exposure} \emph{\cr
A microorganism is categorised as "Susceptible, Increased exposure}" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.
\item \strong{R = Resistant}\cr
A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.
\itemize{
\item \emph{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.
}
}
This AMR package honours this insight. Use \code{\link[=susceptibility]{susceptibility()}} (equal to \code{\link[=proportion_SI]{proportion_SI()}}) to determine antimicrobial susceptibility and \code{\link[=count_susceptible]{count_susceptible()}} (equal to \code{\link[=count_SI]{count_SI()}}) to count susceptible isolates.
}
\section{Combination Therapy}{
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, Drug A and Drug B, about how \code{\link[=susceptibility]{susceptibility()}} works to calculate the \%SI:
\if{html}{\out{<div class="sourceCode">}}\preformatted{--------------------------------------------------------------------
only_all_tested = FALSE only_all_tested = TRUE
----------------------- -----------------------
Drug A Drug B include as include as include as include as
numerator denominator numerator denominator
-------- -------- ---------- ----------- ---------- -----------
S or I S or I X X X X
R S or I X X X X
<NA> S or I X X - -
S or I R X X X X
R R - X - X
<NA> R - - - -
S or I <NA> X X - -
R <NA> - - - -
<NA> <NA> - - - -
--------------------------------------------------------------------
}\if{html}{\out{</div>}}
Please note that, in combination therapies, for \code{only_all_tested = TRUE} applies that:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ count_S() + count_I() + count_R() = count_all()
proportion_S() + proportion_I() + proportion_R() = 1
}\if{html}{\out{</div>}}
and that, in combination therapies, for \code{only_all_tested = FALSE} applies that:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ count_S() + count_I() + count_R() >= count_all()
proportion_S() + proportion_I() + proportion_R() >= 1
}\if{html}{\out{</div>}}
Using \code{only_all_tested} has no impact when only using one antibiotic as input.
}
\examples{
# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.
# base R ------------------------------------------------------------
count_resistant(example_isolates$AMX) # counts "R"
count_susceptible(example_isolates$AMX) # counts "S" and "I"
count_all(example_isolates$AMX) # counts "S", "I" and "R"
# be more specific
count_S(example_isolates$AMX)
count_SI(example_isolates$AMX)
count_I(example_isolates$AMX)
count_IR(example_isolates$AMX)
count_R(example_isolates$AMX)
# Count all available isolates
count_all(example_isolates$AMX)
n_sir(example_isolates$AMX)
# n_sir() is an alias of count_all().
# Since it counts all available isolates, you can
# calculate back to count e.g. susceptible isolates.
# These results are the same:
count_susceptible(example_isolates$AMX)
susceptibility(example_isolates$AMX) * n_sir(example_isolates$AMX)
# dplyr -------------------------------------------------------------
\donttest{
if (require("dplyr")) {
example_isolates \%>\%
group_by(ward) \%>\%
summarise(
R = count_R(CIP),
I = count_I(CIP),
S = count_S(CIP),
n1 = count_all(CIP), # the actual total; sum of all three
n2 = n_sir(CIP), # same - analogous to n_distinct
total = n()
) # NOT the number of tested isolates!
# Number of available isolates for a whole antibiotic class
# (i.e., in this data set columns GEN, TOB, AMK, KAN)
example_isolates \%>\%
group_by(ward) \%>\%
summarise(across(aminoglycosides(), n_sir))
# Count co-resistance between amoxicillin/clav acid and gentamicin,
# so we can see that combination therapy does a lot more than mono therapy.
# Please mind that `susceptibility()` calculates percentages right away instead.
example_isolates \%>\% count_susceptible(AMC) # 1433
example_isolates \%>\% count_all(AMC) # 1879
example_isolates \%>\% count_susceptible(GEN) # 1399
example_isolates \%>\% count_all(GEN) # 1855
example_isolates \%>\% count_susceptible(AMC, GEN) # 1764
example_isolates \%>\% count_all(AMC, GEN) # 1936
# Get number of S+I vs. R immediately of selected columns
example_isolates \%>\%
select(AMX, CIP) \%>\%
count_df(translate = FALSE)
# It also supports grouping variables
example_isolates \%>\%
select(ward, AMX, CIP) \%>\%
group_by(ward) \%>\%
count_df(translate = FALSE)
}
}
}
\seealso{
\code{\link[=proportion]{proportion_*}} to calculate microbial resistance and susceptibility.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/custom_eucast_rules.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/custom_eucast_rules.R
\name{custom_eucast_rules}
\alias{custom_eucast_rules}
\title{Define Custom EUCAST Rules}
\usage{
custom_eucast_rules(...)
}
\arguments{
\item{...}{rules in \link[base:tilde]{formula} notation, see below for instructions, and in \emph{Examples}}
}
\value{
A \link{list} containing the custom rules
}
\description{
Define custom EUCAST rules for your organisation or specific analysis and use the output of this function in \code{\link[=eucast_rules]{eucast_rules()}}.
}
\details{
Some organisations have their own adoption of EUCAST rules. This function can be used to define custom EUCAST rules to be used in the \code{\link[=eucast_rules]{eucast_rules()}} function.
}
\section{How it works}{
\subsection{Basics}{
If you are familiar with the \code{\link[dplyr:case_when]{case_when()}} function of the \code{dplyr} package, you will recognise the input method to set your own rules. Rules must be set using what \R considers to be the 'formula notation'. The rule itself is written \emph{before} the tilde (\code{~}) and the consequence of the rule is written \emph{after} the tilde:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(TZP == "S" ~ aminopenicillins == "S",
TZP == "R" ~ aminopenicillins == "R")
}\if{html}{\out{</div>}}
These are two custom EUCAST rules: if TZP (piperacillin/tazobactam) is "S", all aminopenicillins (ampicillin and amoxicillin) must be made "S", and if TZP is "R", aminopenicillins must be made "R". These rules can also be printed to the console, so it is immediately clear how they work:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x
#> A set of custom EUCAST rules:
#>
#> 1. If TZP is "S" then set to S :
#> amoxicillin (AMX), ampicillin (AMP)
#>
#> 2. If TZP is "R" then set to R :
#> amoxicillin (AMX), ampicillin (AMP)
}\if{html}{\out{</div>}}
The rules (the part \emph{before} the tilde, in above example \code{TZP == "S"} and \code{TZP == "R"}) must be evaluable in your data set: it should be able to run as a filter in your data set without errors. This means for the above example that the column \code{TZP} must exist. We will create a sample data set and test the rules set:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{df <- data.frame(mo = c("Escherichia coli", "Klebsiella pneumoniae"),
TZP = as.sir("R"),
ampi = as.sir("S"),
cipro = as.sir("S"))
df
#> mo TZP ampi cipro
#> 1 Escherichia coli R S S
#> 2 Klebsiella pneumoniae R S S
eucast_rules(df, rules = "custom", custom_rules = x, info = FALSE)
#> mo TZP ampi cipro
#> 1 Escherichia coli R R S
#> 2 Klebsiella pneumoniae R R S
}\if{html}{\out{</div>}}
}
\subsection{Using taxonomic properties in rules}{
There is one exception in columns used for the rules: all column names of the \link{microorganisms} data set can also be used, but do not have to exist in the data set. These column names are: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "oxygen_tolerance", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "mycobank", "mycobank_parent", "mycobank_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence", and "snomed". Thus, this next example will work as well, despite the fact that the \code{df} data set does not contain a column \code{genus}:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{y <- custom_eucast_rules(TZP == "S" & genus == "Klebsiella" ~ aminopenicillins == "S",
TZP == "R" & genus == "Klebsiella" ~ aminopenicillins == "R")
eucast_rules(df, rules = "custom", custom_rules = y, info = FALSE)
#> mo TZP ampi cipro
#> 1 Escherichia coli R S S
#> 2 Klebsiella pneumoniae R R S
}\if{html}{\out{</div>}}
}
\subsection{Usage of multiple antibiotics and antibiotic group names}{
You can define antibiotic groups instead of single antibiotics for the rule consequence, which is the part \emph{after} the tilde (~). In the examples above, the antibiotic group \code{aminopenicillins} includes both ampicillin and amoxicillin.
Rules can also be applied to multiple antibiotics and antibiotic groups simultaneously. Use the \code{c()} function to combine multiple antibiotics. For instance, the following example sets all aminopenicillins and ureidopenicillins to "R" if column TZP (piperacillin/tazobactam) is "R":
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(TZP == "R" ~ c(aminopenicillins, ureidopenicillins) == "R")
x
#> A set of custom EUCAST rules:
#>
#> 1. If TZP is "R" then set to "R":
#> amoxicillin (AMX), ampicillin (AMP), azlocillin (AZL), mezlocillin (MEZ), piperacillin (PIP), piperacillin/tazobactam (TZP)
}\if{html}{\out{</div>}}
These 31 antibiotic groups are allowed in the rules (case-insensitive) and can be used in any combination:
\itemize{
\item aminoglycosides\cr(amikacin, amikacin/fosfomycin, apramycin, arbekacin, astromicin, bekanamycin, dibekacin, framycetin, gentamicin, gentamicin-high, habekacin, hygromycin, isepamicin, kanamycin, kanamycin-high, kanamycin/cephalexin, micronomicin, neomycin, netilmicin, pentisomicin, plazomicin, propikacin, ribostamycin, sisomicin, streptoduocin, streptomycin, streptomycin-high, tobramycin, and tobramycin-high)
\item aminopenicillins\cr(amoxicillin and ampicillin)
\item antifungals\cr(amorolfine, amphotericin B, amphotericin B-high, anidulafungin, butoconazole, caspofungin, ciclopirox, clotrimazole, econazole, fluconazole, flucytosine, fosfluconazole, griseofulvin, hachimycin, ibrexafungerp, isavuconazole, isoconazole, itraconazole, ketoconazole, manogepix, micafungin, miconazole, nystatin, oteseconazole, pimaricin, posaconazole, rezafungin, ribociclib, sulconazole, terbinafine, terconazole, and voriconazole)
\item antimycobacterials\cr(4-aminosalicylic acid, calcium aminosalicylate, capreomycin, clofazimine, delamanid, enviomycin, ethambutol, ethambutol/isoniazid, ethionamide, isoniazid, isoniazid/sulfamethoxazole/trimethoprim/pyridoxine, morinamide, p-aminosalicylic acid, pretomanid, protionamide, pyrazinamide, rifabutin, rifampicin, rifampicin/ethambutol/isoniazid, rifampicin/isoniazid, rifampicin/pyrazinamide/ethambutol/isoniazid, rifampicin/pyrazinamide/isoniazid, rifamycin, rifapentine, simvastatin/fenofibrate, sodium aminosalicylate, streptomycin/isoniazid, terizidone, thioacetazone, thioacetazone/isoniazid, tiocarlide, and viomycin)
\item betalactams\cr(amoxicillin, amoxicillin/clavulanic acid, amoxicillin/sulbactam, ampicillin, ampicillin/sulbactam, apalcillin, aspoxicillin, avibactam, azidocillin, azlocillin, aztreonam, aztreonam/avibactam, aztreonam/nacubactam, bacampicillin, benzathine benzylpenicillin, benzathine phenoxymethylpenicillin, benzylpenicillin, biapenem, carbenicillin, carindacillin, cefacetrile, cefaclor, cefadroxil, cefalexin, cefaloridine, cefalotin, cefamandole, cefapirin, cefatrizine, cefazedone, cefazolin, cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefepime, cefepime/clavulanic acid, cefepime/nacubactam, cefepime/tazobactam, cefetamet, cefetamet pivoxil, cefetecol, cefetrizole, cefiderocol, cefixime, cefmenoxime, cefmetazole, cefodizime, cefonicid, cefoperazone, cefoperazone/sulbactam, ceforanide, cefoselis, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotetan, cefotiam, cefotiam hexetil, cefovecin, cefoxitin, cefoxitin screening, cefozopran, cefpimizole, cefpiramide, cefpirome, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefprozil, cefquinome, cefroxadine, cefsulodin, cefsumide, ceftaroline, ceftaroline/avibactam, ceftazidime, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftezole, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftobiprole, ceftobiprole medocaril, ceftolozane/tazobactam, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, cefuroxime, cefuroxime axetil, cephradine, ciclacillin, clometocillin, cloxacillin, dicloxacillin, doripenem, epicillin, ertapenem, flucloxacillin, hetacillin, imipenem, imipenem/EDTA, imipenem/relebactam, latamoxef, lenampicillin, loracarbef, mecillinam, meropenem, meropenem/nacubactam, meropenem/vaborbactam, metampicillin, meticillin, mezlocillin, mezlocillin/sulbactam, nacubactam, nafcillin, oxacillin, panipenem, penamecillin, penicillin/novobiocin, penicillin/sulbactam, pheneticillin, phenoxymethylpenicillin, piperacillin, piperacillin/sulbactam, piperacillin/tazobactam, piridicillin, pivampicillin, pivmecillinam, procaine benzylpenicillin, propicillin, razupenem, ritipenem, ritipenem acoxil, sarmoxicillin, sulbactam, sulbenicillin, sultamicillin, talampicillin, tazobactam, tebipenem, temocillin, ticarcillin, and ticarcillin/clavulanic acid)
\item betalactams_with_inhibitor\cr(amoxicillin/clavulanic acid, amoxicillin/sulbactam, ampicillin/sulbactam, aztreonam/avibactam, aztreonam/nacubactam, cefepime/clavulanic acid, cefepime/nacubactam, cefepime/tazobactam, cefoperazone/sulbactam, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefpodoxime/clavulanic acid, ceftaroline/avibactam, ceftazidime/avibactam, ceftazidime/clavulanic acid, ceftolozane/tazobactam, ceftriaxone/beta-lactamase inhibitor, imipenem/relebactam, meropenem/nacubactam, meropenem/vaborbactam, mezlocillin/sulbactam, penicillin/novobiocin, penicillin/sulbactam, piperacillin/sulbactam, piperacillin/tazobactam, and ticarcillin/clavulanic acid)
\item carbapenems\cr(biapenem, doripenem, ertapenem, imipenem, imipenem/EDTA, imipenem/relebactam, meropenem, meropenem/nacubactam, meropenem/vaborbactam, panipenem, razupenem, ritipenem, ritipenem acoxil, and tebipenem)
\item cephalosporins\cr(cefacetrile, cefaclor, cefadroxil, cefalexin, cefaloridine, cefalotin, cefamandole, cefapirin, cefatrizine, cefazedone, cefazolin, cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefepime, cefepime/clavulanic acid, cefepime/tazobactam, cefetamet, cefetamet pivoxil, cefetecol, cefetrizole, cefiderocol, cefixime, cefmenoxime, cefmetazole, cefodizime, cefonicid, cefoperazone, cefoperazone/sulbactam, ceforanide, cefoselis, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotetan, cefotiam, cefotiam hexetil, cefovecin, cefoxitin, cefoxitin screening, cefozopran, cefpimizole, cefpiramide, cefpirome, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefprozil, cefquinome, cefroxadine, cefsulodin, cefsumide, ceftaroline, ceftaroline/avibactam, ceftazidime, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftezole, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftobiprole, ceftobiprole medocaril, ceftolozane/tazobactam, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, cefuroxime, cefuroxime axetil, cephradine, latamoxef, and loracarbef)
\item cephalosporins_1st\cr(cefacetrile, cefadroxil, cefalexin, cefaloridine, cefalotin, cefapirin, cefatrizine, cefazedone, cefazolin, cefroxadine, ceftezole, and cephradine)
\item cephalosporins_2nd\cr(cefaclor, cefamandole, cefmetazole, cefonicid, ceforanide, cefotetan, cefotiam, cefoxitin, cefoxitin screening, cefprozil, cefuroxime, cefuroxime axetil, and loracarbef)
\item cephalosporins_3rd\cr(cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefetamet, cefetamet pivoxil, cefixime, cefmenoxime, cefodizime, cefoperazone, cefoperazone/sulbactam, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotiam hexetil, cefovecin, cefpimizole, cefpiramide, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefsulodin, ceftazidime, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, and latamoxef)
\item cephalosporins_4th\cr(cefepime, cefepime/clavulanic acid, cefepime/tazobactam, cefetecol, cefoselis, cefozopran, cefpirome, and cefquinome)
\item cephalosporins_5th\cr(ceftaroline, ceftaroline/avibactam, ceftobiprole, ceftobiprole medocaril, and ceftolozane/tazobactam)
\item cephalosporins_except_caz\cr(cefacetrile, cefaclor, cefadroxil, cefalexin, cefaloridine, cefalotin, cefamandole, cefapirin, cefatrizine, cefazedone, cefazolin, cefcapene, cefcapene pivoxil, cefdinir, cefditoren, cefditoren pivoxil, cefepime, cefepime/clavulanic acid, cefepime/tazobactam, cefetamet, cefetamet pivoxil, cefetecol, cefetrizole, cefiderocol, cefixime, cefmenoxime, cefmetazole, cefodizime, cefonicid, cefoperazone, cefoperazone/sulbactam, ceforanide, cefoselis, cefotaxime, cefotaxime/clavulanic acid, cefotaxime/sulbactam, cefotetan, cefotiam, cefotiam hexetil, cefovecin, cefoxitin, cefoxitin screening, cefozopran, cefpimizole, cefpiramide, cefpirome, cefpodoxime, cefpodoxime proxetil, cefpodoxime/clavulanic acid, cefprozil, cefquinome, cefroxadine, cefsulodin, cefsumide, ceftaroline, ceftaroline/avibactam, ceftazidime/avibactam, ceftazidime/clavulanic acid, cefteram, cefteram pivoxil, ceftezole, ceftibuten, ceftiofur, ceftizoxime, ceftizoxime alapivoxil, ceftobiprole, ceftobiprole medocaril, ceftolozane/tazobactam, ceftriaxone, ceftriaxone/beta-lactamase inhibitor, cefuroxime, cefuroxime axetil, cephradine, latamoxef, and loracarbef)
\item fluoroquinolones\cr(besifloxacin, ciprofloxacin, clinafloxacin, danofloxacin, delafloxacin, difloxacin, enoxacin, enrofloxacin, finafloxacin, fleroxacin, garenoxacin, gatifloxacin, gemifloxacin, grepafloxacin, lascufloxacin, levofloxacin, levonadifloxacin, lomefloxacin, marbofloxacin, metioxate, miloxacin, moxifloxacin, nadifloxacin, nifuroquine, norfloxacin, ofloxacin, orbifloxacin, pazufloxacin, pefloxacin, pradofloxacin, premafloxacin, prulifloxacin, rufloxacin, sarafloxacin, sitafloxacin, sparfloxacin, temafloxacin, tilbroquinol, tioxacin, tosufloxacin, and trovafloxacin)
\item glycopeptides\cr(avoparcin, dalbavancin, norvancomycin, oritavancin, ramoplanin, teicoplanin, teicoplanin-macromethod, telavancin, vancomycin, and vancomycin-macromethod)
\item glycopeptides_except_lipo\cr(avoparcin, norvancomycin, ramoplanin, teicoplanin, teicoplanin-macromethod, vancomycin, and vancomycin-macromethod)
\item lincosamides\cr(acetylmidecamycin, acetylspiramycin, clindamycin, clindamycin inducible screening, gamithromycin, kitasamycin, lincomycin, meleumycin, nafithromycin, pirlimycin, primycin, solithromycin, tildipirosin, tilmicosin, tulathromycin, tylosin, and tylvalosin)
\item lipoglycopeptides\cr(dalbavancin, oritavancin, and telavancin)
\item macrolides\cr(acetylmidecamycin, acetylspiramycin, azithromycin, clarithromycin, dirithromycin, erythromycin, flurithromycin, gamithromycin, josamycin, kitasamycin, meleumycin, midecamycin, miocamycin, nafithromycin, oleandomycin, pirlimycin, primycin, rokitamycin, roxithromycin, solithromycin, spiramycin, telithromycin, tildipirosin, tilmicosin, troleandomycin, tulathromycin, tylosin, and tylvalosin)
\item nitrofurans\cr(furazidin, furazolidone, nifurtoinol, nitrofurantoin, and nitrofurazone)
\item oxazolidinones\cr(cadazolid, cycloserine, linezolid, tedizolid, and thiacetazone)
\item penicillins\cr(amoxicillin, amoxicillin/clavulanic acid, amoxicillin/sulbactam, ampicillin, ampicillin/sulbactam, apalcillin, aspoxicillin, avibactam, azidocillin, azlocillin, aztreonam, aztreonam/avibactam, aztreonam/nacubactam, bacampicillin, benzathine benzylpenicillin, benzathine phenoxymethylpenicillin, benzylpenicillin, carbenicillin, carindacillin, cefepime/nacubactam, ciclacillin, clometocillin, cloxacillin, dicloxacillin, epicillin, flucloxacillin, hetacillin, lenampicillin, mecillinam, metampicillin, meticillin, mezlocillin, mezlocillin/sulbactam, nacubactam, nafcillin, oxacillin, penamecillin, penicillin/novobiocin, penicillin/sulbactam, pheneticillin, phenoxymethylpenicillin, piperacillin, piperacillin/sulbactam, piperacillin/tazobactam, piridicillin, pivampicillin, pivmecillinam, procaine benzylpenicillin, propicillin, sarmoxicillin, sulbactam, sulbenicillin, sultamicillin, talampicillin, tazobactam, temocillin, ticarcillin, and ticarcillin/clavulanic acid)
\item polymyxins\cr(colistin, polymyxin B, and polymyxin B/polysorbate 80)
\item quinolones\cr(besifloxacin, cinoxacin, ciprofloxacin, ciprofloxacin/metronidazole, ciprofloxacin/ornidazole, ciprofloxacin/tinidazole, clinafloxacin, danofloxacin, delafloxacin, difloxacin, enoxacin, enrofloxacin, finafloxacin, fleroxacin, flumequine, garenoxacin, gatifloxacin, gemifloxacin, grepafloxacin, lascufloxacin, levofloxacin, levonadifloxacin, lomefloxacin, marbofloxacin, metioxate, miloxacin, moxifloxacin, nadifloxacin, nalidixic acid, nemonoxacin, nifuroquine, nitroxoline, norfloxacin, ofloxacin, orbifloxacin, oxolinic acid, pazufloxacin, pefloxacin, pipemidic acid, piromidic acid, pradofloxacin, premafloxacin, prulifloxacin, rosoxacin, rufloxacin, sarafloxacin, sitafloxacin, sparfloxacin, temafloxacin, tilbroquinol, tioxacin, tosufloxacin, and trovafloxacin)
\item rifamycins\cr(rifabutin, rifampicin, rifampicin/ethambutol/isoniazid, rifampicin/isoniazid, rifampicin/pyrazinamide/ethambutol/isoniazid, rifampicin/pyrazinamide/isoniazid, rifamycin, and rifapentine)
\item streptogramins\cr(pristinamycin and quinupristin/dalfopristin)
\item tetracyclines\cr(cetocycline, chlortetracycline, clomocycline, demeclocycline, doxycycline, eravacycline, lymecycline, metacycline, minocycline, omadacycline, oxytetracycline, penimepicycline, rolitetracycline, sarecycline, tetracycline, and tigecycline)
\item tetracyclines_except_tgc\cr(cetocycline, chlortetracycline, clomocycline, demeclocycline, doxycycline, eravacycline, lymecycline, metacycline, minocycline, omadacycline, oxytetracycline, penimepicycline, rolitetracycline, sarecycline, and tetracycline)
\item trimethoprims\cr(brodimoprim, sulfadiazine, sulfadiazine/tetroxoprim, sulfadiazine/trimethoprim, sulfadimethoxine, sulfadimidine, sulfadimidine/trimethoprim, sulfafurazole, sulfaisodimidine, sulfalene, sulfamazone, sulfamerazine, sulfamerazine/trimethoprim, sulfamethizole, sulfamethoxazole, sulfamethoxypyridazine, sulfametomidine, sulfametoxydiazine, sulfametrole/trimethoprim, sulfamoxole, sulfamoxole/trimethoprim, sulfanilamide, sulfaperin, sulfaphenazole, sulfapyridine, sulfathiazole, sulfathiourea, trimethoprim, and trimethoprim/sulfamethoxazole)
\item ureidopenicillins\cr(azlocillin, mezlocillin, piperacillin, and piperacillin/tazobactam)
}
}
}
\examples{
x <- custom_eucast_rules(
AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I"
)
x
# run the custom rule set (verbose = TRUE will return a logbook instead of the data set):
eucast_rules(example_isolates,
rules = "custom",
custom_rules = x,
info = FALSE,
verbose = TRUE
)
# combine rule sets
x2 <- c(
x,
custom_eucast_rules(TZP == "R" ~ carbapenems == "R")
)
x2
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/dosage.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{dosage}
\alias{dosage}
\title{Data Set with Treatment Dosages as Defined by EUCAST}
\format{
A \link[tibble:tibble]{tibble} with 503 observations and 9 variables:
\itemize{
\item \code{ab}\cr Antibiotic ID as used in this package (such as \code{AMC}), using the official EARS-Net (European Antimicrobial Resistance Surveillance Network) codes where available
\item \code{name}\cr Official name of the antimicrobial drug as used by WHONET/EARS-Net or the WHO
\item \code{type}\cr Type of the dosage, either "high_dosage", "standard_dosage", or "uncomplicated_uti"
\item \code{dose}\cr Dose, such as "2 g" or "25 mg/kg"
\item \code{dose_times}\cr Number of times a dose must be administered
\item \code{administration}\cr Route of administration, either "im", "iv", or "oral"
\item \code{notes}\cr Additional dosage notes
\item \code{original_txt}\cr Original text in the PDF file of EUCAST
\item \code{eucast_version}\cr Version number of the EUCAST Clinical Breakpoints guideline to which these dosages apply, either 13, 12, or 11
}
}
\usage{
dosage
}
\description{
EUCAST breakpoints used in this package are based on the dosages in this data set. They can be retrieved with \code{\link[=eucast_dosage]{eucast_dosage()}}.
}
\details{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
dosage
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/eucast_rules.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eucast_rules.R
\name{eucast_rules}
\alias{eucast_rules}
\alias{EUCAST}
\alias{eucast_dosage}
\title{Apply EUCAST Rules}
\source{
\itemize{
\item EUCAST Expert Rules. Version 2.0, 2012.\cr
Leclercq et al. \strong{EUCAST expert rules in antimicrobial susceptibility testing.} \emph{Clin Microbiol Infect.} 2013;19(2):141-60; \doi{https://doi.org/10.1111/j.1469-0691.2011.03703.x}
\item EUCAST Expert Rules, Intrinsic Resistance and Exceptional Phenotypes Tables. Version 3.1, 2016. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/Expert_rules_intrinsic_exceptional_V3.1.pdf}{(link)}
\item EUCAST Intrinsic Resistance and Unusual Phenotypes. Version 3.2, 2020. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2020/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.2_20200225.pdf}{(link)}
\item EUCAST Intrinsic Resistance and Unusual Phenotypes. Version 3.3, 2021. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2021/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.3_20211018.pdf}{(link)}
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 9.0, 2019. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_9.0_Breakpoint_Tables.xlsx}{(link)}
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 10.0, 2020. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_10.0_Breakpoint_Tables.xlsx}{(link)}
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 11.0, 2021. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_11.0_Breakpoint_Tables.xlsx}{(link)}
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 12.0, 2022. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_12.0_Breakpoint_Tables.xlsx}{(link)}
}
}
\usage{
eucast_rules(
x,
col_mo = NULL,
info = interactive(),
rules = getOption("AMR_eucastrules", default = c("breakpoints", "expert")),
verbose = FALSE,
version_breakpoints = 12,
version_expertrules = 3.3,
ampc_cephalosporin_resistance = NA,
only_sir_columns = FALSE,
custom_rules = NULL,
...
)
eucast_dosage(ab, administration = "iv", version_breakpoints = 12)
}
\arguments{
\item{x}{a data set with antibiotic columns, such as \code{amox}, \code{AMX} and \code{AMC}}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions}
\item{rules}{a \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expert")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_eucastrules}}: \code{options(AMR_eucastrules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.}
\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time.}
\item{version_breakpoints}{the version number to use for the EUCAST Clinical Breakpoints guideline. Can be "12.0", "11.0", or "10.0".}
\item{version_expertrules}{the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".}
\item{ampc_cephalosporin_resistance}{a \link{character} value that should be applied to cefotaxime, ceftriaxone and ceftazidime for AmpC de-repressed cephalosporin-resistant mutants - the default is \code{NA}. Currently only works when \code{version_expertrules} is \code{3.2} and higher; these version of '\emph{EUCAST Expert Rules on Enterobacterales}' state that results of cefotaxime, ceftriaxone and ceftazidime should be reported with a note, or results should be suppressed (emptied) for these three drugs. A value of \code{NA} (the default) for this argument will remove results for these three drugs, while e.g. a value of \code{"R"} will make the results for these drugs resistant. Use \code{NULL} or \code{FALSE} to not alter results for these three drugs of AmpC de-repressed cephalosporin-resistant mutants. Using \code{TRUE} is equal to using \code{"R"}. \cr For \emph{EUCAST Expert Rules} v3.2, this rule applies to: \emph{Citrobacter braakii}, \emph{Citrobacter freundii}, \emph{Citrobacter gillenii}, \emph{Citrobacter murliniae}, \emph{Citrobacter rodenticum}, \emph{Citrobacter sedlakii}, \emph{Citrobacter werkmanii}, \emph{Citrobacter youngae}, \emph{Enterobacter}, \emph{Hafnia alvei}, \emph{Klebsiella aerogenes}, \emph{Morganella morganii}, \emph{Providencia}, and \emph{Serratia}.}
\item{only_sir_columns}{a \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})}
\item{custom_rules}{custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}}
\item{...}{column name of an antibiotic, see section \emph{Antibiotics} below}
\item{ab}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}}
\item{administration}{route of administration, either "im", "iv", or "oral"}
}
\value{
The input of \code{x}, possibly with edited values of antibiotics. Or, if \code{verbose = TRUE}, a \link{data.frame} with all original and new values of the affected bug-drug combinations.
}
\description{
Apply rules for clinical breakpoints and intrinsic resistance as defined by the European Committee on Antimicrobial Susceptibility Testing (EUCAST, \url{https://www.eucast.org}), see \emph{Source}. Use \code{\link[=eucast_dosage]{eucast_dosage()}} to get a \link{data.frame} with advised dosages of a certain bug-drug combination, which is based on the \link{dosage} data set.
To improve the interpretation of the antibiogram before EUCAST rules are applied, some non-EUCAST rules can applied at default, see \emph{Details}.
}
\details{
\strong{Note:} This function does not translate MIC values to SIR values. Use \code{\link[=as.sir]{as.sir()}} for that. \cr
\strong{Note:} When ampicillin (AMP, J01CA01) is not available but amoxicillin (AMX, J01CA04) is, the latter will be used for all rules where there is a dependency on ampicillin. These drugs are interchangeable when it comes to expression of antimicrobial resistance. \cr
The file containing all EUCAST rules is located here: \url{https://github.com/msberends/AMR/blob/main/data-raw/eucast_rules.tsv}. \strong{Note:} Old taxonomic names are replaced with the current taxonomy where applicable. For example, \emph{Ochrobactrum anthropi} was renamed to \emph{Brucella anthropi} in 2020; the original EUCAST rules v3.1 and v3.2 did not yet contain this new taxonomic name. The \code{AMR} package contains the full microbial taxonomy updated until June 24th, 2024, see \link{microorganisms}.
\subsection{Custom Rules}{
Custom rules can be created using \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}, e.g.:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I")
eucast_rules(example_isolates, rules = "custom", custom_rules = x)
}\if{html}{\out{</div>}}
}
\subsection{'Other' Rules}{
Before further processing, two non-EUCAST rules about drug combinations can be applied to improve the efficacy of the EUCAST rules, and the reliability of your data (analysis). These rules are:
\enumerate{
\item A drug \strong{with} enzyme inhibitor will be set to S if the same drug \strong{without} enzyme inhibitor is S
\item A drug \strong{without} enzyme inhibitor will be set to R if the same drug \strong{with} enzyme inhibitor is R
}
Important examples include amoxicillin and amoxicillin/clavulanic acid, and trimethoprim and trimethoprim/sulfamethoxazole. Needless to say, for these rules to work, both drugs must be available in the data set.
Since these rules are not officially approved by EUCAST, they are not applied at default. To use these rules, include \code{"other"} to the \code{rules} argument, or use \code{eucast_rules(..., rules = "all")}. You can also set the package option \code{\link[=AMR-options]{AMR_eucastrules}}, i.e. run \code{options(AMR_eucastrules = "all")}.
}
}
\section{Antibiotics}{
To define antibiotics column names, leave as it is to determine it automatically with \code{\link[=guess_ab_col]{guess_ab_col()}} or input a text (case-insensitive), or use \code{NULL} to skip a column (e.g. \code{TIC = NULL} to skip ticarcillin). Manually defined but non-existing columns will be skipped with a warning.
The following antibiotics are eligible for the functions \code{\link[=eucast_rules]{eucast_rules()}} and \code{\link[=mdro]{mdro()}}. These are shown below in the format 'name (\verb{antimicrobial ID}, \href{https://atcddd.fhi.no/atc/structure_and_principles/}{ATC code})', sorted alphabetically:
Amikacin (\code{AMK}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB06&showdescription=no}{J01GB06}), amoxicillin (\code{AMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA04&showdescription=no}{J01CA04}), amoxicillin/clavulanic acid (\code{AMC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR02&showdescription=no}{J01CR02}), ampicillin (\code{AMP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA01&showdescription=no}{J01CA01}), ampicillin/sulbactam (\code{SAM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR01&showdescription=no}{J01CR01}), apramycin (\code{APR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QA07AA92&showdescription=no}{QA07AA92}), arbekacin (\code{ARB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB12&showdescription=no}{J01GB12}), aspoxicillin (\code{APX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA19&showdescription=no}{J01CA19}), azidocillin (\code{AZD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE04&showdescription=no}{J01CE04}), azithromycin (\code{AZM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA10&showdescription=no}{J01FA10}), azlocillin (\code{AZL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA09&showdescription=no}{J01CA09}), aztreonam (\code{ATM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DF01&showdescription=no}{J01DF01}), bacampicillin (\code{BAM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA06&showdescription=no}{J01CA06}), bekanamycin (\code{BEK}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB13&showdescription=no}{J01GB13}), benzathine benzylpenicillin (\code{BNB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE08&showdescription=no}{J01CE08}), benzathine phenoxymethylpenicillin (\code{BNP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE10&showdescription=no}{J01CE10}), benzylpenicillin (\code{PEN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE01&showdescription=no}{J01CE01}), besifloxacin (\code{BES}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=S01AE08&showdescription=no}{S01AE08}), biapenem (\code{BIA}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH05&showdescription=no}{J01DH05}), carbenicillin (\code{CRB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA03&showdescription=no}{J01CA03}), carindacillin (\code{CRN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA05&showdescription=no}{J01CA05}), cefacetrile (\code{CAC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB10&showdescription=no}{J01DB10}), cefaclor (\code{CEC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC04&showdescription=no}{J01DC04}), cefadroxil (\code{CFR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB05&showdescription=no}{J01DB05}), cefalexin (\code{LEX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB01&showdescription=no}{J01DB01}), cefaloridine (\code{RID}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB02&showdescription=no}{J01DB02}), cefalotin (\code{CEP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB03&showdescription=no}{J01DB03}), cefamandole (\code{MAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC03&showdescription=no}{J01DC03}), cefapirin (\code{HAP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB08&showdescription=no}{J01DB08}), cefatrizine (\code{CTZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB07&showdescription=no}{J01DB07}), cefazedone (\code{CZD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB06&showdescription=no}{J01DB06}), cefazolin (\code{CZO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB04&showdescription=no}{J01DB04}), cefcapene (\code{CCP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD17&showdescription=no}{J01DD17}), cefdinir (\code{CDR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD15&showdescription=no}{J01DD15}), cefditoren (\code{DIT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD16&showdescription=no}{J01DD16}), cefepime (\code{FEP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DE01&showdescription=no}{J01DE01}), cefetamet (\code{CAT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD10&showdescription=no}{J01DD10}), cefiderocol (\code{FDC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI04&showdescription=no}{J01DI04}), cefixime (\code{CFM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD08&showdescription=no}{J01DD08}), cefmenoxime (\code{CMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD05&showdescription=no}{J01DD05}), cefmetazole (\code{CMZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC09&showdescription=no}{J01DC09}), cefodizime (\code{DIZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD09&showdescription=no}{J01DD09}), cefonicid (\code{CID}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC06&showdescription=no}{J01DC06}), cefoperazone (\code{CFP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD12&showdescription=no}{J01DD12}), cefoperazone/sulbactam (\code{CSL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD62&showdescription=no}{J01DD62}), ceforanide (\code{CND}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC11&showdescription=no}{J01DC11}), cefotaxime (\code{CTX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD01&showdescription=no}{J01DD01}), cefotaxime/clavulanic acid (\code{CTC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD51&showdescription=no}{J01DD51}), cefotetan (\code{CTT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC05&showdescription=no}{J01DC05}), cefotiam (\code{CTF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC07&showdescription=no}{J01DC07}), cefovecin (\code{FOV}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01DD91&showdescription=no}{QJ01DD91}), cefoxitin (\code{FOX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC01&showdescription=no}{J01DC01}), cefozopran (\code{ZOP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DE03&showdescription=no}{J01DE03}), cefpiramide (\code{CPM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD11&showdescription=no}{J01DD11}), cefpirome (\code{CPO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DE02&showdescription=no}{J01DE02}), cefpodoxime (\code{CPD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD13&showdescription=no}{J01DD13}), cefprozil (\code{CPR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC10&showdescription=no}{J01DC10}), cefquinome (\code{CEQ}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QG51AA07&showdescription=no}{QG51AA07}), cefroxadine (\code{CRD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB11&showdescription=no}{J01DB11}), cefsulodin (\code{CFS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD03&showdescription=no}{J01DD03}), ceftaroline (\code{CPT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI02&showdescription=no}{J01DI02}), ceftazidime (\code{CAZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD02&showdescription=no}{J01DD02}), ceftazidime/clavulanic acid (\code{CCV}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD52&showdescription=no}{J01DD52}), cefteram (\code{CEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD18&showdescription=no}{J01DD18}), ceftezole (\code{CTL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB12&showdescription=no}{J01DB12}), ceftibuten (\code{CTB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD14&showdescription=no}{J01DD14}), ceftiofur (\code{TIO}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01DD90&showdescription=no}{QJ01DD90}), ceftizoxime (\code{CZX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD07&showdescription=no}{J01DD07}), ceftobiprole medocaril (\code{CFM1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI01&showdescription=no}{J01DI01}), ceftolozane/tazobactam (\code{CZT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI54&showdescription=no}{J01DI54}), ceftriaxone (\code{CRO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD04&showdescription=no}{J01DD04}), ceftriaxone/beta-lactamase inhibitor (\code{CEB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD63&showdescription=no}{J01DD63}), cefuroxime (\code{CXM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC02&showdescription=no}{J01DC02}), cephradine (\code{CED}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB09&showdescription=no}{J01DB09}), chloramphenicol (\code{CHL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01BA01&showdescription=no}{J01BA01}), ciprofloxacin (\code{CIP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA02&showdescription=no}{J01MA02}), clarithromycin (\code{CLR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA09&showdescription=no}{J01FA09}), clindamycin (\code{CLI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FF01&showdescription=no}{J01FF01}), clometocillin (\code{CLM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE07&showdescription=no}{J01CE07}), cloxacillin (\code{CLO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF02&showdescription=no}{J01CF02}), colistin (\code{COL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XB01&showdescription=no}{J01XB01}), cycloserine (\code{CYC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J04AB01&showdescription=no}{J04AB01}), dalbavancin (\code{DAL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA04&showdescription=no}{J01XA04}), danofloxacin (\code{DAN}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA92&showdescription=no}{QJ01MA92}), daptomycin (\code{DAP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX09&showdescription=no}{J01XX09}), delafloxacin (\code{DFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA23&showdescription=no}{J01MA23}), dibekacin (\code{DKB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB09&showdescription=no}{J01GB09}), dicloxacillin (\code{DIC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF01&showdescription=no}{J01CF01}), difloxacin (\code{DIF}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA94&showdescription=no}{QJ01MA94}), dirithromycin (\code{DIR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA13&showdescription=no}{J01FA13}), doripenem (\code{DOR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH04&showdescription=no}{J01DH04}), doxycycline (\code{DOX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA02&showdescription=no}{J01AA02}), enoxacin (\code{ENX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA04&showdescription=no}{J01MA04}), enrofloxacin (\code{ENR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA90&showdescription=no}{QJ01MA90}), epicillin (\code{EPC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA07&showdescription=no}{J01CA07}), ertapenem (\code{ETP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH03&showdescription=no}{J01DH03}), erythromycin (\code{ERY}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA01&showdescription=no}{J01FA01}), fleroxacin (\code{FLE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA08&showdescription=no}{J01MA08}), flucloxacillin (\code{FLC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF05&showdescription=no}{J01CF05}), flurithromycin (\code{FLR1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA14&showdescription=no}{J01FA14}), fosfomycin (\code{FOS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX01&showdescription=no}{J01XX01}), framycetin (\code{FRM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=D09AA01&showdescription=no}{D09AA01}), fusidic acid (\code{FUS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XC01&showdescription=no}{J01XC01}), gamithromycin (\code{GAM}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA95&showdescription=no}{QJ01FA95}), garenoxacin (\code{GRN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA19&showdescription=no}{J01MA19}), gatifloxacin (\code{GAT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA16&showdescription=no}{J01MA16}), gemifloxacin (\code{GEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA15&showdescription=no}{J01MA15}), gentamicin (\code{GEN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB03&showdescription=no}{J01GB03}), grepafloxacin (\code{GRX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA11&showdescription=no}{J01MA11}), hetacillin (\code{HET}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA18&showdescription=no}{J01CA18}), imipenem (\code{IPM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH51&showdescription=no}{J01DH51}), imipenem/relebactam (\code{IMR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH56&showdescription=no}{J01DH56}), isepamicin (\code{ISE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB11&showdescription=no}{J01GB11}), josamycin (\code{JOS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA07&showdescription=no}{J01FA07}), kanamycin (\code{KAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB04&showdescription=no}{J01GB04}), kitasamycin (\code{KIT}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA93&showdescription=no}{QJ01FA93}), lascufloxacin (\code{LSC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA25&showdescription=no}{J01MA25}), latamoxef (\code{LTM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD06&showdescription=no}{J01DD06}), levofloxacin (\code{LVX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA12&showdescription=no}{J01MA12}), levonadifloxacin (\code{LND}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA24&showdescription=no}{J01MA24}), lincomycin (\code{LIN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FF02&showdescription=no}{J01FF02}), linezolid (\code{LNZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX08&showdescription=no}{J01XX08}), lomefloxacin (\code{LOM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA07&showdescription=no}{J01MA07}), loracarbef (\code{LOR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC08&showdescription=no}{J01DC08}), marbofloxacin (\code{MAR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA93&showdescription=no}{QJ01MA93}), mecillinam (\code{MEC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA11&showdescription=no}{J01CA11}), meropenem (\code{MEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH02&showdescription=no}{J01DH02}), meropenem/vaborbactam (\code{MEV}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH52&showdescription=no}{J01DH52}), metampicillin (\code{MTM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA14&showdescription=no}{J01CA14}), meticillin (\code{MET}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF03&showdescription=no}{J01CF03}), mezlocillin (\code{MEZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA10&showdescription=no}{J01CA10}), micronomicin (\code{MCR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=S01AA22&showdescription=no}{S01AA22}), midecamycin (\code{MID}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA03&showdescription=no}{J01FA03}), minocycline (\code{MNO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA08&showdescription=no}{J01AA08}), miocamycin (\code{MCM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA11&showdescription=no}{J01FA11}), moxifloxacin (\code{MFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA14&showdescription=no}{J01MA14}), nadifloxacin (\code{NAD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=D10AF05&showdescription=no}{D10AF05}), nafcillin (\code{NAF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF06&showdescription=no}{J01CF06}), nalidixic acid (\code{NAL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MB02&showdescription=no}{J01MB02}), neomycin (\code{NEO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB05&showdescription=no}{J01GB05}), netilmicin (\code{NET}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB07&showdescription=no}{J01GB07}), nitrofurantoin (\code{NIT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XE01&showdescription=no}{J01XE01}), norfloxacin (\code{NOR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA06&showdescription=no}{J01MA06}), novobiocin (\code{NOV}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01XX95&showdescription=no}{QJ01XX95}), ofloxacin (\code{OFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA01&showdescription=no}{J01MA01}), oleandomycin (\code{OLE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA05&showdescription=no}{J01FA05}), orbifloxacin (\code{ORB}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA95&showdescription=no}{QJ01MA95}), oritavancin (\code{ORI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA05&showdescription=no}{J01XA05}), oxacillin (\code{OXA}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF04&showdescription=no}{J01CF04}), panipenem (\code{PAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH55&showdescription=no}{J01DH55}), pazufloxacin (\code{PAZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA18&showdescription=no}{J01MA18}), pefloxacin (\code{PEF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA03&showdescription=no}{J01MA03}), penamecillin (\code{PNM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE06&showdescription=no}{J01CE06}), pheneticillin (\code{PHE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE05&showdescription=no}{J01CE05}), phenoxymethylpenicillin (\code{PHN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE02&showdescription=no}{J01CE02}), piperacillin (\code{PIP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA12&showdescription=no}{J01CA12}), piperacillin/tazobactam (\code{TZP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR05&showdescription=no}{J01CR05}), pirlimycin (\code{PRL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ51FF90&showdescription=no}{QJ51FF90}), pivampicillin (\code{PVM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA02&showdescription=no}{J01CA02}), pivmecillinam (\code{PME}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA08&showdescription=no}{J01CA08}), plazomicin (\code{PLZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB14&showdescription=no}{J01GB14}), polymyxin B (\code{PLB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XB02&showdescription=no}{J01XB02}), pradofloxacin (\code{PRA}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA97&showdescription=no}{QJ01MA97}), pristinamycin (\code{PRI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FG01&showdescription=no}{J01FG01}), procaine benzylpenicillin (\code{PRB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE09&showdescription=no}{J01CE09}), propicillin (\code{PRP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE03&showdescription=no}{J01CE03}), prulifloxacin (\code{PRU}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA17&showdescription=no}{J01MA17}), quinupristin/dalfopristin (\code{QDA}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FG02&showdescription=no}{QJ01FG02}), ribostamycin (\code{RST}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB10&showdescription=no}{J01GB10}), rifampicin (\code{RIF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J04AB02&showdescription=no}{J04AB02}), rokitamycin (\code{ROK}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA12&showdescription=no}{J01FA12}), roxithromycin (\code{RXT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA06&showdescription=no}{J01FA06}), rufloxacin (\code{RFL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA10&showdescription=no}{J01MA10}), sarafloxacin (\code{SAR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA98&showdescription=no}{QJ01MA98}), sisomicin (\code{SIS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB08&showdescription=no}{J01GB08}), sitafloxacin (\code{SIT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA21&showdescription=no}{J01MA21}), solithromycin (\code{SOL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA16&showdescription=no}{J01FA16}), sparfloxacin (\code{SPX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA09&showdescription=no}{J01MA09}), spiramycin (\code{SPI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA02&showdescription=no}{J01FA02}), streptoduocin (\code{STR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GA02&showdescription=no}{J01GA02}), streptomycin (\code{STR1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GA01&showdescription=no}{J01GA01}), sulbactam (\code{SUL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CG01&showdescription=no}{J01CG01}), sulbenicillin (\code{SBC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA16&showdescription=no}{J01CA16}), sulfadiazine (\code{SDI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EC02&showdescription=no}{J01EC02}), sulfadiazine/trimethoprim (\code{SLT1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE02&showdescription=no}{J01EE02}), sulfadimethoxine (\code{SUD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED01&showdescription=no}{J01ED01}), sulfadimidine (\code{SDM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB03&showdescription=no}{J01EB03}), sulfadimidine/trimethoprim (\code{SLT2}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE05&showdescription=no}{J01EE05}), sulfafurazole (\code{SLF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB05&showdescription=no}{J01EB05}), sulfaisodimidine (\code{SLF1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB01&showdescription=no}{J01EB01}), sulfalene (\code{SLF2}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED02&showdescription=no}{J01ED02}), sulfamazone (\code{SZO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED09&showdescription=no}{J01ED09}), sulfamerazine (\code{SLF3}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED07&showdescription=no}{J01ED07}), sulfamerazine/trimethoprim (\code{SLT3}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE07&showdescription=no}{J01EE07}), sulfamethizole (\code{SLF4}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB02&showdescription=no}{J01EB02}), sulfamethoxazole (\code{SMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EC01&showdescription=no}{J01EC01}), sulfamethoxypyridazine (\code{SLF5}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED05&showdescription=no}{J01ED05}), sulfametomidine (\code{SLF6}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED03&showdescription=no}{J01ED03}), sulfametoxydiazine (\code{SLF7}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED04&showdescription=no}{J01ED04}), sulfametrole/trimethoprim (\code{SLT4}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE03&showdescription=no}{J01EE03}), sulfamoxole (\code{SLF8}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EC03&showdescription=no}{J01EC03}), sulfamoxole/trimethoprim (\code{SLT5}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE04&showdescription=no}{J01EE04}), sulfanilamide (\code{SLF9}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB06&showdescription=no}{J01EB06}), sulfaperin (\code{SLF10}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED06&showdescription=no}{J01ED06}), sulfaphenazole (\code{SLF11}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED08&showdescription=no}{J01ED08}), sulfapyridine (\code{SLF12}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB04&showdescription=no}{J01EB04}), sulfathiazole (\code{SUT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB07&showdescription=no}{J01EB07}), sulfathiourea (\code{SLF13}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB08&showdescription=no}{J01EB08}), sultamicillin (\code{SLT6}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR04&showdescription=no}{J01CR04}), talampicillin (\code{TAL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA15&showdescription=no}{J01CA15}), tazobactam (\code{TAZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CG02&showdescription=no}{J01CG02}), tebipenem (\code{TBP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH06&showdescription=no}{J01DH06}), tedizolid (\code{TZD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX11&showdescription=no}{J01XX11}), teicoplanin (\code{TEC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA02&showdescription=no}{J01XA02}), telavancin (\code{TLV}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA03&showdescription=no}{J01XA03}), telithromycin (\code{TLT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA15&showdescription=no}{J01FA15}), temafloxacin (\code{TMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA05&showdescription=no}{J01MA05}), temocillin (\code{TEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA17&showdescription=no}{J01CA17}), tetracycline (\code{TCY}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA07&showdescription=no}{J01AA07}), ticarcillin (\code{TIC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA13&showdescription=no}{J01CA13}), ticarcillin/clavulanic acid (\code{TCC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR03&showdescription=no}{J01CR03}), tigecycline (\code{TGC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA12&showdescription=no}{J01AA12}), tilbroquinol (\code{TBQ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=P01AA05&showdescription=no}{P01AA05}), tildipirosin (\code{TIP}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA96&showdescription=no}{QJ01FA96}), tilmicosin (\code{TIL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA91&showdescription=no}{QJ01FA91}), tobramycin (\code{TOB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB01&showdescription=no}{J01GB01}), tosufloxacin (\code{TFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA22&showdescription=no}{J01MA22}), trimethoprim (\code{TMP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EA01&showdescription=no}{J01EA01}), trimethoprim/sulfamethoxazole (\code{SXT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE01&showdescription=no}{J01EE01}), troleandomycin (\code{TRL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA08&showdescription=no}{J01FA08}), trovafloxacin (\code{TVA}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA13&showdescription=no}{J01MA13}), tulathromycin (\code{TUL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA94&showdescription=no}{QJ01FA94}), tylosin (\code{TYL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA90&showdescription=no}{QJ01FA90}), tylvalosin (\code{TYL1}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA92&showdescription=no}{QJ01FA92}), vancomycin (\code{VAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA01&showdescription=no}{J01XA01})
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
\donttest{
a <- data.frame(
mo = c(
"Staphylococcus aureus",
"Enterococcus faecalis",
"Escherichia coli",
"Klebsiella pneumoniae",
"Pseudomonas aeruginosa"
),
VAN = "-", # Vancomycin
AMX = "-", # Amoxicillin
COL = "-", # Colistin
CAZ = "-", # Ceftazidime
CXM = "-", # Cefuroxime
PEN = "S", # Benzylpenicillin
FOX = "S", # Cefoxitin
stringsAsFactors = FALSE
)
head(a)
# apply EUCAST rules: some results wil be changed
b <- eucast_rules(a)
head(b)
# do not apply EUCAST rules, but rather get a data.frame
# containing all details about the transformations:
c <- eucast_rules(a, verbose = TRUE)
head(c)
}
# Dosage guidelines:
eucast_dosage(c("tobra", "genta", "cipro"), "iv")
eucast_dosage(c("tobra", "genta", "cipro"), "iv", version_breakpoints = 10)
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/example_isolates.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{example_isolates}
\alias{example_isolates}
\title{Data Set with 2 000 Example Isolates}
\format{
A \link[tibble:tibble]{tibble} with 2 000 observations and 46 variables:
\itemize{
\item \code{date}\cr Date of receipt at the laboratory
\item \code{patient}\cr ID of the patient
\item \code{age}\cr Age of the patient
\item \code{gender}\cr Gender of the patient, either "F" or "M"
\item \code{ward}\cr Ward type where the patient was admitted, either "Clinical", "ICU", or "Outpatient"
\item \code{mo}\cr ID of microorganism created with \code{\link[=as.mo]{as.mo()}}, see also the \link{microorganisms} data set
\item \code{PEN:RIF}\cr 40 different antibiotics with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}}); these column names occur in the \link{antibiotics} data set and can be translated with \code{\link[=set_ab_names]{set_ab_names()}} or \code{\link[=ab_name]{ab_name()}}
}
}
\usage{
example_isolates
}
\description{
A data set containing 2 000 microbial isolates with their full antibiograms. This data set contains randomised fictitious data, but reflects reality and can be used to practise AMR data analysis. For examples, please read \href{https://msberends.github.io/AMR/articles/AMR.html}{the tutorial on our website}.
}
\details{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
example_isolates
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/example_isolates_unclean.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{example_isolates_unclean}
\alias{example_isolates_unclean}
\title{Data Set with Unclean Data}
\format{
A \link[tibble:tibble]{tibble} with 3 000 observations and 8 variables:
\itemize{
\item \code{patient_id}\cr ID of the patient
\item \code{date}\cr date of receipt at the laboratory
\item \code{hospital}\cr ID of the hospital, from A to C
\item \code{bacteria}\cr info about microorganism that can be transformed with \code{\link[=as.mo]{as.mo()}}, see also \link{microorganisms}
\item \code{AMX:GEN}\cr 4 different antibiotics that have to be transformed with \code{\link[=as.sir]{as.sir()}}
}
}
\usage{
example_isolates_unclean
}
\description{
A data set containing 3 000 microbial isolates that are not cleaned up and consequently not ready for AMR data analysis. This data set can be used for practice.
}
\details{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
example_isolates_unclean
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/export_ncbi_biosample.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/export_biosample.R
\name{export_ncbi_biosample}
\alias{export_ncbi_biosample}
\title{Export Data Set as NCBI BioSample Antibiogram}
\usage{
export_ncbi_biosample(
x,
filename = paste0("biosample_", format(Sys.time(), "\%Y-\%m-\%d-\%H\%M\%S"), ".xlsx"),
type = "pathogen MIC",
columns = where(is.mic),
save_as_xlsx = TRUE
)
}
\arguments{
\item{x}{a data set}
\item{filename}{a character string specifying the file name}
\item{type}{a character string specifying the type of data set, either "pathogen MIC" or "beta-lactamase MIC", see \url{https://www.ncbi.nlm.nih.gov/biosample/docs/}}
}
\description{
Export Data Set as NCBI BioSample Antibiogram
}
\keyword{internal}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/first_isolate.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/first_isolate.R
\name{first_isolate}
\alias{first_isolate}
\alias{filter_first_isolate}
\title{Determine First Isolates}
\source{
Methodology of this function is strictly based on:
\itemize{
\item \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 5th Edition}, 2022, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
\item Hindler JF and Stelling J (2007). \strong{Analysis and Presentation of Cumulative Antibiograms: A New Consensus Guideline from the Clinical and Laboratory Standards Institute.} Clinical Infectious Diseases, 44(6), 867-873. \doi{10.1086/511864}
}
}
\usage{
first_isolate(
x = NULL,
col_date = NULL,
col_patient_id = NULL,
col_mo = NULL,
col_testcode = NULL,
col_specimen = NULL,
col_icu = NULL,
col_keyantimicrobials = NULL,
episode_days = 365,
testcodes_exclude = NULL,
icu_exclude = FALSE,
specimen_group = NULL,
type = "points",
method = c("phenotype-based", "episode-based", "patient-based", "isolate-based"),
ignore_I = TRUE,
points_threshold = 2,
info = interactive(),
include_unknown = FALSE,
include_untested_sir = TRUE,
...
)
filter_first_isolate(
x = NULL,
col_date = NULL,
col_patient_id = NULL,
col_mo = NULL,
episode_days = 365,
method = c("phenotype-based", "episode-based", "patient-based", "isolate-based"),
...
)
}
\arguments{
\item{x}{a \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.}
\item{col_date}{column name of the result date (or date that is was received on the lab) - the default is the first column with a date class}
\item{col_patient_id}{column name of the unique IDs of the patients - the default is the first column that starts with 'patient' or 'patid' (case insensitive)}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{col_testcode}{column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (such as test codes for screening). In that case \code{testcodes_exclude} will be ignored.}
\item{col_specimen}{column name of the specimen type or group}
\item{col_icu}{column name of the logicals (\code{TRUE}/\code{FALSE}) whether a ward or department is an Intensive Care Unit (ICU). This can also be a \link{logical} vector with the same length as rows in \code{x}.}
\item{col_keyantimicrobials}{(only useful when \code{method = "phenotype-based"}) column name of the key antimicrobials to determine first isolates, see \code{\link[=key_antimicrobials]{key_antimicrobials()}}. The default is the first column that starts with 'key' followed by 'ab' or 'antibiotics' or 'antimicrobials' (case insensitive). Use \code{col_keyantimicrobials = FALSE} to prevent this. Can also be the output of \code{\link[=key_antimicrobials]{key_antimicrobials()}}.}
\item{episode_days}{episode in days after which a genus/species combination will be determined as 'first isolate' again. The default of 365 days is based on the guideline by CLSI, see \emph{Source}.}
\item{testcodes_exclude}{a \link{character} vector with test codes that should be excluded (case-insensitive)}
\item{icu_exclude}{a \link{logical} to indicate whether ICU isolates should be excluded (rows with value \code{TRUE} in the column set with \code{col_icu})}
\item{specimen_group}{value in the column set with \code{col_specimen} to filter on}
\item{type}{type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}}
\item{method}{the method to apply, either \code{"phenotype-based"}, \code{"episode-based"}, \code{"patient-based"} or \code{"isolate-based"} (can be abbreviated), see \emph{Details}. The default is \code{"phenotype-based"} if antimicrobial test results are present in the data, and \code{"episode-based"} otherwise.}
\item{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, see \emph{Details}}
\item{points_threshold}{minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}}
\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode}
\item{include_unknown}{a \link{logical} to indicate whether 'unknown' microorganisms should be included too, i.e. microbial code \code{"UNKNOWN"}, which defaults to \code{FALSE}. For WHONET users, this means that all records with organism code \code{"con"} (\emph{contamination}) will be excluded at default. Isolates with a microbial ID of \code{NA} will always be excluded as first isolate.}
\item{include_untested_sir}{a \link{logical} to indicate whether also rows without antibiotic results are still eligible for becoming a first isolate. Use \code{include_untested_sir = FALSE} to always return \code{FALSE} for such rows. This checks the data set for columns of class \code{sir} and consequently requires transforming columns with antibiotic results using \code{\link[=as.sir]{as.sir()}} first.}
\item{...}{arguments passed on to \code{\link[=first_isolate]{first_isolate()}} when using \code{\link[=filter_first_isolate]{filter_first_isolate()}}, otherwise arguments passed on to \code{\link[=key_antimicrobials]{key_antimicrobials()}} (such as \code{universal}, \code{gram_negative}, \code{gram_positive})}
}
\value{
A \link{logical} vector
}
\description{
Determine first isolates of all microorganisms of every patient per episode and (if needed) per specimen type. These functions support all four methods as summarised by Hindler \emph{et al.} in 2007 (\doi{10.1086/511864}). To determine patient episodes not necessarily based on microorganisms, use \code{\link[=is_new_episode]{is_new_episode()}} that also supports grouping with the \code{dplyr} package.
}
\details{
To conduct epidemiological analyses on antimicrobial resistance data, only so-called first isolates should be included to prevent overestimation and underestimation of antimicrobial resistance. Different methods can be used to do so, see below.
These functions are context-aware. This means that the \code{x} argument can be left blank if used inside a \link{data.frame} call, see \emph{Examples}.
The \code{\link[=first_isolate]{first_isolate()}} function is a wrapper around the \code{\link[=is_new_episode]{is_new_episode()}} function, but more efficient for data sets containing microorganism codes or names.
All isolates with a microbial ID of \code{NA} will be excluded as first isolate.
\subsection{Different methods}{
According to Hindler \emph{et al.} (2007, \doi{10.1086/511864}), there are different methods (algorithms) to select first isolates with increasing reliability: isolate-based, patient-based, episode-based and phenotype-based. All methods select on a combination of the taxonomic genus and species (not subspecies).
All mentioned methods are covered in the \code{\link[=first_isolate]{first_isolate()}} function:\tabular{ll}{
\strong{Method} \tab \strong{Function to apply} \cr
\strong{Isolate-based} \tab \code{first_isolate(x, method = "isolate-based")} \cr
\emph{(= all isolates)} \tab \cr
\tab \cr
\tab \cr
\strong{Patient-based} \tab \code{first_isolate(x, method = "patient-based")} \cr
\emph{(= first isolate per patient)} \tab \cr
\tab \cr
\tab \cr
\strong{Episode-based} \tab \code{first_isolate(x, method = "episode-based")}, or: \cr
\emph{(= first isolate per episode)} \tab \cr
- 7-Day interval from initial isolate \tab - \code{first_isolate(x, method = "e", episode_days = 7)} \cr
- 30-Day interval from initial isolate \tab - \code{first_isolate(x, method = "e", episode_days = 30)} \cr
\tab \cr
\tab \cr
\strong{Phenotype-based} \tab \code{first_isolate(x, method = "phenotype-based")}, or: \cr
\emph{(= first isolate per phenotype)} \tab \cr
- Major difference in any antimicrobial result \tab - \code{first_isolate(x, type = "points")} \cr
- Any difference in key antimicrobial results \tab - \code{first_isolate(x, type = "keyantimicrobials")} \cr
}
}
\subsection{Isolate-based}{
This method does not require any selection, as all isolates should be included. It does, however, respect all arguments set in the \code{\link[=first_isolate]{first_isolate()}} function. For example, the default setting for \code{include_unknown} (\code{FALSE}) will omit selection of rows without a microbial ID.
}
\subsection{Patient-based}{
To include every genus-species combination per patient once, set the \code{episode_days} to \code{Inf}. Although often inappropriate, this method makes sure that no duplicate isolates are selected from the same patient. In a large longitudinal data set, this could mean that isolates are \emph{excluded} that were found years after the initial isolate.
}
\subsection{Episode-based}{
To include every genus-species combination per patient episode once, set the \code{episode_days} to a sensible number of days. Depending on the type of analysis, this could be 14, 30, 60 or 365. Short episodes are common for analysing specific hospital or ward data, long episodes are common for analysing regional and national data.
This is the most common method to correct for duplicate isolates. Patients are categorised into episodes based on their ID and dates (e.g., the date of specimen receipt or laboratory result). While this is a common method, it does not take into account antimicrobial test results. This means that e.g. a methicillin-resistant \emph{Staphylococcus aureus} (MRSA) isolate cannot be differentiated from a wildtype \emph{Staphylococcus aureus} isolate.
}
\subsection{Phenotype-based}{
This is a more reliable method, since it also \emph{weighs} the antibiogram (antimicrobial test results) yielding so-called 'first weighted isolates'. There are two different methods to weigh the antibiogram:
\enumerate{
\item Using \code{type = "points"} and argument \code{points_threshold} (default)
This method weighs \emph{all} antimicrobial drugs available in the data set. Any difference from I to S or R (or vice versa) counts as \code{0.5} points, a difference from S to R (or vice versa) counts as \code{1} point. When the sum of points exceeds \code{points_threshold}, which defaults to \code{2}, an isolate will be selected as a first weighted isolate.
All antimicrobials are internally selected using the \code{\link[=all_antimicrobials]{all_antimicrobials()}} function. The output of this function does not need to be passed to the \code{\link[=first_isolate]{first_isolate()}} function.
\item Using \code{type = "keyantimicrobials"} and argument \code{ignore_I}
This method only weighs specific antimicrobial drugs, called \emph{key antimicrobials}. Any difference from S to R (or vice versa) in these key antimicrobials will select an isolate as a first weighted isolate. With \code{ignore_I = FALSE}, also differences from I to S or R (or vice versa) will lead to this.
Key antimicrobials are internally selected using the \code{\link[=key_antimicrobials]{key_antimicrobials()}} function, but can also be added manually as a variable to the data and set in the \code{col_keyantimicrobials} argument. Another option is to pass the output of the \code{\link[=key_antimicrobials]{key_antimicrobials()}} function directly to the \code{col_keyantimicrobials} argument.
}
The default method is phenotype-based (using \code{type = "points"}) and episode-based (using \code{episode_days = 365}). This makes sure that every genus-species combination is selected per patient once per year, while taking into account all antimicrobial test results. If no antimicrobial test results are available in the data set, only the episode-based method is applied at default.
}
}
\examples{
# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates.
example_isolates[first_isolate(info = TRUE), ]
\donttest{
# get all first Gram-negatives
example_isolates[which(first_isolate(info = FALSE) & mo_is_gram_negative()), ]
if (require("dplyr")) {
# filter on first isolates using dplyr:
example_isolates \%>\%
filter(first_isolate(info = TRUE))
}
if (require("dplyr")) {
# short-hand version:
example_isolates \%>\%
filter_first_isolate(info = FALSE)
}
if (require("dplyr")) {
# flag the first isolates per group:
example_isolates \%>\%
group_by(ward) \%>\%
mutate(first = first_isolate(info = TRUE)) \%>\%
select(ward, date, patient, mo, first)
}
}
}
\seealso{
\code{\link[=key_antimicrobials]{key_antimicrobials()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/g.test.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/g.test.R
\name{g.test}
\alias{g.test}
\title{\emph{G}-test for Count Data}
\source{
The code for this function is identical to that of \code{\link[=chisq.test]{chisq.test()}}, except that:
\itemize{
\item The calculation of the statistic was changed to \eqn{2 * sum(x * log(x / E))}
\item Yates' continuity correction was removed as it does not apply to a \emph{G}-test
\item The possibility to simulate p values with \code{simulate.p.value} was removed
}
}
\usage{
g.test(x, y = NULL, p = rep(1/length(x), length(x)), rescale.p = FALSE)
}
\arguments{
\item{x}{a numeric vector or matrix. \code{x} and \code{y} can also
both be factors.}
\item{y}{a numeric vector; ignored if \code{x} is a matrix. If
\code{x} is a factor, \code{y} should be a factor of the same length.}
\item{p}{a vector of probabilities of the same length as \code{x}.
An error is given if any entry of \code{p} is negative.}
\item{rescale.p}{a logical scalar; if TRUE then \code{p} is rescaled
(if necessary) to sum to 1. If \code{rescale.p} is FALSE, and
\code{p} does not sum to 1, an error is given.}
}
\value{
A list with class \code{"htest"} containing the following
components:
\item{statistic}{the value the chi-squared test statistic.}
\item{parameter}{the degrees of freedom of the approximate
chi-squared distribution of the test statistic, \code{NA} if the
p-value is computed by Monte Carlo simulation.}
\item{p.value}{the p-value for the test.}
\item{method}{a character string indicating the type of test
performed, and whether Monte Carlo simulation or continuity
correction was used.}
\item{data.name}{a character string giving the name(s) of the data.}
\item{observed}{the observed counts.}
\item{expected}{the expected counts under the null hypothesis.}
\item{residuals}{the Pearson residuals,
\code{(observed - expected) / sqrt(expected)}.}
\item{stdres}{standardized residuals,
\code{(observed - expected) / sqrt(V)}, where \code{V} is the
residual cell variance (Agresti, 2007, section 2.4.5
for the case where \code{x} is a matrix, \code{n * p * (1 - p)} otherwise).}
}
\description{
\code{\link[=g.test]{g.test()}} performs chi-squared contingency table tests and goodness-of-fit tests, just like \code{\link[=chisq.test]{chisq.test()}} but is more reliable (1). A \emph{G}-test can be used to see whether the number of observations in each category fits a theoretical expectation (called a \strong{\emph{G}-test of goodness-of-fit}), or to see whether the proportions of one variable are different for different values of the other variable (called a \strong{\emph{G}-test of independence}).
}
\details{
If \code{x} is a \link{matrix} with one row or column, or if \code{x} is a vector and \code{y} is not given, then a \emph{goodness-of-fit test} is performed (\code{x} is treated as a one-dimensional contingency table). The entries of \code{x} must be non-negative integers. In this case, the hypothesis tested is whether the population probabilities equal those in \code{p}, or are all equal if \code{p} is not given.
If \code{x} is a \link{matrix} with at least two rows and columns, it is taken as a two-dimensional contingency table: the entries of \code{x} must be non-negative integers. Otherwise, \code{x} and \code{y} must be vectors or factors of the same length; cases with missing values are removed, the objects are coerced to factors, and the contingency table is computed from these. Then Pearson's chi-squared test is performed of the null hypothesis that the joint distribution of the cell counts in a 2-dimensional contingency table is the product of the row and column marginals.
The p-value is computed from the asymptotic chi-squared distribution of the test statistic.
In the contingency table case simulation is done by random sampling from the set of all contingency tables with given marginals, and works only if the marginals are strictly positive. Note that this is not the usual sampling situation assumed for a chi-squared test (such as the \emph{G}-test) but rather that for Fisher's exact test.
In the goodness-of-fit case simulation is done by random sampling from the discrete distribution specified by \code{p}, each sample being of size \code{n = sum(x)}. This simulation is done in \R and may be slow.
\subsection{\emph{G}-test Of Goodness-of-Fit (Likelihood Ratio Test)}{
Use the \emph{G}-test of goodness-of-fit when you have one nominal variable with two or more values (such as male and female, or red, pink and white flowers). You compare the observed counts of numbers of observations in each category with the expected counts, which you calculate using some kind of theoretical expectation (such as a 1:1 sex ratio or a 1:2:1 ratio in a genetic cross).
If the expected number of observations in any category is too small, the \emph{G}-test may give inaccurate results, and you should use an exact test instead (\code{\link[=fisher.test]{fisher.test()}}).
The \emph{G}-test of goodness-of-fit is an alternative to the chi-square test of goodness-of-fit (\code{\link[=chisq.test]{chisq.test()}}); each of these tests has some advantages and some disadvantages, and the results of the two tests are usually very similar.
}
\subsection{\emph{G}-test of Independence}{
Use the \emph{G}-test of independence when you have two nominal variables, each with two or more possible values. You want to know whether the proportions for one variable are different among values of the other variable.
It is also possible to do a \emph{G}-test of independence with more than two nominal variables. For example, Jackson et al. (2013) also had data for children under 3, so you could do an analysis of old vs. young, thigh vs. arm, and reaction vs. no reaction, all analyzed together.
Fisher's exact test (\code{\link[=fisher.test]{fisher.test()}}) is an \strong{exact} test, where the \emph{G}-test is still only an \strong{approximation}. For any 2x2 table, Fisher's Exact test may be slower but will still run in seconds, even if the sum of your observations is multiple millions.
The \emph{G}-test of independence is an alternative to the chi-square test of independence (\code{\link[=chisq.test]{chisq.test()}}), and they will give approximately the same results.
}
\subsection{How the Test Works}{
Unlike the exact test of goodness-of-fit (\code{\link[=fisher.test]{fisher.test()}}), the \emph{G}-test does not directly calculate the probability of obtaining the observed results or something more extreme. Instead, like almost all statistical tests, the \emph{G}-test has an intermediate step; it uses the data to calculate a test statistic that measures how far the observed data are from the null expectation. You then use a mathematical relationship, in this case the chi-square distribution, to estimate the probability of obtaining that value of the test statistic.
The \emph{G}-test uses the log of the ratio of two likelihoods as the test statistic, which is why it is also called a likelihood ratio test or log-likelihood ratio test. The formula to calculate a \emph{G}-statistic is:
\eqn{G = 2 * sum(x * log(x / E))}
where \code{E} are the expected values. Since this is chi-square distributed, the p value can be calculated in \R with:
\if{html}{\out{<div class="sourceCode">}}\preformatted{p <- stats::pchisq(G, df, lower.tail = FALSE)
}\if{html}{\out{</div>}}
where \code{df} are the degrees of freedom.
If there are more than two categories and you want to find out which ones are significantly different from their null expectation, you can use the same method of testing each category vs. the sum of all categories, with the Bonferroni correction. You use \emph{G}-tests for each category, of course.
}
}
\examples{
# = EXAMPLE 1 =
# Shivrain et al. (2006) crossed clearfield rice (which are resistant
# to the herbicide imazethapyr) with red rice (which are susceptible to
# imazethapyr). They then crossed the hybrid offspring and examined the
# F2 generation, where they found 772 resistant plants, 1611 moderately
# resistant plants, and 737 susceptible plants. If resistance is controlled
# by a single gene with two co-dominant alleles, you would expect a 1:2:1
# ratio.
x <- c(772, 1611, 737)
g.test(x, p = c(1, 2, 1) / 4)
# There is no significant difference from a 1:2:1 ratio.
# Meaning: resistance controlled by a single gene with two co-dominant
# alleles, is plausible.
# = EXAMPLE 2 =
# Red crossbills (Loxia curvirostra) have the tip of the upper bill either
# right or left of the lower bill, which helps them extract seeds from pine
# cones. Some have hypothesized that frequency-dependent selection would
# keep the number of right and left-billed birds at a 1:1 ratio. Groth (1992)
# observed 1752 right-billed and 1895 left-billed crossbills.
x <- c(1752, 1895)
g.test(x)
# There is a significant difference from a 1:1 ratio.
# Meaning: there are significantly more left-billed birds.
}
\references{
\enumerate{
\item McDonald, J.H. 2014. \strong{Handbook of Biological Statistics (3rd ed.)}. Sparky House Publishing, Baltimore, Maryland. \url{http://www.biostathandbook.com/gtestgof.html}.
}
}
\seealso{
\code{\link[=chisq.test]{chisq.test()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/get_episode.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_episode.R
\name{get_episode}
\alias{get_episode}
\alias{is_new_episode}
\title{Determine Clinical or Epidemic Episodes}
\usage{
get_episode(x, episode_days = NULL, case_free_days = NULL, ...)
is_new_episode(x, episode_days = NULL, case_free_days = NULL, ...)
}
\arguments{
\item{x}{vector of dates (class \code{Date} or \code{POSIXt}), will be sorted internally to determine episodes}
\item{episode_days}{episode length in days to specify the time period after which a new episode begins, can also be less than a day or \code{Inf}, see \emph{Details}}
\item{case_free_days}{(inter-epidemic) interval length in days after which a new episode will start, can also be less than a day or \code{Inf}, see \emph{Details}}
\item{...}{ignored, only in place to allow future extensions}
}
\value{
\itemize{
\item \code{\link[=get_episode]{get_episode()}}: an \link{integer} vector
\item \code{\link[=is_new_episode]{is_new_episode()}}: a \link{logical} vector
}
}
\description{
These functions determine which items in a vector can be considered (the start of) a new episode. This can be used to determine clinical episodes for any epidemiological analysis. The \code{\link[=get_episode]{get_episode()}} function returns the index number of the episode per group, while the \code{\link[=is_new_episode]{is_new_episode()}} function returns \code{TRUE} for every new \code{\link[=get_episode]{get_episode()}} index. Both absolute and relative episode determination are supported.
}
\details{
Episodes can be determined in two ways: absolute and relative.
\enumerate{
\item Absolute
This method uses \code{episode_days} to define an episode length in days, after which a new episode will start. A common use case in AMR data analysis is microbial epidemiology: episodes of \emph{S. aureus} bacteraemia in ICU patients for example. The episode length could then be 30 days, so that new \emph{S. aureus} isolates after an ICU episode of 30 days will be considered a different (or new) episode.
Thus, this method counts \strong{since the start of the previous episode}.
\item Relative
This method uses \code{case_free_days} to quantify the duration of case-free days (the inter-epidemic interval), after which a new episode will start. A common use case is infectious disease epidemiology: episodes of norovirus outbreaks in a hospital for example. The case-free period could then be 14 days, so that new norovirus cases after that time will be considered a different (or new) episode.
Thus, this methods counts \strong{since the last case in the previous episode}.
}
In a table:\tabular{ccc}{
Date \tab Using \code{episode_days = 7} \tab Using \code{case_free_days = 7} \cr
2023-01-01 \tab 1 \tab 1 \cr
2023-01-02 \tab 1 \tab 1 \cr
2023-01-05 \tab 1 \tab 1 \cr
2023-01-08 \tab 2** \tab 1 \cr
2023-02-21 \tab 3 \tab 2*** \cr
2023-02-22 \tab 3 \tab 2 \cr
2023-02-23 \tab 3 \tab 2 \cr
2023-02-24 \tab 3 \tab 2 \cr
2023-03-01 \tab 4 \tab 2 \cr
}
** This marks the start of a new episode, because 8 January 2023 is more than 7 days since the start of the previous episode (1 January 2023). \cr
*** This marks the start of a new episode, because 21 January 2023 is more than 7 days since the last case in the previous episode (8 January 2023).
Either \code{episode_days} or \code{case_free_days} must be provided in the function.
\subsection{Difference between \code{get_episode()} and \code{is_new_episode()}}{
The \code{\link[=get_episode]{get_episode()}} function returns the index number of the episode, so all cases/patients/isolates in the first episode will have the number 1, all cases/patients/isolates in the second episode will have the number 2, etc.
The \code{\link[=is_new_episode]{is_new_episode()}} function on the other hand, returns \code{TRUE} for every new \code{\link[=get_episode]{get_episode()}} index.
To specify, when setting \code{episode_days = 365} (using method 1 as explained above), this is how the two functions differ:\tabular{cccc}{
patient \tab date \tab \code{get_episode()} \tab \code{is_new_episode()} \cr
A \tab 2019-01-01 \tab 1 \tab TRUE \cr
A \tab 2019-03-01 \tab 1 \tab FALSE \cr
A \tab 2021-01-01 \tab 2 \tab TRUE \cr
B \tab 2008-01-01 \tab 1 \tab TRUE \cr
B \tab 2008-01-01 \tab 1 \tab FALSE \cr
C \tab 2020-01-01 \tab 1 \tab TRUE \cr
}
}
\subsection{Other}{
The \code{\link[=first_isolate]{first_isolate()}} function is a wrapper around the \code{\link[=is_new_episode]{is_new_episode()}} function, but is more efficient for data sets containing microorganism codes or names and allows for different isolate selection methods.
The \code{dplyr} package is not required for these functions to work, but these episode functions do support \link[dplyr:group_by]{variable grouping} and work conveniently inside \code{dplyr} verbs such as \code{\link[dplyr:filter]{filter()}}, \code{\link[dplyr:mutate]{mutate()}} and \code{\link[dplyr:summarise]{summarise()}}.
}
}
\examples{
# difference between absolute and relative determination of episodes:
x <- data.frame(dates = as.Date(c(
"2021-01-01",
"2021-01-02",
"2021-01-05",
"2021-01-08",
"2021-02-21",
"2021-02-22",
"2021-02-23",
"2021-02-24",
"2021-03-01",
"2021-03-01"
)))
x$absolute <- get_episode(x$dates, episode_days = 7)
x$relative <- get_episode(x$dates, case_free_days = 7)
x
# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates
df <- example_isolates[sample(seq_len(2000), size = 100), ]
get_episode(df$date, episode_days = 60) # indices
is_new_episode(df$date, episode_days = 60) # TRUE/FALSE
# filter on results from the third 60-day episode only, using base R
df[which(get_episode(df$date, 60) == 3), ]
# the functions also work for less than a day, e.g. to include one per hour:
get_episode(
c(
Sys.time(),
Sys.time() + 60 * 60
),
episode_days = 1 / 24
)
\donttest{
if (require("dplyr")) {
# is_new_episode() can also be used in dplyr verbs to determine patient
# episodes based on any (combination of) grouping variables:
df \%>\%
mutate(condition = sample(
x = c("A", "B", "C"),
size = 100,
replace = TRUE
)) \%>\%
group_by(patient, condition) \%>\%
mutate(new_episode = is_new_episode(date, 365)) \%>\%
select(patient, date, condition, new_episode) \%>\%
arrange(patient, condition, date)
}
if (require("dplyr")) {
df \%>\%
group_by(ward, patient) \%>\%
transmute(date,
patient,
new_index = get_episode(date, 60),
new_logical = is_new_episode(date, 60)
) \%>\%
arrange(patient, ward, date)
}
if (require("dplyr")) {
df \%>\%
group_by(ward) \%>\%
summarise(
n_patients = n_distinct(patient),
n_episodes_365 = sum(is_new_episode(date, episode_days = 365)),
n_episodes_60 = sum(is_new_episode(date, episode_days = 60)),
n_episodes_30 = sum(is_new_episode(date, episode_days = 30))
)
}
# grouping on patients and microorganisms leads to the same
# results as first_isolate() when using 'episode-based':
if (require("dplyr")) {
x <- df \%>\%
filter_first_isolate(
include_unknown = TRUE,
method = "episode-based"
)
y <- df \%>\%
group_by(patient, mo) \%>\%
filter(is_new_episode(date, 365)) \%>\%
ungroup()
identical(x, y)
}
# but is_new_episode() has a lot more flexibility than first_isolate(),
# since you can now group on anything that seems relevant:
if (require("dplyr")) {
df \%>\%
group_by(patient, mo, ward) \%>\%
mutate(flag_episode = is_new_episode(date, 365)) \%>\%
select(group_vars(.), flag_episode)
}
}
}
\seealso{
\code{\link[=first_isolate]{first_isolate()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/ggplot_pca.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggplot_pca.R
\name{ggplot_pca}
\alias{ggplot_pca}
\title{PCA Biplot with \code{ggplot2}}
\source{
The \code{\link[=ggplot_pca]{ggplot_pca()}} function is based on the \code{ggbiplot()} function from the \code{ggbiplot} package by Vince Vu, as found on GitHub: \url{https://github.com/vqv/ggbiplot} (retrieved: 2 March 2020, their latest commit: \href{https://github.com/vqv/ggbiplot/commit/7325e880485bea4c07465a0304c470608fffb5d9}{\code{7325e88}}; 12 February 2015).
As per their GPL-2 licence that demands documentation of code changes, the changes made based on the source code were:
\enumerate{
\item Rewritten code to remove the dependency on packages \code{plyr}, \code{scales} and \code{grid}
\item Parametrised more options, like arrow and ellipse settings
\item Hardened all input possibilities by defining the exact type of user input for every argument
\item Added total amount of explained variance as a caption in the plot
\item Cleaned all syntax based on the \code{lintr} package, fixed grammatical errors and added integrity checks
\item Updated documentation
}
}
\usage{
ggplot_pca(
x,
choices = 1:2,
scale = 1,
pc.biplot = TRUE,
labels = NULL,
labels_textsize = 3,
labels_text_placement = 1.5,
groups = NULL,
ellipse = TRUE,
ellipse_prob = 0.68,
ellipse_size = 0.5,
ellipse_alpha = 0.5,
points_size = 2,
points_alpha = 0.25,
arrows = TRUE,
arrows_colour = "darkblue",
arrows_size = 0.5,
arrows_textsize = 3,
arrows_textangled = TRUE,
arrows_alpha = 0.75,
base_textsize = 10,
...
)
}
\arguments{
\item{x}{an object returned by \code{\link[=pca]{pca()}}, \code{\link[=prcomp]{prcomp()}} or \code{\link[=princomp]{princomp()}}}
\item{choices}{
length 2 vector specifying the components to plot. Only the default
is a biplot in the strict sense.
}
\item{scale}{
The variables are scaled by \code{lambda ^ scale} and the
observations are scaled by \code{lambda ^ (1-scale)} where
\code{lambda} are the singular values as computed by
\code{\link[stats]{princomp}}. Normally \code{0 <= scale <= 1}, and a warning
will be issued if the specified \code{scale} is outside this range.
}
\item{pc.biplot}{
If true, use what Gabriel (1971) refers to as a "principal component
biplot", with \code{lambda = 1} and observations scaled up by sqrt(n) and
variables scaled down by sqrt(n). Then inner products between
variables approximate covariances and distances between observations
approximate Mahalanobis distance.
}
\item{labels}{an optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.}
\item{labels_textsize}{the size of the text used for the labels}
\item{labels_text_placement}{adjustment factor the placement of the variable names (\verb{>=1} means further away from the arrow head)}
\item{groups}{an optional vector of groups for the labels, with the same length as \code{labels}. If set, the points and labels will be coloured according to these groups. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.}
\item{ellipse}{a \link{logical} to indicate whether a normal data ellipse should be drawn for each group (set with \code{groups})}
\item{ellipse_prob}{statistical size of the ellipse in normal probability}
\item{ellipse_size}{the size of the ellipse line}
\item{ellipse_alpha}{the alpha (transparency) of the ellipse line}
\item{points_size}{the size of the points}
\item{points_alpha}{the alpha (transparency) of the points}
\item{arrows}{a \link{logical} to indicate whether arrows should be drawn}
\item{arrows_colour}{the colour of the arrow and their text}
\item{arrows_size}{the size (thickness) of the arrow lines}
\item{arrows_textsize}{the size of the text at the end of the arrows}
\item{arrows_textangled}{a \link{logical} whether the text at the end of the arrows should be angled}
\item{arrows_alpha}{the alpha (transparency) of the arrows and their text}
\item{base_textsize}{the text size for all plot elements except the labels and arrows}
\item{...}{arguments passed on to functions}
}
\description{
Produces a \code{ggplot2} variant of a so-called \href{https://en.wikipedia.org/wiki/Biplot}{biplot} for PCA (principal component analysis), but is more flexible and more appealing than the base \R \code{\link[=biplot]{biplot()}} function.
}
\details{
The colours for labels and points can be changed by adding another scale layer for colour, such as \code{scale_colour_viridis_d()} and \code{scale_colour_brewer()}.
}
\examples{
# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates.
\donttest{
if (require("dplyr")) {
# calculate the resistance per group first
resistance_data <- example_isolates \%>\%
group_by(
order = mo_order(mo), # group on anything, like order
genus = mo_genus(mo)
) \%>\% # and genus as we do here;
filter(n() >= 30) \%>\% # filter on only 30 results per group
summarise_if(is.sir, resistance) # then get resistance of all drugs
# now conduct PCA for certain antimicrobial drugs
pca_result <- resistance_data \%>\%
pca(AMC, CXM, CTX, CAZ, GEN, TOB, TMP, SXT)
summary(pca_result)
# old base R plotting method:
biplot(pca_result, main = "Base R biplot")
# new ggplot2 plotting method using this package:
if (require("ggplot2")) {
ggplot_pca(pca_result) +
labs(title = "ggplot2 biplot")
}
if (require("ggplot2")) {
# still extendible with any ggplot2 function
ggplot_pca(pca_result) +
scale_colour_viridis_d() +
labs(title = "ggplot2 biplot")
}
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/ggplot_sir.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggplot_sir.R
\name{ggplot_sir}
\alias{ggplot_sir}
\alias{geom_sir}
\alias{facet_sir}
\alias{scale_y_percent}
\alias{scale_sir_colours}
\alias{theme_sir}
\alias{labels_sir_count}
\title{AMR Plots with \code{ggplot2}}
\usage{
ggplot_sir(
data,
position = NULL,
x = "antibiotic",
fill = "interpretation",
facet = NULL,
breaks = seq(0, 1, 0.1),
limits = NULL,
translate_ab = "name",
combine_SI = TRUE,
minimum = 30,
language = get_AMR_locale(),
nrow = NULL,
colours = c(S = "#3CAEA3", SI = "#3CAEA3", I = "#F6D55C", IR = "#ED553B", R =
"#ED553B"),
datalabels = TRUE,
datalabels.size = 2.5,
datalabels.colour = "grey15",
title = NULL,
subtitle = NULL,
caption = NULL,
x.title = "Antimicrobial",
y.title = "Proportion",
...
)
geom_sir(
position = NULL,
x = c("antibiotic", "interpretation"),
fill = "interpretation",
translate_ab = "name",
minimum = 30,
language = get_AMR_locale(),
combine_SI = TRUE,
...
)
facet_sir(facet = c("interpretation", "antibiotic"), nrow = NULL)
scale_y_percent(
breaks = function(x) seq(0, max(x, na.rm = TRUE), 0.1),
limits = NULL
)
scale_sir_colours(..., aesthetics = "fill")
theme_sir()
labels_sir_count(
position = NULL,
x = "antibiotic",
translate_ab = "name",
minimum = 30,
language = get_AMR_locale(),
combine_SI = TRUE,
datalabels.size = 3,
datalabels.colour = "grey15"
)
}
\arguments{
\item{data}{a \link{data.frame} with column(s) of class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})}
\item{position}{position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}}
\item{x}{variable to show on x axis, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable}
\item{fill}{variable to categorise using the plots legend, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable}
\item{facet}{variable to split plots by, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable}
\item{breaks}{a \link{numeric} vector of positions}
\item{limits}{a \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum}
\item{translate_ab}{a column name of the \link{antibiotics} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}}
\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}}
\item{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 \emph{Source}.}
\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{nrow}{(when using \code{facet}) number of rows}
\item{colours}{a named vactor with colour to be used for filling. The default colours are colour-blind friendly.}
\item{datalabels}{show datalabels using \code{\link[=labels_sir_count]{labels_sir_count()}}}
\item{datalabels.size}{size of the datalabels}
\item{datalabels.colour}{colour of the datalabels}
\item{title}{text to show as title of the plot}
\item{subtitle}{text to show as subtitle of the plot}
\item{caption}{text to show as caption of the plot}
\item{x.title}{text to show as x axis description}
\item{y.title}{text to show as y axis description}
\item{...}{other arguments passed on to \code{\link[=geom_sir]{geom_sir()}} or, in case of \code{\link[=scale_sir_colours]{scale_sir_colours()}}, named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See \emph{Examples}.}
\item{aesthetics}{aesthetics to apply the colours to - the default is "fill" but can also be (a combination of) "alpha", "colour", "fill", "linetype", "shape" or "size"}
}
\description{
Use these functions to create bar plots for AMR data analysis. All functions rely on \link[ggplot2:ggplot]{ggplot2} functions.
}
\details{
At default, the names of antibiotics will be shown on the plots using \code{\link[=ab_name]{ab_name()}}. This can be set with the \code{translate_ab} argument. See \code{\link[=count_df]{count_df()}}.
\subsection{The Functions}{
\code{\link[=geom_sir]{geom_sir()}} will take any variable from the data that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) using \code{\link[=sir_df]{sir_df()}} and will plot bars with the percentage S, I, and R. The default behaviour is to have the bars stacked and to have the different antibiotics on the x axis.
\code{\link[=facet_sir]{facet_sir()}} creates 2d plots (at default based on S/I/R) using \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}}.
\code{\link[=scale_y_percent]{scale_y_percent()}} transforms the y axis to a 0 to 100\% range using \code{\link[ggplot2:scale_continuous]{ggplot2::scale_y_continuous()}}.
\code{\link[=scale_sir_colours]{scale_sir_colours()}} sets colours to the bars (green for S, yellow for I, and red for R). with multilingual support. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red.
\code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
\code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and amount of isolates using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}.
\code{\link[=ggplot_sir]{ggplot_sir()}} is a wrapper around all above functions that uses data as first input. This makes it possible to use this function after a pipe (\verb{\%>\%}). See \emph{Examples}.
}
}
\examples{
\donttest{
if (require("ggplot2") && require("dplyr")) {
# get antimicrobial results for drugs against a UTI:
ggplot(example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP)) +
geom_sir()
}
if (require("ggplot2") && require("dplyr")) {
# prettify the plot using some additional functions:
df <- example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP)
ggplot(df) +
geom_sir() +
scale_y_percent() +
scale_sir_colours() +
labels_sir_count() +
theme_sir()
}
if (require("ggplot2") && require("dplyr")) {
# or better yet, simplify this using the wrapper function - a single command:
example_isolates \%>\%
select(AMX, NIT, FOS, TMP, CIP) \%>\%
ggplot_sir()
}
if (require("ggplot2") && require("dplyr")) {
# get only proportions and no counts:
example_isolates \%>\%
select(AMX, NIT, FOS, TMP, CIP) \%>\%
ggplot_sir(datalabels = FALSE)
}
if (require("ggplot2") && require("dplyr")) {
# add other ggplot2 arguments as you like:
example_isolates \%>\%
select(AMX, NIT, FOS, TMP, CIP) \%>\%
ggplot_sir(
width = 0.5,
colour = "black",
size = 1,
linetype = 2,
alpha = 0.25
)
}
if (require("ggplot2") && require("dplyr")) {
# you can alter the colours with colour names:
example_isolates \%>\%
select(AMX) \%>\%
ggplot_sir(colours = c(SI = "yellow"))
}
if (require("ggplot2") && require("dplyr")) {
# but you can also use the built-in colour-blind friendly colours for
# your plots, where "S" is green, "I" is yellow and "R" is red:
data.frame(
x = c("Value1", "Value2", "Value3"),
y = c(1, 2, 3),
z = c("Value4", "Value5", "Value6")
) \%>\%
ggplot() +
geom_col(aes(x = x, y = y, fill = z)) +
scale_sir_colours(Value4 = "S", Value5 = "I", Value6 = "R")
}
if (require("ggplot2") && require("dplyr")) {
# resistance of ciprofloxacine per age group
example_isolates \%>\%
mutate(first_isolate = first_isolate()) \%>\%
filter(
first_isolate == TRUE,
mo == as.mo("Escherichia coli")
) \%>\%
# age_groups() is also a function in this AMR package:
group_by(age_group = age_groups(age)) \%>\%
select(age_group, CIP) \%>\%
ggplot_sir(x = "age_group")
}
if (require("ggplot2") && require("dplyr")) {
# a shorter version which also adjusts data label colours:
example_isolates \%>\%
select(AMX, NIT, FOS, TMP, CIP) \%>\%
ggplot_sir(colours = FALSE)
}
if (require("ggplot2") && require("dplyr")) {
# it also supports groups (don't forget to use the group var on `x` or `facet`):
example_isolates \%>\%
filter(mo_is_gram_negative(), ward != "Outpatient") \%>\%
# select only UTI-specific drugs
select(ward, AMX, NIT, FOS, TMP, CIP) \%>\%
group_by(ward) \%>\%
ggplot_sir(
x = "ward",
facet = "antibiotic",
nrow = 1,
title = "AMR of Anti-UTI Drugs Per Ward",
x.title = "Ward",
datalabels = FALSE
)
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/guess_ab_col.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/guess_ab_col.R
\name{guess_ab_col}
\alias{guess_ab_col}
\title{Guess Antibiotic Column}
\usage{
guess_ab_col(
x = NULL,
search_string = NULL,
verbose = FALSE,
only_sir_columns = FALSE
)
}
\arguments{
\item{x}{a \link{data.frame}}
\item{search_string}{a text to search \code{x} for, will be checked with \code{\link[=as.ab]{as.ab()}} if this value is not a column in \code{x}}
\item{verbose}{a \link{logical} to indicate whether additional info should be printed}
\item{only_sir_columns}{a \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})}
}
\value{
A column name of \code{x}, or \code{NULL} when no result is found.
}
\description{
This tries to find a column name in a data set based on information from the \link{antibiotics} data set. Also supports WHONET abbreviations.
}
\details{
You can look for an antibiotic (trade) name or abbreviation and it will search \code{x} and the \link{antibiotics} data set for any column containing a name or code of that antibiotic.
}
\examples{
df <- data.frame(
amox = "S",
tetr = "R"
)
guess_ab_col(df, "amoxicillin")
guess_ab_col(df, "J01AA07") # ATC code of tetracycline
guess_ab_col(df, "J01AA07", verbose = TRUE)
# NOTE: Using column 'tetr' as input for J01AA07 (tetracycline).
# WHONET codes
df <- data.frame(
AMP_ND10 = "R",
AMC_ED20 = "S"
)
guess_ab_col(df, "ampicillin")
guess_ab_col(df, "J01CR02")
guess_ab_col(df, as.ab("augmentin"))
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/intrinsic_resistant.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{intrinsic_resistant}
\alias{intrinsic_resistant}
\title{Data Set with Bacterial Intrinsic Resistance}
\format{
A \link[tibble:tibble]{tibble} with 301 583 observations and 2 variables:
\itemize{
\item \code{mo}\cr Microorganism ID
\item \code{ab}\cr Antibiotic ID
}
}
\usage{
intrinsic_resistant
}
\description{
Data set containing defined intrinsic resistance by EUCAST of all bug-drug combinations.
}
\details{
This data set is based on \href{https://www.eucast.org/expert_rules_and_expected_phenotypes}{'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3} (2021).
\subsection{Direct download}{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
They \strong{allow for machine reading EUCAST and CLSI guidelines}, which is almost impossible with the MS Excel and PDF files distributed by EUCAST and CLSI.
}
}
\examples{
intrinsic_resistant
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/italicise_taxonomy.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/italicise_taxonomy.R
\name{italicise_taxonomy}
\alias{italicise_taxonomy}
\alias{italicize_taxonomy}
\title{Italicise Taxonomic Families, Genera, Species, Subspecies}
\usage{
italicise_taxonomy(string, type = c("markdown", "ansi", "html"))
italicize_taxonomy(string, type = c("markdown", "ansi", "html"))
}
\arguments{
\item{string}{a \link{character} (vector)}
\item{type}{type of conversion of the taxonomic names, either "markdown", "html" or "ansi", see \emph{Details}}
}
\description{
According to the binomial nomenclature, the lowest four taxonomic levels (family, genus, species, subspecies) should be printed in italics. This function finds taxonomic names within strings and makes them italic.
}
\details{
This function finds the taxonomic names and makes them italic based on the \link{microorganisms} data set.
The taxonomic names can be italicised using markdown (the default) by adding \code{*} before and after the taxonomic names, or \verb{<i>} and \verb{</i>} when using html. When using 'ansi', ANSI colours will be added using \verb{\\033[3m} before and \verb{\\033[23m} after the taxonomic names. If multiple ANSI colours are not available, no conversion will occur.
This function also supports abbreviation of the genus if it is followed by a species, such as "E. coli" and "K. pneumoniae ozaenae".
}
\examples{
italicise_taxonomy("An overview of Staphylococcus aureus isolates")
italicise_taxonomy("An overview of S. aureus isolates")
cat(italicise_taxonomy("An overview of S. aureus isolates", type = "ansi"))
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/join.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/join_microorganisms.R
\name{join}
\alias{join}
\alias{inner_join_microorganisms}
\alias{inner_join}
\alias{left_join_microorganisms}
\alias{right_join_microorganisms}
\alias{full_join_microorganisms}
\alias{semi_join_microorganisms}
\alias{anti_join_microorganisms}
\title{Join \link{microorganisms} to a Data Set}
\usage{
inner_join_microorganisms(x, by = NULL, suffix = c("2", ""), ...)
left_join_microorganisms(x, by = NULL, suffix = c("2", ""), ...)
right_join_microorganisms(x, by = NULL, suffix = c("2", ""), ...)
full_join_microorganisms(x, by = NULL, suffix = c("2", ""), ...)
semi_join_microorganisms(x, by = NULL, ...)
anti_join_microorganisms(x, by = NULL, ...)
}
\arguments{
\item{x}{existing data set to join, or \link{character} vector. In case of a \link{character} vector, the resulting \link{data.frame} will contain a column 'x' with these values.}
\item{by}{a variable to join by - if left empty will search for a column with class \code{\link{mo}} (created with \code{\link[=as.mo]{as.mo()}}) or will be \code{"mo"} if that column name exists in \code{x}, could otherwise be a column name of \code{x} with values that exist in \code{microorganisms$mo} (such as \code{by = "bacteria_id"}), or another column in \link{microorganisms} (but then it should be named, like \code{by = c("bacteria_id" = "fullname")})}
\item{suffix}{if there are non-joined duplicate variables in \code{x} and \code{y}, these suffixes will be added to the output to disambiguate them. Should be a \link{character} vector of length 2.}
\item{...}{ignored, only in place to allow future extensions}
}
\value{
a \link{data.frame}
}
\description{
Join the data set \link{microorganisms} easily to an existing data set or to a \link{character} vector.
}
\details{
\strong{Note:} As opposed to the \code{join()} functions of \code{dplyr}, \link{character} vectors are supported and at default existing columns will get a suffix \code{"2"} and the newly joined columns will not get a suffix.
If the \code{dplyr} package is installed, their join functions will be used. Otherwise, the much slower \code{\link[=merge]{merge()}} and \code{\link[=interaction]{interaction()}} functions from base \R will be used.
}
\examples{
left_join_microorganisms(as.mo("K. pneumoniae"))
left_join_microorganisms("B_KLBSL_PNMN")
df <- data.frame(
date = seq(
from = as.Date("2018-01-01"),
to = as.Date("2018-01-07"),
by = 1
),
bacteria = as.mo(c(
"S. aureus", "MRSA", "MSSA", "STAAUR",
"E. coli", "E. coli", "E. coli"
)),
stringsAsFactors = FALSE
)
colnames(df)
df_joined <- left_join_microorganisms(df, "bacteria")
colnames(df_joined)
\donttest{
if (require("dplyr")) {
example_isolates \%>\%
left_join_microorganisms() \%>\%
colnames()
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/key_antimicrobials.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/key_antimicrobials.R
\name{key_antimicrobials}
\alias{key_antimicrobials}
\alias{all_antimicrobials}
\alias{antimicrobials_equal}
\title{(Key) Antimicrobials for First Weighted Isolates}
\usage{
key_antimicrobials(
x = NULL,
col_mo = NULL,
universal = c("ampicillin", "amoxicillin/clavulanic acid", "cefuroxime",
"piperacillin/tazobactam", "ciprofloxacin", "trimethoprim/sulfamethoxazole"),
gram_negative = c("gentamicin", "tobramycin", "colistin", "cefotaxime", "ceftazidime",
"meropenem"),
gram_positive = c("vancomycin", "teicoplanin", "tetracycline", "erythromycin",
"oxacillin", "rifampin"),
antifungal = c("anidulafungin", "caspofungin", "fluconazole", "miconazole", "nystatin",
"voriconazole"),
only_sir_columns = FALSE,
...
)
all_antimicrobials(x = NULL, only_sir_columns = FALSE, ...)
antimicrobials_equal(
y,
z,
type = c("points", "keyantimicrobials"),
ignore_I = TRUE,
points_threshold = 2,
...
)
}
\arguments{
\item{x}{a \link{data.frame} with antibiotics columns, like \code{AMX} or \code{amox}. Can be left blank to determine automatically}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{universal}{names of \strong{broad-spectrum} antimicrobial drugs, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antimicrobial drugs}
\item{gram_negative}{names of antibiotic drugs for \strong{Gram-positives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs}
\item{gram_positive}{names of antibiotic drugs for \strong{Gram-negatives}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antibiotic drugs}
\item{antifungal}{names of antifungal drugs for \strong{fungi}, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antifungal drugs}
\item{only_sir_columns}{a \link{logical} to indicate whether only columns must be included that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})}
\item{...}{ignored, only in place to allow future extensions}
\item{y, z}{\link{character} vectors to compare}
\item{type}{type to determine weighed isolates; can be \code{"keyantimicrobials"} or \code{"points"}, see \emph{Details}}
\item{ignore_I}{\link{logical} to indicate whether antibiotic interpretations with \code{"I"} will be ignored when \code{type = "keyantimicrobials"}, see \emph{Details}}
\item{points_threshold}{minimum number of points to require before differences in the antibiogram will lead to inclusion of an isolate when \code{type = "points"}, see \emph{Details}}
}
\description{
These functions can be used to determine first weighted isolates by considering the phenotype for isolate selection (see \code{\link[=first_isolate]{first_isolate()}}). Using a phenotype-based method to determine first isolates is more reliable than methods that disregard phenotypes.
}
\details{
The \code{\link[=key_antimicrobials]{key_antimicrobials()}} and \code{\link[=all_antimicrobials]{all_antimicrobials()}} functions are context-aware. This means that the \code{x} argument can be left blank if used inside a \link{data.frame} call, see \emph{Examples}.
The function \code{\link[=key_antimicrobials]{key_antimicrobials()}} returns a \link{character} vector with 12 antimicrobial results for every isolate. The function \code{\link[=all_antimicrobials]{all_antimicrobials()}} returns a \link{character} vector with all antimicrobial drug results for every isolate. These vectors can then be compared using \code{\link[=antimicrobials_equal]{antimicrobials_equal()}}, to check if two isolates have generally the same antibiogram. Missing and invalid values are replaced with a dot (\code{"."}) by \code{\link[=key_antimicrobials]{key_antimicrobials()}} and ignored by \code{\link[=antimicrobials_equal]{antimicrobials_equal()}}.
Please see the \code{\link[=first_isolate]{first_isolate()}} function how these important functions enable the 'phenotype-based' method for determination of first isolates.
The default antimicrobial drugs used for \strong{all rows} (set in \code{universal}) are:
\itemize{
\item Ampicillin
\item Amoxicillin/clavulanic acid
\item Cefuroxime
\item Ciprofloxacin
\item Piperacillin/tazobactam
\item Trimethoprim/sulfamethoxazole
}
The default antimicrobial drugs used for \strong{Gram-negative bacteria} (set in \code{gram_negative}) are:
\itemize{
\item Cefotaxime
\item Ceftazidime
\item Colistin
\item Gentamicin
\item Meropenem
\item Tobramycin
}
The default antimicrobial drugs used for \strong{Gram-positive bacteria} (set in \code{gram_positive}) are:
\itemize{
\item Erythromycin
\item Oxacillin
\item Rifampin
\item Teicoplanin
\item Tetracycline
\item Vancomycin
}
The default antimicrobial drugs used for \strong{fungi} (set in \code{antifungal}) are:
\itemize{
\item Anidulafungin
\item Caspofungin
\item Fluconazole
\item Miconazole
\item Nystatin
\item Voriconazole
}
}
\examples{
# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates.
# output of the `key_antimicrobials()` function could be like this:
strainA <- "SSSRR.S.R..S"
strainB <- "SSSIRSSSRSSS"
# those strings can be compared with:
antimicrobials_equal(strainA, strainB, type = "keyantimicrobials")
# TRUE, because I is ignored (as well as missing values)
antimicrobials_equal(strainA, strainB, type = "keyantimicrobials", ignore_I = FALSE)
# FALSE, because I is not ignored and so the 4th [character] differs
\donttest{
if (require("dplyr")) {
# set key antibiotics to a new variable
my_patients <- example_isolates \%>\%
mutate(keyab = key_antimicrobials(antifungal = NULL)) \%>\% # no need to define `x`
mutate(
# now calculate first isolates
first_regular = first_isolate(col_keyantimicrobials = FALSE),
# and first WEIGHTED isolates
first_weighted = first_isolate(col_keyantimicrobials = "keyab")
)
# Check the difference in this data set, 'weighted' results in more isolates:
sum(my_patients$first_regular, na.rm = TRUE)
sum(my_patients$first_weighted, na.rm = TRUE)
}
}
}
\seealso{
\code{\link[=first_isolate]{first_isolate()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/kurtosis.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/kurtosis.R
\name{kurtosis}
\alias{kurtosis}
\alias{kurtosis.default}
\alias{kurtosis.matrix}
\alias{kurtosis.data.frame}
\title{Kurtosis of the Sample}
\usage{
kurtosis(x, na.rm = FALSE, excess = FALSE)
\method{kurtosis}{default}(x, na.rm = FALSE, excess = FALSE)
\method{kurtosis}{matrix}(x, na.rm = FALSE, excess = FALSE)
\method{kurtosis}{data.frame}(x, na.rm = FALSE, excess = FALSE)
}
\arguments{
\item{x}{a vector of values, a \link{matrix} or a \link{data.frame}}
\item{na.rm}{a \link{logical} to indicate whether \code{NA} values should be stripped before the computation proceeds}
\item{excess}{a \link{logical} to indicate whether the \emph{excess kurtosis} should be returned, defined as the kurtosis minus 3.}
}
\description{
Kurtosis is a measure of the "tailedness" of the probability distribution of a real-valued random variable. A normal distribution has a kurtosis of 3 and a excess kurtosis of 0.
}
\examples{
kurtosis(rnorm(10000))
kurtosis(rnorm(10000), excess = TRUE)
}
\seealso{
\code{\link[=skewness]{skewness()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/like.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/like.R
\name{like}
\alias{like}
\alias{\%like\%}
\alias{\%unlike\%}
\alias{\%like_case\%}
\alias{\%unlike_case\%}
\title{Vectorised Pattern Matching with Keyboard Shortcut}
\source{
Idea from the \href{https://github.com/Rdatatable/data.table/blob/ec1259af1bf13fc0c96a1d3f9e84d55d8106a9a4/R/like.R}{\code{like} function from the \code{data.table} package}, although altered as explained in \emph{Details}.
}
\usage{
like(x, pattern, ignore.case = TRUE)
x \%like\% pattern
x \%unlike\% pattern
x \%like_case\% pattern
x \%unlike_case\% pattern
}
\arguments{
\item{x}{a \link{character} vector where matches are sought, or an object which can be coerced by \code{\link[=as.character]{as.character()}} to a \link{character} vector.}
\item{pattern}{a \link{character} vector containing regular expressions (or a \link{character} string for \code{fixed = TRUE}) to be matched in the given \link{character} vector. Coerced by \code{\link[=as.character]{as.character()}} to a \link{character} string if possible.}
\item{ignore.case}{if \code{FALSE}, the pattern matching is \emph{case sensitive} and if \code{TRUE}, case is ignored during matching.}
}
\value{
A \link{logical} vector
}
\description{
Convenient wrapper around \code{\link[=grepl]{grepl()}} to match a pattern: \code{x \%like\% pattern}. It always returns a \code{\link{logical}} vector and is always case-insensitive (use \code{x \%like_case\% pattern} for case-sensitive matching). Also, \code{pattern} can be as long as \code{x} to compare items of each index in both vectors, or they both can have the same length to iterate over all cases.
}
\details{
These \code{\link[=like]{like()}} and \verb{\%like\%}/\verb{\%unlike\%} functions:
\itemize{
\item Are case-insensitive (use \verb{\%like_case\%}/\verb{\%unlike_case\%} for case-sensitive matching)
\item Support multiple patterns
\item Check if \code{pattern} is a valid regular expression and sets \code{fixed = TRUE} if not, to greatly improve speed (vectorised over \code{pattern})
\item Always use compatibility with Perl unless \code{fixed = TRUE}, to greatly improve speed
}
Using RStudio? The \verb{\%like\%}/\verb{\%unlike\%} functions can also be directly inserted in your code from the Addins menu and can have its own keyboard shortcut like \code{Shift+Ctrl+L} or \code{Shift+Cmd+L} (see menu \code{Tools} > \verb{Modify Keyboard Shortcuts...}). If you keep pressing your shortcut, the inserted text will be iterated over \verb{\%like\%} -> \verb{\%unlike\%} -> \verb{\%like_case\%} -> \verb{\%unlike_case\%}.
}
\examples{
# data.table has a more limited version of \%like\%, so unload it:
try(detach("package:data.table", unload = TRUE), silent = TRUE)
a <- "This is a test"
b <- "TEST"
a \%like\% b
b \%like\% a
# also supports multiple patterns
a <- c("Test case", "Something different", "Yet another thing")
b <- c("case", "diff", "yet")
a \%like\% b
a \%unlike\% b
a[1] \%like\% b
a \%like\% b[1]
\donttest{
# get isolates whose name start with 'Entero' (case-insensitive)
example_isolates[which(mo_name() \%like\% "^entero"), ]
if (require("dplyr")) {
example_isolates \%>\%
filter(mo_name() \%like\% "^ent")
}
}
}
\seealso{
\code{\link[=grepl]{grepl()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/mdro.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mdro.R
\name{mdro}
\alias{mdro}
\alias{MDR}
\alias{XDR}
\alias{PDR}
\alias{BRMO}
\alias{3MRGN}
\alias{4MRGN}
\alias{custom_mdro_guideline}
\alias{brmo}
\alias{mrgn}
\alias{mdr_tb}
\alias{mdr_cmi2012}
\alias{eucast_exceptional_phenotypes}
\title{Determine Multidrug-Resistant Organisms (MDRO)}
\source{
See the supported guidelines above for the \link{list} of publications used for this function.
}
\usage{
mdro(
x = NULL,
guideline = "CMI2012",
col_mo = NULL,
info = interactive(),
pct_required_classes = 0.5,
combine_SI = TRUE,
verbose = FALSE,
only_sir_columns = FALSE,
...
)
custom_mdro_guideline(..., as_factor = TRUE)
brmo(x = NULL, only_sir_columns = FALSE, ...)
mrgn(x = NULL, only_sir_columns = FALSE, ...)
mdr_tb(x = NULL, only_sir_columns = FALSE, ...)
mdr_cmi2012(x = NULL, only_sir_columns = FALSE, ...)
eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, ...)
}
\arguments{
\item{x}{a \link{data.frame} with antibiotics columns, like \code{AMX} or \code{amox}. Can be left blank for automatic determination.}
\item{guideline}{a specific guideline to follow, see sections \emph{Supported international / national guidelines} and \emph{Using Custom Guidelines} below. When left empty, the publication by Magiorakos \emph{et al.} (see below) will be followed.}
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions}
\item{pct_required_classes}{minimal required percentage of antimicrobial classes that must be available per isolate, rounded down. For example, with the default guideline, 17 antimicrobial classes must be available for \emph{S. aureus}. Setting this \code{pct_required_classes} argument to \code{0.5} (default) means that for every \emph{S. aureus} isolate at least 8 different classes must be available. Any lower number of available classes will return \code{NA} for that isolate.}
\item{combine_SI}{a \link{logical} to indicate whether all values of S and I must be merged into one, so resistance is only considered when isolates are R, not I. As this is the default behaviour of the \code{\link[=mdro]{mdro()}} function, it follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section 'Interpretation of S, I and R' below. When using \code{combine_SI = FALSE}, resistance is considered when isolates are R or I.}
\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not return the MDRO results, but instead returns a data set in logbook form with extensive info about which isolates would be MDRO-positive, or why they are not.}
\item{only_sir_columns}{a \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})}
\item{...}{in case of \code{\link[=custom_mdro_guideline]{custom_mdro_guideline()}}: a set of rules, see section \emph{Using Custom Guidelines} below. Otherwise: column name of an antibiotic, see section \emph{Antibiotics} below.}
\item{as_factor}{a \link{logical} to indicate whether the returned value should be an ordered \link{factor} (\code{TRUE}, default), or otherwise a \link{character} vector}
}
\value{
\itemize{
\item CMI 2012 paper - function \code{\link[=mdr_cmi2012]{mdr_cmi2012()}} or \code{\link[=mdro]{mdro()}}:\cr
Ordered \link{factor} with levels \code{Negative} < \code{Multi-drug-resistant (MDR)} < \verb{Extensively drug-resistant (XDR)} < \code{Pandrug-resistant (PDR)}
\item TB guideline - function \code{\link[=mdr_tb]{mdr_tb()}} or \code{\link[=mdro]{mdro(..., guideline = "TB")}}:\cr
Ordered \link{factor} with levels \code{Negative} < \code{Mono-resistant} < \code{Poly-resistant} < \code{Multi-drug-resistant} < \verb{Extensively drug-resistant}
\item German guideline - function \code{\link[=mrgn]{mrgn()}} or \code{\link[=mdro]{mdro(..., guideline = "MRGN")}}:\cr
Ordered \link{factor} with levels \code{Negative} < \verb{3MRGN} < \verb{4MRGN}
\item Everything else, except for custom guidelines:\cr
Ordered \link{factor} with levels \code{Negative} < \verb{Positive, unconfirmed} < \code{Positive}. The value \code{"Positive, unconfirmed"} means that, according to the guideline, it is not entirely sure if the isolate is multi-drug resistant and this should be confirmed with additional (e.g. molecular) tests
}
}
\description{
Determine which isolates are multidrug-resistant organisms (MDRO) according to international, national and custom guidelines.
}
\details{
These functions are context-aware. This means that the \code{x} argument can be left blank if used inside a \link{data.frame} call, see \emph{Examples}.
For the \code{pct_required_classes} argument, values above 1 will be divided by 100. This is to support both fractions (\code{0.75} or \code{3/4}) and percentages (\code{75}).
\strong{Note:} Every test that involves the Enterobacteriaceae family, will internally be performed using its newly named \emph{order} Enterobacterales, since the Enterobacteriaceae family has been taxonomically reclassified by Adeolu \emph{et al.} in 2016. Before that, Enterobacteriaceae was the only family under the Enterobacteriales (with an i) order. All species under the old Enterobacteriaceae family are still under the new Enterobacterales (without an i) order, but divided into multiple families. The way tests are performed now by this \code{\link[=mdro]{mdro()}} function makes sure that results from before 2016 and after 2016 are identical.
}
\section{Supported International / National Guidelines}{
Currently supported guidelines are (case-insensitive):
\itemize{
\item \code{guideline = "CMI2012"} (default)
Magiorakos AP, Srinivasan A \emph{et al.} "Multidrug-resistant, extensively drug-resistant and pandrug-resistant bacteria: an international expert proposal for interim standard definitions for acquired resistance." Clinical Microbiology and Infection (2012) (\doi{10.1111/j.1469-0691.2011.03570.x})
\item \code{guideline = "EUCAST3.3"} (or simply \code{guideline = "EUCAST"})
The European international guideline - EUCAST Expert Rules Version 3.3 "Intrinsic Resistance and Unusual Phenotypes" (\href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2021/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.3_20211018.pdf}{link})
\item \code{guideline = "EUCAST3.2"}
The European international guideline - EUCAST Expert Rules Version 3.2 "Intrinsic Resistance and Unusual Phenotypes" (\href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2020/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.2_20200225.pdf}{link})
\item \code{guideline = "EUCAST3.1"}
The European international guideline - EUCAST Expert Rules Version 3.1 "Intrinsic Resistance and Exceptional Phenotypes Tables" (\href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/Expert_rules_intrinsic_exceptional_V3.1.pdf}{link})
\item \code{guideline = "TB"}
The international guideline for multi-drug resistant tuberculosis - World Health Organization "Companion handbook to the WHO guidelines for the programmatic management of drug-resistant tuberculosis" (\href{https://www.who.int/publications/i/item/9789241548809}{link})
\item \code{guideline = "MRGN"}
The German national guideline - Mueller et al. (2015) Antimicrobial Resistance and Infection Control 4:7; \doi{10.1186/s13756-015-0047-6}
\item \code{guideline = "BRMO"}
The Dutch national guideline - Rijksinstituut voor Volksgezondheid en Milieu "WIP-richtlijn BRMO (Bijzonder Resistente Micro-Organismen) (ZKH)" (\href{https://www.rivm.nl/wip-richtlijn-brmo-bijzonder-resistente-micro-organismen-zkh}{link})
}
Please suggest your own (country-specific) guidelines by letting us know: \url{https://github.com/msberends/AMR/issues/new}.
}
\section{Using Custom Guidelines}{
Custom guidelines can be set with the \code{\link[=custom_mdro_guideline]{custom_mdro_guideline()}} function. This is of great importance if you have custom rules to determine MDROs in your hospital, e.g., rules that are dependent on ward, state of contact isolation or other variables in your data.
If you are familiar with the \code{\link[dplyr:case_when]{case_when()}} function of the \code{dplyr} package, you will recognise the input method to set your own rules. Rules must be set using what \R considers to be the 'formula notation'. The rule is written \emph{before} the tilde (\code{~}) and the consequence of the rule is written \emph{after} the tilde:
\if{html}{\out{<div class="sourceCode">}}\preformatted{custom <- custom_mdro_guideline(CIP == "R" & age > 60 ~ "Elderly Type A",
ERY == "R" & age > 60 ~ "Elderly Type B")
}\if{html}{\out{</div>}}
If a row/an isolate matches the first rule, the value after the first \code{~} (in this case \emph{'Elderly Type A'}) will be set as MDRO value. Otherwise, the second rule will be tried and so on. The number of rules is unlimited.
You can print the rules set in the console for an overview. Colours will help reading it if your console supports colours.
\if{html}{\out{<div class="sourceCode">}}\preformatted{custom
#> A set of custom MDRO rules:
#> 1. CIP is "R" and age is higher than 60 -> Elderly Type A
#> 2. ERY is "R" and age is higher than 60 -> Elderly Type B
#> 3. Otherwise -> Negative
#>
#> Unmatched rows will return NA.
}\if{html}{\out{</div>}}
The outcome of the function can be used for the \code{guideline} argument in the \code{\link[=mdro]{mdro()}} function:
\if{html}{\out{<div class="sourceCode">}}\preformatted{x <- mdro(example_isolates,
guideline = custom)
table(x)
#> Negative Elderly Type A Elderly Type B
#> 1070 198 732
}\if{html}{\out{</div>}}
Rules can also be combined with other custom rules by using \code{\link[=c]{c()}}:
\if{html}{\out{<div class="sourceCode">}}\preformatted{x <- mdro(example_isolates,
guideline = c(custom,
custom_mdro_guideline(ERY == "R" & age > 50 ~ "Elderly Type C")))
table(x)
#> Negative Elderly Type A Elderly Type B Elderly Type C
#> 961 198 732 109
}\if{html}{\out{</div>}}
The rules set (the \code{custom} object in this case) could be exported to a shared file location using \code{\link[=saveRDS]{saveRDS()}} if you collaborate with multiple users. The custom rules set could then be imported using \code{\link[=readRDS]{readRDS()}}.
}
\section{Antibiotics}{
To define antibiotics column names, leave as it is to determine it automatically with \code{\link[=guess_ab_col]{guess_ab_col()}} or input a text (case-insensitive), or use \code{NULL} to skip a column (e.g. \code{TIC = NULL} to skip ticarcillin). Manually defined but non-existing columns will be skipped with a warning.
The following antibiotics are eligible for the functions \code{\link[=eucast_rules]{eucast_rules()}} and \code{\link[=mdro]{mdro()}}. These are shown below in the format 'name (\verb{antimicrobial ID}, \href{https://atcddd.fhi.no/atc/structure_and_principles/}{ATC code})', sorted alphabetically:
Amikacin (\code{AMK}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB06&showdescription=no}{J01GB06}), amoxicillin (\code{AMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA04&showdescription=no}{J01CA04}), amoxicillin/clavulanic acid (\code{AMC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR02&showdescription=no}{J01CR02}), ampicillin (\code{AMP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA01&showdescription=no}{J01CA01}), ampicillin/sulbactam (\code{SAM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR01&showdescription=no}{J01CR01}), apramycin (\code{APR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QA07AA92&showdescription=no}{QA07AA92}), arbekacin (\code{ARB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB12&showdescription=no}{J01GB12}), aspoxicillin (\code{APX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA19&showdescription=no}{J01CA19}), azidocillin (\code{AZD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE04&showdescription=no}{J01CE04}), azithromycin (\code{AZM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA10&showdescription=no}{J01FA10}), azlocillin (\code{AZL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA09&showdescription=no}{J01CA09}), aztreonam (\code{ATM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DF01&showdescription=no}{J01DF01}), bacampicillin (\code{BAM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA06&showdescription=no}{J01CA06}), bekanamycin (\code{BEK}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB13&showdescription=no}{J01GB13}), benzathine benzylpenicillin (\code{BNB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE08&showdescription=no}{J01CE08}), benzathine phenoxymethylpenicillin (\code{BNP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE10&showdescription=no}{J01CE10}), benzylpenicillin (\code{PEN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE01&showdescription=no}{J01CE01}), besifloxacin (\code{BES}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=S01AE08&showdescription=no}{S01AE08}), biapenem (\code{BIA}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH05&showdescription=no}{J01DH05}), carbenicillin (\code{CRB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA03&showdescription=no}{J01CA03}), carindacillin (\code{CRN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA05&showdescription=no}{J01CA05}), cefacetrile (\code{CAC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB10&showdescription=no}{J01DB10}), cefaclor (\code{CEC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC04&showdescription=no}{J01DC04}), cefadroxil (\code{CFR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB05&showdescription=no}{J01DB05}), cefalexin (\code{LEX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB01&showdescription=no}{J01DB01}), cefaloridine (\code{RID}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB02&showdescription=no}{J01DB02}), cefalotin (\code{CEP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB03&showdescription=no}{J01DB03}), cefamandole (\code{MAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC03&showdescription=no}{J01DC03}), cefapirin (\code{HAP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB08&showdescription=no}{J01DB08}), cefatrizine (\code{CTZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB07&showdescription=no}{J01DB07}), cefazedone (\code{CZD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB06&showdescription=no}{J01DB06}), cefazolin (\code{CZO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB04&showdescription=no}{J01DB04}), cefcapene (\code{CCP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD17&showdescription=no}{J01DD17}), cefdinir (\code{CDR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD15&showdescription=no}{J01DD15}), cefditoren (\code{DIT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD16&showdescription=no}{J01DD16}), cefepime (\code{FEP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DE01&showdescription=no}{J01DE01}), cefetamet (\code{CAT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD10&showdescription=no}{J01DD10}), cefiderocol (\code{FDC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI04&showdescription=no}{J01DI04}), cefixime (\code{CFM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD08&showdescription=no}{J01DD08}), cefmenoxime (\code{CMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD05&showdescription=no}{J01DD05}), cefmetazole (\code{CMZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC09&showdescription=no}{J01DC09}), cefodizime (\code{DIZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD09&showdescription=no}{J01DD09}), cefonicid (\code{CID}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC06&showdescription=no}{J01DC06}), cefoperazone (\code{CFP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD12&showdescription=no}{J01DD12}), cefoperazone/sulbactam (\code{CSL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD62&showdescription=no}{J01DD62}), ceforanide (\code{CND}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC11&showdescription=no}{J01DC11}), cefotaxime (\code{CTX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD01&showdescription=no}{J01DD01}), cefotaxime/clavulanic acid (\code{CTC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD51&showdescription=no}{J01DD51}), cefotetan (\code{CTT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC05&showdescription=no}{J01DC05}), cefotiam (\code{CTF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC07&showdescription=no}{J01DC07}), cefovecin (\code{FOV}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01DD91&showdescription=no}{QJ01DD91}), cefoxitin (\code{FOX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC01&showdescription=no}{J01DC01}), cefozopran (\code{ZOP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DE03&showdescription=no}{J01DE03}), cefpiramide (\code{CPM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD11&showdescription=no}{J01DD11}), cefpirome (\code{CPO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DE02&showdescription=no}{J01DE02}), cefpodoxime (\code{CPD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD13&showdescription=no}{J01DD13}), cefprozil (\code{CPR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC10&showdescription=no}{J01DC10}), cefquinome (\code{CEQ}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QG51AA07&showdescription=no}{QG51AA07}), cefroxadine (\code{CRD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB11&showdescription=no}{J01DB11}), cefsulodin (\code{CFS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD03&showdescription=no}{J01DD03}), ceftaroline (\code{CPT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI02&showdescription=no}{J01DI02}), ceftazidime (\code{CAZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD02&showdescription=no}{J01DD02}), ceftazidime/clavulanic acid (\code{CCV}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD52&showdescription=no}{J01DD52}), cefteram (\code{CEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD18&showdescription=no}{J01DD18}), ceftezole (\code{CTL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB12&showdescription=no}{J01DB12}), ceftibuten (\code{CTB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD14&showdescription=no}{J01DD14}), ceftiofur (\code{TIO}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01DD90&showdescription=no}{QJ01DD90}), ceftizoxime (\code{CZX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD07&showdescription=no}{J01DD07}), ceftobiprole medocaril (\code{CFM1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI01&showdescription=no}{J01DI01}), ceftolozane/tazobactam (\code{CZT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DI54&showdescription=no}{J01DI54}), ceftriaxone (\code{CRO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD04&showdescription=no}{J01DD04}), ceftriaxone/beta-lactamase inhibitor (\code{CEB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD63&showdescription=no}{J01DD63}), cefuroxime (\code{CXM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC02&showdescription=no}{J01DC02}), cephradine (\code{CED}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DB09&showdescription=no}{J01DB09}), chloramphenicol (\code{CHL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01BA01&showdescription=no}{J01BA01}), ciprofloxacin (\code{CIP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA02&showdescription=no}{J01MA02}), clarithromycin (\code{CLR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA09&showdescription=no}{J01FA09}), clindamycin (\code{CLI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FF01&showdescription=no}{J01FF01}), clometocillin (\code{CLM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE07&showdescription=no}{J01CE07}), cloxacillin (\code{CLO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF02&showdescription=no}{J01CF02}), colistin (\code{COL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XB01&showdescription=no}{J01XB01}), cycloserine (\code{CYC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J04AB01&showdescription=no}{J04AB01}), dalbavancin (\code{DAL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA04&showdescription=no}{J01XA04}), danofloxacin (\code{DAN}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA92&showdescription=no}{QJ01MA92}), daptomycin (\code{DAP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX09&showdescription=no}{J01XX09}), delafloxacin (\code{DFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA23&showdescription=no}{J01MA23}), dibekacin (\code{DKB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB09&showdescription=no}{J01GB09}), dicloxacillin (\code{DIC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF01&showdescription=no}{J01CF01}), difloxacin (\code{DIF}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA94&showdescription=no}{QJ01MA94}), dirithromycin (\code{DIR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA13&showdescription=no}{J01FA13}), doripenem (\code{DOR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH04&showdescription=no}{J01DH04}), doxycycline (\code{DOX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA02&showdescription=no}{J01AA02}), enoxacin (\code{ENX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA04&showdescription=no}{J01MA04}), enrofloxacin (\code{ENR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA90&showdescription=no}{QJ01MA90}), epicillin (\code{EPC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA07&showdescription=no}{J01CA07}), ertapenem (\code{ETP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH03&showdescription=no}{J01DH03}), erythromycin (\code{ERY}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA01&showdescription=no}{J01FA01}), fleroxacin (\code{FLE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA08&showdescription=no}{J01MA08}), flucloxacillin (\code{FLC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF05&showdescription=no}{J01CF05}), flurithromycin (\code{FLR1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA14&showdescription=no}{J01FA14}), fosfomycin (\code{FOS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX01&showdescription=no}{J01XX01}), framycetin (\code{FRM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=D09AA01&showdescription=no}{D09AA01}), fusidic acid (\code{FUS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XC01&showdescription=no}{J01XC01}), gamithromycin (\code{GAM}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA95&showdescription=no}{QJ01FA95}), garenoxacin (\code{GRN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA19&showdescription=no}{J01MA19}), gatifloxacin (\code{GAT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA16&showdescription=no}{J01MA16}), gemifloxacin (\code{GEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA15&showdescription=no}{J01MA15}), gentamicin (\code{GEN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB03&showdescription=no}{J01GB03}), grepafloxacin (\code{GRX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA11&showdescription=no}{J01MA11}), hetacillin (\code{HET}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA18&showdescription=no}{J01CA18}), imipenem (\code{IPM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH51&showdescription=no}{J01DH51}), imipenem/relebactam (\code{IMR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH56&showdescription=no}{J01DH56}), isepamicin (\code{ISE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB11&showdescription=no}{J01GB11}), josamycin (\code{JOS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA07&showdescription=no}{J01FA07}), kanamycin (\code{KAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB04&showdescription=no}{J01GB04}), kitasamycin (\code{KIT}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA93&showdescription=no}{QJ01FA93}), lascufloxacin (\code{LSC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA25&showdescription=no}{J01MA25}), latamoxef (\code{LTM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DD06&showdescription=no}{J01DD06}), levofloxacin (\code{LVX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA12&showdescription=no}{J01MA12}), levonadifloxacin (\code{LND}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA24&showdescription=no}{J01MA24}), lincomycin (\code{LIN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FF02&showdescription=no}{J01FF02}), linezolid (\code{LNZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX08&showdescription=no}{J01XX08}), lomefloxacin (\code{LOM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA07&showdescription=no}{J01MA07}), loracarbef (\code{LOR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DC08&showdescription=no}{J01DC08}), marbofloxacin (\code{MAR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA93&showdescription=no}{QJ01MA93}), mecillinam (\code{MEC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA11&showdescription=no}{J01CA11}), meropenem (\code{MEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH02&showdescription=no}{J01DH02}), meropenem/vaborbactam (\code{MEV}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH52&showdescription=no}{J01DH52}), metampicillin (\code{MTM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA14&showdescription=no}{J01CA14}), meticillin (\code{MET}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF03&showdescription=no}{J01CF03}), mezlocillin (\code{MEZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA10&showdescription=no}{J01CA10}), micronomicin (\code{MCR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=S01AA22&showdescription=no}{S01AA22}), midecamycin (\code{MID}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA03&showdescription=no}{J01FA03}), minocycline (\code{MNO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA08&showdescription=no}{J01AA08}), miocamycin (\code{MCM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA11&showdescription=no}{J01FA11}), moxifloxacin (\code{MFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA14&showdescription=no}{J01MA14}), nadifloxacin (\code{NAD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=D10AF05&showdescription=no}{D10AF05}), nafcillin (\code{NAF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF06&showdescription=no}{J01CF06}), nalidixic acid (\code{NAL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MB02&showdescription=no}{J01MB02}), neomycin (\code{NEO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB05&showdescription=no}{J01GB05}), netilmicin (\code{NET}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB07&showdescription=no}{J01GB07}), nitrofurantoin (\code{NIT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XE01&showdescription=no}{J01XE01}), norfloxacin (\code{NOR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA06&showdescription=no}{J01MA06}), novobiocin (\code{NOV}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01XX95&showdescription=no}{QJ01XX95}), ofloxacin (\code{OFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA01&showdescription=no}{J01MA01}), oleandomycin (\code{OLE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA05&showdescription=no}{J01FA05}), orbifloxacin (\code{ORB}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA95&showdescription=no}{QJ01MA95}), oritavancin (\code{ORI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA05&showdescription=no}{J01XA05}), oxacillin (\code{OXA}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CF04&showdescription=no}{J01CF04}), panipenem (\code{PAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH55&showdescription=no}{J01DH55}), pazufloxacin (\code{PAZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA18&showdescription=no}{J01MA18}), pefloxacin (\code{PEF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA03&showdescription=no}{J01MA03}), penamecillin (\code{PNM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE06&showdescription=no}{J01CE06}), pheneticillin (\code{PHE}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE05&showdescription=no}{J01CE05}), phenoxymethylpenicillin (\code{PHN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE02&showdescription=no}{J01CE02}), piperacillin (\code{PIP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA12&showdescription=no}{J01CA12}), piperacillin/tazobactam (\code{TZP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR05&showdescription=no}{J01CR05}), pirlimycin (\code{PRL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ51FF90&showdescription=no}{QJ51FF90}), pivampicillin (\code{PVM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA02&showdescription=no}{J01CA02}), pivmecillinam (\code{PME}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA08&showdescription=no}{J01CA08}), plazomicin (\code{PLZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB14&showdescription=no}{J01GB14}), polymyxin B (\code{PLB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XB02&showdescription=no}{J01XB02}), pradofloxacin (\code{PRA}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA97&showdescription=no}{QJ01MA97}), pristinamycin (\code{PRI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FG01&showdescription=no}{J01FG01}), procaine benzylpenicillin (\code{PRB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE09&showdescription=no}{J01CE09}), propicillin (\code{PRP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CE03&showdescription=no}{J01CE03}), prulifloxacin (\code{PRU}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA17&showdescription=no}{J01MA17}), quinupristin/dalfopristin (\code{QDA}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FG02&showdescription=no}{QJ01FG02}), ribostamycin (\code{RST}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB10&showdescription=no}{J01GB10}), rifampicin (\code{RIF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J04AB02&showdescription=no}{J04AB02}), rokitamycin (\code{ROK}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA12&showdescription=no}{J01FA12}), roxithromycin (\code{RXT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA06&showdescription=no}{J01FA06}), rufloxacin (\code{RFL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA10&showdescription=no}{J01MA10}), sarafloxacin (\code{SAR}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01MA98&showdescription=no}{QJ01MA98}), sisomicin (\code{SIS}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB08&showdescription=no}{J01GB08}), sitafloxacin (\code{SIT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA21&showdescription=no}{J01MA21}), solithromycin (\code{SOL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA16&showdescription=no}{J01FA16}), sparfloxacin (\code{SPX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA09&showdescription=no}{J01MA09}), spiramycin (\code{SPI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA02&showdescription=no}{J01FA02}), streptoduocin (\code{STR}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GA02&showdescription=no}{J01GA02}), streptomycin (\code{STR1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GA01&showdescription=no}{J01GA01}), sulbactam (\code{SUL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CG01&showdescription=no}{J01CG01}), sulbenicillin (\code{SBC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA16&showdescription=no}{J01CA16}), sulfadiazine (\code{SDI}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EC02&showdescription=no}{J01EC02}), sulfadiazine/trimethoprim (\code{SLT1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE02&showdescription=no}{J01EE02}), sulfadimethoxine (\code{SUD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED01&showdescription=no}{J01ED01}), sulfadimidine (\code{SDM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB03&showdescription=no}{J01EB03}), sulfadimidine/trimethoprim (\code{SLT2}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE05&showdescription=no}{J01EE05}), sulfafurazole (\code{SLF}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB05&showdescription=no}{J01EB05}), sulfaisodimidine (\code{SLF1}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB01&showdescription=no}{J01EB01}), sulfalene (\code{SLF2}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED02&showdescription=no}{J01ED02}), sulfamazone (\code{SZO}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED09&showdescription=no}{J01ED09}), sulfamerazine (\code{SLF3}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED07&showdescription=no}{J01ED07}), sulfamerazine/trimethoprim (\code{SLT3}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE07&showdescription=no}{J01EE07}), sulfamethizole (\code{SLF4}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB02&showdescription=no}{J01EB02}), sulfamethoxazole (\code{SMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EC01&showdescription=no}{J01EC01}), sulfamethoxypyridazine (\code{SLF5}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED05&showdescription=no}{J01ED05}), sulfametomidine (\code{SLF6}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED03&showdescription=no}{J01ED03}), sulfametoxydiazine (\code{SLF7}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED04&showdescription=no}{J01ED04}), sulfametrole/trimethoprim (\code{SLT4}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE03&showdescription=no}{J01EE03}), sulfamoxole (\code{SLF8}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EC03&showdescription=no}{J01EC03}), sulfamoxole/trimethoprim (\code{SLT5}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE04&showdescription=no}{J01EE04}), sulfanilamide (\code{SLF9}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB06&showdescription=no}{J01EB06}), sulfaperin (\code{SLF10}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED06&showdescription=no}{J01ED06}), sulfaphenazole (\code{SLF11}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01ED08&showdescription=no}{J01ED08}), sulfapyridine (\code{SLF12}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB04&showdescription=no}{J01EB04}), sulfathiazole (\code{SUT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB07&showdescription=no}{J01EB07}), sulfathiourea (\code{SLF13}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EB08&showdescription=no}{J01EB08}), sultamicillin (\code{SLT6}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR04&showdescription=no}{J01CR04}), talampicillin (\code{TAL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA15&showdescription=no}{J01CA15}), tazobactam (\code{TAZ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CG02&showdescription=no}{J01CG02}), tebipenem (\code{TBP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01DH06&showdescription=no}{J01DH06}), tedizolid (\code{TZD}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XX11&showdescription=no}{J01XX11}), teicoplanin (\code{TEC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA02&showdescription=no}{J01XA02}), telavancin (\code{TLV}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA03&showdescription=no}{J01XA03}), telithromycin (\code{TLT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA15&showdescription=no}{J01FA15}), temafloxacin (\code{TMX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA05&showdescription=no}{J01MA05}), temocillin (\code{TEM}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA17&showdescription=no}{J01CA17}), tetracycline (\code{TCY}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA07&showdescription=no}{J01AA07}), ticarcillin (\code{TIC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CA13&showdescription=no}{J01CA13}), ticarcillin/clavulanic acid (\code{TCC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01CR03&showdescription=no}{J01CR03}), tigecycline (\code{TGC}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01AA12&showdescription=no}{J01AA12}), tilbroquinol (\code{TBQ}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=P01AA05&showdescription=no}{P01AA05}), tildipirosin (\code{TIP}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA96&showdescription=no}{QJ01FA96}), tilmicosin (\code{TIL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA91&showdescription=no}{QJ01FA91}), tobramycin (\code{TOB}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01GB01&showdescription=no}{J01GB01}), tosufloxacin (\code{TFX}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA22&showdescription=no}{J01MA22}), trimethoprim (\code{TMP}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EA01&showdescription=no}{J01EA01}), trimethoprim/sulfamethoxazole (\code{SXT}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01EE01&showdescription=no}{J01EE01}), troleandomycin (\code{TRL}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01FA08&showdescription=no}{J01FA08}), trovafloxacin (\code{TVA}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01MA13&showdescription=no}{J01MA13}), tulathromycin (\code{TUL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA94&showdescription=no}{QJ01FA94}), tylosin (\code{TYL}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA90&showdescription=no}{QJ01FA90}), tylvalosin (\code{TYL1}, \href{https://atcddd.fhi.no/atcvet/atcvet_index/?code=QJ01FA92&showdescription=no}{QJ01FA92}), vancomycin (\code{VAN}, \href{https://atcddd.fhi.no/atc_ddd_index//?code=J01XA01&showdescription=no}{J01XA01})
}
\section{Interpretation of SIR}{
In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (\url{https://www.eucast.org/newsiandr}):
\itemize{
\item \strong{S - Susceptible, standard dosing regimen}\cr
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.
\item \strong{I - Susceptible, increased exposure} \emph{\cr
A microorganism is categorised as "Susceptible, Increased exposure}" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.
\item \strong{R = Resistant}\cr
A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.
\itemize{
\item \emph{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.
}
}
This AMR package honours this insight. Use \code{\link[=susceptibility]{susceptibility()}} (equal to \code{\link[=proportion_SI]{proportion_SI()}}) to determine antimicrobial susceptibility and \code{\link[=count_susceptible]{count_susceptible()}} (equal to \code{\link[=count_SI]{count_SI()}}) to count susceptible isolates.
}
\examples{
out <- mdro(example_isolates, guideline = "EUCAST")
str(out)
table(out)
out <- mdro(example_isolates,
guideline = custom_mdro_guideline(
AMX == "R" ~ "Custom MDRO 1",
VAN == "R" ~ "Custom MDRO 2"
)
)
table(out)
\donttest{
if (require("dplyr")) {
example_isolates \%>\%
mdro() \%>\%
table()
# no need to define `x` when used inside dplyr verbs:
example_isolates \%>\%
mutate(MDRO = mdro()) \%>\%
pull(MDRO) \%>\%
table()
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/mean_amr_distance.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mean_amr_distance.R
\name{mean_amr_distance}
\alias{mean_amr_distance}
\alias{mean_amr_distance.sir}
\alias{mean_amr_distance.data.frame}
\alias{amr_distance_from_row}
\title{Calculate the Mean AMR Distance}
\usage{
mean_amr_distance(x, ...)
\method{mean_amr_distance}{sir}(x, ..., combine_SI = TRUE)
\method{mean_amr_distance}{data.frame}(x, ..., combine_SI = TRUE)
amr_distance_from_row(amr_distance, row)
}
\arguments{
\item{x}{a vector of class \link[=as.sir]{sir}, \link[=as.mic]{mic} or \link[=as.disk]{disk}, or a \link{data.frame} containing columns of any of these classes}
\item{...}{variables to select (supports \link[tidyselect:language]{tidyselect language} such as \code{column1:column4} and \code{where(is.mic)}, and can thus also be \link[=ab_selector]{antibiotic selectors}}
\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the input only consists of S+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}}
\item{amr_distance}{the outcome of \code{\link[=mean_amr_distance]{mean_amr_distance()}}}
\item{row}{an index, such as a row number}
}
\description{
Calculates a normalised mean for antimicrobial resistance between multiple observations, to help to identify similar isolates without comparing antibiograms by hand.
}
\details{
The mean AMR distance is effectively \href{https://en.wikipedia.org/wiki/Standard_score}{the Z-score}; a normalised numeric value to compare AMR test results which can help to identify similar isolates, without comparing antibiograms by hand.
MIC values (see \code{\link[=as.mic]{as.mic()}}) are transformed with \code{\link[=log2]{log2()}} first; their distance is thus calculated as \code{(log2(x) - mean(log2(x))) / sd(log2(x))}.
SIR values (see \code{\link[=as.sir]{as.sir()}}) are transformed using \code{"S"} = 1, \code{"I"} = 2, and \code{"R"} = 3. If \code{combine_SI} is \code{TRUE} (default), the \code{"I"} will be considered to be 1.
For data sets, the mean AMR distance will be calculated per column, after which the mean per row will be returned, see \emph{Examples}.
Use \code{\link[=amr_distance_from_row]{amr_distance_from_row()}} to subtract distances from the distance of one row, see \emph{Examples}.
}
\section{Interpretation}{
Isolates with distances less than 0.01 difference from each other should be considered similar. Differences lower than 0.025 should be considered suspicious.
}
\examples{
sir <- random_sir(10)
sir
mean_amr_distance(sir)
mic <- random_mic(10)
mic
mean_amr_distance(mic)
# equal to the Z-score of their log2:
(log2(mic) - mean(log2(mic))) / sd(log2(mic))
disk <- random_disk(10)
disk
mean_amr_distance(disk)
y <- data.frame(
id = LETTERS[1:10],
amox = random_sir(10, ab = "amox", mo = "Escherichia coli"),
cipr = random_disk(10, ab = "cipr", mo = "Escherichia coli"),
gent = random_mic(10, ab = "gent", mo = "Escherichia coli"),
tobr = random_mic(10, ab = "tobr", mo = "Escherichia coli")
)
y
mean_amr_distance(y)
y$amr_distance <- mean_amr_distance(y, where(is.mic))
y[order(y$amr_distance), ]
if (require("dplyr")) {
y \%>\%
mutate(
amr_distance = mean_amr_distance(y),
check_id_C = amr_distance_from_row(amr_distance, id == "C")
) \%>\%
arrange(check_id_C)
}
if (require("dplyr")) {
# support for groups
example_isolates \%>\%
filter(mo_genus() == "Enterococcus" & mo_species() != "") \%>\%
select(mo, TCY, carbapenems()) \%>\%
group_by(mo) \%>\%
mutate(dist = mean_amr_distance(.)) \%>\%
arrange(mo, dist)
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/microorganisms.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{microorganisms}
\alias{microorganisms}
\title{Data Set with 78 678 Taxonomic Records of Microorganisms}
\format{
A \link[tibble:tibble]{tibble} with 78 678 observations and 26 variables:
\itemize{
\item \code{mo}\cr ID of microorganism as used by this package. \emph{\strong{This is a unique identifier.}}
\item \code{fullname}\cr Full name, like \code{"Escherichia coli"}. For the taxonomic ranks genus, species and subspecies, this is the 'pasted' text of genus, species, and subspecies. For all taxonomic ranks higher than genus, this is the name of the taxon. \emph{\strong{This is a unique identifier.}}
\item \code{status} \cr Status of the taxon, either "accepted", "not validly published", "synonym", or "unknown"
\item \code{kingdom}, \code{phylum}, \code{class}, \code{order}, \code{family}, \code{genus}, \code{species}, \code{subspecies}\cr Taxonomic rank of the microorganism. Note that for fungi, \emph{phylum} is equal to their taxonomic \emph{division}. Also, for fungi, \emph{subkingdom} and \emph{subdivision} were left out since they do not occur in the bacterial taxonomy.
\item \code{rank}\cr Text of the taxonomic rank of the microorganism, such as \code{"species"} or \code{"genus"}
\item \code{ref}\cr Author(s) and year of related scientific publication. This contains only the \emph{first surname} and year of the \emph{latest} authors, e.g. "Wallis \emph{et al.} 2006 \emph{emend.} Smith and Jones 2018" becomes "Smith \emph{et al.}, 2018". This field is directly retrieved from the source specified in the column \code{source}. Moreover, accents were removed to comply with CRAN that only allows ASCII characters.
\item \code{oxygen_tolerance} \cr Oxygen tolerance, either "aerobe", "anaerobe", "anaerobe/microaerophile", "facultative anaerobe", "likely facultative anaerobe", or "microaerophile". These data were retrieved from BacDive (see \emph{Source}). Items that contain "likely" are missing from BacDive and were extrapolated from other species within the same genus to guess the oxygen tolerance. Currently 68.3\% of all ~39 000 bacteria in the data set contain an oxygen tolerance.
\item \code{source}\cr Either "GBIF", "LPSN", "MycoBank", or "manually added" (see \emph{Source})
\item \code{lpsn}\cr Identifier ('Record number') of List of Prokaryotic names with Standing in Nomenclature (LPSN). This will be the first/highest LPSN identifier to keep one identifier per row. For example, \emph{Acetobacter ascendens} has LPSN Record number 7864 and 11011. Only the first is available in the \code{microorganisms} data set. \emph{\strong{This is a unique identifier}}, though available for only ~33 000 records.
\item \code{lpsn_parent}\cr LPSN identifier of the parent taxon
\item \code{lpsn_renamed_to}\cr LPSN identifier of the currently valid taxon
\item \code{mycobank}\cr Identifier ('MycoBank #') of MycoBank. \emph{\strong{This is a unique identifier}}, though available for only ~18 000 records.
\item \code{mycobank_parent}\cr MycoBank identifier of the parent taxon
\item \code{mycobank_renamed_to}\cr MycoBank identifier of the currently valid taxon
\item \code{gbif}\cr Identifier ('taxonID') of Global Biodiversity Information Facility (GBIF). \emph{\strong{This is a unique identifier}}, though available for only ~49 000 records.
\item \code{gbif_parent}\cr GBIF identifier of the parent taxon
\item \code{gbif_renamed_to}\cr GBIF identifier of the currently valid taxon
\item \code{prevalence}\cr Prevalence of the microorganism based on Bartlett \emph{et al.} (2022, \doi{10.1099/mic.0.001269}), see \code{\link[=mo_matching_score]{mo_matching_score()}} for the full explanation
\item \code{snomed}\cr Systematized Nomenclature of Medicine (SNOMED) code of the microorganism, version of July 16th, 2024 (see \emph{Source}). Use \code{\link[=mo_snomed]{mo_snomed()}} to retrieve it quickly, see \code{\link[=mo_property]{mo_property()}}.
}
}
\source{
Taxonomic entries were imported in this order of importance:
\enumerate{
\item List of Prokaryotic names with Standing in Nomenclature (LPSN):\cr\cr
Parte, AC \emph{et al.} (2020). \strong{List of Prokaryotic names with Standing in Nomenclature (LPSN) moves to the DSMZ.} International Journal of Systematic and Evolutionary Microbiology, 70, 5607-5612; \doi{10.1099/ijsem.0.004332}. Accessed from \url{https://lpsn.dsmz.de} on June 24th, 2024.
\item MycoBank:\cr\cr
Vincent, R \emph{et al} (2013). \strong{MycoBank gearing up for new horizons.} IMA Fungus, 4(2), 371-9; \doi{10.5598/imafungus.2013.04.02.16}. Accessed from \url{https://www.mycobank.org} on June 24th, 2024.
\item Global Biodiversity Information Facility (GBIF):\cr\cr
GBIF Secretariat (2023). GBIF Backbone Taxonomy. Checklist dataset \doi{10.15468/39omei}. Accessed from \url{https://www.gbif.org} on June 24th, 2024.
}
Furthermore, these sources were used for additional details:
\itemize{
\item BacDive:\cr\cr
Reimer, LC \emph{et al.} (2022). \strong{\emph{BacDive} in 2022: the knowledge base for standardized bacterial and archaeal data.} Nucleic Acids Res., 50(D1):D741-D74; \doi{10.1093/nar/gkab961}. Accessed from \url{https://bacdive.dsmz.de} on July 16th, 2024.
\item Systematized Nomenclature of Medicine - Clinical Terms (SNOMED-CT):\cr\cr
Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS). US Edition of SNOMED CT from 1 September 2020. Value Set Name 'Microorganism', OID 2.16.840.1.114222.4.11.1009 (v12). Accessed from \url{https://phinvads.cdc.gov} on July 16th, 2024.
\item Grimont \emph{et al.} (2007). Antigenic Formulae of the Salmonella Serovars, 9th Edition. WHO Collaborating Centre for Reference and Research on \emph{Salmonella} (WHOCC-SALM).
\item Bartlett \emph{et al.} (2022). \strong{A comprehensive list of bacterial pathogens infecting humans} \emph{Microbiology} 168:001269; \doi{10.1099/mic.0.001269}
}
}
\usage{
microorganisms
}
\description{
A data set containing the full microbial taxonomy (\strong{last updated: June 24th, 2024}) of six kingdoms. This data set is the backbone of this \code{AMR} package. MO codes can be looked up using \code{\link[=as.mo]{as.mo()}} and microorganism properties can be looked up using any of the \code{\link[=mo_property]{mo_*}} functions.
This data set is carefully crafted, yet made 100\% reproducible from public and authoritative taxonomic sources (using \href{https://github.com/msberends/AMR/blob/main/data-raw/reproduction_of_microorganisms.R}{this script}), namely: \emph{List of Prokaryotic names with Standing in Nomenclature (LPSN)} for bacteria, \emph{MycoBank} for fungi, and \emph{Global Biodiversity Information Facility (GBIF)} for all others taxons.
}
\details{
Please note that entries are only based on LPSN, MycoBank, and GBIF (see below). Since these sources incorporate entries based on (recent) publications in the International Journal of Systematic and Evolutionary Microbiology (IJSEM), it can happen that the year of publication is sometimes later than one might expect.
For example, \emph{Staphylococcus pettenkoferi} was described for the first time in Diagnostic Microbiology and Infectious Disease in 2002 (\doi{10.1016/s0732-8893(02)00399-1}), but it was not until 2007 that a publication in IJSEM followed (\doi{10.1099/ijs.0.64381-0}). Consequently, the \code{AMR} package returns 2007 for \code{mo_year("S. pettenkoferi")}.
}
\section{Included Taxa}{
Included taxonomic data from \href{https://lpsn.dsmz.de}{LPSN}, \href{https://www.mycobank.org}{MycoBank}, and \href{https://www.gbif.org}{GBIF} are:
\itemize{
\item All ~39 000 (sub)species from the kingdoms of Archaea and Bacteria
\item ~28 000 species from the kingdom of Fungi. The kingdom of Fungi is a very large taxon with almost 300,000 different (sub)species, of which most are not microbial (but rather macroscopic, like mushrooms). Because of this, not all fungi fit the scope of this package. Only relevant fungi are covered (such as all species of \emph{Aspergillus}, \emph{Candida}, \emph{Cryptococcus}, \emph{Histoplasma}, \emph{Pneumocystis}, \emph{Saccharomyces} and \emph{Trichophyton}).
\item ~8 100 (sub)species from the kingdom of Protozoa
\item ~1 600 (sub)species from 39 other relevant genera from the kingdom of Animalia (such as \emph{Strongyloides} and \emph{Taenia})
\item All ~22 000 previously accepted names of all included (sub)species (these were taxonomically renamed)
\item The complete taxonomic tree of all included (sub)species: from kingdom to subspecies
\item The identifier of the parent taxons
\item The year and first author of the related scientific publication
}
\subsection{Manual additions}{
For convenience, some entries were added manually:
\itemize{
\item ~1 500 entries of \emph{Salmonella}, such as the city-like serovars and groups A to H
\item 36 species groups (such as the beta-haemolytic \emph{Streptococcus} groups A to K, coagulase-negative \emph{Staphylococcus} (CoNS), \emph{Mycobacterium tuberculosis} complex, etc.), of which the group compositions are stored in the \link{microorganisms.groups} data set
\item 1 entry of \emph{Blastocystis} (\emph{B. hominis}), although it officially does not exist (Noel \emph{et al.} 2005, PMID 15634993)
\item 1 entry of \emph{Moraxella} (\emph{M. catarrhalis}), which was formally named \emph{Branhamella catarrhalis} (Catlin, 1970) though this change was never accepted within the field of clinical microbiology
\item 8 other 'undefined' entries (unknown, unknown Gram-negatives, unknown Gram-positives, unknown yeast, unknown fungus, and unknown anaerobic Gram-pos/Gram-neg bacteria)
}
The syntax used to transform the original data to a cleansed \R format, can be \href{https://github.com/msberends/AMR/blob/main/data-raw/reproduction_of_microorganisms.R}{found here}.
}
\subsection{Direct download}{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
}
\examples{
microorganisms
}
\seealso{
\code{\link[=as.mo]{as.mo()}}, \code{\link[=mo_property]{mo_property()}}, \link{microorganisms.groups}, \link{microorganisms.codes}, \link{intrinsic_resistant}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/microorganisms.codes.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{microorganisms.codes}
\alias{microorganisms.codes}
\title{Data Set with 4 971 Common Microorganism Codes}
\format{
A \link[tibble:tibble]{tibble} with 4 971 observations and 2 variables:
\itemize{
\item \code{code}\cr Commonly used code of a microorganism. \emph{\strong{This is a unique identifier.}}
\item \code{mo}\cr ID of the microorganism in the \link{microorganisms} data set
}
}
\usage{
microorganisms.codes
}
\description{
A data set containing commonly used codes for microorganisms, from laboratory systems and \href{https://whonet.org}{WHONET}. Define your own with \code{\link[=set_mo_source]{set_mo_source()}}. They will all be searched when using \code{\link[=as.mo]{as.mo()}} and consequently all the \code{\link[=mo_property]{mo_*}} functions.
}
\details{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
microorganisms.codes
# 'ECO' or 'eco' is the WHONET code for E. coli:
microorganisms.codes[microorganisms.codes$code == "ECO", ]
# and therefore, 'eco' will be understood as E. coli in this package:
mo_info("eco")
# works for all AMR functions:
mo_is_intrinsic_resistant("eco", ab = "vancomycin")
}
\seealso{
\code{\link[=as.mo]{as.mo()}} \link{microorganisms}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/microorganisms.groups.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/data.R
\docType{data}
\name{microorganisms.groups}
\alias{microorganisms.groups}
\title{Data Set with 521 Microorganisms In Species Groups}
\format{
A \link[tibble:tibble]{tibble} with 521 observations and 4 variables:
\itemize{
\item \code{mo_group}\cr ID of the species group / microbiological complex
\item \code{mo}\cr ID of the microorganism belonging in the species group / microbiological complex
\item \code{mo_group_name}\cr Name of the species group / microbiological complex, as retrieved with \code{\link[=mo_name]{mo_name()}}
\item \code{mo_name}\cr Name of the microorganism belonging in the species group / microbiological complex, as retrieved with \code{\link[=mo_name]{mo_name()}}
}
}
\usage{
microorganisms.groups
}
\description{
A data set containing species groups and microbiological complexes, which are used in \link[=clinical_breakpoints]{the clinical breakpoints table}.
}
\details{
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
microorganisms.groups
# these are all species in the Bacteroides fragilis group, as per WHONET:
microorganisms.groups[microorganisms.groups$mo_group == "B_BCTRD_FRGL-C", ]
}
\seealso{
\code{\link[=as.mo]{as.mo()}} \link{microorganisms}
}
\keyword{datasets}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/mo_matching_score.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mo_matching_score.R
\name{mo_matching_score}
\alias{mo_matching_score}
\title{Calculate the Matching Score for Microorganisms}
\usage{
mo_matching_score(x, n)
}
\arguments{
\item{x}{Any user input value(s)}
\item{n}{A full taxonomic name, that exists in \code{\link[=microorganisms]{microorganisms$fullname}}}
}
\description{
This algorithm is used by \code{\link[=as.mo]{as.mo()}} and all the \code{\link[=mo_property]{mo_*}} functions to determine the most probable match of taxonomic records based on user input.
}
\note{
This algorithm was originally developed in 2018 and subsequently described in: Berends MS \emph{et al.} (2022). \strong{AMR: An R Package for Working with Antimicrobial Resistance Data}. \emph{Journal of Statistical Software}, 104(3), 1-31; \doi{10.18637/jss.v104.i03}.
Later, the work of Bartlett A \emph{et al.} about bacterial pathogens infecting humans (2022, \doi{10.1099/mic.0.001269}) was incorporated, and optimalisations to the algorithm were made.
}
\section{Matching Score for Microorganisms}{
With ambiguous user input in \code{\link[=as.mo]{as.mo()}} and all the \code{\link[=mo_property]{mo_*}} functions, the returned results are chosen based on their matching score using \code{\link[=mo_matching_score]{mo_matching_score()}}. This matching score \eqn{m}, is calculated as:
\ifelse{latex}{\deqn{m_{(x, n)} = \frac{l_{n} - 0.5 \cdot \min \begin{cases}l_{n} \\ \textrm{lev}(x, n)\end{cases}}{l_{n} \cdot p_{n} \cdot k_{n}}}}{
\ifelse{html}{\figure{mo_matching_score.png}{options: width="300" alt="mo matching score"}}{m(x, n) = ( l_n * min(l_n, lev(x, n) ) ) / ( l_n * p_n * k_n )}}
where:
\itemize{
\item \eqn{x} is the user input;
\item \eqn{n} is a taxonomic name (genus, species, and subspecies);
\item \eqn{l_n} is the length of \eqn{n};
\item \eqn{lev} is the \href{https://en.wikipedia.org/wiki/Levenshtein_distance}{Levenshtein distance function} (counting any insertion as 1, and any deletion or substitution as 2) that is needed to change \eqn{x} into \eqn{n};
\item \eqn{p_n} is the human pathogenic prevalence group of \eqn{n}, as described below;
\item \eqn{k_n} is the taxonomic kingdom of \eqn{n}, set as Bacteria = 1, Fungi = 1.25, Protozoa = 1.5, Chromista = 1.75, Archaea = 2, others = 3.
}
The grouping into human pathogenic prevalence \eqn{p} is based on recent work from Bartlett \emph{et al.} (2022, \doi{10.1099/mic.0.001269}) who extensively studied medical-scientific literature to categorise all bacterial species into these groups:
\itemize{
\item \strong{Established}, if a taxonomic species has infected at least three persons in three or more references. These records have \code{prevalence = 1.15} in the \link{microorganisms} data set;
\item \strong{Putative}, if a taxonomic species has fewer than three known cases. These records have \code{prevalence = 1.25} in the \link{microorganisms} data set.
}
Furthermore,
\itemize{
\item Genera from the World Health Organization's (WHO) Priority Pathogen List have \code{prevalence = 1.0} in the \link{microorganisms} data set;
\item Any genus present in the \strong{established} list also has \code{prevalence = 1.15} in the \link{microorganisms} data set;
\item Any other genus present in the \strong{putative} list has \code{prevalence = 1.25} in the \link{microorganisms} data set;
\item Any other species or subspecies of which the genus is present in the two aforementioned groups, has \code{prevalence = 1.5} in the \link{microorganisms} data set;
\item Any \emph{non-bacterial} genus, species or subspecies of which the genus is present in the following list, has \code{prevalence = 1.25} in the \link{microorganisms} data set: \emph{Absidia}, \emph{Acanthamoeba}, \emph{Acremonium}, \emph{Actinomucor}, \emph{Aedes}, \emph{Alternaria}, \emph{Amoeba}, \emph{Ancylostoma}, \emph{Angiostrongylus}, \emph{Anisakis}, \emph{Anopheles}, \emph{Apophysomyces}, \emph{Arthroderma}, \emph{Aspergillus}, \emph{Aureobasidium}, \emph{Basidiobolus}, \emph{Beauveria}, \emph{Bipolaris}, \emph{Blastobotrys}, \emph{Blastocystis}, \emph{Blastomyces}, \emph{Candida}, \emph{Capillaria}, \emph{Chaetomium}, \emph{Chilomastix}, \emph{Chrysonilia}, \emph{Chrysosporium}, \emph{Cladophialophora}, \emph{Cladosporium}, \emph{Clavispora}, \emph{Coccidioides}, \emph{Cokeromyces}, \emph{Conidiobolus}, \emph{Coniochaeta}, \emph{Contracaecum}, \emph{Cordylobia}, \emph{Cryptococcus}, \emph{Cryptosporidium}, \emph{Cunninghamella}, \emph{Curvularia}, \emph{Cyberlindnera}, \emph{Debaryozyma}, \emph{Demodex}, \emph{Dermatobia}, \emph{Dientamoeba}, \emph{Diphyllobothrium}, \emph{Dirofilaria}, \emph{Echinostoma}, \emph{Entamoeba}, \emph{Enterobius}, \emph{Epidermophyton}, \emph{Exidia}, \emph{Exophiala}, \emph{Exserohilum}, \emph{Fasciola}, \emph{Fonsecaea}, \emph{Fusarium}, \emph{Geotrichum}, \emph{Giardia}, \emph{Graphium}, \emph{Haloarcula}, \emph{Halobacterium}, \emph{Halococcus}, \emph{Hansenula}, \emph{Hendersonula}, \emph{Heterophyes}, \emph{Histomonas}, \emph{Histoplasma}, \emph{Hortaea}, \emph{Hymenolepis}, \emph{Hypomyces}, \emph{Hysterothylacium}, \emph{Kloeckera}, \emph{Kluyveromyces}, \emph{Kodamaea}, \emph{Lacazia}, \emph{Leishmania}, \emph{Lichtheimia}, \emph{Lodderomyces}, \emph{Lomentospora}, \emph{Madurella}, \emph{Malassezia}, \emph{Malbranchea}, \emph{Metagonimus}, \emph{Meyerozyma}, \emph{Microsporidium}, \emph{Microsporum}, \emph{Millerozyma}, \emph{Mortierella}, \emph{Mucor}, \emph{Mycocentrospora}, \emph{Nannizzia}, \emph{Necator}, \emph{Nectria}, \emph{Ochroconis}, \emph{Oesophagostomum}, \emph{Oidiodendron}, \emph{Opisthorchis}, \emph{Paecilomyces}, \emph{Paracoccidioides}, \emph{Pediculus}, \emph{Penicillium}, \emph{Phaeoacremonium}, \emph{Phaeomoniella}, \emph{Phialophora}, \emph{Phlebotomus}, \emph{Phoma}, \emph{Pichia}, \emph{Piedraia}, \emph{Pithomyces}, \emph{Pityrosporum}, \emph{Pneumocystis}, \emph{Pseudallescheria}, \emph{Pseudoscopulariopsis}, \emph{Pseudoterranova}, \emph{Pulex}, \emph{Purpureocillium}, \emph{Quambalaria}, \emph{Rhinocladiella}, \emph{Rhizomucor}, \emph{Rhizopus}, \emph{Rhodotorula}, \emph{Saccharomyces}, \emph{Saksenaea}, \emph{Saprochaete}, \emph{Sarcoptes}, \emph{Scedosporium}, \emph{Schistosoma}, \emph{Schizosaccharomyces}, \emph{Scolecobasidium}, \emph{Scopulariopsis}, \emph{Scytalidium}, \emph{Spirometra}, \emph{Sporobolomyces}, \emph{Sporopachydermia}, \emph{Sporothrix}, \emph{Sporotrichum}, \emph{Stachybotrys}, \emph{Strongyloides}, \emph{Syncephalastrum}, \emph{Syngamus}, \emph{Taenia}, \emph{Talaromyces}, \emph{Teleomorph}, \emph{Toxocara}, \emph{Trichinella}, \emph{Trichobilharzia}, \emph{Trichoderma}, \emph{Trichomonas}, \emph{Trichophyton}, \emph{Trichosporon}, \emph{Trichostrongylus}, \emph{Trichuris}, \emph{Tritirachium}, \emph{Trombicula}, \emph{Trypanosoma}, \emph{Tunga}, \emph{Ulocladium}, \emph{Ustilago}, \emph{Verticillium}, \emph{Wallemia}, \emph{Wangiella}, \emph{Wickerhamomyces}, \emph{Wuchereria}, \emph{Yarrowia}, or \emph{Zygosaccharomyces};
\item All other records have \code{prevalence = 2.0} in the \link{microorganisms} data set.
}
When calculating the matching score, all characters in \eqn{x} and \eqn{n} are ignored that are other than A-Z, a-z, 0-9, spaces and parentheses.
All matches are sorted descending on their matching score and for all user input values, the top match will be returned. This will lead to the effect that e.g., \code{"E. coli"} will return the microbial ID of \emph{Escherichia coli} (\eqn{m = 0.688}, a highly prevalent microorganism found in humans) and not \emph{Entamoeba coli} (\eqn{m = 0.381}, a less prevalent microorganism in humans), although the latter would alphabetically come first.
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
mo_reset_session()
as.mo("E. coli")
mo_uncertainties()
mo_matching_score(
x = "E. coli",
n = c("Escherichia coli", "Entamoeba coli")
)
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/mo_property.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mo_property.R
\name{mo_property}
\alias{mo_property}
\alias{mo_name}
\alias{mo_fullname}
\alias{mo_shortname}
\alias{mo_subspecies}
\alias{mo_species}
\alias{mo_genus}
\alias{mo_family}
\alias{mo_order}
\alias{mo_class}
\alias{mo_phylum}
\alias{mo_kingdom}
\alias{mo_domain}
\alias{mo_type}
\alias{mo_status}
\alias{mo_pathogenicity}
\alias{mo_gramstain}
\alias{mo_is_gram_negative}
\alias{mo_is_gram_positive}
\alias{mo_is_yeast}
\alias{mo_is_intrinsic_resistant}
\alias{mo_oxygen_tolerance}
\alias{mo_is_anaerobic}
\alias{mo_snomed}
\alias{mo_ref}
\alias{mo_authors}
\alias{mo_year}
\alias{mo_lpsn}
\alias{mo_mycobank}
\alias{mo_gbif}
\alias{mo_rank}
\alias{mo_taxonomy}
\alias{mo_synonyms}
\alias{mo_current}
\alias{mo_group_members}
\alias{mo_info}
\alias{mo_url}
\title{Get Properties of a Microorganism}
\usage{
mo_name(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_fullname(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_shortname(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_subspecies(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_species(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_genus(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_family(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_order(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_class(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_phylum(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_kingdom(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_domain(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_type(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_status(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_pathogenicity(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_gramstain(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_is_gram_negative(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_is_gram_positive(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_is_yeast(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_is_intrinsic_resistant(
x,
ab,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_oxygen_tolerance(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_is_anaerobic(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_snomed(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_ref(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_authors(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_year(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_lpsn(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_mycobank(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_gbif(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_rank(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_taxonomy(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_synonyms(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_current(x, language = get_AMR_locale(), ...)
mo_group_members(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_info(
x,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_url(
x,
open = FALSE,
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
mo_property(
x,
property = "fullname",
language = get_AMR_locale(),
keep_synonyms = getOption("AMR_keep_synonyms", FALSE),
...
)
}
\arguments{
\item{x}{any \link{character} (vector) that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}. Can be left blank for auto-guessing the column containing microorganism codes if used in a data set, see \emph{Examples}.}
\item{language}{language to translate text like "no growth", which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})}
\item{keep_synonyms}{a \link{logical} to indicate if old, previously valid taxonomic names must be preserved and not be corrected to currently accepted names. The default is \code{FALSE}, which will return a note if old taxonomic names were processed. The default can be set with the package option \code{\link[=AMR-options]{AMR_keep_synonyms}}, i.e. \code{options(AMR_keep_synonyms = TRUE)} or \code{options(AMR_keep_synonyms = FALSE)}.}
\item{...}{other arguments passed on to \code{\link[=as.mo]{as.mo()}}, such as 'minimum_matching_score', 'ignore_pattern', and 'remove_from_input'}
\item{ab}{any (vector of) text that can be coerced to a valid antibiotic drug code with \code{\link[=as.ab]{as.ab()}}}
\item{open}{browse the URL using \code{\link[utils:browseURL]{browseURL()}}}
\item{property}{one of the column names of the \link{microorganisms} data set: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "oxygen_tolerance", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "mycobank", "mycobank_parent", "mycobank_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence", or "snomed", or must be \code{"shortname"}}
}
\value{
\itemize{
\item An \link{integer} in case of \code{\link[=mo_year]{mo_year()}}
\item An \link[=factor]{ordered factor} in case of \code{\link[=mo_pathogenicity]{mo_pathogenicity()}}
\item A \link{list} in case of \code{\link[=mo_taxonomy]{mo_taxonomy()}}, \code{\link[=mo_synonyms]{mo_synonyms()}}, \code{\link[=mo_snomed]{mo_snomed()}}, and \code{\link[=mo_info]{mo_info()}}
\item A \link{logical} in case of \code{\link[=mo_is_anaerobic]{mo_is_anaerobic()}}, \code{\link[=mo_is_gram_negative]{mo_is_gram_negative()}}, \code{\link[=mo_is_gram_positive]{mo_is_gram_positive()}}, \code{\link[=mo_is_intrinsic_resistant]{mo_is_intrinsic_resistant()}}, and \code{\link[=mo_is_yeast]{mo_is_yeast()}}
\item A named \link{character} in case of \code{\link[=mo_synonyms]{mo_synonyms()}} and \code{\link[=mo_url]{mo_url()}}
\item A \link{character} in all other cases
}
}
\description{
Use these functions to return a specific property of a microorganism based on the latest accepted taxonomy. All input values will be evaluated internally with \code{\link[=as.mo]{as.mo()}}, which makes it possible to use microbial abbreviations, codes and names as input. See \emph{Examples}.
}
\details{
All functions will, at default, \strong{not} keep old taxonomic properties, as synonyms are automatically replaced with the current taxonomy. Take for example \emph{Enterobacter aerogenes}, which was initially named in 1960 but renamed to \emph{Klebsiella aerogenes} in 2017:
\itemize{
\item \code{mo_genus("Enterobacter aerogenes")} will return \code{"Klebsiella"} (with a note about the renaming)
\item \code{mo_genus("Enterobacter aerogenes", keep_synonyms = TRUE)} will return \code{"Enterobacter"} (with a once-per-session warning that the name is outdated)
\item \code{mo_ref("Enterobacter aerogenes")} will return \code{"Tindall et al., 2017"} (with a note about the renaming)
\item \code{mo_ref("Enterobacter aerogenes", keep_synonyms = TRUE)} will return \code{"Hormaeche et al., 1960"} (with a once-per-session warning that the name is outdated)
}
The short name (\code{\link[=mo_shortname]{mo_shortname()}}) returns the first character of the genus and the full species, such as \code{"E. coli"}, for species and subspecies. Exceptions are abbreviations of staphylococci (such as \emph{"CoNS"}, Coagulase-Negative Staphylococci) and beta-haemolytic streptococci (such as \emph{"GBS"}, Group B Streptococci). Please bear in mind that e.g. \emph{E. coli} could mean \emph{Escherichia coli} (kingdom of Bacteria) as well as \emph{Entamoeba coli} (kingdom of Protozoa). Returning to the full name will be done using \code{\link[=as.mo]{as.mo()}} internally, giving priority to bacteria and human pathogens, i.e. \code{"E. coli"} will be considered \emph{Escherichia coli}. As a result, \code{mo_fullname(mo_shortname("Entamoeba coli"))} returns \code{"Escherichia coli"}.
Since the top-level of the taxonomy is sometimes referred to as 'kingdom' and sometimes as 'domain', the functions \code{\link[=mo_kingdom]{mo_kingdom()}} and \code{\link[=mo_domain]{mo_domain()}} return the exact same results.
Determination of human pathogenicity (\code{\link[=mo_pathogenicity]{mo_pathogenicity()}}) is strongly based on Bartlett \emph{et al.} (2022, \doi{10.1099/mic.0.001269}). This function returns a \link{factor} with the levels \emph{Pathogenic}, \emph{Potentially pathogenic}, \emph{Non-pathogenic}, and \emph{Unknown}.
Determination of the Gram stain (\code{\link[=mo_gramstain]{mo_gramstain()}}) will be based on the taxonomic kingdom and phylum. Originally, Cavalier-Smith defined the so-called subkingdoms Negibacteria and Posibacteria (2002, \href{https://pubmed.ncbi.nlm.nih.gov/11837318/}{PMID 11837318}), and only considered these phyla as Posibacteria: Actinobacteria, Chloroflexi, Firmicutes, and Tenericutes. These phyla were later renamed to Actinomycetota, Chloroflexota, Bacillota, and Mycoplasmatota (2021, \href{https://pubmed.ncbi.nlm.nih.gov/34694987/}{PMID 34694987}). Bacteria in these phyla are considered Gram-positive in this \code{AMR} package, except for members of the class Negativicutes (within phylum Bacillota) which are Gram-negative. All other bacteria are considered Gram-negative. Species outside the kingdom of Bacteria will return a value \code{NA}. Functions \code{\link[=mo_is_gram_negative]{mo_is_gram_negative()}} and \code{\link[=mo_is_gram_positive]{mo_is_gram_positive()}} always return \code{TRUE} or \code{FALSE} (or \code{NA} when the input is \code{NA} or the MO code is \code{UNKNOWN}), thus always return \code{FALSE} for species outside the taxonomic kingdom of Bacteria.
Determination of yeasts (\code{\link[=mo_is_yeast]{mo_is_yeast()}}) will be based on the taxonomic kingdom and class. \emph{Budding yeasts} are yeasts that reproduce asexually through a process called budding, where a new cell develops from a small protrusion on the parent cell. Taxonomically, these are members of the phylum Ascomycota, class Saccharomycetes (also called Hemiascomycetes) or Pichiomycetes. \emph{True yeasts} quite specifically refers to yeasts in the underlying order Saccharomycetales (such as \emph{Saccharomyces cerevisiae}). Thus, for all microorganisms that are member of the taxonomic class Saccharomycetes or Pichiomycetes, the function will return \code{TRUE}. It returns \code{FALSE} otherwise (or \code{NA} when the input is \code{NA} or the MO code is \code{UNKNOWN}).
Determination of intrinsic resistance (\code{\link[=mo_is_intrinsic_resistant]{mo_is_intrinsic_resistant()}}) will be based on the \link{intrinsic_resistant} data set, which is based on \href{https://www.eucast.org/expert_rules_and_expected_phenotypes}{'EUCAST Expert Rules' and 'EUCAST Intrinsic Resistance and Unusual Phenotypes' v3.3} (2021). The \code{\link[=mo_is_intrinsic_resistant]{mo_is_intrinsic_resistant()}} function can be vectorised over both argument \code{x} (input for microorganisms) and \code{ab} (input for antibiotics).
Determination of bacterial oxygen tolerance (\code{\link[=mo_oxygen_tolerance]{mo_oxygen_tolerance()}}) will be based on BacDive, see \emph{Source}. The function \code{\link[=mo_is_anaerobic]{mo_is_anaerobic()}} only returns \code{TRUE} if the oxygen tolerance is \code{"anaerobe"}, indicting an obligate anaerobic species or genus. It always returns \code{FALSE} for species outside the taxonomic kingdom of Bacteria.
The function \code{\link[=mo_url]{mo_url()}} will return the direct URL to the online database entry, which also shows the scientific reference of the concerned species. \href{https://www.mycobank.org}{This MycoBank URL} will be used for fungi wherever available , \href{https://www.mycobank.org}{this LPSN URL} for bacteria wherever available, and \href{https://www.gbif.org}{this GBIF link} otherwise.
SNOMED codes (\code{\link[=mo_snomed]{mo_snomed()}}) was last updated on July 16th, 2024. See \emph{Source} and the \link{microorganisms} data set for more info.
Old taxonomic names (so-called 'synonyms') can be retrieved with \code{\link[=mo_synonyms]{mo_synonyms()}} (which will have the scientific reference as \link[base:names]{name}), the current taxonomic name can be retrieved with \code{\link[=mo_current]{mo_current()}}. Both functions return full names.
All output \link[=translate]{will be translated} where possible.
}
\section{Matching Score for Microorganisms}{
This function uses \code{\link[=as.mo]{as.mo()}} internally, which uses an advanced algorithm to translate arbitrary user input to valid taxonomy using a so-called matching score. You can read about this public algorithm on the \link[=mo_matching_score]{MO matching score page}.
}
\section{Source}{
\itemize{
\item Berends MS \emph{et al.} (2022). \strong{AMR: An R Package for Working with Antimicrobial Resistance Data}. \emph{Journal of Statistical Software}, 104(3), 1-31; \doi{10.18637/jss.v104.i03}
\item Parte, AC \emph{et al.} (2020). \strong{List of Prokaryotic names with Standing in Nomenclature (LPSN) moves to the DSMZ.} International Journal of Systematic and Evolutionary Microbiology, 70, 5607-5612; \doi{10.1099/ijsem.0.004332}. Accessed from \url{https://lpsn.dsmz.de} on June 24th, 2024.
\item Vincent, R \emph{et al} (2013). \strong{MycoBank gearing up for new horizons.} IMA Fungus, 4(2), 371-9; \doi{10.5598/imafungus.2013.04.02.16}. Accessed from \url{https://www.mycobank.org} on June 24th, 2024.
\item GBIF Secretariat (2023). GBIF Backbone Taxonomy. Checklist dataset \doi{10.15468/39omei}. Accessed from \url{https://www.gbif.org} on June 24th, 2024.
\item Reimer, LC \emph{et al.} (2022). \strong{\emph{BacDive} in 2022: the knowledge base for standardized bacterial and archaeal data.} Nucleic Acids Res., 50(D1):D741-D74; \doi{10.1093/nar/gkab961}. Accessed from \url{https://bacdive.dsmz.de} on July 16th, 2024.
\item Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS). US Edition of SNOMED CT from 1 September 2020. Value Set Name 'Microorganism', OID 2.16.840.1.114222.4.11.1009 (v12). URL: \url{https://phinvads.cdc.gov}
\item Bartlett A \emph{et al.} (2022). \strong{A comprehensive list of bacterial pathogens infecting humans} \emph{Microbiology} 168:001269; \doi{10.1099/mic.0.001269}
}
}
\section{Reference Data Publicly Available}{
All data sets in this \code{AMR} package (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
}
\examples{
# taxonomic tree -----------------------------------------------------------
mo_kingdom("Klebsiella pneumoniae")
mo_phylum("Klebsiella pneumoniae")
mo_class("Klebsiella pneumoniae")
mo_order("Klebsiella pneumoniae")
mo_family("Klebsiella pneumoniae")
mo_genus("Klebsiella pneumoniae")
mo_species("Klebsiella pneumoniae")
mo_subspecies("Klebsiella pneumoniae")
# full names and short names -----------------------------------------------
mo_name("Klebsiella pneumoniae")
mo_fullname("Klebsiella pneumoniae")
mo_shortname("Klebsiella pneumoniae")
# other properties ---------------------------------------------------------
mo_pathogenicity("Klebsiella pneumoniae")
mo_gramstain("Klebsiella pneumoniae")
mo_snomed("Klebsiella pneumoniae")
mo_type("Klebsiella pneumoniae")
mo_rank("Klebsiella pneumoniae")
mo_url("Klebsiella pneumoniae")
mo_is_yeast(c("Candida", "Trichophyton", "Klebsiella"))
mo_group_members(c("Streptococcus group A",
"Streptococcus group C",
"Streptococcus group G",
"Streptococcus group L"))
# scientific reference -----------------------------------------------------
mo_ref("Klebsiella aerogenes")
mo_authors("Klebsiella aerogenes")
mo_year("Klebsiella aerogenes")
mo_synonyms("Klebsiella aerogenes")
mo_lpsn("Klebsiella aerogenes")
mo_gbif("Klebsiella aerogenes")
mo_mycobank("Candida albicans")
mo_mycobank("Candida krusei")
mo_mycobank("Candida krusei", keep_synonyms = TRUE)
# abbreviations known in the field -----------------------------------------
mo_genus("MRSA")
mo_species("MRSA")
mo_shortname("VISA")
mo_gramstain("VISA")
mo_genus("EHEC")
mo_species("EIEC")
mo_name("UPEC")
# known subspecies ---------------------------------------------------------
mo_fullname("K. pneu rh")
mo_shortname("K. pneu rh")
\donttest{
# Becker classification, see ?as.mo ----------------------------------------
mo_fullname("Staph epidermidis")
mo_fullname("Staph epidermidis", Becker = TRUE)
mo_shortname("Staph epidermidis")
mo_shortname("Staph epidermidis", Becker = TRUE)
# Lancefield classification, see ?as.mo ------------------------------------
mo_fullname("Strep agalactiae")
mo_fullname("Strep agalactiae", Lancefield = TRUE)
mo_shortname("Strep agalactiae")
mo_shortname("Strep agalactiae", Lancefield = TRUE)
# language support --------------------------------------------------------
mo_gramstain("Klebsiella pneumoniae", language = "de") # German
mo_gramstain("Klebsiella pneumoniae", language = "nl") # Dutch
mo_gramstain("Klebsiella pneumoniae", language = "es") # Spanish
mo_gramstain("Klebsiella pneumoniae", language = "el") # Greek
mo_gramstain("Klebsiella pneumoniae", language = "uk") # Ukrainian
# mo_type is equal to mo_kingdom, but mo_kingdom will remain untranslated
mo_kingdom("Klebsiella pneumoniae")
mo_type("Klebsiella pneumoniae")
mo_kingdom("Klebsiella pneumoniae", language = "zh") # Chinese, no effect
mo_type("Klebsiella pneumoniae", language = "zh") # Chinese, translated
mo_fullname("S. pyogenes", Lancefield = TRUE, language = "de")
mo_fullname("S. pyogenes", Lancefield = TRUE, language = "uk")
# other --------------------------------------------------------------------
# gram stains and intrinsic resistance can be used as a filter in dplyr verbs
if (require("dplyr")) {
example_isolates \%>\%
filter(mo_is_gram_positive()) \%>\%
count(mo_genus(), sort = TRUE)
}
if (require("dplyr")) {
example_isolates \%>\%
filter(mo_is_intrinsic_resistant(ab = "vanco")) \%>\%
count(mo_genus(), sort = TRUE)
}
# get a list with the complete taxonomy (from kingdom to subspecies)
mo_taxonomy("Klebsiella pneumoniae")
# get a list with the taxonomy, the authors, Gram-stain,
# SNOMED codes, and URL to the online database
mo_info("Klebsiella pneumoniae")
}
}
\seealso{
Data set \link{microorganisms}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/mo_source.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mo_source.R
\name{mo_source}
\alias{mo_source}
\alias{set_mo_source}
\alias{get_mo_source}
\title{User-Defined Reference Data Set for Microorganisms}
\usage{
set_mo_source(
path,
destination = getOption("AMR_mo_source", "~/mo_source.rds")
)
get_mo_source(destination = getOption("AMR_mo_source", "~/mo_source.rds"))
}
\arguments{
\item{path}{location of your reference file, this can be any text file (comma-, tab- or pipe-separated) or an Excel file (see \emph{Details}). Can also be \code{""}, \code{NULL} or \code{FALSE} to delete the reference file.}
\item{destination}{destination of the compressed data file - the default is the user's home directory.}
}
\description{
These functions can be used to predefine your own reference to be used in \code{\link[=as.mo]{as.mo()}} and consequently all \code{\link[=mo_property]{mo_*}} functions (such as \code{\link[=mo_genus]{mo_genus()}} and \code{\link[=mo_gramstain]{mo_gramstain()}}).
This is \strong{the fastest way} to have your organisation (or analysis) specific codes picked up and translated by this package, since you don't have to bother about it again after setting it up once.
}
\details{
The reference file can be a text file separated with commas (CSV) or tabs or pipes, an Excel file (either 'xls' or 'xlsx' format) or an \R object file (extension '.rds'). To use an Excel file, you will need to have the \code{readxl} package installed.
\code{\link[=set_mo_source]{set_mo_source()}} will check the file for validity: it must be a \link{data.frame}, must have a column named \code{"mo"} which contains values from \code{\link[=microorganisms]{microorganisms$mo}} or \code{\link[=microorganisms]{microorganisms$fullname}} and must have a reference column with your own defined values. If all tests pass, \code{\link[=set_mo_source]{set_mo_source()}} will read the file into \R and will ask to export it to \code{"~/mo_source.rds"}. The CRAN policy disallows packages to write to the file system, although '\emph{exceptions may be allowed in interactive sessions if the package obtains confirmation from the user}'. For this reason, this function only works in interactive sessions so that the user can \strong{specifically confirm and allow} that this file will be created. The destination of this file can be set with the \code{destination} argument and defaults to the user's home directory. It can also be set with the package option \code{\link[=AMR-options]{AMR_mo_source}}, e.g. \code{options(AMR_mo_source = "my/location/file.rds")}.
The created compressed data file \code{"mo_source.rds"} will be used at default for MO determination (function \code{\link[=as.mo]{as.mo()}} and consequently all \verb{mo_*} functions like \code{\link[=mo_genus]{mo_genus()}} and \code{\link[=mo_gramstain]{mo_gramstain()}}). The location and timestamp of the original file will be saved as an \link[base:attributes]{attribute} to the compressed data file.
The function \code{\link[=get_mo_source]{get_mo_source()}} will return the data set by reading \code{"mo_source.rds"} with \code{\link[=readRDS]{readRDS()}}. If the original file has changed (by checking the location and timestamp of the original file), it will call \code{\link[=set_mo_source]{set_mo_source()}} to update the data file automatically if used in an interactive session.
Reading an Excel file (\code{.xlsx}) with only one row has a size of 8-9 kB. The compressed file created with \code{\link[=set_mo_source]{set_mo_source()}} will then have a size of 0.1 kB and can be read by \code{\link[=get_mo_source]{get_mo_source()}} in only a couple of microseconds (millionths of a second).
}
\section{How to Setup}{
Imagine this data on a sheet of an Excel file. The first column contains the organisation specific codes, the second column contains valid taxonomic names:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ | A | B |
--|--------------------|-----------------------|
1 | Organisation XYZ | mo |
2 | lab_mo_ecoli | Escherichia coli |
3 | lab_mo_kpneumoniae | Klebsiella pneumoniae |
4 | | |
}\if{html}{\out{</div>}}
We save it as \code{"home/me/ourcodes.xlsx"}. Now we have to set it as a source:
\if{html}{\out{<div class="sourceCode">}}\preformatted{set_mo_source("home/me/ourcodes.xlsx")
#> NOTE: Created mo_source file '/Users/me/mo_source.rds' (0.3 kB) from
#> '/Users/me/Documents/ourcodes.xlsx' (9 kB), columns
#> "Organisation XYZ" and "mo"
}\if{html}{\out{</div>}}
It has now created a file \code{"~/mo_source.rds"} with the contents of our Excel file. Only the first column with foreign values and the 'mo' column will be kept when creating the RDS file.
And now we can use it in our functions:
\if{html}{\out{<div class="sourceCode">}}\preformatted{as.mo("lab_mo_ecoli")
#> Class 'mo'
#> [1] B_ESCHR_COLI
mo_genus("lab_mo_kpneumoniae")
#> [1] "Klebsiella"
# other input values still work too
as.mo(c("Escherichia coli", "E. coli", "lab_mo_ecoli"))
#> NOTE: Translation to one microorganism was guessed with uncertainty.
#> Use mo_uncertainties() to review it.
#> Class 'mo'
#> [1] B_ESCHR_COLI B_ESCHR_COLI B_ESCHR_COLI
}\if{html}{\out{</div>}}
If we edit the Excel file by, let's say, adding row 4 like this:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ | A | B |
--|--------------------|-----------------------|
1 | Organisation XYZ | mo |
2 | lab_mo_ecoli | Escherichia coli |
3 | lab_mo_kpneumoniae | Klebsiella pneumoniae |
4 | lab_Staph_aureus | Staphylococcus aureus |
5 | | |
}\if{html}{\out{</div>}}
...any new usage of an MO function in this package will update your data file:
\if{html}{\out{<div class="sourceCode">}}\preformatted{as.mo("lab_mo_ecoli")
#> NOTE: Updated mo_source file '/Users/me/mo_source.rds' (0.3 kB) from
#> '/Users/me/Documents/ourcodes.xlsx' (9 kB), columns
#> "Organisation XYZ" and "mo"
#> Class 'mo'
#> [1] B_ESCHR_COLI
mo_genus("lab_Staph_aureus")
#> [1] "Staphylococcus"
}\if{html}{\out{</div>}}
To delete the reference data file, just use \code{""}, \code{NULL} or \code{FALSE} as input for \code{\link[=set_mo_source]{set_mo_source()}}:
\if{html}{\out{<div class="sourceCode">}}\preformatted{set_mo_source(NULL)
#> Removed mo_source file '/Users/me/mo_source.rds'
}\if{html}{\out{</div>}}
If the original file (in the previous case an Excel file) is moved or deleted, the \code{mo_source.rds} file will be removed upon the next use of \code{\link[=as.mo]{as.mo()}} or any \code{\link[=mo_property]{mo_*}} function.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/pca.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pca.R
\name{pca}
\alias{pca}
\title{Principal Component Analysis (for AMR)}
\usage{
pca(
x,
...,
retx = TRUE,
center = TRUE,
scale. = TRUE,
tol = NULL,
rank. = NULL
)
}
\arguments{
\item{x}{a \link{data.frame} containing \link{numeric} columns}
\item{...}{columns of \code{x} to be selected for PCA, can be unquoted since it supports quasiquotation.}
\item{retx}{a logical value indicating whether the rotated variables
should be returned.}
\item{center}{a logical value indicating whether the variables
should be shifted to be zero centered. Alternately, a vector of
length equal the number of columns of \code{x} can be supplied.
The value is passed to \code{scale}.}
\item{scale.}{a logical value indicating whether the variables should
be scaled to have unit variance before the analysis takes
place. The default is \code{FALSE} for consistency with S, but
in general scaling is advisable. Alternatively, a vector of length
equal the number of columns of \code{x} can be supplied. The
value is passed to \code{\link{scale}}.}
\item{tol}{a value indicating the magnitude below which components
should be omitted. (Components are omitted if their
standard deviations are less than or equal to \code{tol} times the
standard deviation of the first component.) With the default null
setting, no components are omitted (unless \code{rank.} is specified
less than \code{min(dim(x))}.). Other settings for \code{tol} could be
\code{tol = 0} or \code{tol = sqrt(.Machine$double.eps)}, which
would omit essentially constant components.}
\item{rank.}{optionally, a number specifying the maximal rank, i.e.,
maximal number of principal components to be used. Can be set as
alternative or in addition to \code{tol}, useful notably when the
desired rank is considerably smaller than the dimensions of the matrix.}
}
\value{
An object of classes \link{pca} and \link{prcomp}
}
\description{
Performs a principal component analysis (PCA) based on a data set with automatic determination for afterwards plotting the groups and labels, and automatic filtering on only suitable (i.e. non-empty and numeric) variables.
}
\details{
The \code{\link[=pca]{pca()}} function takes a \link{data.frame} as input and performs the actual PCA with the \R function \code{\link[=prcomp]{prcomp()}}.
The result of the \code{\link[=pca]{pca()}} function is a \link{prcomp} object, with an additional attribute \code{non_numeric_cols} which is a vector with the column names of all columns that do not contain \link{numeric} values. These are probably the groups and labels, and will be used by \code{\link[=ggplot_pca]{ggplot_pca()}}.
}
\examples{
# `example_isolates` is a data set available in the AMR package.
# See ?example_isolates.
\donttest{
if (require("dplyr")) {
# calculate the resistance per group first
resistance_data <- example_isolates \%>\%
group_by(
order = mo_order(mo), # group on anything, like order
genus = mo_genus(mo)
) \%>\% # and genus as we do here;
filter(n() >= 30) \%>\% # filter on only 30 results per group
summarise_if(is.sir, resistance) # then get resistance of all drugs
# now conduct PCA for certain antimicrobial drugs
pca_result <- resistance_data \%>\%
pca(AMC, CXM, CTX, CAZ, GEN, TOB, TMP, SXT)
pca_result
summary(pca_result)
# old base R plotting method:
biplot(pca_result)
# new ggplot2 plotting method using this package:
if (require("ggplot2")) {
ggplot_pca(pca_result)
ggplot_pca(pca_result) +
scale_colour_viridis_d() +
labs(title = "Title here")
}
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/plot.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting.R
\name{plot}
\alias{plot}
\alias{scale_x_mic}
\alias{scale_y_mic}
\alias{scale_colour_mic}
\alias{scale_fill_mic}
\alias{plot.mic}
\alias{autoplot.mic}
\alias{fortify.mic}
\alias{plot.disk}
\alias{autoplot.disk}
\alias{fortify.disk}
\alias{plot.sir}
\alias{autoplot.sir}
\alias{fortify.sir}
\title{Plotting for Classes \code{sir}, \code{mic} and \code{disk}}
\usage{
scale_x_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
scale_y_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
scale_colour_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
scale_fill_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
\method{plot}{mic}(
x,
mo = NULL,
ab = NULL,
guideline = "EUCAST",
main = deparse(substitute(x)),
ylab = translate_AMR("Frequency", language = language),
xlab = translate_AMR("Minimum Inhibitory Concentration (mg/L)", language = language),
colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B"),
language = get_AMR_locale(),
expand = TRUE,
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
...
)
\method{autoplot}{mic}(
object,
mo = NULL,
ab = NULL,
guideline = "EUCAST",
title = deparse(substitute(object)),
ylab = translate_AMR("Frequency", language = language),
xlab = translate_AMR("Minimum Inhibitory Concentration (mg/L)", language = language),
colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B"),
language = get_AMR_locale(),
expand = TRUE,
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
...
)
\method{fortify}{mic}(object, ...)
\method{plot}{disk}(
x,
main = deparse(substitute(x)),
ylab = translate_AMR("Frequency", language = language),
xlab = translate_AMR("Disk diffusion diameter (mm)", language = language),
mo = NULL,
ab = NULL,
guideline = "EUCAST",
colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B"),
language = get_AMR_locale(),
expand = TRUE,
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
...
)
\method{autoplot}{disk}(
object,
mo = NULL,
ab = NULL,
title = deparse(substitute(object)),
ylab = translate_AMR("Frequency", language = language),
xlab = translate_AMR("Disk diffusion diameter (mm)", language = language),
guideline = "EUCAST",
colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B"),
language = get_AMR_locale(),
expand = TRUE,
include_PKPD = getOption("AMR_include_PKPD", TRUE),
breakpoint_type = getOption("AMR_breakpoint_type", "human"),
...
)
\method{fortify}{disk}(object, ...)
\method{plot}{sir}(
x,
ylab = translate_AMR("Percentage", language = language),
xlab = translate_AMR("Antimicrobial Interpretation", language = language),
main = deparse(substitute(x)),
language = get_AMR_locale(),
...
)
\method{autoplot}{sir}(
object,
title = deparse(substitute(object)),
xlab = translate_AMR("Antimicrobial Interpretation", language = language),
ylab = translate_AMR("Frequency", language = language),
colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B"),
language = get_AMR_locale(),
...
)
\method{fortify}{sir}(object, ...)
}
\arguments{
\item{keep_operators}{a \link{character} specifying how to handle operators (such as \code{>} and \code{<=}) in the input. Accepts one of three values: \code{"all"} (or \code{TRUE}) to keep all operators, \code{"none"} (or \code{FALSE}) to remove all operators, or \code{"edges"} to keep operators only at both ends of the range.}
\item{mic_range}{a manual range to limit the MIC values, e.g., \code{mic_range = c(0.001, 32)}. Use \code{NA} to set no limit on one side, e.g., \code{mic_range = c(NA, 32)}.}
\item{drop}{a \link{logical} to remove intermediate MIC values, defaults to \code{FALSE}}
\item{...}{arguments passed on to methods}
\item{x, object}{values created with \code{\link[=as.mic]{as.mic()}}, \code{\link[=as.disk]{as.disk()}} or \code{\link[=as.sir]{as.sir()}} (or their \verb{random_*} variants, such as \code{\link[=random_mic]{random_mic()}})}
\item{mo}{any (vector of) text that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}}
\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}}
\item{guideline}{interpretation guideline to use - the default is the latest included EUCAST guideline, see \emph{Details}}
\item{main, title}{title of the plot}
\item{xlab, ylab}{axis title}
\item{colours_SIR}{colours to use for filling in the bars, must be a vector of three values (in the order S, I and R). The default colours are colour-blind friendly.}
\item{language}{language to be used to translate 'Susceptible', 'Increased exposure'/'Intermediate' and 'Resistant' - the default is system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can be overwritten by setting the package option \code{\link[=AMR-options]{AMR_locale}}, e.g. \code{options(AMR_locale = "de")}, see \link{translate}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{expand}{a \link{logical} to indicate whether the range on the x axis should be expanded between the lowest and highest value. For MIC values, intermediate values will be factors of 2 starting from the highest MIC value. For disk diameters, the whole diameter range will be filled.}
\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort - the default is \code{TRUE}. Can also be set with the package option \code{\link[=AMR-options]{AMR_include_PKPD}}.}
\item{breakpoint_type}{the type of breakpoints to use, either "ECOFF", "animal", or "human". ECOFF stands for Epidemiological Cut-Off values. The default is \code{"human"}, which can also be set with the package option \code{\link[=AMR-options]{AMR_breakpoint_type}}. If \code{host} is set to values of veterinary species, this will automatically be set to \code{"animal"}.}
}
\value{
The \code{autoplot()} functions return a \code{\link[ggplot2:ggplot]{ggplot}} model that is extendible with any \code{ggplot2} function.
The \code{fortify()} functions return a \link{data.frame} as an extension for usage in the \code{\link[ggplot2:ggplot]{ggplot2::ggplot()}} function.
}
\description{
Functions to plot classes \code{sir}, \code{mic} and \code{disk}, with support for base \R and \code{ggplot2}.
Especially the \verb{scale_*_mic()} functions are relevant wrappers to plot MIC values for \code{ggplot2}. They allows custom MIC ranges and to plot intermediate log2 levels for missing MIC values.
}
\details{
The interpretation of "I" will be named "Increased exposure" for all EUCAST guidelines since 2019, and will be named "Intermediate" in all other cases.
For interpreting MIC values as well as disk diffusion diameters, supported guidelines to be used as input for the \code{guideline} argument are: "EUCAST 2024", "EUCAST 2023", "EUCAST 2022", "EUCAST 2021", "EUCAST 2020", "EUCAST 2019", "EUCAST 2018", "EUCAST 2017", "EUCAST 2016", "EUCAST 2015", "EUCAST 2014", "EUCAST 2013", "EUCAST 2012", "EUCAST 2011", "CLSI 2024", "CLSI 2023", "CLSI 2022", "CLSI 2021", "CLSI 2020", "CLSI 2019", "CLSI 2018", "CLSI 2017", "CLSI 2016", "CLSI 2015", "CLSI 2014", "CLSI 2013", "CLSI 2012", and "CLSI 2011".
Simply using \code{"CLSI"} or \code{"EUCAST"} as input will automatically select the latest version of that guideline.
}
\examples{
some_mic_values <- random_mic(size = 100)
some_disk_values <- random_disk(size = 100, mo = "Escherichia coli", ab = "cipro")
some_sir_values <- random_sir(50, prob_SIR = c(0.55, 0.05, 0.30))
plot(some_mic_values)
plot(some_disk_values)
plot(some_sir_values)
# when providing the microorganism and antibiotic, colours will show interpretations:
plot(some_mic_values, mo = "S. aureus", ab = "ampicillin")
plot(some_disk_values, mo = "Escherichia coli", ab = "cipro")
plot(some_disk_values, mo = "Escherichia coli", ab = "cipro", language = "nl")
# Plotting using scale_x_mic()
\donttest{
if (require("ggplot2")) {
mic_plot <- ggplot(data.frame(mics = as.mic(c(0.25, "<=4", 4, 8, 32, ">=32")),
counts = c(1, 1, 2, 2, 3, 3)),
aes(mics, counts)) +
geom_col()
mic_plot +
labs(title = "without scale_x_mic()")
}
if (require("ggplot2")) {
mic_plot +
scale_x_mic() +
labs(title = "with scale_x_mic()")
}
if (require("ggplot2")) {
mic_plot +
scale_x_mic(keep_operators = "all") +
labs(title = "with scale_x_mic() keeping all operators")
}
if (require("ggplot2")) {
mic_plot +
scale_x_mic(mic_range = c(1, 16)) +
labs(title = "with scale_x_mic() using a manual 'within' range")
}
if (require("ggplot2")) {
mic_plot +
scale_x_mic(mic_range = c(0.032, 256)) +
labs(title = "with scale_x_mic() using a manual 'outside' range")
}
if (require("ggplot2")) {
autoplot(some_mic_values)
}
if (require("ggplot2")) {
autoplot(some_disk_values, mo = "Escherichia coli", ab = "cipro")
}
if (require("ggplot2")) {
autoplot(some_sir_values)
}
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/proportion.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/proportion.R, R/sir_df.R
\name{proportion}
\alias{proportion}
\alias{resistance}
\alias{portion}
\alias{susceptibility}
\alias{sir_confidence_interval}
\alias{proportion_R}
\alias{proportion_IR}
\alias{proportion_I}
\alias{proportion_SI}
\alias{proportion_S}
\alias{proportion_df}
\alias{sir_df}
\title{Calculate Antimicrobial Resistance}
\source{
\strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 5th Edition}, 2022, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}.
}
\usage{
resistance(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
susceptibility(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
sir_confidence_interval(
...,
ab_result = "R",
minimum = 30,
as_percent = FALSE,
only_all_tested = FALSE,
confidence_level = 0.95,
side = "both",
collapse = FALSE
)
proportion_R(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
proportion_IR(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
proportion_I(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
proportion_SI(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
proportion_S(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE)
proportion_df(
data,
translate_ab = "name",
language = get_AMR_locale(),
minimum = 30,
as_percent = FALSE,
combine_SI = TRUE,
confidence_level = 0.95
)
sir_df(
data,
translate_ab = "name",
language = get_AMR_locale(),
minimum = 30,
as_percent = FALSE,
combine_SI = TRUE,
confidence_level = 0.95
)
}
\arguments{
\item{...}{one or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} 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 \emph{Examples}.}
\item{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 \emph{Source}.}
\item{as_percent}{a \link{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\%"}.}
\item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antibiotics, see section \emph{Combination Therapy} below}
\item{ab_result}{antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R"}
\item{confidence_level}{the confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.}
\item{side}{the side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.}
\item{collapse}{a \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing}
\item{data}{a \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}})}
\item{translate_ab}{a column name of the \link{antibiotics} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}}
\item{language}{language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
\item{combine_SI}{a \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}}
}
\value{
A \link{double} or, when \code{as_percent = TRUE}, a \link{character}.
}
\description{
These functions can be used to calculate the (co-)resistance or susceptibility of microbial isolates (i.e. percentage of S, SI, I, IR or R). All functions support quasiquotation with pipes, can be used in \code{summarise()} from the \code{dplyr} package and also support grouped variables, see \emph{Examples}.
\code{\link[=resistance]{resistance()}} should be used to calculate resistance, \code{\link[=susceptibility]{susceptibility()}} should be used to calculate susceptibility.\cr
}
\details{
\strong{Remember that you should filter your data to let it contain only first isolates!} This is needed to exclude duplicates and to reduce selection bias. Use \code{\link[=first_isolate]{first_isolate()}} to determine them in your data set with one of the four available algorithms.
The function \code{\link[=resistance]{resistance()}} is equal to the function \code{\link[=proportion_R]{proportion_R()}}. The function \code{\link[=susceptibility]{susceptibility()}} is equal to the function \code{\link[=proportion_SI]{proportion_SI()}}. Since AMR v3.0, \code{\link[=proportion_SI]{proportion_SI()}} and \code{\link[=proportion_I]{proportion_I()}} include dose-dependent susceptibility ('SDD').
Use \code{\link[=sir_confidence_interval]{sir_confidence_interval()}} to calculate the confidence interval, which relies on \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method. This function returns a vector of length 2 at default for antimicrobial \emph{resistance}. Change the \code{side} argument to "left"/"min" or "right"/"max" to return a single value, and change the \code{ab_result} argument to e.g. \code{c("S", "I")} to test for antimicrobial \emph{susceptibility}, see Examples.
These functions are not meant to count isolates, but to calculate the proportion of resistance/susceptibility. Use the \code{\link[=count]{count_*()}} functions to count isolates. The function \code{\link[=susceptibility]{susceptibility()}} is essentially equal to \code{\link[=count_susceptible]{count_susceptible()}}\code{/}\code{\link[=count_all]{count_all()}}. \emph{Low counts can influence the outcome - the \verb{proportion_*()} functions may camouflage this, since they only return the proportion (albeit dependent on the \code{minimum} argument).}
The function \code{\link[=proportion_df]{proportion_df()}} takes any variable from \code{data} that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) and calculates the proportions S, I, and R. It also supports grouped variables. The function \code{\link[=sir_df]{sir_df()}} works exactly like \code{\link[=proportion_df]{proportion_df()}}, but adds the number of isolates.
}
\section{Combination Therapy}{
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, Drug A and Drug B, about how \code{\link[=susceptibility]{susceptibility()}} works to calculate the \%SI:
\if{html}{\out{<div class="sourceCode">}}\preformatted{--------------------------------------------------------------------
only_all_tested = FALSE only_all_tested = TRUE
----------------------- -----------------------
Drug A Drug B include as include as include as include as
numerator denominator numerator denominator
-------- -------- ---------- ----------- ---------- -----------
S or I S or I X X X X
R S or I X X X X
<NA> S or I X X - -
S or I R X X X X
R R - X - X
<NA> R - - - -
S or I <NA> X X - -
R <NA> - - - -
<NA> <NA> - - - -
--------------------------------------------------------------------
}\if{html}{\out{</div>}}
Please note that, in combination therapies, for \code{only_all_tested = TRUE} applies that:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ count_S() + count_I() + count_R() = count_all()
proportion_S() + proportion_I() + proportion_R() = 1
}\if{html}{\out{</div>}}
and that, in combination therapies, for \code{only_all_tested = FALSE} applies that:
\if{html}{\out{<div class="sourceCode">}}\preformatted{ count_S() + count_I() + count_R() >= count_all()
proportion_S() + proportion_I() + proportion_R() >= 1
}\if{html}{\out{</div>}}
Using \code{only_all_tested} has no impact when only using one antibiotic as input.
}
\section{Interpretation of SIR}{
In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (\url{https://www.eucast.org/newsiandr}):
\itemize{
\item \strong{S - Susceptible, standard dosing regimen}\cr
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.
\item \strong{I - Susceptible, increased exposure} \emph{\cr
A microorganism is categorised as "Susceptible, Increased exposure}" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.
\item \strong{R = Resistant}\cr
A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.
\itemize{
\item \emph{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.
}
}
This AMR package honours this insight. Use \code{\link[=susceptibility]{susceptibility()}} (equal to \code{\link[=proportion_SI]{proportion_SI()}}) to determine antimicrobial susceptibility and \code{\link[=count_susceptible]{count_susceptible()}} (equal to \code{\link[=count_SI]{count_SI()}}) to count susceptible isolates.
}
\examples{
# example_isolates is a data set available in the AMR package.
# run ?example_isolates for more info.
example_isolates
# base R ------------------------------------------------------------
# determines \%R
resistance(example_isolates$AMX)
sir_confidence_interval(example_isolates$AMX)
sir_confidence_interval(example_isolates$AMX,
confidence_level = 0.975
)
sir_confidence_interval(example_isolates$AMX,
confidence_level = 0.975,
collapse = ", "
)
# determines \%S+I:
susceptibility(example_isolates$AMX)
sir_confidence_interval(example_isolates$AMX,
ab_result = c("S", "I")
)
# be more specific
proportion_S(example_isolates$AMX)
proportion_SI(example_isolates$AMX)
proportion_I(example_isolates$AMX)
proportion_IR(example_isolates$AMX)
proportion_R(example_isolates$AMX)
# dplyr -------------------------------------------------------------
\donttest{
if (require("dplyr")) {
example_isolates \%>\%
group_by(ward) \%>\%
summarise(
r = resistance(CIP),
n = n_sir(CIP)
) # n_sir works like n_distinct in dplyr, see ?n_sir
}
if (require("dplyr")) {
example_isolates \%>\%
group_by(ward) \%>\%
summarise(
cipro_R = resistance(CIP),
ci_min = sir_confidence_interval(CIP, side = "min"),
ci_max = sir_confidence_interval(CIP, side = "max"),
)
}
if (require("dplyr")) {
# scoped dplyr verbs with antibiotic selectors
# (you could also use across() of course)
example_isolates \%>\%
group_by(ward) \%>\%
summarise_at(
c(aminoglycosides(), carbapenems()),
resistance
)
}
if (require("dplyr")) {
example_isolates \%>\%
group_by(ward) \%>\%
summarise(
R = resistance(CIP, as_percent = TRUE),
SI = susceptibility(CIP, as_percent = TRUE),
n1 = count_all(CIP), # the actual total; sum of all three
n2 = n_sir(CIP), # same - analogous to n_distinct
total = n()
) # NOT the number of tested isolates!
# Calculate co-resistance between amoxicillin/clav acid and gentamicin,
# so we can see that combination therapy does a lot more than mono therapy:
example_isolates \%>\% susceptibility(AMC) # \%SI = 76.3\%
example_isolates \%>\% count_all(AMC) # n = 1879
example_isolates \%>\% susceptibility(GEN) # \%SI = 75.4\%
example_isolates \%>\% count_all(GEN) # n = 1855
example_isolates \%>\% susceptibility(AMC, GEN) # \%SI = 94.1\%
example_isolates \%>\% count_all(AMC, GEN) # n = 1939
# See Details on how `only_all_tested` works. Example:
example_isolates \%>\%
summarise(
numerator = count_susceptible(AMC, GEN),
denominator = count_all(AMC, GEN),
proportion = susceptibility(AMC, GEN)
)
example_isolates \%>\%
summarise(
numerator = count_susceptible(AMC, GEN, only_all_tested = TRUE),
denominator = count_all(AMC, GEN, only_all_tested = TRUE),
proportion = susceptibility(AMC, GEN, only_all_tested = TRUE)
)
example_isolates \%>\%
group_by(ward) \%>\%
summarise(
cipro_p = susceptibility(CIP, as_percent = TRUE),
cipro_n = count_all(CIP),
genta_p = susceptibility(GEN, as_percent = TRUE),
genta_n = count_all(GEN),
combination_p = susceptibility(CIP, GEN, as_percent = TRUE),
combination_n = count_all(CIP, GEN)
)
# Get proportions S/I/R immediately of all sir columns
example_isolates \%>\%
select(AMX, CIP) \%>\%
proportion_df(translate = FALSE)
# It also supports grouping variables
# (use sir_df to also include the count)
example_isolates \%>\%
select(ward, AMX, CIP) \%>\%
group_by(ward) \%>\%
sir_df(translate = FALSE)
}
}
}
\seealso{
\code{\link[=count]{count()}} to count resistant and susceptible isolates.
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/random.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/random.R
\name{random}
\alias{random}
\alias{random_mic}
\alias{random_disk}
\alias{random_sir}
\title{Random MIC Values/Disk Zones/SIR Generation}
\usage{
random_mic(size = NULL, mo = NULL, ab = NULL, ...)
random_disk(size = NULL, mo = NULL, ab = NULL, ...)
random_sir(size = NULL, prob_SIR = c(0.33, 0.33, 0.33), ...)
}
\arguments{
\item{size}{desired size of the returned vector. If used in a \link{data.frame} call or \code{dplyr} verb, will get the current (group) size if left blank.}
\item{mo}{any \link{character} that can be coerced to a valid microorganism code with \code{\link[=as.mo]{as.mo()}}}
\item{ab}{any \link{character} that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}}
\item{...}{ignored, only in place to allow future extensions}
\item{prob_SIR}{a vector of length 3: the probabilities for "S" (1st value), "I" (2nd value) and "R" (3rd value)}
}
\value{
class \code{mic} for \code{\link[=random_mic]{random_mic()}} (see \code{\link[=as.mic]{as.mic()}}) and class \code{disk} for \code{\link[=random_disk]{random_disk()}} (see \code{\link[=as.disk]{as.disk()}})
}
\description{
These functions can be used for generating random MIC values and disk diffusion diameters, for AMR data analysis practice. By providing a microorganism and antimicrobial drug, the generated results will reflect reality as much as possible.
}
\details{
The base \R function \code{\link[=sample]{sample()}} is used for generating values.
Generated values are based on the EUCAST 2024 guideline as implemented in the \link{clinical_breakpoints} data set. To create specific generated values per bug or drug, set the \code{mo} and/or \code{ab} argument.
}
\examples{
random_mic(25)
random_disk(25)
random_sir(25)
\donttest{
# make the random generation more realistic by setting a bug and/or drug:
random_mic(25, "Klebsiella pneumoniae") # range 0.0625-64
random_mic(25, "Klebsiella pneumoniae", "meropenem") # range 0.0625-16
random_mic(25, "Streptococcus pneumoniae", "meropenem") # range 0.0625-4
random_disk(25, "Klebsiella pneumoniae") # range 8-50
random_disk(25, "Klebsiella pneumoniae", "ampicillin") # range 11-17
random_disk(25, "Streptococcus pneumoniae", "ampicillin") # range 12-27
}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/resistance_predict.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resistance_predict.R
\name{resistance_predict}
\alias{resistance_predict}
\alias{sir_predict}
\alias{plot.resistance_predict}
\alias{ggplot_sir_predict}
\alias{autoplot.resistance_predict}
\title{Predict Antimicrobial Resistance}
\usage{
resistance_predict(
x,
col_ab,
col_date = NULL,
year_min = NULL,
year_max = NULL,
year_every = 1,
minimum = 30,
model = NULL,
I_as_S = TRUE,
preserve_measurements = TRUE,
info = interactive(),
...
)
sir_predict(
x,
col_ab,
col_date = NULL,
year_min = NULL,
year_max = NULL,
year_every = 1,
minimum = 30,
model = NULL,
I_as_S = TRUE,
preserve_measurements = TRUE,
info = interactive(),
...
)
\method{plot}{resistance_predict}(x, main = paste("Resistance Prediction of", x_name), ...)
ggplot_sir_predict(
x,
main = paste("Resistance Prediction of", x_name),
ribbon = TRUE,
...
)
\method{autoplot}{resistance_predict}(
object,
main = paste("Resistance Prediction of", x_name),
ribbon = TRUE,
...
)
}
\arguments{
\item{x}{a \link{data.frame} containing isolates. Can be left blank for automatic determination, see \emph{Examples}.}
\item{col_ab}{column name of \code{x} containing antimicrobial interpretations (\code{"R"}, \code{"I"} and \code{"S"})}
\item{col_date}{column name of the date, will be used to calculate years if this column doesn't consist of years already - the default is the first column of with a date class}
\item{year_min}{lowest year to use in the prediction model, dafaults to the lowest year in \code{col_date}}
\item{year_max}{highest year to use in the prediction model - the default is 10 years after today}
\item{year_every}{unit of sequence between lowest year found in the data and \code{year_max}}
\item{minimum}{minimal amount of available isolates per year to include. Years containing less observations will be estimated by the model.}
\item{model}{the statistical model of choice. This could be a generalised linear regression model with binomial distribution (i.e. using \code{glm(..., family = binomial)}, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance. See \emph{Details} for all valid options.}
\item{I_as_S}{a \link{logical} to indicate whether values \code{"I"} should be treated as \code{"S"} (will otherwise be treated as \code{"R"}). The default, \code{TRUE}, follows the redefinition by EUCAST about the interpretation of I (increased exposure) in 2019, see section \emph{Interpretation of S, I and R} below.}
\item{preserve_measurements}{a \link{logical} to indicate whether predictions of years that are actually available in the data should be overwritten by the original data. The standard errors of those years will be \code{NA}.}
\item{info}{a \link{logical} to indicate whether textual analysis should be printed with the name and \code{\link[=summary]{summary()}} of the statistical model.}
\item{...}{arguments passed on to functions}
\item{main}{title of the plot}
\item{ribbon}{a \link{logical} to indicate whether a ribbon should be shown (default) or error bars}
\item{object}{model data to be plotted}
}
\value{
A \link{data.frame} with extra class \code{\link{resistance_predict}} with columns:
\itemize{
\item \code{year}
\item \code{value}, the same as \code{estimated} when \code{preserve_measurements = FALSE}, and a combination of \code{observed} and \code{estimated} otherwise
\item \code{se_min}, the lower bound of the standard error with a minimum of \code{0} (so the standard error will never go below 0\%)
\item \code{se_max} the upper bound of the standard error with a maximum of \code{1} (so the standard error will never go above 100\%)
\item \code{observations}, the total number of available observations in that year, i.e. \eqn{S + I + R}
\item \code{observed}, the original observed resistant percentages
\item \code{estimated}, the estimated resistant percentages, calculated by the model
}
Furthermore, the model itself is available as an attribute: \code{attributes(x)$model}, see \emph{Examples}.
}
\description{
Create a prediction model to predict antimicrobial resistance for the next years on statistical solid ground. Standard errors (SE) will be returned as columns \code{se_min} and \code{se_max}. See \emph{Examples} for a real live example.
}
\details{
Valid options for the statistical model (argument \code{model}) are:
\itemize{
\item \code{"binomial"} or \code{"binom"} or \code{"logit"}: a generalised linear regression model with binomial distribution
\item \code{"loglin"} or \code{"poisson"}: a generalised log-linear regression model with poisson distribution
\item \code{"lin"} or \code{"linear"}: a linear regression model
}
}
\section{Interpretation of SIR}{
In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R as shown below (\url{https://www.eucast.org/newsiandr}):
\itemize{
\item \strong{S - Susceptible, standard dosing regimen}\cr
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.
\item \strong{I - Susceptible, increased exposure} \emph{\cr
A microorganism is categorised as "Susceptible, Increased exposure}" when there is a high likelihood of therapeutic success because exposure to the agent is increased by adjusting the dosing regimen or by its concentration at the site of infection.
\item \strong{R = Resistant}\cr
A microorganism is categorised as "Resistant" when there is a high likelihood of therapeutic failure even when there is increased exposure.
\itemize{
\item \emph{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.
}
}
This AMR package honours this insight. Use \code{\link[=susceptibility]{susceptibility()}} (equal to \code{\link[=proportion_SI]{proportion_SI()}}) to determine antimicrobial susceptibility and \code{\link[=count_susceptible]{count_susceptible()}} (equal to \code{\link[=count_SI]{count_SI()}}) to count susceptible isolates.
}
\examples{
x <- resistance_predict(example_isolates,
col_ab = "AMX",
year_min = 2010,
model = "binomial"
)
plot(x)
\donttest{
if (require("ggplot2")) {
ggplot_sir_predict(x)
}
# using dplyr:
if (require("dplyr")) {
x <- example_isolates \%>\%
filter_first_isolate() \%>\%
filter(mo_genus(mo) == "Staphylococcus") \%>\%
resistance_predict("PEN", model = "binomial")
print(plot(x))
# get the model from the object
mymodel <- attributes(x)$model
summary(mymodel)
}
# create nice plots with ggplot2 yourself
if (require("dplyr") && require("ggplot2")) {
data <- example_isolates \%>\%
filter(mo == as.mo("E. coli")) \%>\%
resistance_predict(
col_ab = "AMX",
col_date = "date",
model = "binomial",
info = FALSE,
minimum = 15
)
head(data)
autoplot(data)
}
}
}
\seealso{
The \code{\link[=proportion]{proportion()}} functions to calculate resistance
Models: \code{\link[=lm]{lm()}} \code{\link[=glm]{glm()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/skewness.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/skewness.R
\name{skewness}
\alias{skewness}
\alias{skewness.default}
\alias{skewness.matrix}
\alias{skewness.data.frame}
\title{Skewness of the Sample}
\usage{
skewness(x, na.rm = FALSE)
\method{skewness}{default}(x, na.rm = FALSE)
\method{skewness}{matrix}(x, na.rm = FALSE)
\method{skewness}{data.frame}(x, na.rm = FALSE)
}
\arguments{
\item{x}{a vector of values, a \link{matrix} or a \link{data.frame}}
\item{na.rm}{a \link{logical} value indicating whether \code{NA} values should be stripped before the computation proceeds}
}
\description{
Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean.
When negative ('left-skewed'): the left tail is longer; the mass of the distribution is concentrated on the right of a histogram. When positive ('right-skewed'): the right tail is longer; the mass of the distribution is concentrated on the left of a histogram. A normal distribution has a skewness of 0.
}
\examples{
skewness(runif(1000))
}
\seealso{
\code{\link[=kurtosis]{kurtosis()}}
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/translate.Rd':
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/translate.R
\name{translate}
\alias{translate}
\alias{get_AMR_locale}
\alias{set_AMR_locale}
\alias{reset_AMR_locale}
\alias{translate_AMR}
\title{Translate Strings from the AMR Package}
\usage{
get_AMR_locale()
set_AMR_locale(language)
reset_AMR_locale()
translate_AMR(x, language = get_AMR_locale())
}
\arguments{
\item{language}{language to choose. Use one of these supported language names or ISO-639-1 codes: English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), or Ukrainian (uk).}
\item{x}{text to translate}
}
\description{
For language-dependent output of \code{AMR} functions, such as \code{\link[=mo_name]{mo_name()}}, \code{\link[=mo_gramstain]{mo_gramstain()}}, \code{\link[=mo_type]{mo_type()}} and \code{\link[=ab_name]{ab_name()}}.
}
\details{
The currently 20 supported languages are English (en), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), German (de), Greek (el), Italian (it), Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Turkish (tr), and Ukrainian (uk). All these languages have translations available for all antimicrobial drugs and colloquial microorganism names.
To permanently silence the once-per-session language note on a non-English operating system, you can set the package option \code{\link[=AMR-options]{AMR_locale}} in your \code{.Rprofile} file like this:
\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Open .Rprofile file
utils::file.edit("~/.Rprofile")
# Then add e.g. Italian support to that file using:
options(AMR_locale = "Italian")
}\if{html}{\out{</div>}}
And then save the file.
Please read about adding or updating a language in \href{https://github.com/msberends/AMR/wiki/}{our Wiki}.
\subsection{Changing the Default Language}{
The system language will be used at default (as returned by \code{Sys.getenv("LANG")} or, if \code{LANG} is not set, \code{\link[=Sys.getlocale]{Sys.getlocale("LC_COLLATE")}}), if that language is supported. But the language to be used can be overwritten in two ways and will be checked in this order:
\enumerate{
\item Setting the package option \code{\link[=AMR-options]{AMR_locale}}, either by using e.g. \code{set_AMR_locale("German")} or by running e.g. \code{options(AMR_locale = "German")}.
Note that setting an \R option only works in the same session. Save the command \code{options(AMR_locale = "(your language)")} to your \code{.Rprofile} file to apply it for every session. Run \code{utils::file.edit("~/.Rprofile")} to edit your \code{.Rprofile} file.
\item Setting the system variable \code{LANGUAGE} or \code{LANG}, e.g. by adding \code{LANGUAGE="de_DE.utf8"} to your \code{.Renviron} file in your home directory.
}
Thus, if the package option \code{\link[=AMR-options]{AMR_locale}} is set, the system variables \code{LANGUAGE} and \code{LANG} will be ignored.
}
}
\examples{
# Current settings (based on system language)
ab_name("Ciprofloxacin")
mo_name("Coagulase-negative Staphylococcus (CoNS)")
# setting another language
set_AMR_locale("Dutch")
ab_name("Ciprofloxacin")
mo_name("Coagulase-negative Staphylococcus (CoNS)")
# setting yet another language
set_AMR_locale("German")
ab_name("Ciprofloxacin")
mo_name("Coagulase-negative Staphylococcus (CoNS)")
# set_AMR_locale() understands endonyms, English exonyms, and ISO-639-1:
set_AMR_locale("Deutsch")
set_AMR_locale("German")
set_AMR_locale("de")
ab_name("amox/clav")
# reset to system default
reset_AMR_locale()
ab_name("amox/clav")
}
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/AMR.Rmd':
---
title: "How to conduct AMR data analysis"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{How to conduct AMR data analysis}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
warning = FALSE,
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 5
)
```
**Note:** values on this page will change with every website update since they are based on randomly created values and the page was written in [R Markdown](https://rmarkdown.rstudio.com/). However, the methodology remains unchanged. This page was generated on `r format(Sys.Date(), "%d %B %Y")`.
# Introduction
Conducting AMR data analysis unfortunately requires in-depth knowledge from different scientific fields, which makes it hard to do right. At least, it requires:
* Good questions (always start with those!) and reliable data
* A thorough understanding of (clinical) epidemiology, to understand the clinical and epidemiological relevance and possible bias of results
* A thorough understanding of (clinical) microbiology/infectious diseases, to understand which microorganisms are causal to which infections and the implications of pharmaceutical treatment, as well as understanding intrinsic and acquired microbial resistance
* Experience with data analysis with microbiological tests and their results, to understand the determination and limitations of MIC values and their interpretations to SIR values
* Availability of the biological taxonomy of microorganisms and probably normalisation factors for pharmaceuticals, such as defined daily doses (DDD)
* Available (inter-)national guidelines, and profound methods to apply them
Of course, we cannot instantly provide you with knowledge and experience. But with this `AMR` package, we aimed at providing (1) tools to simplify antimicrobial resistance data cleaning, transformation and analysis, (2) methods to easily incorporate international guidelines and (3) scientifically reliable reference data, including the requirements mentioned above.
The `AMR` package enables standardised and reproducible AMR data analysis, with the application of evidence-based rules, determination of first isolates, translation of various codes for microorganisms and antimicrobial agents, determination of (multi-drug) resistant microorganisms, and calculation of antimicrobial resistance, prevalence and future trends.
# Preparation
For this tutorial, we will create fake demonstration data to work with.
You can skip to [Cleaning the data](#cleaning-the-data) if you already have your own data ready. If you start your analysis, try to make the structure of your data generally look like this:
```{r example table, echo = FALSE, results = 'asis'}
knitr::kable(
data.frame(
date = Sys.Date(),
patient_id = c("abcd", "abcd", "efgh"),
mo = "Escherichia coli",
AMX = c("S", "S", "R"),
CIP = c("S", "R", "S"),
stringsAsFactors = FALSE
),
align = "c"
)
```
## Needed R packages
As with many uses in R, we need some additional packages for AMR data analysis. Our package works closely together with the [tidyverse packages](https://www.tidyverse.org) [`dplyr`](https://dplyr.tidyverse.org/) and [`ggplot2`](https://ggplot2.tidyverse.org) by RStudio. The tidyverse tremendously improves the way we conduct data science - it allows for a very natural way of writing syntaxes and creating beautiful plots in R.
We will also use the `cleaner` package, that can be used for cleaning data and creating frequency tables.
```{r lib packages, message = FALSE, warning = FALSE, results = 'asis'}
library(dplyr)
library(ggplot2)
library(AMR)
# (if not yet installed, install with:)
# install.packages(c("dplyr", "ggplot2", "AMR"))
```
The `AMR` package contains a data set `example_isolates_unclean`, which might look data that users have extracted from their laboratory systems:
```{r}
example_isolates_unclean
# we will use 'our_data' as the data set name for this tutorial
our_data <- example_isolates_unclean
```
For AMR data analysis, we would like the microorganism column to contain valid, up-to-date taxonomy, and the antibiotic columns to be cleaned as SIR values as well.
## Taxonomy of microorganisms
With `as.mo()`, users can transform arbitrary microorganism names or codes to current taxonomy. The `AMR` package contains up-to-date taxonomic data. To be specific, currently included data were retrieved on `r format(AMR:::TAXONOMY_VERSION$LPSN$accessed_date, "%d %b %Y")`.
The codes of the AMR packages that come from `as.mo()` are short, but still human readable. More importantly, `as.mo()` supports all kinds of input:
```{r, message = FALSE}
as.mo("Klebsiella pneumoniae")
as.mo("K. pneumoniae")
as.mo("KLEPNE")
as.mo("KLPN")
```
The first character in above codes denote their taxonomic kingdom, such as Bacteria (B), Fungi (F), and Protozoa (P).
The `AMR` package also contain functions to directly retrieve taxonomic properties, such as the name, genus, species, family, order, and even Gram-stain. They all start with `mo_` and they use `as.mo()` internally, so that still any arbitrary user input can be used:
```{r, message = FALSE}
mo_family("K. pneumoniae")
mo_genus("K. pneumoniae")
mo_species("K. pneumoniae")
mo_gramstain("Klebsiella pneumoniae")
mo_ref("K. pneumoniae")
mo_snomed("K. pneumoniae")
```
Now we can thus clean our data:
```{r, echo = FALSE, message = FALSE}
mo_reset_session()
```
```{r, message = TRUE}
our_data$bacteria <- as.mo(our_data$bacteria, info = TRUE)
```
Apparently, there was some uncertainty about the translation to taxonomic codes. Let's check this:
```{r}
mo_uncertainties()
```
That's all good.
## Antibiotic results
The column with antibiotic test results must also be cleaned. The `AMR` package comes with three new data types to work with such test results: `mic` for minimal inhibitory concentrations (MIC), `disk` for disk diffusion diameters, and `sir` for SIR data that have been interpreted already. This package can also determine SIR values based on MIC or disk diffusion values, read more about that on the `as.sir()` page.
For now, we will just clean the SIR columns in our data using dplyr:
```{r}
# method 1, be explicit about the columns:
our_data <- our_data %>%
mutate_at(vars(AMX:GEN), as.sir)
# method 2, let the AMR package determine the eligible columns
our_data <- our_data %>%
mutate_if(is_sir_eligible, as.sir)
# result:
our_data
```
This is basically it for the cleaning, time to start the data inclusion.
## First isolates
We need to know which isolates we can *actually* use for analysis without repetition bias.
To conduct an analysis of antimicrobial resistance, you must [only include the first isolate of every patient per episode](https:/pubmed.ncbi.nlm.nih.gov/17304462/) (Hindler *et al.*, Clin Infect Dis. 2007). If you would not do this, you could easily get an overestimate or underestimate of the resistance of an antibiotic. Imagine that a patient was admitted with an MRSA and that it was found in 5 different blood cultures the following weeks (yes, some countries like the Netherlands have these blood drawing policies). The resistance percentage of oxacillin of all \emph{S. aureus} isolates would be overestimated, because you included this MRSA more than once. It would clearly be [selection bias](https://en.wikipedia.org/wiki/Selection_bias).
The Clinical and Laboratory Standards Institute (CLSI) appoints this as follows:
> *(...) When preparing a cumulative antibiogram to guide clinical decisions about empirical antimicrobial therapy of initial infections, **only the first isolate of a given species per patient, per analysis period (eg, one year) should be included, irrespective of body site, antimicrobial susceptibility profile, or other phenotypical characteristics (eg, biotype)**. The first isolate is easily identified, and cumulative antimicrobial susceptibility test data prepared using the first isolate are generally comparable to cumulative antimicrobial susceptibility test data calculated by other methods, providing duplicate isolates are excluded.*
<br>[M39-A4 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 4th Edition. CLSI, 2014. Chapter 6.4](https://clsi.org/standards/products/microbiology/documents/m39/)
This `AMR` package includes this methodology with the `first_isolate()` function and is able to apply the four different methods as defined by [Hindler *et al.* in 2007](https://academic.oup.com/cid/article/44/6/867/364325): phenotype-based, episode-based, patient-based, isolate-based. The right method depends on your goals and analysis, but the default phenotype-based method is in any case the method to properly correct for most duplicate isolates. Read more about the methods on the `first_isolate()` page.
The outcome of the function can easily be added to our data:
```{r 1st isolate}
our_data <- our_data %>%
mutate(first = first_isolate(info = TRUE))
```
So only `r round((sum(our_data$first) / nrow(our_data) * 100))`% is suitable for resistance analysis! We can now filter on it with the `filter()` function, also from the `dplyr` package:
```{r 1st isolate filter}
our_data_1st <- our_data %>%
filter(first == TRUE)
```
For future use, the above two syntaxes can be shortened:
```{r 1st isolate filter 2}
our_data_1st <- our_data %>%
filter_first_isolate()
```
So we end up with `r format(nrow(our_data_1st), big.mark = " ")` isolates for analysis. Now our data looks like:
```{r preview data set 3}
our_data_1st
```
Time for the analysis.
# Analysing the data
The base R `summary()` function gives a good first impression, as it comes with support for the new `mo` and `sir` classes that we now have in our data set:
```{r}
summary(our_data_1st)
glimpse(our_data_1st)
# number of unique values per column:
sapply(our_data_1st, n_distinct)
```
## Availability of species
To just get an idea how the species are distributed, create a frequency table with `count()` based on the name of the microorganisms:
```{r freq 1}
our_data %>%
count(mo_name(bacteria), sort = TRUE)
our_data_1st %>%
count(mo_name(bacteria), sort = TRUE)
```
## Select and filter with antibiotic selectors
Using so-called antibiotic class selectors, you can select or filter columns based on the antibiotic class that your antibiotic results are in:
```{r bug_drg 2a}
our_data_1st %>%
select(date, aminoglycosides())
our_data_1st %>%
select(bacteria, betalactams())
our_data_1st %>%
select(bacteria, where(is.sir))
# filtering using AB selectors is also possible:
our_data_1st %>%
filter(any(aminoglycosides() == "R"))
our_data_1st %>%
filter(all(betalactams() == "R"))
# even works in base R (since R 3.0):
our_data_1st[all(betalactams() == "R"), ]
```
## Generate antibiograms
Since AMR v2.0 (March 2023), it is very easy to create different types of antibiograms, with support for 20 different languages.
There are four antibiogram types, as proposed by Klinker *et al.* (2021, [DOI 10.1177/20499361211011373](https://doi.org/10.1177/20499361211011373)), and they are all supported by the new `antibiogram()` function:
1. **Traditional Antibiogram (TA)** e.g, for the susceptibility of *Pseudomonas aeruginosa* to piperacillin/tazobactam (TZP)
2. **Combination Antibiogram (CA)** e.g, for the sdditional susceptibility of *Pseudomonas aeruginosa* to TZP + tobramycin versus TZP alone
3. **Syndromic Antibiogram (SA)** e.g, for the susceptibility of *Pseudomonas aeruginosa* to TZP among respiratory specimens (obtained among ICU patients only)
4. **Weighted-Incidence Syndromic Combination Antibiogram (WISCA)** e.g, for the susceptibility of *Pseudomonas aeruginosa* to TZP among respiratory specimens (obtained among ICU patients only) for male patients age >=65 years with heart failure
In this section, we show how to use the `antibiogram()` function to create any of the above antibiogram types. For starters, this is what the included `example_isolates` data set looks like:
```{r}
example_isolates
```
### Traditional Antibiogram
To create a traditional antibiogram, simply state which antibiotics should be used. The `antibiotics` argument in the `antibiogram()` function supports any (combination) of the previously mentioned antibiotic class selectors:
```{r trad}
antibiogram(example_isolates,
antibiotics = c(aminoglycosides(), carbapenems()))
```
Notice that the `antibiogram()` function automatically prints in the right format when using Quarto or R Markdown (such as this page), and even applies italics for taxonomic names (by using `italicise_taxonomy()` internally).
It also uses the language of your OS if this is either `r AMR:::vector_or(vapply(FUN.VALUE = character(1), AMR:::LANGUAGES_SUPPORTED_NAMES, function(x) x$exonym), quotes = FALSE, sort = FALSE)`. In this next example, we force the language to be Spanish using the `language` argument:
```{r trad2}
antibiogram(example_isolates,
mo_transform = "gramstain",
antibiotics = aminoglycosides(),
ab_transform = "name",
language = "es")
```
### Combined Antibiogram
To create a combined antibiogram, use antibiotic codes or names with a plus `+` character like this:
```{r comb}
antibiogram(example_isolates,
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"))
```
### Syndromic Antibiogram
To create a syndromic antibiogram, the `syndromic_group` argument must be used. This can be any column in the data, or e.g. an `ifelse()` with calculations based on certain columns:
```{r synd}
antibiogram(example_isolates,
antibiotics = c(aminoglycosides(), carbapenems()),
syndromic_group = "ward")
```
### Weighted-Incidence Syndromic Combination Antibiogram (WISCA)
To create a WISCA, you must state combination therapy in the `antibiotics` argument (similar to the Combination Antibiogram), define a syndromic group with the `syndromic_group` argument (similar to the Syndromic Antibiogram) in which cases are predefined based on clinical or demographic characteristics (e.g., endocarditis in 75+ females). This next example is a simplification without clinical characteristics, but just gives an idea of how a WISCA can be created:
```{r wisca}
wisca <- antibiogram(example_isolates,
antibiotics = c("AMC", "AMC+CIP", "TZP", "TZP+TOB"),
mo_transform = "gramstain",
minimum = 10, # this should be >= 30, but now just as example
syndromic_group = ifelse(example_isolates$age >= 65 &
example_isolates$gender == "M",
"WISCA Group 1", "WISCA Group 2"))
wisca
```
### Plotting antibiograms
Antibiograms can be plotted using `autoplot()` from the `ggplot2` packages, since this `AMR` package provides an extension to that function:
```{r}
autoplot(wisca)
```
To calculate antimicrobial resistance in a more sensible way, also by correcting for too few results, we use the `resistance()` and `susceptibility()` functions.
## Resistance percentages
The functions `resistance()` and `susceptibility()` can be used to calculate antimicrobial resistance or susceptibility. For more specific analyses, the functions `proportion_S()`, `proportion_SI()`, `proportion_I()`, `proportion_IR()` and `proportion_R()` can be used to determine the proportion of a specific antimicrobial outcome.
All these functions contain a `minimum` argument, denoting the minimum required number of test results for returning a value. These functions will otherwise return `NA`. The default is `minimum = 30`, following the [CLSI M39-A4 guideline](https://clsi.org/standards/products/microbiology/documents/m39/) for applying microbial epidemiology.
As per the EUCAST guideline of 2019, we calculate resistance as the proportion of R (`proportion_R()`, equal to `resistance()`) and susceptibility as the proportion of S and I (`proportion_SI()`, equal to `susceptibility()`). These functions can be used on their own:
```{r}
our_data_1st %>% resistance(AMX)
```
Or can be used in conjunction with `group_by()` and `summarise()`, both from the `dplyr` package:
```{r}
our_data_1st %>%
group_by(hospital) %>%
summarise(amoxicillin = resistance(AMX))
```
----
*Author: Dr. Matthijs Berends, 26th Feb 2023*
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/AMR_for_Python.Rmd':
---
title: "AMR for Python"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{AMR for Python}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
warning = FALSE,
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 5
)
```
# Introduction
The `AMR` package for R is a powerful tool for antimicrobial resistance (AMR) analysis. It provides extensive features for handling microbial and antimicrobial data. However, for those who work primarily in Python, we now have a more intuitive option available: the [`AMR` Python Package Index](https://pypi.org/project/AMR/).
This Python package is a wrapper round the `AMR` R package. It uses the `rpy2` package internally. Despite the need to have R installed, Python users can now easily work with AMR data directly through Python code.
# Install
1. Since the Python package is available on the official [Python Package Index](https://pypi.org/project/AMR/), you can just run:
```bash
pip install AMR
```
2. Make sure you have R installed. There is **no need to install the `AMR` R package**, as it will be installed automatically.
For Linux:
```bash
# Ubuntu / Debian
sudo apt install r-base
# Fedora:
sudo dnf install R
# CentOS/RHEL
sudo yum install R
```
For macOS (using [Homebrew](https://brew.sh)):
```bash
brew install r
```
For Windows, visit the [CRAN download page](https://cran.r-project.org) to download and install R.
# Examples of Usage
## Cleaning Taxonomy
Here’s an example that demonstrates how to clean microorganism and drug names using the `AMR` Python package:
```python
import pandas as pd
import AMR
# Sample data
data = {
"MOs": ['E. coli', 'ESCCOL', 'esco', 'Esche coli'],
"Drug": ['Cipro', 'CIP', 'J01MA02', 'Ciproxin']
}
df = pd.DataFrame(data)
# Use AMR functions to clean microorganism and drug names
df['MO_clean'] = AMR.mo_name(df['MOs'])
df['Drug_clean'] = AMR.ab_name(df['Drug'])
# Display the results
print(df)
```
| MOs | Drug | MO_clean | Drug_clean |
|-------------|-----------|--------------------|---------------|
| E. coli | Cipro | Escherichia coli | Ciprofloxacin |
| ESCCOL | CIP | Escherichia coli | Ciprofloxacin |
| esco | J01MA02 | Escherichia coli | Ciprofloxacin |
| Esche coli | Ciproxin | Escherichia coli | Ciprofloxacin |
### Explanation
* **mo_name:** This function standardises microorganism names. Here, different variations of *Escherichia coli* (such as "E. coli", "ESCCOL", "esco", and "Esche coli") are all converted into the correct, standardised form, "Escherichia coli".
* **ab_name**: Similarly, this function standardises antimicrobial names. The different representations of ciprofloxacin (e.g., "Cipro", "CIP", "J01MA02", and "Ciproxin") are all converted to the standard name, "Ciprofloxacin".
## Taxonomic Data Sets Now in Python!
As a Python user, you might like that the most important data sets of the `AMR` R package, `microorganisms`, `antibiotics`, `clinical_breakpoints`, and `example_isolates`, are now available as regular Python data frames:
```python
AMR.microorganisms
```
| mo | fullname | status | kingdom | gbif | gbif_parent | gbif_renamed_to | prevalence |
|--------------|------------------------------------|----------|----------|-----------|-------------|-----------------|------------|
| B_GRAMN | (unknown Gram-negatives) | unknown | Bacteria | None | None | None | 2.0 |
| B_GRAMP | (unknown Gram-positives) | unknown | Bacteria | None | None | None | 2.0 |
| B_ANAER-NEG | (unknown anaerobic Gram-negatives) | unknown | Bacteria | None | None | None | 2.0 |
| B_ANAER-POS | (unknown anaerobic Gram-positives) | unknown | Bacteria | None | None | None | 2.0 |
| B_ANAER | (unknown anaerobic bacteria) | unknown | Bacteria | None | None | None | 2.0 |
| ... | ... | ... | ... | ... | ... | ... | ... |
| B_ZYMMN_POMC | Zymomonas pomaceae | accepted | Bacteria | 10744418 | 3221412 | None | 2.0 |
| B_ZYMPH | Zymophilus | synonym | Bacteria | None | 9475166 | None | 2.0 |
| B_ZYMPH_PCVR | Zymophilus paucivorans | synonym | Bacteria | None | None | None | 2.0 |
| B_ZYMPH_RFFN | Zymophilus raffinosivorans | synonym | Bacteria | None | None | None | 2.0 |
| F_ZYZYG | Zyzygomyces | unknown | Fungi | None | 7581 | None | 2.0 |
```python
AMR.antibiotics
```
| ab | cid | name | group | oral_ddd | oral_units | iv_ddd | iv_units |
|-----|-------------|----------------------|----------------------------|----------|------------|--------|----------|
| AMA | 4649.0 | 4-aminosalicylic acid| Antimycobacterials | 12.00 | g | NaN | None |
| ACM | 6450012.0 | Acetylmidecamycin | Macrolides/lincosamides | NaN | None | NaN | None |
| ASP | 49787020.0 | Acetylspiramycin | Macrolides/lincosamides | NaN | None | NaN | None |
| ALS | 8954.0 | Aldesulfone sodium | Other antibacterials | 0.33 | g | NaN | None |
| AMK | 37768.0 | Amikacin | Aminoglycosides | NaN | None | 1.0 | g |
| ... | ... | ... | ... | ... | ... | ... | ... |
| VIR | 11979535.0 | Virginiamycine | Other antibacterials | NaN | None | NaN | None |
| VOR | 71616.0 | Voriconazole | Antifungals/antimycotics | 0.40 | g | 0.4 | g |
| XBR | 72144.0 | Xibornol | Other antibacterials | NaN | None | NaN | None |
| ZID | 77846445.0 | Zidebactam | Other antibacterials | NaN | None | NaN | None |
| ZFD | NaN | Zoliflodacin | None | NaN | None | NaN | None |
## Calculating AMR
```python
import AMR
import pandas as pd
df = AMR.example_isolates
result = AMR.resistance(df["AMX"])
print(result)
```
```
[0.59555556]
```
## Generating Antibiograms
One of the core functions of the `AMR` package is generating an antibiogram, a table that summarises the antimicrobial susceptibility of bacterial isolates. Here’s how you can generate an antibiogram from Python:
```python
result2a = AMR.antibiogram(df[["mo", "AMX", "CIP", "TZP"]])
print(result2a)
```
| Pathogen | Amoxicillin | Ciprofloxacin | Piperacillin/tazobactam |
|-----------------|-----------------|-----------------|--------------------------|
| CoNS | 7% (10/142) | 73% (183/252) | 30% (10/33) |
| E. coli | 50% (196/392) | 88% (399/456) | 94% (393/416) |
| K. pneumoniae | 0% (0/58) | 96% (53/55) | 89% (47/53) |
| P. aeruginosa | 0% (0/30) | 100% (30/30) | None |
| P. mirabilis | None | 94% (34/36) | None |
| S. aureus | 6% (8/131) | 90% (171/191) | None |
| S. epidermidis | 1% (1/91) | 64% (87/136) | None |
| S. hominis | None | 80% (56/70) | None |
| S. pneumoniae | 100% (112/112) | None | 100% (112/112) |
```python
result2b = AMR.antibiogram(df[["mo", "AMX", "CIP", "TZP"]], mo_transform = "gramstain")
print(result2b)
```
| Pathogen | Amoxicillin | Ciprofloxacin | Piperacillin/tazobactam |
|----------------|-----------------|------------------|--------------------------|
| Gram-negative | 36% (226/631) | 91% (621/684) | 88% (565/641) |
| Gram-positive | 43% (305/703) | 77% (560/724) | 86% (296/345) |
In this example, we generate an antibiogram by selecting various antibiotics.
# Conclusion
With the `AMR` Python package, Python users can now effortlessly call R functions from the `AMR` R package. This eliminates the need for complex `rpy2` configurations and provides a clean, easy-to-use interface for antimicrobial resistance analysis. The examples provided above demonstrate how this can be applied to typical workflows, such as standardising microorganism and antimicrobial names or calculating resistance.
By just running `import AMR`, users can seamlessly integrate the robust features of the R `AMR` package into Python workflows.
Whether you're cleaning data or analysing resistance patterns, the `AMR` Python package makes it easy to work with AMR data in Python.
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/EUCAST.Rmd':
---
title: "How to apply EUCAST rules"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{How to apply EUCAST rules}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 4.5
)
library(AMR)
```
## Introduction
What are EUCAST rules? The European Committee on Antimicrobial Susceptibility Testing (EUCAST) states [on their website](https://www.eucast.org/expert_rules_and_intrinsic_resistance/):
> *EUCAST expert rules are a tabulated collection of expert knowledge on intrinsic resistances, exceptional resistance phenotypes and interpretive rules that may be applied to antimicrobial susceptibility testing in order to reduce errors and make appropriate recommendations for reporting particular resistances.*
In Europe, a lot of medical microbiological laboratories already apply these rules ([Brown *et al.*, 2015](https://www.eurosurveillance.org/content/10.2807/1560-7917.ES2015.20.2.21008)). Our package features their latest insights on intrinsic resistance and unusual phenotypes (`r AMR:::EUCAST_VERSION_EXPERT_RULES[[length(AMR:::EUCAST_VERSION_EXPERT_RULES)]]$version_txt`, `r AMR:::EUCAST_VERSION_EXPERT_RULES[[length(AMR:::EUCAST_VERSION_EXPERT_RULES)]]$year`).
Moreover, the `eucast_rules()` function we use for this purpose can also apply additional rules, like forcing <help title="ATC: J01CA01">ampicillin</help> = R in isolates when <help title="ATC: J01CR02">amoxicillin/clavulanic acid</help> = R.
## Examples
These rules can be used to discard impossible bug-drug combinations in your data. For example, *Klebsiella* produces beta-lactamase that prevents ampicillin (or amoxicillin) from working against it. In other words, practically every strain of *Klebsiella* is resistant to ampicillin.
Sometimes, laboratory data can still contain such strains with ampicillin being susceptible to ampicillin. This could be because an antibiogram is available before an identification is available, and the antibiogram is then not re-interpreted based on the identification (namely, *Klebsiella*). EUCAST expert rules solve this, that can be applied using `eucast_rules()`:
```{r, warning = FALSE, message = FALSE}
oops <- data.frame(
mo = c(
"Klebsiella",
"Escherichia"
),
ampicillin = "S"
)
oops
eucast_rules(oops, info = FALSE)
```
A more convenient function is `mo_is_intrinsic_resistant()` that uses the same guideline, but allows to check for one or more specific microorganisms or antibiotics:
```{r, warning = FALSE, message = FALSE}
mo_is_intrinsic_resistant(
c("Klebsiella", "Escherichia"),
"ampicillin"
)
mo_is_intrinsic_resistant(
"Klebsiella",
c("ampicillin", "kanamycin")
)
```
EUCAST rules can not only be used for correction, they can also be used for filling in known resistance and susceptibility based on results of other antimicrobials drugs. This process is called *interpretive reading*, is basically a form of imputation, and is part of the `eucast_rules()` function as well:
```{r, warning = FALSE, message = FALSE}
data <- data.frame(
mo = c(
"Staphylococcus aureus",
"Enterococcus faecalis",
"Escherichia coli",
"Klebsiella pneumoniae",
"Pseudomonas aeruginosa"
),
VAN = "-", # Vancomycin
AMX = "-", # Amoxicillin
COL = "-", # Colistin
CAZ = "-", # Ceftazidime
CXM = "-", # Cefuroxime
PEN = "S", # Benzylenicillin
FOX = "S", # Cefoxitin
stringsAsFactors = FALSE
)
```
```{r, eval = FALSE}
data
```
```{r, echo = FALSE}
knitr::kable(data, align = "lccccccc")
```
```{r, warning = FALSE, eval = FALSE}
eucast_rules(data)
```
```{r, warning = FALSE, echo = FALSE, message = FALSE}
knitr::kable(eucast_rules(data), align = "lccccccc")
```
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/MDR.Rmd':
---
title: "How to determine multi-drug resistance (MDR)"
output:
rmarkdown::html_vignette:
toc: true
vignette: >
%\VignetteIndexEntry{How to determine multi-drug resistance (MDR)}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(AMR)
```
With the function `mdro()`, you can determine which micro-organisms are multi-drug resistant organisms (MDRO).
### Type of input
The `mdro()` function takes a data set as input, such as a regular `data.frame`. It tries to automatically determine the right columns for info about your isolates, such as the name of the species and all columns with results of antimicrobial agents. See the help page for more info about how to set the right settings for your data with the command `?mdro`.
For WHONET data (and most other data), all settings are automatically set correctly.
### Guidelines
The `mdro()` function support multiple guidelines. You can select a guideline with the `guideline` parameter. Currently supported guidelines are (case-insensitive):
* `guideline = "CMI2012"` (default)
Magiorakos AP, Srinivasan A *et al.* "Multidrug-resistant, extensively drug-resistant and pandrug-resistant bacteria: an international expert proposal for interim standard definitions for acquired resistance." Clinical Microbiology and Infection (2012) ([link](https://www.clinicalmicrobiologyandinfection.com/article/S1198-743X(14)61632-3/fulltext))
* `guideline = "EUCAST3.2"` (or simply `guideline = "EUCAST"`)
The European international guideline - EUCAST Expert Rules Version 3.2 "Intrinsic Resistance and Unusual Phenotypes" ([link](https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2020/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.2_20200225.pdf))
* `guideline = "EUCAST3.1"`
The European international guideline - EUCAST Expert Rules Version 3.1 "Intrinsic Resistance and Exceptional Phenotypes Tables" ([link](https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/Expert_rules_intrinsic_exceptional_V3.1.pdf))
* `guideline = "TB"`
The international guideline for multi-drug resistant tuberculosis - World Health Organization "Companion handbook to the WHO guidelines for the programmatic management of drug-resistant tuberculosis" ([link](https://www.who.int/tb/publications/pmdt_companionhandbook/en/))
* `guideline = "MRGN"`
The German national guideline - Mueller *et al.* (2015) Antimicrobial Resistance and Infection Control 4:7. DOI: 10.1186/s13756-015-0047-6
* `guideline = "BRMO"`
The Dutch national guideline - Rijksinstituut voor Volksgezondheid en Milieu "WIP-richtlijn BRMO (Bijzonder Resistente Micro-Organismen) (ZKH)" ([link](https://www.rivm.nl/wip-richtlijn-brmo-bijzonder-resistente-micro-organismen-zkh))
Please suggest your own (country-specific) guidelines by letting us know: <https://github.com/msberends/AMR/issues/new>.
#### Custom Guidelines
You can also use your own custom guideline. Custom guidelines can be set with the `custom_mdro_guideline()` function. This is of great importance if you have custom rules to determine MDROs in your hospital, e.g., rules that are dependent on ward, state of contact isolation or other variables in your data.
If you are familiar with `case_when()` of the `dplyr` package, you will recognise the input method to set your own rules. Rules must be set using what R considers to be the 'formula notation':
```{r}
custom <- custom_mdro_guideline(
CIP == "R" & age > 60 ~ "Elderly Type A",
ERY == "R" & age > 60 ~ "Elderly Type B"
)
```
If a row/an isolate matches the first rule, the value after the first `~` (in this case *'Elderly Type A'*) will be set as MDRO value. Otherwise, the second rule will be tried and so on. The maximum number of rules is unlimited.
You can print the rules set in the console for an overview. Colours will help reading it if your console supports colours.
```{r}
custom
```
The outcome of the function can be used for the `guideline` argument in the `mdro()` function:
```{r}
x <- mdro(example_isolates, guideline = custom)
table(x)
```
The rules set (the `custom` object in this case) could be exported to a shared file location using `saveRDS()` if you collaborate with multiple users. The custom rules set could then be imported using `readRDS()`.
### Examples
The `mdro()` function always returns an ordered `factor` for predefined guidelines. For example, the output of the default guideline by Magiorakos *et al.* returns a `factor` with levels 'Negative', 'MDR', 'XDR' or 'PDR' in that order.
The next example uses the `example_isolates` data set. This is a data set included with this package and contains full antibiograms of 2,000 microbial isolates. It reflects reality and can be used to practise AMR data analysis. If we test the MDR/XDR/PDR guideline on this data set, we get:
```{r, message = FALSE}
library(dplyr) # to support pipes: %>%
library(cleaner) # to create frequency tables
```
```{r, results = 'hide'}
example_isolates %>%
mdro() %>%
freq() # show frequency table of the result
```
```{r, echo = FALSE, results = 'asis', message = FALSE, warning = FALSE}
example_isolates %>%
mdro(info = FALSE) %>%
freq() # show frequency table of the result
```
For another example, I will create a data set to determine multi-drug resistant TB:
```{r}
# random_sir() is a helper function to generate
# a random vector with values S, I and R
my_TB_data <- data.frame(
rifampicin = random_sir(5000),
isoniazid = random_sir(5000),
gatifloxacin = random_sir(5000),
ethambutol = random_sir(5000),
pyrazinamide = random_sir(5000),
moxifloxacin = random_sir(5000),
kanamycin = random_sir(5000)
)
```
Because all column names are automatically verified for valid drug names or codes, this would have worked exactly the same way:
```{r, eval = FALSE}
my_TB_data <- data.frame(
RIF = random_sir(5000),
INH = random_sir(5000),
GAT = random_sir(5000),
ETH = random_sir(5000),
PZA = random_sir(5000),
MFX = random_sir(5000),
KAN = random_sir(5000)
)
```
The data set now looks like this:
```{r}
head(my_TB_data)
```
We can now add the interpretation of MDR-TB to our data set. You can use:
```r
mdro(my_TB_data, guideline = "TB")
```
or its shortcut `mdr_tb()`:
```{r}
my_TB_data$mdr <- mdr_tb(my_TB_data)
```
Create a frequency table of the results:
```{r, results = 'asis'}
freq(my_TB_data$mdr)
```
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/PCA.Rmd':
---
title: "How to conduct principal component analysis (PCA) for AMR"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{How to conduct principal component analysis (PCA) for AMR}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 4.5,
dpi = 100
)
```
**NOTE: This page will be updated soon, as the pca() function is currently being developed.**
# Introduction
# Transforming
For PCA, we need to transform our AMR data first. This is what the `example_isolates` data set in this package looks like:
```{r, message = FALSE}
library(AMR)
library(dplyr)
glimpse(example_isolates)
```
Now to transform this to a data set with only resistance percentages per taxonomic order and genus:
```{r, warning = FALSE}
resistance_data <- example_isolates %>%
group_by(
order = mo_order(mo), # group on anything, like order
genus = mo_genus(mo)
) %>% # and genus as we do here
summarise_if(is.sir, resistance) %>% # then get resistance of all drugs
select(
order, genus, AMC, CXM, CTX,
CAZ, GEN, TOB, TMP, SXT
) # and select only relevant columns
head(resistance_data)
```
# Perform principal component analysis
The new `pca()` function will automatically filter on rows that contain numeric values in all selected variables, so we now only need to do:
```{r pca}
pca_result <- pca(resistance_data)
```
The result can be reviewed with the good old `summary()` function:
```{r}
summary(pca_result)
```
```{r, echo = FALSE}
proportion_of_variance <- summary(pca_result)$importance[2, ]
```
Good news. The first two components explain a total of `r cleaner::percentage(sum(proportion_of_variance[1:2]))` of the variance (see the PC1 and PC2 values of the *Proportion of Variance*. We can create a so-called biplot with the base R `biplot()` function, to see which antimicrobial resistance per drug explain the difference per microorganism.
# Plotting the results
```{r}
biplot(pca_result)
```
But we can't see the explanation of the points. Perhaps this works better with our new `ggplot_pca()` function, that automatically adds the right labels and even groups:
```{r}
ggplot_pca(pca_result)
```
You can also print an ellipse per group, and edit the appearance:
```{r}
ggplot_pca(pca_result, ellipse = TRUE) +
ggplot2::labs(title = "An AMR/PCA biplot!")
```
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/WHONET.Rmd':
---
title: "How to work with WHONET data"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{How to work with WHONET data}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 4.5
)
```
### Import of data
This tutorial assumes you already imported the WHONET data with e.g. the [`readxl` package](https://readxl.tidyverse.org/). In RStudio, this can be done using the menu button 'Import Dataset' in the tab 'Environment'. Choose the option 'From Excel' and select your exported file. Make sure date fields are imported correctly.
An example syntax could look like this:
```{r, eval = FALSE}
library(readxl)
data <- read_excel(path = "path/to/your/file.xlsx")
```
This package comes with an [example data set `WHONET`](https://msberends.github.io/AMR/reference/WHONET.html). We will use it for this analysis.
### Preparation
First, load the relevant packages if you did not yet did this. I use the tidyverse for all of my analyses. All of them. If you don't know it yet, I suggest you read about it on their website: https://www.tidyverse.org/.
```{r, message = FALSE}
library(dplyr) # part of tidyverse
library(ggplot2) # part of tidyverse
library(AMR) # this package
library(cleaner) # to create frequency tables
```
We will have to transform some variables to simplify and automate the analysis:
* Microorganisms should be transformed to our own microorganism codes (called an `mo`) using [our Catalogue of Life reference data set](https://msberends.github.io/AMR/reference/catalogue_of_life), which contains all ~70,000 microorganisms from the taxonomic kingdoms Bacteria, Fungi and Protozoa. We do the tranformation with `as.mo()`. This function also recognises almost all WHONET abbreviations of microorganisms.
* Antimicrobial results or interpretations have to be clean and valid. In other words, they should only contain values `"S"`, `"I"` or `"R"`. That is exactly where the `as.sir()` function is for.
```{r}
# transform variables
data <- WHONET %>%
# get microbial ID based on given organism
mutate(mo = as.mo(Organism)) %>%
# transform everything from "AMP_ND10" to "CIP_EE" to the new `sir` class
mutate_at(vars(AMP_ND10:CIP_EE), as.sir)
```
No errors or warnings, so all values are transformed succesfully.
We also created a package dedicated to data cleaning and checking, called the `cleaner` package. Its `freq()` function can be used to create frequency tables.
So let's check our data, with a couple of frequency tables:
```{r, results = 'asis'}
# our newly created `mo` variable, put in the mo_name() function
data %>% freq(mo_name(mo), nmax = 10)
```
```{r, results = 'asis'}
# our transformed antibiotic columns
# amoxicillin/clavulanic acid (J01CR02) as an example
data %>% freq(AMC_ND2)
```
### A first glimpse at results
An easy `ggplot` will already give a lot of information, using the included `ggplot_sir()` function:
```{r, eval = FALSE}
data %>%
group_by(Country) %>%
select(Country, AMP_ND2, AMC_ED20, CAZ_ED10, CIP_ED5) %>%
ggplot_sir(translate_ab = "ab", facet = "Country", datalabels = FALSE)
```
```{r, echo = FALSE}
# on very old and some new releases of R, this may lead to an error
tryCatch(
data %>%
group_by(Country) %>%
select(Country, AMP_ND2, AMC_ED20, CAZ_ED10, CIP_ED5) %>%
ggplot_sir(translate_ab = "ab", facet = "Country", datalabels = FALSE) %>%
print(),
error = function(e) base::invisible()
)
```
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/datasets.Rmd':
---
title: "Data sets for download / own use"
date: '`r format(Sys.Date(), "%d %B %Y")`'
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 1
vignette: >
%\VignetteIndexEntry{Data sets for download / own use}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = "markup"}
knitr::opts_chunk$set(
warning = FALSE,
collapse = TRUE,
comment = "#",
fig.width = 7.5,
fig.height = 5
)
library(AMR)
library(dplyr)
options(knitr.kable.NA = "")
structure_txt <- function(dataset) {
paste0(
"A data set with ",
format(nrow(dataset), big.mark = " "), " rows and ",
ncol(dataset), " columns, containing the following column names: \n",
AMR:::vector_or(colnames(dataset), quotes = "*", last_sep = " and ", sort = FALSE), "."
)
}
download_txt <- function(filename) {
msg <- paste0(
"It was last updated on ",
trimws(format(file.mtime(paste0("../data/", filename, ".rda")), "%e %B %Y %H:%M:%S %Z", tz = "UTC")),
". Find more info about the structure of this data set [here](https://msberends.github.io/AMR/reference/", ifelse(filename == "antivirals", "antibiotics", filename), ".html).\n"
)
github_base <- "https://github.com/msberends/AMR/raw/main/data-raw/"
filename <- paste0("../data-raw/", filename)
rds <- paste0(filename, ".rds")
txt <- paste0(filename, ".txt")
excel <- paste0(filename, ".xlsx")
feather <- paste0(filename, ".feather")
parquet <- paste0(filename, ".parquet")
xpt <- paste0(filename, ".xpt")
spss <- paste0(filename, ".sav")
stata <- paste0(filename, ".dta")
create_txt <- function(filename, type, software, exists) {
if (isTRUE(exists)) {
paste0(
"* Download as [", software, "](", github_base, filename, ") (",
AMR:::formatted_filesize(filename), ") \n"
)
} else {
paste0("* *(unavailable as ", software, ")*\n")
}
}
if (any(
file.exists(rds),
file.exists(txt),
file.exists(excel),
file.exists(feather),
file.exists(parquet),
file.exists(xpt),
file.exists(spss),
file.exists(stata)
)) {
msg <- c(
msg, "\n**Direct download links:**\n\n",
create_txt(rds, "rds", "original R Data Structure (RDS) file", file.exists(rds)),
create_txt(txt, "txt", "tab-separated text file", file.exists(txt)),
create_txt(excel, "xlsx", "Microsoft Excel workbook", file.exists(excel)),
create_txt(feather, "feather", "Apache Feather file", file.exists(feather)),
create_txt(parquet, "parquet", "Apache Parquet file", file.exists(parquet)),
# create_txt(xpt, "xpt", "SAS transport (XPT) file", file.exists(xpt)),
create_txt(spss, "sav", "IBM SPSS Statistics data file", file.exists(spss)),
create_txt(stata, "dta", "Stata DTA file", file.exists(stata))
)
}
paste0(msg, collapse = "")
}
print_df <- function(x, rows = 6) {
x %>%
as.data.frame(stringsAsFactors = FALSE) %>%
head(n = rows) %>%
mutate_all(function(x) {
if (is.list(x)) {
sapply(x, function(y) {
if (length(y) > 3) {
paste0(paste(y[1:3], collapse = ", "), ", ...")
} else if (length(y) == 0 || all(is.na(y))) {
""
} else {
paste(y, collapse = ", ")
}
})
} else {
x
}
}) %>%
knitr::kable(align = "c")
}
```
All reference data (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) in this `AMR` package are reliable, up-to-date and freely available. We continually export our data sets to formats for use in R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated text files that are machine-readable and suitable for input in any software program, such as laboratory information systems.
On this page, we explain how to download them and how the structure of the data sets look like.
## `microorganisms`: Full Microbial Taxonomy
`r structure_txt(microorganisms)`
This data set is in R available as `microorganisms`, after you load the `AMR` package.
`r download_txt("microorganisms")`
**NOTE: The exported files for SPSS and Stata contain only the first 50 SNOMED codes per record, as their file size would otherwise exceed 100 MB; the file size limit of GitHub.** Their file structures and compression techniques are very inefficient. Advice? Use R instead. It's free and much better in many ways.
The tab-separated text file and Microsoft Excel workbook both contain all SNOMED codes as comma separated values.
### Source
This data set contains the full microbial taxonomy of `r AMR:::nr2char(length(unique(AMR::microorganisms$kingdom[!AMR::microorganisms$kingdom %like% "unknown"])))` kingdoms from the `r AMR:::TAXONOMY_VERSION$LPSN$name`, `r AMR:::TAXONOMY_VERSION$MycoBank$name`, and the `r AMR:::TAXONOMY_VERSION$GBIF$name`:
* `r AMR:::TAXONOMY_VERSION$LPSN$citation` Accessed from <`r AMR:::TAXONOMY_VERSION$LPSN$url`> on `r AMR:::documentation_date(AMR:::TAXONOMY_VERSION$LPSN$accessed_date)`.
* `r AMR:::TAXONOMY_VERSION$MycoBank$citation` Accessed from <`r AMR:::TAXONOMY_VERSION$MycoBank$url`> on `r AMR:::documentation_date(AMR:::TAXONOMY_VERSION$MycoBank$accessed_date)`.
* `r AMR:::TAXONOMY_VERSION$GBIF$citation` Accessed from <`r AMR:::TAXONOMY_VERSION$GBIF$url`> on `r AMR:::documentation_date(AMR:::TAXONOMY_VERSION$GBIF$accessed_date)`.
* `r AMR:::TAXONOMY_VERSION$BacDive$citation` Accessed from <`r AMR:::TAXONOMY_VERSION$BacDive$url`> on `r AMR:::documentation_date(AMR:::TAXONOMY_VERSION$BacDive$accessed_date)`.
* `r AMR:::TAXONOMY_VERSION$SNOMED$citation` URL: <`r AMR:::TAXONOMY_VERSION$SNOMED$url`>
### Example content
Included (sub)species per taxonomic kingdom:
```{r, echo = FALSE}
microorganisms %>%
count(kingdom) %>%
mutate(n = format(n, big.mark = " ")) %>%
setNames(c("Kingdom", "Number of (sub)species")) %>%
print_df()
```
Example rows when filtering on genus *Escherichia*:
```{r, echo = FALSE}
microorganisms %>%
filter(genus == "Escherichia") %>%
print_df()
```
## `antibiotics`: Antibiotic (+Antifungal) Drugs
`r structure_txt(antibiotics)`
This data set is in R available as `antibiotics`, after you load the `AMR` package.
`r download_txt("antibiotics")`
The tab-separated text, Microsoft Excel, SPSS, and Stata files all contain the ATC codes, common abbreviations, trade names and LOINC codes as comma separated values.
### Source
This data set contains all EARS-Net and ATC codes gathered from WHO and WHONET, and all compound IDs from PubChem. It also contains all brand names (synonyms) as found on PubChem and Defined Daily Doses (DDDs) for oral and parenteral administration.
* [ATC/DDD index from WHO Collaborating Centre for Drug Statistics Methodology](https://atcddd.fhi.no/atc_ddd_index/) (note: this may not be used for commercial purposes, but is freely available from the WHO CC website for personal use)
* [PubChem by the US National Library of Medicine](https://pubchem.ncbi.nlm.nih.gov)
* [WHONET software 2019](https://whonet.org)
* [LOINC (Logical Observation Identifiers Names and Codes)](https://loinc.org)
### Example content
```{r, echo = FALSE}
antibiotics %>%
filter(ab %in% colnames(example_isolates)) %>%
print_df()
```
## `antivirals`: Antiviral Drugs
`r structure_txt(antivirals)`
This data set is in R available as `antivirals`, after you load the `AMR` package.
`r download_txt("antivirals")`
The tab-separated text, Microsoft Excel, SPSS, and Stata files all contain the trade names and LOINC codes as comma separated values.
### Source
This data set contains all ATC codes gathered from WHO and all compound IDs from PubChem. It also contains all brand names (synonyms) as found on PubChem and Defined Daily Doses (DDDs) for oral and parenteral administration.
* [ATC/DDD index from WHO Collaborating Centre for Drug Statistics Methodology](https://atcddd.fhi.no/atc_ddd_index/) (note: this may not be used for commercial purposes, but is freely available from the WHO CC website for personal use)
* [PubChem by the US National Library of Medicine](https://pubchem.ncbi.nlm.nih.gov)
* [LOINC (Logical Observation Identifiers Names and Codes)](https://loinc.org)
### Example content
```{r, echo = FALSE}
antivirals %>%
print_df()
```
## `clinical_breakpoints`: Interpretation from MIC values & disk diameters to SIR
`r structure_txt(clinical_breakpoints)`
This data set is in R available as `clinical_breakpoints`, after you load the `AMR` package.
`r download_txt("clinical_breakpoints")`
### Source
This data set contains interpretation rules for MIC values and disk diffusion diameters. Included guidelines are CLSI (`r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "CLSI")$guideline)))`) and EUCAST (`r min(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`-`r max(as.integer(gsub("[^0-9]", "", subset(clinical_breakpoints, guideline %like% "EUCAST")$guideline)))`).
Clinical breakpoints in this package were validated through and imported from [WHONET](https://whonet.org), a free desktop Windows application developed and supported by the WHO Collaborating Centre for Surveillance of Antimicrobial Resistance. More can be read on [their website](https://whonet.org). The developers of WHONET and this `AMR` package have been in contact about sharing their work. We highly appreciate their development on the WHONET software.
The CEO of CLSI and the chairman of EUCAST have endorsed the work and public use of this `AMR` package (and consequently the use of their breakpoints) in June 2023, when future development of distributing clinical breakpoints was discussed in a meeting between CLSI, EUCAST, the WHO, and developers of WHONET and the `AMR` package.
**NOTE:** this `AMR` package (and the WHONET software as well) contains internal methods to apply the guidelines, which is rather complex. For example, some breakpoints must be applied on certain species groups (which are in case of this package available through the `microorganisms.groups` data set). It is important that this is considered when using the breakpoints for own use.
### Example content
```{r, echo = FALSE}
clinical_breakpoints %>%
mutate(mo_name = mo_name(mo, language = NULL), .after = mo) %>%
mutate(ab_name = ab_name(ab, language = NULL), .after = ab) %>%
print_df()
```
## `intrinsic_resistant`: Intrinsic Bacterial Resistance
`r structure_txt(intrinsic_resistant)`
This data set is in R available as `intrinsic_resistant`, after you load the `AMR` package.
`r download_txt("intrinsic_resistant")`
### Source
This data set contains all defined intrinsic resistance by EUCAST of all bug-drug combinations, and is based on `r AMR:::format_eucast_version_nr("3.3")`.
### Example content
Example rows when filtering on *Enterobacter cloacae*:
```{r, echo = FALSE}
intrinsic_resistant %>%
transmute(
microorganism = mo_name(mo),
antibiotic = ab_name(ab)
) %>%
filter(microorganism == "Enterobacter cloacae") %>%
arrange(antibiotic) %>%
print_df(rows = Inf)
```
## `dosage`: Dosage Guidelines from EUCAST
`r structure_txt(dosage)`
This data set is in R available as `dosage`, after you load the `AMR` package.
`r download_txt("dosage")`
### Source
EUCAST breakpoints used in this package are based on the dosages in this data set.
Currently included dosages in the data set are meant for: `r AMR:::format_eucast_version_nr(unique(dosage$eucast_version))`.
### Example content
```{r, echo = FALSE}
dosage %>%
print_df()
```
## `example_isolates`: Example Data for Practice
`r structure_txt(example_isolates)`
This data set is in R available as `example_isolates`, after you load the `AMR` package.
`r download_txt("example_isolates")`
### Source
This data set contains randomised fictitious data, but reflects reality and can be used to practise AMR data analysis.
### Example content
```{r, echo = FALSE}
example_isolates %>%
print_df()
```
## `example_isolates_unclean`: Example Data for Practice
`r structure_txt(example_isolates_unclean)`
This data set is in R available as `example_isolates_unclean`, after you load the `AMR` package.
`r download_txt("example_isolates_unclean")`
### Source
This data set contains randomised fictitious data, but reflects reality and can be used to practise AMR data analysis.
### Example content
```{r, echo = FALSE}
example_isolates_unclean %>%
print_df()
```
## `microorganisms.groups`: Species Groups and Microbiological Complexes
`r structure_txt(microorganisms.groups)`
This data set is in R available as `microorganisms.groups`, after you load the `AMR` package.
`r download_txt("microorganisms.groups")`
### Source
This data set contains species groups and microbiological complexes, which are used in the `clinical_breakpoints` data set.
### Example content
```{r, echo = FALSE}
microorganisms.groups %>%
print_df()
```
## `microorganisms.codes`: Common Laboratory Codes
`r structure_txt(microorganisms.codes)`
This data set is in R available as `microorganisms.codes`, after you load the `AMR` package.
`r download_txt("microorganisms.codes")`
### Source
This data set contains commonly used codes for microorganisms, from laboratory systems and [WHONET](https://whonet.org).
### Example content
```{r, echo = FALSE}
microorganisms.codes %>%
print_df()
```
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/resistance_predict.Rmd':
---
title: "How to predict antimicrobial resistance"
output:
rmarkdown::html_vignette:
toc: true
vignette: >
%\VignetteIndexEntry{How to predict antimicrobial resistance}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 4.75
)
```
## Needed R packages
As with many uses in R, we need some additional packages for AMR data analysis. Our package works closely together with the [tidyverse packages](https://www.tidyverse.org) [`dplyr`](https://dplyr.tidyverse.org/) and [`ggplot2`](https://ggplot2.tidyverse.org). The tidyverse tremendously improves the way we conduct data science - it allows for a very natural way of writing syntaxes and creating beautiful plots in R.
Our `AMR` package depends on these packages and even extends their use and functions.
```{r lib packages, message = FALSE}
library(dplyr)
library(ggplot2)
library(AMR)
# (if not yet installed, install with:)
# install.packages(c("tidyverse", "AMR"))
```
## Prediction analysis
Our package contains a function `resistance_predict()`, which takes the same input as functions for [other AMR data analysis](./AMR.html). Based on a date column, it calculates cases per year and uses a regression model to predict antimicrobial resistance.
It is basically as easy as:
```{r, eval = FALSE}
# resistance prediction of piperacillin/tazobactam (TZP):
resistance_predict(tbl = example_isolates, col_date = "date", col_ab = "TZP", model = "binomial")
# or:
example_isolates %>%
resistance_predict(
col_ab = "TZP",
model = "binomial"
)
# to bind it to object 'predict_TZP' for example:
predict_TZP <- example_isolates %>%
resistance_predict(
col_ab = "TZP",
model = "binomial"
)
```
The function will look for a date column itself if `col_date` is not set.
When running any of these commands, a summary of the regression model will be printed unless using `resistance_predict(..., info = FALSE)`.
```{r, echo = FALSE, message = FALSE}
predict_TZP <- example_isolates %>%
resistance_predict(col_ab = "TZP", model = "binomial")
```
This text is only a printed summary - the actual result (output) of the function is a `data.frame` containing for each year: the number of observations, the actual observed resistance, the estimated resistance and the standard error below and above the estimation:
```{r}
predict_TZP
```
The function `plot` is available in base R, and can be extended by other packages to depend the output based on the type of input. We extended its function to cope with resistance predictions:
```{r, fig.height = 5.5}
plot(predict_TZP)
```
This is the fastest way to plot the result. It automatically adds the right axes, error bars, titles, number of available observations and type of model.
We also support the `ggplot2` package with our custom function `ggplot_sir_predict()` to create more appealing plots:
```{r}
ggplot_sir_predict(predict_TZP)
# choose for error bars instead of a ribbon
ggplot_sir_predict(predict_TZP, ribbon = FALSE)
```
### Choosing the right model
Resistance is not easily predicted; if we look at vancomycin resistance in Gram-positive bacteria, the spread (i.e. standard error) is enormous:
```{r}
example_isolates %>%
filter(mo_gramstain(mo, language = NULL) == "Gram-positive") %>%
resistance_predict(col_ab = "VAN", year_min = 2010, info = FALSE, model = "binomial") %>%
ggplot_sir_predict()
```
Vancomycin resistance could be 100% in ten years, but might remain very low.
You can define the model with the `model` parameter. The model chosen above is a generalised linear regression model using a binomial distribution, assuming that a period of zero resistance was followed by a period of increasing resistance leading slowly to more and more resistance.
Valid values are:
| Input values | Function used by R | Type of model |
|----------------------------------------|-------------------------------|-----------------------------------------------------|
| `"binomial"` or `"binom"` or `"logit"` | `glm(..., family = binomial)` | Generalised linear model with binomial distribution |
| `"loglin"` or `"poisson"` | `glm(..., family = poisson)` | Generalised linear model with poisson distribution |
| `"lin"` or `"linear"` | `lm()` | Linear model |
For the vancomycin resistance in Gram-positive bacteria, a linear model might be more appropriate:
```{r}
example_isolates %>%
filter(mo_gramstain(mo, language = NULL) == "Gram-positive") %>%
resistance_predict(col_ab = "VAN", year_min = 2010, info = FALSE, model = "linear") %>%
ggplot_sir_predict()
```
The model itself is also available from the object, as an `attribute`:
```{r}
model <- attributes(predict_TZP)$model
summary(model)$family
summary(model)$coefficients
```
THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'vignettes/welcome_to_AMR.Rmd':
---
title: "Welcome to the `AMR` package"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{Welcome to the `AMR` package}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
warning = FALSE,
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 5
)
```
Note: to keep the package size as small as possible, we only include this vignette on CRAN. You can read more vignettes on our website about how to conduct AMR data analysis, determine MDROs, find explanation of EUCAST and CLSI breakpoints, and much more: <https://msberends.github.io/AMR/articles/>.
----
The `AMR` package is a [free and open-source](https://msberends.github.io/AMR/#copyright) R package with [zero dependencies](https://en.wikipedia.org/wiki/Dependency_hell) to simplify the analysis and prediction of Antimicrobial Resistance (AMR) and to work with microbial and antimicrobial data and properties, by using evidence-based methods. **Our aim is to provide a standard** for clean and reproducible AMR data analysis, that can therefore empower epidemiological analyses to continuously enable surveillance and treatment evaluation in any setting. [Many different researchers](https://msberends.github.io/AMR/authors.html) from around the globe are continually helping us to make this a successful and durable project!
This work was published in the Journal of Statistical Software (Volume 104(3); [DOI 10.18637/jss.v104.i03](https://doi.org/10.18637/jss.v104.i03)) and formed the basis of two PhD theses ([DOI 10.33612/diss.177417131](https://doi.org/10.33612/diss.177417131) and [DOI 10.33612/diss.192486375](https://doi.org/10.33612/diss.192486375)).
After installing this package, R knows `r AMR:::format_included_data_number(AMR::microorganisms)` distinct microbial species and all `r AMR:::format_included_data_number(rbind(AMR::antibiotics[, "atc", drop = FALSE], AMR::antivirals[, "atc", drop = FALSE]))` antibiotic, antimycotic and antiviral drugs by name and code (including ATC, EARS-Net, ASIARS-Net, PubChem, LOINC and SNOMED CT), and knows all about valid SIR and MIC values. The integral breakpoint guidelines from CLSI and EUCAST are included from the last 10 years. It supports and can read any data format, including WHONET data.
With the help of contributors from all corners of the world, the `AMR` package is available in English, Czech, Chinese, Danish, Dutch, Finnish, French, German, Greek, Italian, Japanese, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Turkish, and Ukrainian. Antimicrobial drug (group) names and colloquial microorganism names are provided in these languages.
This package is fully independent of any other R package and works on Windows, macOS and Linux with all versions of R since R-3.0 (April 2013). **It was designed to work in any setting, including those with very limited resources**. Since its first public release in early 2018, this package has been downloaded from more than 175 countries.
This package can be used for:
* Reference for the taxonomy of microorganisms, since the package contains all microbial (sub)species from the List of Prokaryotic names with Standing in Nomenclature (LPSN) and the Global Biodiversity Information Facility (GBIF)
* Interpreting raw MIC and disk diffusion values, based on the latest CLSI or EUCAST guidelines
* Retrieving antimicrobial drug names, doses and forms of administration from clinical health care records
* Determining first isolates to be used for AMR data analysis
* Calculating antimicrobial resistance
* Determining multi-drug resistance (MDR) / multi-drug resistant organisms (MDRO)
* Calculating (empirical) susceptibility of both mono therapy and combination therapies
* Predicting future antimicrobial resistance using regression models
* Getting properties for any microorganism (like Gram stain, species, genus or family)
* Getting properties for any antibiotic (like name, code of EARS-Net/ATC/LOINC/PubChem, defined daily dose or trade name)
* Plotting antimicrobial resistance
* Applying EUCAST expert rules
* Getting SNOMED codes of a microorganism, or getting properties of a microorganism based on a SNOMED code
* Getting LOINC codes of an antibiotic, or getting properties of an antibiotic based on a LOINC code
* Machine reading the EUCAST and CLSI guidelines from 2011-2020 to translate MIC values and disk diffusion diameters to SIR
* Principal component analysis for AMR
All reference data sets (about microorganisms, antibiotics, SIR interpretation, EUCAST rules, etc.) in this `AMR` package are publicly and freely available. We continually export our data sets to formats for use in R, SPSS, Stata and Excel. We also supply flat files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please find [all download links on our website](https://msberends.github.io/AMR/articles/datasets.html), which is automatically updated with every code change.
This R package was created for both routine data analysis and academic research at the Faculty of Medical Sciences of the [University of Groningen](https://www.rug.nl), in collaboration with non-profit organisations [Certe Medical Diagnostics and Advice Foundation](https://www.certe.nl) and [University Medical Center Groningen](https://www.umcg.nl), and is being [actively and durably maintained](https://msberends.github.io/AMR/news/) by two public healthcare organisations in the Netherlands.
----
<small>
This AMR package for R is free, open-source software and licensed under the [GNU General Public License v2.0 (GPL-2)](https://msberends.github.io/AMR/LICENSE-text.html). These requirements are consequently legally binding: modifications must be released under the same license when distributing the package, changes made to the code must be documented, source code must be made available when the package is distributed, and a copy of the license and copyright notice must be included with the package.
</small>
THE PART HEREAFTER CONTAINS THE README OF OUR PYTHON PACKAGE
---
title: "AMR for Python"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{AMR for Python}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r setup, include = FALSE, results = 'markup'}
knitr::opts_chunk$set(
warning = FALSE,
collapse = TRUE,
comment = "#>",
fig.width = 7.5,
fig.height = 5
)
```
# Introduction
The `AMR` package for R is a powerful tool for antimicrobial resistance (AMR) analysis. It provides extensive features for handling microbial and antimicrobial data. However, for those who work primarily in Python, we now have a more intuitive option available: the [`AMR` Python Package Index](https://pypi.org/project/AMR/).
This Python package is a wrapper round the `AMR` R package. It uses the `rpy2` package internally. Despite the need to have R installed, Python users can now easily work with AMR data directly through Python code.
# Install
1. Since the Python package is available on the official [Python Package Index](https://pypi.org/project/AMR/), you can just run:
```bash
pip install AMR
```
2. Make sure you have R installed. There is **no need to install the `AMR` R package**, as it will be installed automatically.
For Linux:
```bash
# Ubuntu / Debian
sudo apt install r-base
# Fedora:
sudo dnf install R
# CentOS/RHEL
sudo yum install R
```
For macOS (using [Homebrew](https://brew.sh)):
```bash
brew install r
```
For Windows, visit the [CRAN download page](https://cran.r-project.org) to download and install R.
# Examples of Usage
## Cleaning Taxonomy
Here’s an example that demonstrates how to clean microorganism and drug names using the `AMR` Python package:
```python
import pandas as pd
import AMR
# Sample data
data = {
"MOs": ['E. coli', 'ESCCOL', 'esco', 'Esche coli'],
"Drug": ['Cipro', 'CIP', 'J01MA02', 'Ciproxin']
}
df = pd.DataFrame(data)
# Use AMR functions to clean microorganism and drug names
df['MO_clean'] = AMR.mo_name(df['MOs'])
df['Drug_clean'] = AMR.ab_name(df['Drug'])
# Display the results
print(df)
```
| MOs | Drug | MO_clean | Drug_clean |
|-------------|-----------|--------------------|---------------|
| E. coli | Cipro | Escherichia coli | Ciprofloxacin |
| ESCCOL | CIP | Escherichia coli | Ciprofloxacin |
| esco | J01MA02 | Escherichia coli | Ciprofloxacin |
| Esche coli | Ciproxin | Escherichia coli | Ciprofloxacin |
### Explanation
* **mo_name:** This function standardises microorganism names. Here, different variations of *Escherichia coli* (such as "E. coli", "ESCCOL", "esco", and "Esche coli") are all converted into the correct, standardised form, "Escherichia coli".
* **ab_name**: Similarly, this function standardises antimicrobial names. The different representations of ciprofloxacin (e.g., "Cipro", "CIP", "J01MA02", and "Ciproxin") are all converted to the standard name, "Ciprofloxacin".
## Taxonomic Data Sets Now in Python!
As a Python user, you might like that the most important data sets of the `AMR` R package, `microorganisms`, `antibiotics`, `clinical_breakpoints`, and `example_isolates`, are now available as regular Python data frames:
```python
AMR.microorganisms
```
| mo | fullname | status | kingdom | gbif | gbif_parent | gbif_renamed_to | prevalence |
|--------------|------------------------------------|----------|----------|-----------|-------------|-----------------|------------|
| B_GRAMN | (unknown Gram-negatives) | unknown | Bacteria | None | None | None | 2.0 |
| B_GRAMP | (unknown Gram-positives) | unknown | Bacteria | None | None | None | 2.0 |
| B_ANAER-NEG | (unknown anaerobic Gram-negatives) | unknown | Bacteria | None | None | None | 2.0 |
| B_ANAER-POS | (unknown anaerobic Gram-positives) | unknown | Bacteria | None | None | None | 2.0 |
| B_ANAER | (unknown anaerobic bacteria) | unknown | Bacteria | None | None | None | 2.0 |
| ... | ... | ... | ... | ... | ... | ... | ... |
| B_ZYMMN_POMC | Zymomonas pomaceae | accepted | Bacteria | 10744418 | 3221412 | None | 2.0 |
| B_ZYMPH | Zymophilus | synonym | Bacteria | None | 9475166 | None | 2.0 |
| B_ZYMPH_PCVR | Zymophilus paucivorans | synonym | Bacteria | None | None | None | 2.0 |
| B_ZYMPH_RFFN | Zymophilus raffinosivorans | synonym | Bacteria | None | None | None | 2.0 |
| F_ZYZYG | Zyzygomyces | unknown | Fungi | None | 7581 | None | 2.0 |
```python
AMR.antibiotics
```
| ab | cid | name | group | oral_ddd | oral_units | iv_ddd | iv_units |
|-----|-------------|----------------------|----------------------------|----------|------------|--------|----------|
| AMA | 4649.0 | 4-aminosalicylic acid| Antimycobacterials | 12.00 | g | NaN | None |
| ACM | 6450012.0 | Acetylmidecamycin | Macrolides/lincosamides | NaN | None | NaN | None |
| ASP | 49787020.0 | Acetylspiramycin | Macrolides/lincosamides | NaN | None | NaN | None |
| ALS | 8954.0 | Aldesulfone sodium | Other antibacterials | 0.33 | g | NaN | None |
| AMK | 37768.0 | Amikacin | Aminoglycosides | NaN | None | 1.0 | g |
| ... | ... | ... | ... | ... | ... | ... | ... |
| VIR | 11979535.0 | Virginiamycine | Other antibacterials | NaN | None | NaN | None |
| VOR | 71616.0 | Voriconazole | Antifungals/antimycotics | 0.40 | g | 0.4 | g |
| XBR | 72144.0 | Xibornol | Other antibacterials | NaN | None | NaN | None |
| ZID | 77846445.0 | Zidebactam | Other antibacterials | NaN | None | NaN | None |
| ZFD | NaN | Zoliflodacin | None | NaN | None | NaN | None |
## Calculating AMR
```python
import AMR
import pandas as pd
df = AMR.example_isolates
result = AMR.resistance(df["AMX"])
print(result)
```
```
[0.59555556]
```
## Generating Antibiograms
One of the core functions of the `AMR` package is generating an antibiogram, a table that summarises the antimicrobial susceptibility of bacterial isolates. Here’s how you can generate an antibiogram from Python:
```python
result2a = AMR.antibiogram(df[["mo", "AMX", "CIP", "TZP"]])
print(result2a)
```
| Pathogen | Amoxicillin | Ciprofloxacin | Piperacillin/tazobactam |
|-----------------|-----------------|-----------------|--------------------------|
| CoNS | 7% (10/142) | 73% (183/252) | 30% (10/33) |
| E. coli | 50% (196/392) | 88% (399/456) | 94% (393/416) |
| K. pneumoniae | 0% (0/58) | 96% (53/55) | 89% (47/53) |
| P. aeruginosa | 0% (0/30) | 100% (30/30) | None |
| P. mirabilis | None | 94% (34/36) | None |
| S. aureus | 6% (8/131) | 90% (171/191) | None |
| S. epidermidis | 1% (1/91) | 64% (87/136) | None |
| S. hominis | None | 80% (56/70) | None |
| S. pneumoniae | 100% (112/112) | None | 100% (112/112) |
```python
result2b = AMR.antibiogram(df[["mo", "AMX", "CIP", "TZP"]], mo_transform = "gramstain")
print(result2b)
```
| Pathogen | Amoxicillin | Ciprofloxacin | Piperacillin/tazobactam |
|----------------|-----------------|------------------|--------------------------|
| Gram-negative | 36% (226/631) | 91% (621/684) | 88% (565/641) |
| Gram-positive | 43% (305/703) | 77% (560/724) | 86% (296/345) |
In this example, we generate an antibiogram by selecting various antibiotics.
# Conclusion
With the `AMR` Python package, Python users can now effortlessly call R functions from the `AMR` R package. This eliminates the need for complex `rpy2` configurations and provides a clean, easy-to-use interface for antimicrobial resistance analysis. The examples provided above demonstrate how this can be applied to typical workflows, such as standardising microorganism and antimicrobial names or calculating resistance.
By just running `import AMR`, users can seamlessly integrate the robust features of the R `AMR` package into Python workflows.
Whether you're cleaning data or analysing resistance patterns, the `AMR` Python package makes it easy to work with AMR data in Python.
View Git Blame Copy Permalink