1
0
mirror of https://github.com/msberends/AMR.git synced 2024-12-25 06:46:11 +01:00

website update

This commit is contained in:
dr. M.S. (Matthijs) Berends 2023-02-26 21:26:58 +01:00
parent 1d3d7d40bc
commit 4416394e10
17 changed files with 192 additions and 471 deletions

View File

@ -1,6 +1,6 @@
Package: AMR Package: AMR
Version: 1.8.2.9146 Version: 1.8.2.9147
Date: 2023-02-24 Date: 2023-02-26
Title: Antimicrobial Resistance Data Analysis Title: Antimicrobial Resistance Data Analysis
Description: Functions to simplify and standardise antimicrobial resistance (AMR) Description: Functions to simplify and standardise antimicrobial resistance (AMR)
data analysis and to work with microbial and antimicrobial properties by data analysis and to work with microbial and antimicrobial properties by

View File

@ -1,4 +1,4 @@
# AMR 1.8.2.9146 # AMR 1.8.2.9147
*(this beta version will eventually become v2.0! We're happy to reach a new major milestone soon!)* *(this beta version will eventually become v2.0! We're happy to reach a new major milestone soon!)*

17
R/mo.R
View File

@ -336,7 +336,7 @@ as.mo <- function(x,
input = x_search_cleaned, input = x_search_cleaned,
fullname = top_hits[1], fullname = top_hits[1],
mo = result_mo, mo = result_mo,
candidates = ifelse(length(top_hits) > 1, paste(top_hits[2:min(26, length(top_hits))], collapse = ", "), ""), candidates = ifelse(length(top_hits) > 1, paste(top_hits[2:min(99, length(top_hits))], collapse = ", "), ""),
minimum_matching_score = ifelse(is.null(minimum_matching_score), "NULL", minimum_matching_score), minimum_matching_score = ifelse(is.null(minimum_matching_score), "NULL", minimum_matching_score),
keep_synonyms = keep_synonyms, keep_synonyms = keep_synonyms,
stringsAsFactors = FALSE stringsAsFactors = FALSE
@ -798,7 +798,7 @@ rep.mo <- function(x, ...) {
#' @method print mo_uncertainties #' @method print mo_uncertainties
#' @export #' @export
#' @noRd #' @noRd
print.mo_uncertainties <- function(x, ...) { print.mo_uncertainties <- function(x, n = 10, ...) {
if (NROW(x) == 0) { if (NROW(x) == 0) {
cat(word_wrap("No uncertainties to show. Only uncertainties of the last call of `as.mo()` or any `mo_*()` function are stored.\n\n", add_fn = font_blue)) cat(word_wrap("No uncertainties to show. Only uncertainties of the last call of `as.mo()` or any `mo_*()` function are stored.\n\n", add_fn = font_blue))
return(invisible(NULL)) return(invisible(NULL))
@ -833,9 +833,14 @@ print.mo_uncertainties <- function(x, ...) {
} }
txt <- "" txt <- ""
any_maxed_out <- FALSE
for (i in seq_len(nrow(x))) { for (i in seq_len(nrow(x))) {
if (x[i, ]$candidates != "") { if (x[i, ]$candidates != "") {
candidates <- unlist(strsplit(x[i, ]$candidates, ", ", fixed = TRUE)) candidates <- unlist(strsplit(x[i, ]$candidates, ", ", fixed = TRUE))
if (length(candidates) > n) {
any_maxed_out <- TRUE
candidates <- candidates[seq_len(n)]
}
scores <- mo_matching_score(x = x[i, ]$input, n = candidates) scores <- mo_matching_score(x = x[i, ]$input, n = candidates)
n_candidates <- length(candidates) n_candidates <- length(candidates)
@ -856,10 +861,6 @@ print.mo_uncertainties <- function(x, ...) {
font_blue(paste0(" (", scores_formatted, ")"), collapse = NULL) font_blue(paste0(" (", scores_formatted, ")"), collapse = NULL)
), ),
quotes = FALSE, sort = FALSE quotes = FALSE, sort = FALSE
),
ifelse(n_candidates == 25,
font_grey(" [showing first 25]"),
""
) )
), ),
extra_indent = nchar("Also matched: "), extra_indent = nchar("Also matched: "),
@ -905,7 +906,11 @@ print.mo_uncertainties <- function(x, ...) {
txt <- gsub("(^[\n]|[\n]$)", "", txt) txt <- gsub("(^[\n]|[\n]$)", "", txt)
txt <- paste0("\n", txt, "\n") txt <- paste0("\n", txt, "\n")
} }
cat(txt) cat(txt)
if (isTRUE(any_maxed_out)) {
cat(font_blue(word_wrap("\nOnly the first ", n, " other matches of each record are shown. Run `print(mo_uncertainties(), n = ...)` to view more entries, or save `mo_uncertainties()` to an object.")))
}
} }
#' @method print mo_renamed #' @method print mo_renamed

View File

@ -76,9 +76,6 @@ navbar:
- text: "How to" - text: "How to"
icon: "fa-question-circle" icon: "fa-question-circle"
menu: menu:
- text: "User- Or Team-specific Package Settings"
icon: "fa-gear"
href: "reference/AMR-options.html"
- text: "Conduct AMR Analysis" - text: "Conduct AMR Analysis"
icon: "fa-directions" icon: "fa-directions"
href: "articles/AMR.html" href: "articles/AMR.html"
@ -88,9 +85,12 @@ navbar:
- text: "Predict Antimicrobial Resistance" - text: "Predict Antimicrobial Resistance"
icon: "fa-dice" icon: "fa-dice"
href: "articles/resistance_predict.html" href: "articles/resistance_predict.html"
- text: "Data Sets for Download / Own Use" - text: "Download Data Sets for Own Use"
icon: "fa-database" icon: "fa-database"
href: "articles/datasets.html" href: "articles/datasets.html"
- text: "Set User- Or Team-specific Package Settings"
icon: "fa-gear"
href: "reference/AMR-options.html"
- text: "Conduct Principal Component Analysis for AMR" - text: "Conduct Principal Component Analysis for AMR"
icon: "fa-compress" icon: "fa-compress"
href: "articles/PCA.html" href: "articles/PCA.html"

Binary file not shown.

Binary file not shown.

View File

@ -1 +1 @@
b3734ad222d485de6923fc9957d8f2f5 7846247d4113c4e8f550cfd2cb87467f

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

View File

@ -45279,7 +45279,7 @@
"B_STNTR_INDC" "Stenotrophomonas indicatrix" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "indicatrix" "" "species" "Weber et al., 2018" "LPSN" "797782" "516670" "10701219" 1.5 "" "B_STNTR_INDC" "Stenotrophomonas indicatrix" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "indicatrix" "" "species" "Weber et al., 2018" "LPSN" "797782" "516670" "10701219" 1.5 ""
"B_STNTR_KRNS" "Stenotrophomonas koreensis" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "koreensis" "" "species" "Yang et al., 2006" "LPSN" "781248" "516670" "3222376" 1.5 "" "B_STNTR_KRNS" "Stenotrophomonas koreensis" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "koreensis" "" "species" "Yang et al., 2006" "LPSN" "781248" "516670" "3222376" 1.5 ""
"B_STNTR_LCTT" "Stenotrophomonas lactitubi" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "lactitubi" "" "species" "Weber et al., 2018" "LPSN" "797783" "516670" "10788780" 1.5 "" "B_STNTR_LCTT" "Stenotrophomonas lactitubi" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "lactitubi" "" "species" "Weber et al., 2018" "LPSN" "797783" "516670" "10788780" 1.5 ""
"B_STNTR_MLTP" "Stenotrophomonas maltophilia" "synonym" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "maltophilia" "" "species" "Palleroni et al., 1993" "LPSN" "781249" "516670" "783141" "10912104" 1 "113697002" "B_STNTR_MLTP" "Stenotrophomonas maltophilia" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "maltophilia" "" "species" "Palleroni et al., 1993" "LPSN" "781249" "516670" "10912104" 1 "113697002"
"B_STNTR_NTRT" "Stenotrophomonas nitritireducens" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "nitritireducens" "" "species" "Finkmann et al., 2000" "LPSN" "781250" "516670" "3222370" 1.5 "416746005" "B_STNTR_NTRT" "Stenotrophomonas nitritireducens" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "nitritireducens" "" "species" "Finkmann et al., 2000" "LPSN" "781250" "516670" "3222370" 1.5 "416746005"
"B_STNTR_PNCH" "Stenotrophomonas panacihumi" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "panacihumi" "" "species" "Yi et al., 2010" "GBIF" "11141735" 1.5 "" "B_STNTR_PNCH" "Stenotrophomonas panacihumi" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "panacihumi" "" "species" "Yi et al., 2010" "GBIF" "11141735" 1.5 ""
"B_STNTR_PAVN" "Stenotrophomonas pavanii" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "pavanii" "" "species" "Ramos et al., 2011" "LPSN" "789171" "516670" "8102737" 1.5 "704977000" "B_STNTR_PAVN" "Stenotrophomonas pavanii" "accepted" "Bacteria" "Pseudomonadota" "Gammaproteobacteria" "Lysobacterales" "Lysobacteraceae" "Stenotrophomonas" "pavanii" "" "species" "Ramos et al., 2011" "LPSN" "789171" "516670" "8102737" 1.5 "704977000"

Binary file not shown.

View File

@ -1357,19 +1357,27 @@ taxonomy <- taxonomy %>%
# set class <mo> # set class <mo>
class(taxonomy$mo) <- c("mo", "character") class(taxonomy$mo) <- c("mo", "character")
microorganisms <- taxonomy
### this was previously needed?? Since 2022 M. catarrhalis seems to be "accepted" again
# # Moraxella catarrhalis was named Branhamella catarrhalis (Catlin, 1970), but this is unaccepted in clinical microbiology # Restore 'synonym' microorganisms to 'accepted' --------------------------
# # we keep them both
# taxonomy$status[which(taxonomy$fullname == "Moraxella catarrhalis")] # according to LPSN: Stenotrophomonas maltophilia is the correct name if this species is regarded as a separate species (i.e., if its nomenclatural type is not assigned to another species whose name is validly published, legitimate and not rejected and has priority) within a separate genus Stenotrophomonas.
# taxonomy$lpsn_renamed_to[which(taxonomy$fullname == "Moraxella catarrhalis")] # https://lpsn.dsmz.de/species/stenotrophomonas-maltophilia
# taxonomy$status[which(taxonomy$fullname == "Moraxella catarrhalis")] <- "accepted"
# taxonomy$lpsn_renamed_to[which(taxonomy$fullname == "Moraxella catarrhalis")] <- NA_character_ # all MO's to keep as 'accepted', not as 'synonym':
to_restore <- c("Stenotrophomonas maltophilia",
"Moraxella catarrhalis")
all(to_restore %in% microorganisms$fullname)
for (nm in to_restore) {
microorganisms$lpsn_renamed_to[which(microorganisms$fullname == nm)] <- NA
microorganisms$gbif_renamed_to[which(microorganisms$fullname == nm)] <- NA
microorganisms$status[which(microorganisms$fullname == nm)] <- "accepted"
}
# Save to package --------------------------------------------------------- # Save to package ---------------------------------------------------------
microorganisms <- taxonomy
usethis::use_data(microorganisms, overwrite = TRUE, version = 2, compress = "xz") usethis::use_data(microorganisms, overwrite = TRUE, version = 2, compress = "xz")
rm(microorganisms) rm(microorganisms)

Binary file not shown.

View File

@ -78,7 +78,7 @@ This base R snippet will work in any version of R since April 2013 (R-3.0).
The `AMR` package supports generating traditional, combined, syndromic, and even weighted-incidence syndromic combination antibiograms (WISCA). 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.) when using `print()` on an antibiogram object. 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 ```r
antibiogram(example_isolates, antibiogram(example_isolates,

View File

@ -28,7 +28,7 @@ knitr::opts_chunk$set(
Conducting AMR data analysis unfortunately requires in-depth knowledge from different scientific fields, which makes it hard to do right. At least, it requires: 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!) * 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) 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 * 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 * 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
@ -60,6 +60,7 @@ knitr::kable(
``` ```
## Needed R packages ## 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. 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. We will also use the `cleaner` package, that can be used for cleaning data and creating frequency tables.
@ -68,156 +69,93 @@ We will also use the `cleaner` package, that can be used for cleaning data and c
library(dplyr) library(dplyr)
library(ggplot2) library(ggplot2)
library(AMR) library(AMR)
library(cleaner)
# (if not yet installed, install with:) # (if not yet installed, install with:)
# install.packages(c("dplyr", "ggplot2", "AMR", "cleaner")) # install.packages(c("dplyr", "ggplot2", "AMR"))
``` ```
# Creation of data The `AMR` package contains a data set `example_isolates_unclean`, which might look data that users have extracted from their laboratory systems:
We will create some fake example data to use for analysis. For AMR data analysis, we need at least: a patient ID, name or code of a microorganism, a date and antimicrobial results (an antibiogram). It could also include a specimen type (e.g. to filter on blood or urine), the ward type (e.g. to filter on ICUs).
With additional columns (like a hospital name, the patients gender of even [well-defined] clinical properties) you can do a comparative analysis, as this tutorial will demonstrate too. ```{r}
example_isolates_unclean
## Patients # we will use 'our_data' as the data set name for this tutorial
To start with patients, we need a unique list of patients. our_data <- example_isolates_unclean
```{r create patients}
patients <- unlist(lapply(LETTERS, paste0, 1:10))
``` ```
The `LETTERS` object is available in R - it's a vector with 26 characters: `A` to `Z`. The `patients` object we just created is now a vector of length `r length(patients)`, with values (patient IDs) varying from ``r patients[1]`` to ``r patients[length(patients)]``. Now we we also set the gender of our patients, by putting the ID and the gender in a table: 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.
```{r create gender} ## Taxonomy of microorganisms
patients_table <- data.frame(
patient_id = patients, 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")`.
gender = c(
rep("M", 135), 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:
rep("F", 125)
) ```{r, message = FALSE}
) as.mo("Klebsiella pneumoniae")
as.mo("K. pneumoniae")
as.mo("KLEPNE")
as.mo("KLPN")
``` ```
The first 135 patient IDs are now male, the other 125 are female. The first character in above codes denote their taxonomic kingdom, such as Bacteria (B), Fungi (F), and Protozoa (P).
## Dates 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:
Let's pretend that our data consists of blood cultures isolates from between 1 January 2010 and 1 January 2018.
```{r create dates} ```{r, message = FALSE}
dates <- seq(as.Date("2010-01-01"), as.Date("2018-01-01"), by = "day") mo_family("K. pneumoniae")
mo_genus("K. pneumoniae")
mo_species("K. pneumoniae")
mo_gramstain("Klebsiella pneumoniae")
mo_ref("K. pneumoniae")
mo_snomed("K. pneumoniae")
``` ```
This `dates` object now contains all days in our date range. Now we can thus clean our data:
#### Microorganisms ```{r, echo = FALSE, message = FALSE}
For this tutorial, we will uses four different microorganisms: *Escherichia coli*, *Staphylococcus aureus*, *Streptococcus pneumoniae*, and *Klebsiella pneumoniae*: mo_reset_session()
```{r mo}
bacteria <- c(
"Escherichia coli", "Staphylococcus aureus",
"Streptococcus pneumoniae", "Klebsiella pneumoniae"
)
``` ```
## Put everything together ```{r, message = TRUE}
our_data$bacteria <- as.mo(our_data$bacteria, info = TRUE)
Using the `sample()` function, we can randomly select items from all objects we defined earlier. To let our fake data reflect reality a bit, we will also approximately define the probabilities of bacteria and the antibiotic results, using the `random_sir()` function.
```{r merge data}
sample_size <- 20000
data <- data.frame(
date = sample(dates, size = sample_size, replace = TRUE),
patient_id = sample(patients, size = sample_size, replace = TRUE),
hospital = sample(
c(
"Hospital A",
"Hospital B",
"Hospital C",
"Hospital D"
),
size = sample_size, replace = TRUE,
prob = c(0.30, 0.35, 0.15, 0.20)
),
bacteria = sample(bacteria,
size = sample_size, replace = TRUE,
prob = c(0.50, 0.25, 0.15, 0.10)
),
AMX = random_sir(sample_size, prob_sir = c(0.35, 0.60, 0.05)),
AMC = random_sir(sample_size, prob_sir = c(0.15, 0.75, 0.10)),
CIP = random_sir(sample_size, prob_sir = c(0.20, 0.80, 0.00)),
GEN = random_sir(sample_size, prob_sir = c(0.08, 0.92, 0.00))
)
``` ```
Using the `left_join()` function from the `dplyr` package, we can 'map' the gender to the patient ID using the `patients_table` object we created earlier: Apparently, there was some uncertainty about the translation to taxonomic codes. Let's check this:
```{r merge data 2, message = FALSE, warning = FALSE} ```{r}
data <- data %>% left_join(patients_table) mo_uncertainties()
``` ```
The resulting data set contains `r format(nrow(data), big.mark = " ")` blood culture isolates. With the `head()` function we can preview the first 6 rows of this data set: That's all good.
```{r preview data set 1, eval = FALSE} ## Antibiotic results
head(data)
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
``` ```
```{r preview data set 2, echo = FALSE, results = 'asis'} This is basically it for the cleaning, time to start the data inclusion.
knitr::kable(head(data), align = "c")
```
Now, let's start the cleaning and the analysis!
# Cleaning the data
We also created a package dedicated to data cleaning and checking, called the `cleaner` package. It `freq()` function can be used to create frequency tables.
For example, for the `gender` variable:
```{r freq gender 1, results="asis"}
data %>% freq(gender)
```
So, we can draw at least two conclusions immediately. From a data scientists perspective, the data looks clean: only values `M` and `F`. From a researchers perspective: there are slightly more men. Nothing we didn't already know.
The data is already quite clean, but we still need to transform some variables. The `bacteria` column now consists of text, and we want to add more variables based on microbial IDs later on. So, we will transform this column to valid IDs. The `mutate()` function of the `dplyr` package makes this really easy:
```{r transform mo 1}
data <- data %>%
mutate(bacteria = as.mo(bacteria))
```
We also want to transform the antibiotics, because in real life data we don't know if they are really clean. The `as.sir()` function ensures reliability and reproducibility in these kind of variables. The `is_sir_eligible()` can check which columns are probably columns with SIR test results. Using `mutate()` and `across()`, we can apply the transformation to the formal `<rsi>` class:
```{r transform abx}
is_sir_eligible(data)
colnames(data)[is_sir_eligible(data)]
data <- data %>%
mutate(across(where(is_sir_eligible), as.sir))
```
Finally, we will apply [EUCAST rules](https://www.eucast.org/expert_rules_and_intrinsic_resistance/) on our antimicrobial results. In Europe, most medical microbiological laboratories already apply these rules. Our package features their latest insights on intrinsic resistance and exceptional phenotypes. Moreover, the `eucast_rules()` function can also apply additional rules, like forcing <help title="ATC: J01CA01">ampicillin</help> = R when <help title="ATC: J01CR02">amoxicillin/clavulanic acid</help> = R.
Because the amoxicillin (column `AMX`) and amoxicillin/clavulanic acid (column `AMC`) in our data were generated randomly, some rows will undoubtedly contain AMX = S and AMC = R, which is technically impossible. The `eucast_rules()` fixes this:
```{r eucast, warning = FALSE, message = FALSE}
data <- eucast_rules(data, col_mo = "bacteria", rules = "all")
```
# Adding new variables
Now that we have the microbial ID, we can add some taxonomic properties:
```{r new taxo}
data <- data %>%
mutate(
gramstain = mo_gramstain(bacteria),
genus = mo_genus(bacteria),
species = mo_species(bacteria)
)
```
## First isolates ## First isolates
We also need to know which isolates we can *actually* use for analysis.
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). 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).
@ -226,116 +164,143 @@ 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.* > *(...) 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/) <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. This method also takes into account the antimicrobial susceptibility test results using `all_microbials()`. Read more about the methods on the `first_isolate()` page. 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: The outcome of the function can easily be added to our data:
```{r 1st isolate} ```{r 1st isolate}
data <- data %>% our_data <- our_data %>%
mutate(first = first_isolate(info = TRUE)) mutate(first = first_isolate(info = TRUE))
``` ```
So only `r percentage(sum(data$first) / nrow(data))` is suitable for resistance analysis! We can now filter on it with the `filter()` function, also from the `dplyr` package: 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} ```{r 1st isolate filter}
data_1st <- data %>% our_data_1st <- our_data %>%
filter(first == TRUE) filter(first == TRUE)
``` ```
For future use, the above two syntaxes can be shortened: For future use, the above two syntaxes can be shortened:
```{r 1st isolate filter 2} ```{r 1st isolate filter 2}
data_1st <- data %>% our_data_1st <- our_data %>%
filter_first_isolate() filter_first_isolate()
``` ```
So we end up with `r format(nrow(data_1st), big.mark = " ")` isolates for analysis. Now our data looks like: 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, eval = FALSE} ```{r preview data set 3}
head(data_1st) our_data_1st
``` ```
```{r preview data set 4, echo = FALSE, results = 'asis'} Time for the analysis.
knitr::kable(head(data_1st), align = "c")
```
Time for the analysis!
# Analysing the data # Analysing the data
You might want to start by getting an idea of how the data is distributed. It's an important start, because it also decides how you will continue your analysis. Although this package contains a convenient function to make frequency tables, exploratory data analysis (EDA) is not the primary scope of this package. Use a package like [`DataExplorer`](https://cran.r-project.org/package=DataExplorer) for that, or read the free online book [Exploratory Data Analysis with R](https://bookdown.org/rdpeng/exdata/) by Roger D. Peng.
## Dispersion of species 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:
To just get an idea how the species are distributed, create a frequency table with our `freq()` function. We created the `genus` and `species` column earlier based on the microbial ID. With `paste()`, we can concatenate them together.
The `freq()` function can be used like the base R language was intended: ```{r}
summary(our_data_1st)
```{r freq 1, eval = FALSE} glimpse(our_data_1st)
freq(paste(data_1st$genus, data_1st$species))
# number of unique values per column:
sapply(our_data_1st, n_distinct)
``` ```
Or can be used like the `dplyr` way, which is easier readable: ## Availability of species
```{r freq 2a, eval = FALSE} To just get an idea how the species are distributed, create a frequency table with `count()` based on the name of the microorganisms:
data_1st %>% freq(genus, species)
``` ```{r freq 1}
```{r freq 2b, results = 'asis', echo = FALSE} our_data %>%
data_1st %>% count(mo_name(bacteria), sort = TRUE)
freq(genus, species, header = TRUE)
our_data_1st %>%
count(mo_name(bacteria), sort = TRUE)
``` ```
## Overview of different bug/drug combinations ## Select and filter with antibiotic selectors
Using [tidyverse selections](https://tidyselect.r-lib.org/reference/language.html), you can also select or filter columns based on the antibiotic class they are in: 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, eval = FALSE} ```{r bug_drg 2a}
data_1st %>% 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")) 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"), ]
``` ```
```{r bug_drg 2b, echo = FALSE, results = 'asis'} ## Generate antibiograms
knitr::kable(
data_1st %>% This package comes with `antibiogram()`, a function that automatically generates traditional, combined, syndromic, and even weighted-incidence syndromic combination antibiograms (WISCA). For R Markdown (such as this page) it automatically prints in the right table format.
filter(any(aminoglycosides() == "R")) %>%
head(), Below are some suggestions for how to generate the different antibiograms:
align = "c"
) ```{r}
# traditional:
antibiogram(our_data_1st)
antibiogram(our_data_1st,
ab_transform = "name")
antibiogram(our_data_1st,
ab_transform = "name",
language = "es") # support for 20 languages
``` ```
If you want to get a quick glance of the number of isolates in different bug/drug combinations, you can use the `bug_drug_combinations()` function: ```{r}
# combined:
```{r bug_drg 1a, eval = FALSE} antibiogram(our_data_1st,
data_1st %>% antibiotics = c("AMC", "AMC+CIP", "AMC+GEN"))
bug_drug_combinations() %>%
head() # show first 6 rows
``` ```
```{r bug_drg 1b, echo = FALSE, results = 'asis'} ```{r}
knitr::kable( # for a syndromic antibiogram, we must fake some clinical conditions:
data_1st %>% our_data_1st$condition <- sample(c("Cardial", "Respiratory", "Rheumatic"),
bug_drug_combinations() %>% size = nrow(our_data_1st),
head(), replace = TRUE)
align = "c"
) # syndromic:
antibiogram(our_data_1st,
syndromic_group = "condition")
antibiogram(our_data_1st,
# you can use AB selectors here as well:
antibiotics = c(penicillins(), aminoglycosides()),
syndromic_group = "condition",
mo_transform = "gramstain")
``` ```
```{r}
```{r bug_drg 3a, eval = FALSE} # WISCA:
data_1st %>% # (we lack some details, but it could contain a filter on e.g. >65 year-old males)
select(bacteria, aminoglycosides()) %>% wisca <- antibiogram(our_data_1st,
bug_drug_combinations() antibiotics = c("AMC", "AMC+CIP", "AMC+GEN"),
syndromic_group = "condition",
mo_transform = "gramstain")
wisca
``` ```
Antibiograms can be plotted using `autoplot()` from the `ggplot2` packages, since this package provides an extension to that function:
```{r bug_drg 3b, echo = FALSE, results = 'asis'} ```{r}
knitr::kable( autoplot(wisca)
data_1st %>%
select(bacteria, aminoglycosides()) %>%
bug_drug_combinations(),
align = "c"
)
``` ```
This will only give you the crude numbers in the data. To calculate antimicrobial resistance in a more sensible way, also by correcting for too few results, we use the `resistance()` and `susceptibility()` functions. 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 ## Resistance percentages
@ -346,274 +311,17 @@ All these functions contain a `minimum` argument, denoting the minimum required
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: 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} ```{r}
data_1st %>% resistance(AMX) our_data_1st %>% resistance(AMX)
``` ```
Or can be used in conjunction with `group_by()` and `summarise()`, both from the `dplyr` package: Or can be used in conjunction with `group_by()` and `summarise()`, both from the `dplyr` package:
```{r, eval = FALSE} ```{r}
data_1st %>% our_data_1st %>%
group_by(hospital) %>% group_by(hospital) %>%
summarise(amoxicillin = resistance(AMX)) summarise(amoxicillin = resistance(AMX))
``` ```
```{r, echo = FALSE}
data_1st %>%
group_by(hospital) %>%
summarise(amoxicillin = resistance(AMX)) %>%
knitr::kable(align = "c", big.mark = " ")
```
Of course it would be very convenient to know the number of isolates responsible for the percentages. For that purpose the `n_sir()` can be used, which works exactly like `n_distinct()` from the `dplyr` package. It counts all isolates available for every group (i.e. values S, I or R):
```{r, eval = FALSE}
data_1st %>%
group_by(hospital) %>%
summarise(
amoxicillin = resistance(AMX),
available = n_sir(AMX)
)
```
```{r, echo = FALSE}
data_1st %>%
group_by(hospital) %>%
summarise(
amoxicillin = resistance(AMX),
available = n_sir(AMX)
) %>%
knitr::kable(align = "c", big.mark = " ")
```
These functions can also be used to get the proportion of multiple antibiotics, to calculate empiric susceptibility of combination therapies very easily:
```{r, eval = FALSE}
data_1st %>%
group_by(genus) %>%
summarise(
amoxiclav = susceptibility(AMC),
gentamicin = susceptibility(GEN),
amoxiclav_genta = susceptibility(AMC, GEN)
)
```
```{r, echo = FALSE}
data_1st %>%
group_by(genus) %>%
summarise(
amoxiclav = susceptibility(AMC),
gentamicin = susceptibility(GEN),
amoxiclav_genta = susceptibility(AMC, GEN)
) %>%
knitr::kable(align = "c", big.mark = " ")
```
Or if you are curious for the resistance within certain antibiotic classes, use a antibiotic class selector such as `penicillins()`, which automatically will include the columns `AMX` and `AMC` of our data:
```{r, eval = FALSE}
data_1st %>%
# group by hospital
group_by(hospital) %>%
# / -> select all penicillins in the data for calculation
# | / -> use resistance() for all peni's per hospital
# | | / -> print as percentages
summarise(across(penicillins(), resistance, as_percent = TRUE)) %>%
# format the antibiotic column names, using so-called snake case,
# so 'Amoxicillin/clavulanic acid' becomes 'amoxicillin_clavulanic_acid'
rename_with(set_ab_names, penicillins())
```
```{r, echo = FALSE, message = FALSE}
data_1st %>%
group_by(hospital) %>%
summarise(across(penicillins(), resistance, as_percent = TRUE)) %>%
rename_with(set_ab_names, penicillins()) %>%
knitr::kable(align = "lrr")
```
To make a transition to the next part, let's see how differences in the previously calculated combination therapies could be plotted:
```{r plot 1}
data_1st %>%
group_by(genus) %>%
summarise(
"1. Amoxi/clav" = susceptibility(AMC),
"2. Gentamicin" = susceptibility(GEN),
"3. Amoxi/clav + genta" = susceptibility(AMC, GEN)
) %>%
# pivot_longer() from the tidyr package "lengthens" data:
tidyr::pivot_longer(-genus, names_to = "antibiotic") %>%
ggplot(aes(
x = genus,
y = value,
fill = antibiotic
)) +
geom_col(position = "dodge2")
```
## Plots
To show results in plots, most R users would nowadays use the `ggplot2` package. This package lets you create plots in layers. You can read more about it [on their website](https://ggplot2.tidyverse.org/). A quick example would look like these syntaxes:
```{r plot 2, eval = FALSE}
ggplot(
data = a_data_set,
mapping = aes(
x = year,
y = value
)
) +
geom_col() +
labs(
title = "A title",
subtitle = "A subtitle",
x = "My X axis",
y = "My Y axis"
)
# or as short as:
ggplot(a_data_set) +
geom_bar(aes(year))
```
The `AMR` package contains functions to extend this `ggplot2` package, for example `geom_sir()`. It automatically transforms data with `count_df()` or `proportion_df()` and show results in stacked bars. Its simplest and shortest example:
```{r plot 3}
ggplot(data_1st) +
geom_sir(translate_ab = FALSE)
```
Omit the `translate_ab = FALSE` to have the antibiotic codes (AMX, AMC, CIP, GEN) translated to official WHO names (amoxicillin, amoxicillin/clavulanic acid, ciprofloxacin, gentamicin).
If we group on e.g. the `genus` column and add some additional functions from our package, we can create this:
```{r plot 4}
# group the data on `genus`
ggplot(data_1st %>% group_by(genus)) +
# create bars with genus on x axis
# it looks for variables with class `sir`,
# of which we have 4 (earlier created with `as.sir`)
geom_sir(x = "genus") +
# split plots on antibiotic
facet_sir(facet = "antibiotic") +
# set colours to the SIR interpretations (colour-blind friendly)
scale_sir_colours() +
# show percentages on y axis
scale_y_percent(breaks = 0:4 * 25) +
# turn 90 degrees, to make it bars instead of columns
coord_flip() +
# add labels
labs(
title = "Resistance per genus and antibiotic",
subtitle = "(this is fake data)"
) +
# and print genus in italic to follow our convention
# (is now y axis because we turned the plot)
theme(axis.text.y = element_text(face = "italic"))
```
To simplify this, we also created the `ggplot_sir()` function, which combines almost all above functions:
```{r plot 5}
data_1st %>%
group_by(genus) %>%
ggplot_sir(
x = "genus",
facet = "antibiotic",
breaks = 0:4 * 25,
datalabels = FALSE
) +
coord_flip()
```
### Plotting MIC and disk diffusion values
The AMR package also extends the `plot()` and `ggplot2::autoplot()` functions for plotting minimum inhibitory concentrations (MIC, created with `as.mic()`) and disk diffusion diameters (created with `as.disk()`).
With the `random_mic()` and `random_disk()` functions, we can generate sampled values for the new data types (S3 classes) `<mic>` and `<disk>`:
```{r, results='markup'}
mic_values <- random_mic(size = 100)
mic_values
```
```{r mic_plots}
# base R:
plot(mic_values)
# ggplot2:
autoplot(mic_values)
```
But we could also be more specific, by generating MICs that are likely to be found in *E. coli* for ciprofloxacin:
```{r, results = 'markup', message = FALSE, warning = FALSE}
mic_values <- random_mic(size = 100, mo = "E. coli", ab = "cipro")
```
For the `plot()` and `autoplot()` function, we can define the microorganism and an antimicrobial agent the same way. This will add the interpretation of those values according to a chosen guidelines (defaults to the latest EUCAST guideline).
Default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red:
```{r mic_plots_mo_ab, message = FALSE, warning = FALSE}
# base R:
plot(mic_values, mo = "E. coli", ab = "cipro")
# ggplot2:
autoplot(mic_values, mo = "E. coli", ab = "cipro")
```
For disk diffusion values, there is not much of a difference in plotting:
```{r, results = 'markup'}
disk_values <- random_disk(size = 100, mo = "E. coli", ab = "cipro")
disk_values
```
```{r disk_plots, message = FALSE, warning = FALSE}
# base R:
plot(disk_values, mo = "E. coli", ab = "cipro")
```
And when using the `ggplot2` package, but now choosing the latest implemented CLSI guideline (notice that the EUCAST-specific term "Susceptible, incr. exp." has changed to "Intermediate"):
```{r disk_plots_mo_ab, message = FALSE, warning = FALSE}
autoplot(
disk_values,
mo = "E. coli",
ab = "cipro",
guideline = "CLSI"
)
```
## Independence test
The next example uses the `example_isolates` data set. This is a data set included with this package and contains 2,000 microbial isolates with their full antibiograms. It reflects reality and can be used to practise AMR data analysis.
We will compare the resistance to amoxicillin/clavulanic acid (column `AMC`) between an ICU and other clinical wards. The input for the `fisher.test()` can be retrieved with a transformation like this:
```{r, results = 'markup'}
# use package 'tidyr' to pivot data:
library(tidyr)
check_AMC <- example_isolates %>%
filter(ward %in% c("ICU", "Clinical")) %>% # filter on only these wards
select(ward, AMC) %>% # select the wards and amoxi/clav
group_by(ward) %>% # group on the wards
count_df(combine_SI = TRUE) %>% # count all isolates per group (ward)
pivot_wider(
names_from = ward, # transform output so "ICU" and "Clinical" are columns
values_from = value
) %>%
select(ICU, Clinical) %>% # and only select these columns
as.matrix() # transform to a good old matrix for fisher.test()
check_AMC
```
We can apply the test now with:
```{r}
# do Fisher's Exact Test
fisher.test(check_AMC)
```
As can be seen, the p value is practically zero (`r format(fisher.test(check_AMC)$p.value, scientific = FALSE)`), which means that the amoxicillin/clavulanic acid resistance found in isolates between patients in ICUs and other clinical wards are really different.
---- ----
*Author: Dr. Matthijs Berends* *Author: Dr. Matthijs Berends, 26th Feb 2023*