AMR/README.md

203 lines
8.3 KiB
Markdown
Raw Normal View History

2018-02-21 11:52:31 +01:00
# `AMR`
2018-02-21 12:14:17 +01:00
This is an [R package](https://www.r-project.org) to simplify the analysis and prediction of Antimicrobial Resistance (AMR).
2018-02-21 11:52:31 +01:00
2018-02-21 12:21:34 +01:00
![logo_uni](man/figures/logo_en.png)![logo_umcg](man/figures/logo_umcg.png)
2018-02-21 12:10:00 +01:00
2018-03-22 13:45:04 +01:00
This R package was created for academic research by PhD students of the Faculty of Medical Sciences of the [University of Groningen (rug.nl)](https://www.rug.nl/) and the Medical Microbiology & Infection Prevention department of the [University Medical Center Groningen (UMCG, umcg.nl)](https://www.umcg.nl). They also maintain this package, see [Authors](#authors).
2018-02-21 12:10:00 +01:00
2018-02-21 11:52:31 +01:00
## Why this package?
2018-03-22 13:45:04 +01:00
This R package contains functions to make microbiological, epidemiological data analysis easier. It allows the use of some new classes to work with MIC values and antimicrobial interpretations (i.e. values S, I and R).
2018-02-21 11:52:31 +01:00
2018-03-22 13:45:04 +01:00
With AMR you can also apply EUCAST rules to isolates, identify first isolates of every patient, translate antibiotic codes from the lab (like `"AMOX"`) or the [WHO](https://www.whocc.no/atc_ddd_index/?code=J01CA04&showdescription=no) (like `"J01CA04"`) to trivial names (like `"amoxicillin"`), or predict antimicrobial resistance for the nextcoming years with the `rsi_predict` function.
2018-02-21 11:52:31 +01:00
2018-03-22 13:45:04 +01:00
For regular AMR analysis, the `rsi` function can be used. This function als works with the `dplyr` package (e.g. in conjunction with `summarise`) to calculate the resistance percentages of different antibiotic columns of a table.
This package contains an example data set `septic_patients`, consisting of 2000 isolates from anonymised septic patients between 2001 and 2017.
2018-02-21 12:19:42 +01:00
2018-02-22 20:48:48 +01:00
## How to get it?
2018-03-13 14:34:10 +01:00
This package is available on CRAN and also here on GitHub.
2018-02-22 20:48:48 +01:00
2018-03-22 13:45:04 +01:00
### From CRAN (recommended)
2018-03-13 14:34:10 +01:00
[![CRAN_Badge](https://img.shields.io/cran/v/AMR.svg?label=CRAN&colorB=3679BC)](http://cran.r-project.org/package=AMR)
[![CRAN_Downloads](https://cranlogs.r-pkg.org/badges/grand-total/AMR)](http://cran.r-project.org/package=AMR)
[![CRAN_Downloads](https://cranlogs.r-pkg.org/badges/AMR)](http://cran.r-project.org/package=AMR)
2018-03-22 13:45:04 +01:00
- <img src="http://www.rstudio.com/favicon.ico" alt="RStudio favicon" height="20px"> In [RStudio](http://www.rstudio.com) (recommended):
- Click on `Tools` and then `Install Packages...`
- Type in `AMR` and press <kbd>Install</kbd>
2018-03-22 13:45:04 +01:00
- <img src="https://cran.r-project.org/favicon.ico" alt="R favicon" height="20px"> In R directly:
- `install.packages("AMR")`
- <img src="https://exploratory.io/favicon.ico" alt="Exploratory favicon" height="20px"> In [Exploratory.io](https://exploratory.io):
2018-04-02 16:05:09 +02:00
- (Exploratory.io costs $40/month, but is free for students and teachers; if you have an `@umcg.nl` or `@rug.nl` email address, [click here to enroll](https://exploratory.io/plan?plan=Community))
2018-03-22 13:45:04 +01:00
- Start the software and log in
- Click on your username at the right hand side top
- Click on `R Packages`
- Click on the `Install` tab
- Type in `AMR` and press <kbd>Install</kbd>
- Once its installed it will show up in the `User Packages` section under the `Packages` tab.
2018-03-13 14:34:10 +01:00
### From GitHub (latest development version)
[![Travis_Build](https://travis-ci.org/msberends/AMR.svg?branch=master)](https://travis-ci.org/msberends/AMR)
[![Since_Release](https://img.shields.io/github/commits-since/msberends/AMR/latest.svg?colorB=3679BC)](https://github.com/msberends/AMR/commits/master)
[![Last_Commit](https://img.shields.io/github/last-commit/msberends/AMR.svg)](https://github.com/msberends/AMR/commits/master)
[![Code_Coverage](https://codecov.io/gh/msberends/AMR/branch/master/graph/badge.svg)](https://codecov.io/gh/msberends/AMR)
2018-02-22 20:48:48 +01:00
```r
2018-03-13 14:34:10 +01:00
install.packages("devtools")
2018-02-22 20:48:48 +01:00
devtools::install_github("msberends/AMR")
```
2018-02-21 11:52:31 +01:00
## How to use it?
```r
# Call it with:
library(AMR)
# For a list of functions:
help(package = "AMR")
```
2018-02-22 21:37:10 +01:00
### Overwrite/force resistance based on EUCAST rules
This is also called *interpretive reading*.
2018-02-21 11:52:31 +01:00
```r
2018-02-22 21:37:10 +01:00
before <- data.frame(bactid = c("STAAUR", # Staphylococcus aureus
2018-03-13 14:40:52 +01:00
"ENCFAE", # Enterococcus faecalis
2018-02-22 21:37:10 +01:00
"ESCCOL", # Escherichia coli
"KLEPNE", # Klebsiella pneumoniae
"PSEAER"), # Pseudomonas aeruginosa
vanc = "-", # Vancomycin
amox = "-", # Amoxicillin
coli = "-", # Colistin
cfta = "-", # Ceftazidime
cfur = "-", # Cefuroxime
stringsAsFactors = FALSE)
before
# bactid vanc amox coli cfta cfur
# 1 STAAUR - - - - -
# 2 ENCFAE - - - - -
# 3 ESCCOL - - - - -
# 4 KLEPNE - - - - -
# 5 PSEAER - - - - -
# Now apply those rules; just need a column with bacteria ID's and antibiotic results:
after <- EUCAST_rules(before)
after
# bactid vanc amox coli cfta cfur
# 1 STAAUR - - R R -
# 2 ENCFAE - - R R R
# 3 ESCCOL R - - - -
# 4 KLEPNE R R - - -
# 5 PSEAER R R - - R
2018-02-21 11:52:31 +01:00
```
### New classes
This package contains two new S3 classes: `mic` for MIC values (e.g. from Vitek or Phoenix) and `rsi` for antimicrobial drug interpretations (i.e. S, I and R). Both are actually ordered factors under the hood (an MIC of `2` being higher than `<=1` but lower than `>=32`, and for class `rsi` factors are ordered as `S < I < R`).
Both classes have extensions for existing generic functions like `print`, `summary` and `plot`.
```r
# Transform values to new classes
mic_data <- as.mic(c(">=32", "1.0", "8", "<=0.128", "8", "16", "16"))
rsi_data <- as.rsi(c(rep("S", 474), rep("I", 36), rep("R", 370)))
```
These functions also try to coerce valid values.
Quick overviews when just printing objects:
```r
mic_data
# Class 'mic': 7 isolates
#
# <NA> 0
#
# <=0.128 1 8 16 >=32
# 1 1 2 2 1
rsi_data
# Class 'rsi': 880 isolates
#
# <NA>: 0
# Sum of S: 474
# Sum of IR: 406
# - Sum of R: 370
# - Sum of I: 36
#
# %S %IR %I %R
# 53.9 46.1 4.1 42.0
```
A plot of `rsi_data`:
```r
plot(rsi_data)
```
![example1](man/figures/rsi_example.png)
A plot of `mic_data` (defaults to bar plot):
```r
plot(mic_data)
```
![example2](man/figures/mic_example.png)
2018-02-21 11:52:31 +01:00
Other epidemiological functions:
```r
# Determine key antibiotic based on bacteria ID
key_antibiotics(...)
# Selection of first isolates of any patient
first_isolate(...)
2018-02-22 21:37:10 +01:00
# Calculate resistance levels of antibiotics, can be used with `summarise` (dplyr)
2018-02-21 11:52:31 +01:00
rsi(...)
# Predict resistance levels of antibiotics
rsi_predict(...)
# Get name of antibiotic by ATC code
abname(...)
abname("J01CR02", from = "atc", to = "umcg") # "AMCL"
```
2018-02-22 21:37:10 +01:00
### Databases included in package
Datasets to work with antibiotics and bacteria properties.
```r
# Dataset with ATC antibiotics codes, official names and DDD's (oral and parenteral)
ablist # A tibble: 420 x 12
# Dataset with bacteria codes and properties like gram stain and aerobic/anaerobic
bactlist # A tibble: 2,507 x 10
```
2018-02-21 11:52:31 +01:00
## Authors
2018-02-21 12:14:17 +01:00
- [Berends MS](https://github.com/msberends)<sup>1,2</sup>, PhD Student
- [Luz CF](https://github.com/ceefluz)<sup>1</sup>, PhD Student
- [Hassing EEA](https://github.com/erwinhassing)<sup>2</sup>, Data Analyst (contributor)
2018-02-21 11:52:31 +01:00
<sup>1</sup> Department of Medical Microbiology, University of Groningen, University Medical Center Groningen, Groningen, the Netherlands
<sup>2</sup> Department of Medical, Market and Innovation (MMI), Certe Medische diagnostiek & advies, Groningen, the Netherlands
## Copyright
2018-03-13 14:34:10 +01:00
[![License](https://img.shields.io/github/license/msberends/AMR.svg?colorB=3679BC)](https://github.com/msberends/AMR/blob/master/LICENSE)
2018-02-21 11:52:31 +01:00
This R package is licensed under the [GNU General Public License (GPL) v2.0](https://github.com/msberends/AMR/blob/master/LICENSE). In a nutshell, this means that this package:
- May be used for commercial purposes
- May be used for private 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