AMR/index.md

310 lines
20 KiB
Markdown
Raw Normal View History

2022-08-21 16:37:20 +02:00
# The `AMR` Package for R <a href="https://msberends.github.io/AMR/"><img src="./logo.svg" align="right" height="139" /></a>
2018-12-29 22:24:19 +01:00
2024-06-04 20:17:54 +02:00
<img src="./endorsement_clsi_eucast.jpg" align="right" height="120" />
2024-02-25 14:20:43 +01:00
* Provides an **all-in-one solution** for AMR data analysis in a One Health approach
* Generates **antibiograms** - traditional, combined, syndromic, and even WISCA
2024-06-04 20:17:54 +02:00
* Provides the **full microbiological taxonomy** and extensive info on **all antimicrobial drugs**
* Applies all recent **CLSI and EUCAST clinical and veterinary breakpoints** for MICs and disk zones
2022-11-13 13:44:25 +01:00
* Corrects for duplicate isolates, **calculates and predicts AMR** per antibiotic class
2024-06-04 20:17:54 +02:00
* Integrates with **WHONET**, ATC, **EARS-Net**, PubChem, **LOINC**, **SNOMED CT**, and **NCBI**
2022-12-21 09:12:53 +01:00
* Works on Windows, macOS and Linux with **all versions of R** since R-3.0 and is completely **dependency-free**, highly suitable for places with **limited resources**
2022-11-13 13:44:25 +01:00
2023-02-18 11:57:17 +01:00
<div style="display: flex; font-size: 0.8em;">
2022-11-13 13:44:25 +01:00
<p style="text-align:left; width: 50%;"><small><a href="https://msberends.github.io/AMR/">https://msberends.github.io/AMR</a></small></p>
2024-06-04 20:17:54 +02:00
<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>
2022-11-13 13:44:25 +01:00
</div>
----
2022-08-21 16:37:20 +02:00
### Introduction
2018-12-29 22:24:19 +01:00
2023-01-14 17:10:10 +01:00
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!
2019-11-30 12:01:50 +01:00
2022-10-05 09:12:22 +02:00
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).
2019-11-30 12:01:50 +01:00
2023-02-11 21:57:12 +01:00
##### Used in over 175 countries, translated into 20 languages
2024-06-04 20:17:54 +02:00
<a href="./countries_large.png" target="_blank"><img src="./countries.png" align="right" style="max-width: 300px;" /></a>
2019-02-14 15:18:17 +01:00
2022-08-21 16:37:20 +02:00
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.
2019-08-09 23:22:10 +02:00
2023-02-12 11:20:14 +01:00
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.
2022-08-21 16:37:20 +02:00
### Practical examples
2019-08-09 23:22:10 +02:00
2022-08-21 16:37:20 +02:00
#### Filtering and selecting data
2020-12-08 12:37:25 +01:00
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`:
2020-12-08 12:37:25 +01:00
```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())
2020-12-08 12:37:25 +01:00
```
2020-12-13 13:44:04 +01:00
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:
2020-12-09 09:40:50 +01:00
2021-07-04 15:26:50 +02:00
|bacteria | GEN | TOB | AMK | KAN | IPM | MEM |
2021-01-24 23:27:11 +01:00
|:------------------------------|:---:|:---:|:---:|:---:|:---:|:---:|
2021-07-04 15:26:50 +02:00
|*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 |
2021-01-24 23:27:11 +01:00
|*Stenotrophomonas maltophilia* | R | R | R | R | R | R |
2021-07-04 15:26:50 +02:00
|*Pseudomonas aeruginosa* | S | S | S | R | | S |
|*Pseudomonas aeruginosa* | S | S | S | R | | S |
|*Pseudomonas aeruginosa* | S | S | S | R | S | S |
2020-12-08 12:37:25 +01:00
2022-08-21 16:37:20 +02:00
A base R equivalent would be:
```r
library(AMR)
2021-01-24 23:27:11 +01:00
example_isolates$bacteria <- mo_fullname(example_isolates$mo)
example_isolates[which(mo_is_gram_negative() &
mo_is_intrinsic_resistant(ab = "cefotax")),
2021-01-24 23:27:11 +01:00
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)
```
2019-08-09 23:22:10 +02:00
#### Generating antibiograms
The `AMR` package supports generating traditional, combined, syndromic, and even weighted-incidence syndromic combination antibiograms (WISCA).
2023-02-26 21:26:58 +01:00
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()))
```
2023-02-17 09:42:51 +01:00
|Pathogen (N min-max) | AMK| GEN| IPM| KAN| MEM| TOB|
|:------------------------|---:|---:|---:|---:|---:|---:|
|CoNS (43-309) | 0| 86| 52| 0| 52| 22|
|*E. coli* (0-462) | 100| 98| 100| | 100| 97|
|*E. faecalis* (0-39) | 0| 0| 100| 0| | 0|
|*K. pneumoniae* (0-58) | | 90| 100| | 100| 90|
|*P. aeruginosa* (17-30) | | 100| | 0| | 100|
|*P. mirabilis* (0-34) | | 94| 94| | | 94|
|*S. aureus* (2-233) | | 99| | | | 98|
|*S. epidermidis* (8-163) | 0| 79| | 0| | 51|
|*S. hominis* (3-80) | | 92| | | | 85|
|*S. pneumoniae* (11-117) | 0| 0| | 0| | 0|
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 (N min-max) | TZP| TZP + GEN| TZP + TOB|
|:------------------------|---:|---------:|---------:|
|Gram-negative (641-693) | 88| 99| 98|
|Gram-positive (345-1044) | 86| 98| 95|
2023-02-17 09:42:51 +01:00
Like many other functions in this package, `antibiogram()` comes with support for 20 languages that are often detected automatically based on system language:
2023-02-15 17:16:40 +01:00
```r
antibiogram(example_isolates,
antibiotics = c("cipro", "tobra", "genta"), # any arbitrary name or code will work
2023-02-15 17:16:40 +01:00
mo_transform = "gramstain",
ab_transform = "name",
language = "uk") # Ukrainian
```
|Збудник (N min-max) | Гентаміцин| Тобраміцин| Ципрофлоксацин|
|:------------------------|----------:|----------:|--------------:|
|Грамнегативні (684-686) | 96| 96| 91|
|Грампозитивні (665-1170) | 63| 34| 77|
2022-08-21 16:37:20 +02:00
#### Calculating resistance per group
2019-08-09 23:22:10 +02:00
2023-02-17 09:42:51 +01:00
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:
2022-08-21 16:37:20 +02:00
```r
library(AMR)
library(dplyr)
2019-08-09 23:22:10 +02:00
2022-08-21 16:37:20 +02:00
out <- example_isolates %>%
2022-08-27 20:49:37 +02:00
# group by ward:
group_by(ward) %>%
# calculate AMR using resistance(), over all aminoglycosides and polymyxins:
2022-08-21 16:37:20 +02:00
summarise(across(c(aminoglycosides(), polymyxins()),
resistance))
out
```
2019-01-26 23:22:56 +01:00
2022-08-27 20:49:37 +02:00
| 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 |
2023-02-17 09:42:51 +01:00
| Outpatient | 0.200 | 0.368 | 0.605 | | 0.889 |
2022-08-21 16:37:20 +02:00
```r
# transform the antibiotic columns to names:
out %>% set_ab_names()
```
2022-08-27 20:49:37 +02:00
| 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 |
2023-02-17 09:42:51 +01:00
| Outpatient | 0.200 | 0.368 | 0.605 | | 0.889 |
2022-08-21 16:37:20 +02:00
```r
# transform the antibiotic column to ATC codes:
out %>% set_ab_names(property = "atc")
```
2022-08-27 20:49:37 +02:00
| 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 |
2023-02-17 09:42:51 +01:00
| Outpatient | 0.200 | 0.368 | 0.605 | | 0.889 |
2022-08-21 16:37:20 +02:00
### 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:
2019-01-26 23:22:56 +01:00
2022-10-05 09:12:22 +02:00
* 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))
2019-05-23 16:58:59 +02:00
* 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))
2019-05-23 16:58:59 +02:00
* 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))
2019-05-23 16:58:59 +02:00
* Plotting antimicrobial resistance ([tutorial](./articles/AMR.html))
2019-05-23 18:53:18 +02:00
* 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))
2023-01-21 23:47:20 +01:00
* Machine reading the EUCAST and CLSI guidelines from 2011-2021 to translate MIC values and disk diffusion diameters to SIR ([link](./articles/datasets.html))
2020-03-14 14:05:43 +01:00
* Principal component analysis for AMR ([tutorial](./articles/PCA.html))
2018-12-29 22:24:19 +01:00
2019-08-09 23:22:10 +02:00
### Get this package
2018-12-29 22:24:19 +01:00
2022-08-21 16:37:20 +02:00
#### Latest official version
2019-01-30 19:52:58 +01:00
2021-06-03 15:19:21 +02:00
[![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)
2021-05-26 11:10:34 +02:00
2021-06-03 15:19:21 +02:00
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:
2021-06-01 15:33:06 +02:00
```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>.
2018-12-29 22:24:19 +01:00
2019-02-22 22:12:10 +01:00
**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.
2019-02-20 13:57:23 +01:00
2021-06-03 15:19:21 +02:00
#### Latest development version
2018-12-29 22:24:19 +01:00
2024-02-25 16:48:04 +01:00
[![check-recent](https://github.com/msberends/AMR/workflows/check-old/badge.svg?branch=main)](https://codecov.io/gh/msberends/AMR?branch=main)
[![check-recent](https://github.com/msberends/AMR/workflows/check-recent/badge.svg?branch=main)](https://codecov.io/gh/msberends/AMR?branch=main)
2021-07-11 13:20:45 +02:00
[![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)
2021-05-26 14:04:12 +02:00
2022-08-21 16:37:20 +02:00
Please read our [Developer Guideline here](https://github.com/msberends/AMR/wiki/Developer-Guideline).
2021-06-03 15:19:21 +02:00
The latest and unpublished development version can be installed from GitHub in two ways:
2021-07-11 13:20:45 +02:00
1. Manually, using:
2021-06-03 15:19:21 +02:00
```r
install.packages("remotes") # if you haven't already
remotes::install_github("msberends/AMR")
```
2021-07-11 13:20:45 +02:00
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'):
2021-06-03 15:19:21 +02:00
```r
options(repos = c(getOption("repos"),
msberends = "https://msberends.r-universe.dev"))
```
2021-07-11 13:20:45 +02:00
2021-06-03 15:19:21 +02:00
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...*).
2019-08-09 23:22:10 +02:00
### Get started
2021-07-11 13:20:45 +02:00
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/).
2019-01-12 19:31:30 +01:00
2022-08-21 16:37:20 +02:00
### Partners
2022-12-11 11:44:29 +01:00
The development of this package is part of, related to, or made possible by the following non-profit organisations and initiatives:
2022-08-21 16:37:20 +02:00
<div align="center">
2022-08-29 09:35:36 +02:00
<a href="https://www.rug.nl" title="University of Groningen"><img src="./logo_rug.svg" style="max-width: 200px;"></a>
2022-12-11 11:44:29 +01:00
<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>
2022-08-29 09:35:36 +02:00
<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>
2022-08-21 16:37:20 +02:00
</div>
2019-08-30 14:50:56 +02:00
### 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