support for Dutch national MDR guideline

.github/workflows/website.yaml

@@ -46,6 +46,7 @@ jobs:
       - uses: actions/checkout@v3
         with:
           # this is to keep timestamps, the default fetch-depth: 1 gets the timestamps of the moment of cloning
+          # we need this for the download page on our website - dates must be of the files, not of the latest git push
           fetch-depth: 0
 
       - name: Preserve timestamps
@@ -69,7 +70,6 @@ jobs:
           extra-packages: |
             any::pkgdown
             any::tidymodels
-            any::data.table
 
       # Send updates to repo using GH Actions bot
       - name: Create website in separate branch

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AMR
-Version: 2.1.1.9117
+Version: 2.1.1.9118
-Date: 2024-12-13
+Date: 2024-12-14
 Title: Antimicrobial Resistance Data Analysis
 Description: Functions to simplify and standardise antimicrobial resistance (AMR)
   data analysis and to work with microbial and antimicrobial properties by

NEWS.md

@@ -1,4 +1,4 @@
-# AMR 2.1.1.9117
+# AMR 2.1.1.9118
 
 *(this beta version will eventually become v3.0. We're happy to reach a new major milestone soon, which will be all about the new One Health support! Install this beta using [the instructions here](https://msberends.github.io/AMR/#latest-development-version).)*
 

PythonPackage/AMR/AMR.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: AMR
-Version: 2.1.1.9117
+Version: 2.1.1.9118
 Summary: A Python wrapper for the AMR R package
 Home-page: https://github.com/msberends/AMR
-Author: Dr. Matthijs Berends
+Author: Matthijs Berends
 Author-email: m.s.berends@umcg.nl
 License: GPL 2
 Project-URL: Bug Tracker, https://github.com/msberends/AMR/issues

PythonPackage/AMR/AMR/__init__.py

@@ -117,8 +117,6 @@ from .functions import is_new_episode
 from .functions import ggplot_pca
 from .functions import ggplot_sir
 from .functions import geom_sir
-from .functions import theme_sir
-from .functions import labels_sir_count
 from .functions import guess_ab_col
 from .functions import italicise_taxonomy
 from .functions import italicize_taxonomy
@@ -181,6 +179,8 @@ from .functions import mo_info
 from .functions import mo_url
 from .functions import mo_property
 from .functions import pca
+from .functions import theme_sir
+from .functions import labels_sir_count
 from .functions import resistance
 from .functions import susceptibility
 from .functions import sir_confidence_interval

PythonPackage/AMR/AMR/functions.py

@@ -381,12 +381,6 @@ def ggplot_sir(*args, **kwargs):
 def geom_sir(*args, **kwargs):
     """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
     return convert_to_python(amr_r.geom_sir(*args, **kwargs))
-def theme_sir(*args, **kwargs):
-    """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
-    return convert_to_python(amr_r.theme_sir(*args, **kwargs))
-def labels_sir_count(*args, **kwargs):
-    """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
-    return convert_to_python(amr_r.labels_sir_count(*args, **kwargs))
 def guess_ab_col(*args, **kwargs):
     """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
     return convert_to_python(amr_r.guess_ab_col(*args, **kwargs))
@@ -573,6 +567,12 @@ def mo_property(*args, **kwargs):
 def pca(*args, **kwargs):
     """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
     return convert_to_python(amr_r.pca(*args, **kwargs))
+def theme_sir(*args, **kwargs):
+    """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
+    return convert_to_python(amr_r.theme_sir(*args, **kwargs))
+def labels_sir_count(*args, **kwargs):
+    """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
+    return convert_to_python(amr_r.labels_sir_count(*args, **kwargs))
 def resistance(*args, **kwargs):
     """See our website of the R package for the manual: https://msberends.github.io/AMR/index.html"""
     return convert_to_python(amr_r.resistance(*args, **kwargs))

PythonPackage/AMR/setup.py

@@ -2,14 +2,14 @@ from setuptools import setup, find_packages
 
 setup(
     name='AMR',
-    version='2.1.1.9117',
+    version='2.1.1.9118',
     packages=find_packages(),
     install_requires=[
         'rpy2',
         'numpy',
         'pandas',
     ],
-    author='Dr. Matthijs Berends',
+    author='Matthijs Berends',
     author_email='m.s.berends@umcg.nl',
     description='A Python wrapper for the AMR R package',
     long_description=open('README.md').read(),

R/ggplot_sir.R

@@ -52,18 +52,15 @@
 #' @param ... other arguments passed on to [geom_sir()] or, in case of [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 *Examples*.
 #' @details At default, the names of antibiotics will be shown on the plots using [ab_name()]. This can be set with the `translate_ab` argument. See [count_df()].
 #'
-#' ### The Functions
 #' [geom_sir()] will take any variable from the data that has an [`sir`] class (created with [as.sir()]) using [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.
 #' 
-#' [facet_sir()] creates 2d plots (at default based on S/I/R) using [ggplot2::facet_wrap()].
+#' Additional functions include:
 #'
-#' [scale_y_percent()] transforms the y axis to a 0 to 100% range using [ggplot2::scale_y_continuous()].
+#' * [facet_sir()] creates 2d plots (at default based on S/I/R) using [ggplot2::facet_wrap()].
-#'
+#' * [scale_y_percent()] transforms the y axis to a 0 to 100% range using [ggplot2::scale_y_continuous()].
-#' [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.
+#' * [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.
-#'
+#' * [theme_sir()] is a [ggplot2 theme][[ggplot2::theme()] with minimal distraction.
-#' [theme_sir()] is a [ggplot2 theme][[ggplot2::theme()] with minimal distraction.
+#' * [labels_sir_count()] print datalabels on the bars with percentage and amount of isolates using [ggplot2::geom_text()].
-#'
-#' [labels_sir_count()] print datalabels on the bars with percentage and amount of isolates using [ggplot2::geom_text()].
 #'
 #' [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 (`%>%`). See *Examples*.
 #' @rdname ggplot_sir
@@ -344,187 +341,3 @@ geom_sir <- function(position = NULL,
     ...
   )
 }
-
-#' @rdname ggplot_sir
-#' @export
-facet_sir <- function(facet = c("interpretation", "antibiotic"), nrow = NULL) {
-  facet <- facet[1]
-  stop_ifnot_installed("ggplot2")
-  meet_criteria(facet, allow_class = "character", has_length = 1)
-  meet_criteria(nrow, allow_class = c("numeric", "integer"), has_length = 1, allow_NULL = TRUE, is_positive = TRUE, is_finite = TRUE)
-
-  # we work with aes_string later on
-  facet_deparse <- deparse(substitute(facet))
-  if (facet_deparse != "facet") {
-    facet <- facet_deparse
-  }
-  if (facet %like% '".*"') {
-    facet <- substr(facet, 2, nchar(facet) - 1)
-  }
-
-  if (tolower(facet) %in% tolower(c("SIR", "sir", "interpretations", "result"))) {
-    facet <- "interpretation"
-  } else if (tolower(facet) %in% tolower(c("ab", "abx", "antibiotics"))) {
-    facet <- "antibiotic"
-  }
-
-  ggplot2::facet_wrap(facets = facet, scales = "free_x", nrow = nrow)
-}
-
-#' @rdname ggplot_sir
-#' @export
-scale_y_percent <- function(breaks = function(x) seq(0, max(x, na.rm = TRUE), 0.1), limits = NULL) {
-  stop_ifnot_installed("ggplot2")
-  meet_criteria(breaks, allow_class = c("numeric", "integer", "function"))
-  meet_criteria(limits, allow_class = c("numeric", "integer"), has_length = 2, allow_NULL = TRUE, allow_NA = TRUE)
-
-  if (!is.function(breaks) && all(breaks[breaks != 0] > 1)) {
-    breaks <- breaks / 100
-  }
-  ggplot2::scale_y_continuous(
-    breaks = breaks,
-    labels = if (is.function(breaks)) function(x) percentage(breaks(x)) else percentage(breaks),
-    limits = limits
-  )
-}
-
-#' @rdname ggplot_sir
-#' @export
-scale_sir_colours <- function(...,
-                              aesthetics = "fill") {
-  stop_ifnot_installed("ggplot2")
-  meet_criteria(aesthetics, allow_class = "character", is_in = c("alpha", "colour", "color", "fill", "linetype", "shape", "size"))
-  # behaviour until AMR pkg v1.5.0 and also when coming from ggplot_sir()
-  if ("colours" %in% names(list(...))) {
-    original_cols <- c(
-      S = "#3CAEA3",
-      SI = "#3CAEA3",
-      I = "#F6D55C",
-      IR = "#ED553B",
-      R = "#ED553B"
-    )
-    colours <- replace(original_cols, names(list(...)$colours), list(...)$colours)
-    # limits = force is needed in ggplot2 3.3.4 and 3.3.5, see here;
-    # https://github.com/tidyverse/ggplot2/issues/4511#issuecomment-866185530
-    return(ggplot2::scale_fill_manual(values = colours, limits = force))
-  }
-  if (identical(unlist(list(...)), FALSE)) {
-    return(invisible())
-  }
-
-  names_susceptible <- c(
-    "S", "SI", "IS", "S+I", "I+S", "susceptible", "Susceptible",
-    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Susceptible"),
-      "replacement",
-      drop = TRUE
-    ])
-  )
-  names_incr_exposure <- c(
-    "I", "intermediate", "increased exposure", "incr. exposure",
-    "Increased exposure", "Incr. exposure", "Susceptible, incr. exp.",
-    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Intermediate"),
-      "replacement",
-      drop = TRUE
-    ]),
-    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Susceptible, incr. exp."),
-      "replacement",
-      drop = TRUE
-    ])
-  )
-  names_resistant <- c(
-    "R", "IR", "RI", "R+I", "I+R", "resistant", "Resistant",
-    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Resistant"),
-      "replacement",
-      drop = TRUE
-    ])
-  )
-
-  susceptible <- rep("#3CAEA3", length(names_susceptible))
-  names(susceptible) <- names_susceptible
-  incr_exposure <- rep("#F6D55C", length(names_incr_exposure))
-  names(incr_exposure) <- names_incr_exposure
-  resistant <- rep("#ED553B", length(names_resistant))
-  names(resistant) <- names_resistant
-
-  original_cols <- c(susceptible, incr_exposure, resistant)
-  dots <- c(...)
-  # replace S, I, R as colours: scale_sir_colours(mydatavalue = "S")
-  dots[dots == "S"] <- "#3CAEA3"
-  dots[dots == "I"] <- "#F6D55C"
-  dots[dots == "R"] <- "#ED553B"
-  cols <- replace(original_cols, names(dots), dots)
-  # limits = force is needed in ggplot2 3.3.4 and 3.3.5, see here;
-  # https://github.com/tidyverse/ggplot2/issues/4511#issuecomment-866185530
-  ggplot2::scale_discrete_manual(aesthetics = aesthetics, values = cols, limits = force)
-}
-
-#' @rdname ggplot_sir
-#' @export
-theme_sir <- function() {
-  stop_ifnot_installed("ggplot2")
-  ggplot2::theme_minimal(base_size = 10) +
-    ggplot2::theme(
-      panel.grid.major.x = ggplot2::element_blank(),
-      panel.grid.minor = ggplot2::element_blank(),
-      panel.grid.major.y = ggplot2::element_line(colour = "grey75"),
-      # center title and subtitle
-      plot.title = ggplot2::element_text(hjust = 0.5),
-      plot.subtitle = ggplot2::element_text(hjust = 0.5)
-    )
-}
-
-#' @rdname ggplot_sir
-#' @export
-labels_sir_count <- function(position = NULL,
-                             x = "antibiotic",
-                             translate_ab = "name",
-                             minimum = 30,
-                             language = get_AMR_locale(),
-                             combine_SI = TRUE,
-                             datalabels.size = 3,
-                             datalabels.colour = "grey15") {
-  stop_ifnot_installed("ggplot2")
-  meet_criteria(position, allow_class = "character", has_length = 1, is_in = c("fill", "stack", "dodge"), allow_NULL = TRUE)
-  meet_criteria(x, allow_class = "character", has_length = 1)
-  meet_criteria(translate_ab, allow_class = c("character", "logical"), has_length = 1, allow_NA = TRUE)
-  meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
-  language <- validate_language(language)
-  meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
-  meet_criteria(datalabels.size, allow_class = c("numeric", "integer"), has_length = 1, is_positive = TRUE, is_finite = TRUE)
-  meet_criteria(datalabels.colour, allow_class = "character", has_length = 1)
-
-  if (is.null(position)) {
-    position <- "fill"
-  }
-  if (identical(position, "fill")) {
-    position <- ggplot2::position_fill(vjust = 0.5, reverse = TRUE)
-  }
-  x_name <- x
-  ggplot2::geom_text(
-    mapping = ggplot2::aes_string(
-      label = "lbl",
-      x = x,
-      y = "value"
-    ),
-    position = position,
-    inherit.aes = FALSE,
-    size = datalabels.size,
-    colour = datalabels.colour,
-    lineheight = 0.75,
-    data = function(x) {
-      transformed <- sir_df(
-        data = x,
-        translate_ab = translate_ab,
-        combine_SI = combine_SI,
-        minimum = minimum,
-        language = language
-      )
-      transformed$gr <- transformed[, x_name, drop = TRUE]
-      transformed %pm>%
-        pm_group_by(gr) %pm>%
-        pm_mutate(lbl = paste0("n=", isolates)) %pm>%
-        pm_ungroup() %pm>%
-        pm_select(-gr)
-    }
-  )
-}

R/mdro.R

@@ -29,7 +29,7 @@
 
 #' Determine Multidrug-Resistant Organisms (MDRO)
 #'
-#' Determine which isolates are multidrug-resistant organisms (MDRO) according to international, national and custom guidelines.
+#' Determine which isolates are multidrug-resistant organisms (MDRO) according to international, national, or custom guidelines.
 #' @param x a [data.frame] with antibiotics columns, like `AMX` or `amox`. Can be left blank for automatic determination.
 #' @param guideline a specific guideline to follow, see sections *Supported international / national guidelines* and *Using Custom Guidelines* below. When left empty, the publication by Magiorakos *et al.* (see below) will be followed.
 #' @param ... in case of [custom_mdro_guideline()]: a set of rules, see section *Using Custom Guidelines* below. Otherwise: column name of an antibiotic, see section *Antibiotics* below.
@@ -76,9 +76,15 @@
 #'
 #' * `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))
+#'   The Dutch national guideline - Samenwerkingverband Richtlijnen Infectiepreventie (SRI) (2024) "Bijzonder Resistente Micro-Organismen (BRMO)" ([link](https://www.sri-richtlijnen.nl/brmo))
 #'   
-#' Please suggest your own (country-specific) guidelines by letting us know: <https://github.com/msberends/AMR/issues/new>.
+#'   Also:
+#'   
+#'   * `guideline = "BRMO 2017"`
+#'
+#'     The former Dutch national guideline - Werkgroep Infectiepreventie (WIP), RIVM, last revision as of 2017: "Bijzonder Resistente Micro-Organismen (BRMO)"
+#'
+#' Please suggest to implement guidelines by letting us know: <https://github.com/msberends/AMR/issues/new>.
 #'
 #' @section Using Custom Guidelines:
 #'
@@ -333,7 +339,7 @@ mdro <- function(x = NULL,
   if (guideline$code == "cmi2012") {
     guideline$name <- "Multidrug-resistant, extensively drug-resistant and pandrug-resistant bacteria: an international expert proposal for interim standard definitions for acquired resistance."
     guideline$author <- "Magiorakos AP, Srinivasan A, Carey RB, ..., Vatopoulos A, Weber JT, Monnet DL"
-    guideline$version <- NA
+    guideline$version <- NA_character_
     guideline$source_url <- paste0("Clinical Microbiology and Infection 18:3, 2012; ", font_url("https://doi.org/10.1111/j.1469-0691.2011.03570.x", "doi: 10.1111/j.1469-0691.2011.03570.x"))
     guideline$type <- "MDRs/XDRs/PDRs"
   } else if (guideline$code == "eucast3.1") {
@@ -365,14 +371,21 @@ mdro <- function(x = NULL,
   } else if (guideline$code == "mrgn") {
     guideline$name <- "Cross-border comparison of the Dutch and German guidelines on multidrug-resistant Gram-negative microorganisms"
     guideline$author <- "M\u00fcller J, Voss A, K\u00f6ck R, ..., Kern WV, Wendt C, Friedrich AW"
-    guideline$version <- NA
+    guideline$version <- NA_character_
     guideline$source_url <- paste0("Antimicrobial Resistance and Infection Control 4:7, 2015; ", font_url("https://doi.org/10.1186/s13756-015-0047-6", "doi: 10.1186/s13756-015-0047-6"))
     guideline$type <- "MRGNs"
   } else if (guideline$code == "brmo") {
+    combine_SI <- TRUE # I must not be considered resistant
+    guideline$name <- "Bijzonder Resistente Micro-organismen (BRMO)"
+    guideline$author <- "Samenwerkingsverband Richtlijnen Infectiepreventie (SRI)"
+    guideline$version <- "November 2024"
+    guideline$source_url <- font_url("https://www.sri-richtlijnen.nl/brmo", "Direct link")
+    guideline$type <- "BRMOs"
+  } else if (guideline$code == "brmo2017") {
     guideline$name <- "WIP-Richtlijn Bijzonder Resistente Micro-organismen (BRMO)"
     guideline$author <- "RIVM (Rijksinstituut voor de Volksgezondheid)"
-    guideline$version <- "Revision as of December 2017"
+    guideline$version <- "Last revision (December 2017) - since 2024 superseded by SRI guideline"
-    guideline$source_url <- font_url("https://www.rivm.nl/Documenten_en_publicaties/Professioneel_Praktisch/Richtlijnen/Infectieziekten/WIP_Richtlijnen/WIP_Richtlijnen/Ziekenhuizen/WIP_richtlijn_BRMO_Bijzonder_Resistente_Micro_Organismen_ZKH", "Direct download")
+    guideline$source_url <- NA_character_
     guideline$type <- "BRMOs"
   } else {
     stop("This guideline is currently unsupported: ", guideline$code, call. = FALSE)
@@ -429,6 +442,17 @@ mdro <- function(x = NULL,
       fn = "mdro",
       ...
     )
+  } else if (guideline$code == "brmo") {
+    # Dutch 2024 guideline
+    cols_ab <- get_column_abx(
+      x = x,
+      soft_dependencies = c("SXT", "GEN", "TOB", "AMK", "IPM", "MEM", "CIP", "LVX", "NOR", "PIP", "CAZ", "VAN", "PEN", "AMX", "AMP", "FLC", "OXA", "FOX", "FOX1"),
+      verbose = verbose,
+      info = info,
+      only_sir_columns = only_sir_columns,
+      fn = "mdro",
+      ...
+    )
   } else if (guideline$code == "mrgn") {
     cols_ab <- get_column_abx(
       x = x,
@@ -524,6 +548,7 @@ mdro <- function(x = NULL,
   FLE <- cols_ab["FLE"]
   FOS <- cols_ab["FOS"]
   FOX <- cols_ab["FOX"]
+  FOX1 <- cols_ab["FOX1"]
   FUS <- cols_ab["FUS"]
   GAT <- cols_ab["GAT"]
   GEH <- cols_ab["GEH"]
@@ -651,7 +676,7 @@ mdro <- function(x = NULL,
   # nolint end
 
   # helper function for editing the table
-  trans_tbl <- function(to, rows, cols, any_all) {
+  trans_tbl <- function(to, rows, cols, any_all, reason = NULL) {
     cols <- cols[!ab_missing(cols)]
     cols <- cols[!is.na(cols)]
     if (length(rows) > 0 && length(cols) > 0) {
@@ -696,14 +721,18 @@ mdro <- function(x = NULL,
       )
       rows_affected <- x[which(rows_affected), "row_number", drop = TRUE]
       rows_to_change <- rows[rows %in% rows_affected]
-      x[rows_to_change, "MDRO"] <<- to
+      rows_not_to_change <- rows[!rows %in% c(rows_affected, rows_to_change)]
-      x[rows_to_change, "reason"] <<- paste0(
+      rows_not_to_change <- rows_not_to_change[is.na(x[rows_not_to_change, "reason"])]
-        any_all,
+      if (is.null(reason)) {
+        reason <- paste0(any_all,
                          " of the required antibiotics ",
                          ifelse(any_all == "any", "is", "are"),
                          " R",
-        ifelse(!isTRUE(combine_SI), " or I", "")
+                         ifelse(!isTRUE(combine_SI), " or I", ""))
-      )
+      }
+      x[rows_to_change, "MDRO"] <<- to
+      x[rows_to_change, "reason"] <<- reason
+      x[rows_not_to_change, "reason"] <<- "guideline criteria not met"
     }
   }
   
@@ -784,7 +813,7 @@ mdro <- function(x = NULL,
   x <- left_join_microorganisms(x, by = col_mo)
   x$MDRO <- ifelse(!is.na(x$genus), 1, NA_integer_)
   x$row_number <- seq_len(nrow(x))
-  x$reason <- paste0("not covered by ", toupper(guideline$code), " guideline")
+  x$reason <- NA_character_
   x$columns_nonsusceptible <- ""
 
   if (guideline$code == "cmi2012") {
@@ -1402,7 +1431,147 @@ mdro <- function(x = NULL,
   }
 
   if (guideline$code == "brmo") {
-    # Netherlands -------------------------------------------------------------
+    # Netherlands 2024 --------------------------------------------------------
+    aminoglycosides <- c(GEN, TOB, AMK) # note 4: gentamicin or tobramycin or amikacin
+    aminoglycosides_serratia_marcescens <- GEN # note 4: TOB and AMK do not count towards S. marcescens
+    fluoroquinolones <- c(CIP, NOR, LVX) # note 5:  ciprofloxacin or norfloxacin or levofloxacin
+    carbapenems <- carbapenems[!is.na(carbapenems)]
+    carbapenems_without_imipenem <- carbapenems[carbapenems != IPM]
+    amino <- AMX %or% AMP
+    third <- CAZ %or% CTX
+    ESBLs <- c(amino, third)
+    ESBLs <- ESBLs[!is.na(ESBLs)]
+    if (length(ESBLs) != 2) {
+      ESBLs <- character(0)
+    }
+    
+    # Enterobacterales
+    if (length(ESBLs) > 0) {
+      trans_tbl(
+        2, # positive, unconfirmed
+        which(x$order == "Enterobacterales" & x[[ESBLs[1]]] == "R" & x[[ESBLs[2]]] == "R"),
+        c(AMX %or% AMP, cephalosporins_3rd),
+        "all",
+        reason = "Enterobacterales: ESBL"
+      )
+    }
+    trans_tbl(
+      3, # positive
+      which(x$order == "Enterobacterales" & (x$genus %in% c("Proteus", "Providencia") | paste(x$genus, x$species) %in% c("Serratia marcescens", "Morganella morganii"))),
+      carbapenems_without_imipenem,
+      "any",
+      reason = "Enterobacterales: carbapenem or carbapenemase"
+    )
+    trans_tbl(
+      3,
+      which(x$order == "Enterobacterales" & !(x$genus %in% c("Proteus", "Providencia") | paste(x$genus, x$species) %in% c("Serratia marcescens", "Morganella morganii"))),
+      carbapenems,
+      "any",
+      reason = "Enterobacterales: carbapenem or carbapenemase"
+    )
+    trans_tbl(
+      3,
+      which(x[[SXT]] == "R" &
+              (x[[GEN]] == "R" | x[[TOB]] == "R" | x[[AMK]] == "R") &
+              (x[[CIP]] == "R" | x[[NOR]] == "R" | x[[LVX]] == "R") &
+              (x$genus %in% c("Enterobacter", "Providencia") | paste(x$genus, x$species) %in% c("Citrobacter freundii", "Klebsiella aerogenes", "Hafnia alvei", "Morganella morganii"))),
+      c(SXT, aminoglycosides, fluoroquinolones),
+      "any",
+      reason = "Enterobacterales group II: aminoglycoside + fluoroquinolone + cotrimoxazol"
+    )
+    trans_tbl(
+      3,
+      which(x[[SXT]] == "R" &
+              x[[GEN]] == "R" &
+              (x[[CIP]] == "R" | x[[NOR]] == "R" | x[[LVX]] == "R") &
+              paste(x$genus, x$species) == "Serratia marcescens"),
+      c(SXT, aminoglycosides_serratia_marcescens, fluoroquinolones),
+      "any",
+      reason = "Enterobacterales group II: aminoglycoside + fluoroquinolone + cotrimoxazol"
+    )
+    
+    # Acinetobacter baumannii-calcoaceticus complex
+    trans_tbl(
+      3,
+      which((x[[GEN]] == "R" | x[[TOB]] == "R" | x[[AMK]] == "R") &
+              (x[[CIP]] == "R" | x[[LVX]] == "R") &
+              x[[col_mo]] %in% AMR::microorganisms.groups$mo[AMR::microorganisms.groups$mo_group_name == "Acinetobacter baumannii complex"]),
+      c(aminoglycosides, CIP, LVX),
+      "any",
+      reason = "A. baumannii-calcoaceticus complex: aminoglycoside + ciprofloxacin or levofloxacin"
+    )
+    trans_tbl(
+      2, # unconfirmed
+      which(x[[col_mo]] %in% AMR::microorganisms.groups$mo[AMR::microorganisms.groups$mo_group_name == "Acinetobacter baumannii complex"]),
+      carbapenems,
+      "any",
+      reason = "A. baumannii-calcoaceticus complex: carbapenemase"
+    )
+    
+    # Pseudomonas aeruginosa
+    if (ab_missing(PIP) && !ab_missing(TZP)) {
+      # take pip/tazo if just pip is not available - many labs only test for pip/tazo because of availability on a Vitek card
+      PIP <- TZP
+    }
+    if (!ab_missing(MEM) && !ab_missing(IPM) &&
+        !ab_missing(GEN) && !ab_missing(TOB) &&
+        !ab_missing(CIP) &&
+        !ab_missing(CAZ) &&
+        !ab_missing(PIP)) {
+      x$psae <- 0
+      x[which(x[, MEM, drop = TRUE] == "R" | x[, IPM, drop = TRUE] == "R"), "psae"] <- 1 + x[which(x[, MEM, drop = TRUE] == "R" | x[, IPM, drop = TRUE] == "R"), "psae"]
+      x[which(x[, GEN, drop = TRUE] == "R" & x[, TOB, drop = TRUE] == "R"), "psae"] <- 1 + x[which(x[, GEN, drop = TRUE] == "R" & x[, TOB, drop = TRUE] == "R"), "psae"]
+      x[which(x[, CIP, drop = TRUE] == "R"), "psae"] <- 1 + x[which(x[, CIP, drop = TRUE] == "R"), "psae"]
+      x[which(x[, CAZ, drop = TRUE] == "R"), "psae"] <- 1 + x[which(x[, CAZ, drop = TRUE] == "R"), "psae"]
+      x[which(x[, PIP, drop = TRUE] == "R"), "psae"] <- 1 + x[which(x[, PIP, drop = TRUE] == "R"), "psae"]
+    } else {
+      x$psae <- 0
+    }
+    trans_tbl(
+      3,
+      which(x$genus == "Pseudomonas" & x$species == "aeruginosa"),
+      c(CAZ, CIP, GEN, IPM, MEM, TOB, PIP),
+      "all", # this will set all negatives to "guideline criteria not met" instead of "not covered by guideline"
+      reason = "P. aeruginosa: at least 3 classes contain R"
+    )
+    trans_tbl(
+      3,
+      which(x$genus == "Pseudomonas" & x$species == "aeruginosa" & x$psae >= 3),
+      c(CAZ, CIP, GEN, IPM, MEM, TOB, PIP),
+      "any", # this is the actual one, changing the ones with x$psae >= 3
+      reason = "P. aeruginosa: at least 3 classes contain R"
+    )
+
+    # Enterococcus faecium
+    trans_tbl(
+      3,
+      which(x$genus == "Enterococcus" & x$species == "faecium"),
+      c(PEN %or% AMX %or% AMP, VAN),
+      "all",
+      reason = "E. faecium: vancomycin or vanA/vanB gene + penicillin group"
+    )
+    
+    # Staphylococcus aureus
+    trans_tbl(
+      2,
+      which(x$genus == "Staphylococcus" & x$species == "aureus"),
+      c(PEN, AMX, AMP, FLC, OXA, FOX, FOX1),
+      "any",
+      reason = "S. aureus: MRSA"
+    )
+    
+    # Candida auris
+    trans_tbl(
+      3,
+      which(x$genus == "Candida" & x$species == "auris"),
+      character(0),
+      "any",
+      reason = "C. auris: regardless of resistance"
+    )
+  }
+  
+  if (guideline$code == "brmo2017") {
+    # Netherlands 2017 --------------------------------------------------------
     aminoglycosides <- aminoglycosides[!is.na(aminoglycosides)]
     fluoroquinolones <- fluoroquinolones[!is.na(fluoroquinolones)]
     carbapenems <- carbapenems[!is.na(carbapenems)]
@@ -1477,10 +1646,7 @@ mdro <- function(x = NULL,
       c(CAZ, CIP, GEN, IPM, MEM, TOB, TZP),
       "any"
     )
-    x[which(
+    x[which(x$genus == "Pseudomonas" & x$species == "aeruginosa" & x$psae >= 3), "reason"] <- paste0("at least 3 classes contain R", ifelse(!isTRUE(combine_SI), " or I", ""))
-      x$genus == "Pseudomonas" & x$species == "aeruginosa" &
-        x$psae >= 3
-    ), "reason"] <- paste0("at least 3 classes contain R", ifelse(!isTRUE(combine_SI), " or I", ""))
     
     # Table 3
     trans_tbl(
@@ -1580,7 +1746,7 @@ mdro <- function(x = NULL,
         " (3 required for MDR)"
       )
     } else {
-      x[which(x$MDRO == 1), "reason"] <- "too few antibiotics are R"
+      #x[which(x$MDRO == 1), "reason"] <- "too few antibiotics are R"
     }
   }
 
@@ -1610,12 +1776,14 @@ mdro <- function(x = NULL,
     if (isTRUE(info.bak)) {
       cat(font_italic(paste0(" (", length(rows_empty), " isolates had no test results)\n")))
     }
-    x[rows_empty, "MDRO"] <- NA
-    x[rows_empty, "reason"] <- "none of the antibiotics have test results"
   } else if (isTRUE(info.bak)) {
     cat("\n")
   }
   
+  if (isTRUE(info.bak) && !isTRUE(verbose)) {
+    cat("\nRerun with 'verbose = TRUE' to retrieve detailed info and reasons for every MDRO classification.\n")
+  }
+
   # Results ----
   if (guideline$code == "cmi2012") {
     if (any(x$MDRO == -1, na.rm = TRUE)) {
@@ -1663,7 +1831,12 @@ mdro <- function(x = NULL,
     )
   }
   
+  
   if (isTRUE(verbose)) {
+    # fill in empty reasons
+    x$reason[is.na(x$reason)] <- "not covered by guideline"
+    x[rows_empty, "reason"] <- paste(x[rows_empty, "reason"], "(note: no available test results)")
+    # format data set
     colnames(x)[colnames(x) == col_mo] <- "microorganism"
     x$microorganism <- mo_name(x$microorganism, language = NULL)
     x[, c(

R/plotting.R

@@ -27,7 +27,7 @@
 # how to conduct AMR data analysis: https://msberends.github.io/AMR/   #
 # ==================================================================== #
 
-#' Plotting for Classes `sir`, `mic` and `disk`
+#' Plotting Helpers for AMR Data Analysis
 #'
 #' @description
 #' Functions to plot classes `sir`, `mic` and `disk`, with support for base \R and `ggplot2`.
@@ -49,6 +49,16 @@
 #' For interpreting MIC values as well as disk diffusion diameters, supported guidelines to be used as input for the `guideline` argument are: `r vector_and(AMR::clinical_breakpoints$guideline, quotes = TRUE, reverse = TRUE)`.
 #'
 #' Simply using `"CLSI"` or `"EUCAST"` as input will automatically select the latest version of that guideline.
+#' 
+#' ### Additional `ggplot2` Functions
+#' 
+#' This package contains several functions that extend the `ggplot2` package, to help in visualising AMR data results. All these functions are internally used by [ggplot_sir()] too.
+#' 
+#' * [facet_sir()] creates 2d plots (at default based on S/I/R) using [ggplot2::facet_wrap()].
+#' * [scale_y_percent()] transforms the y axis to a 0 to 100% range using [ggplot2::scale_y_continuous()].
+#' * [scale_sir_colours()] sets colours to the bars (green for S, yellow for I, and red for R). Has 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.
+#' * [theme_sir()] is a [ggplot2 theme][[ggplot2::theme()] with minimal distraction.
+#' * [labels_sir_count()] print datalabels on the bars with percentage and number of isolates, using [ggplot2::geom_text()].
 #' @name plot
 #' @rdname plot
 #' @return The `autoplot()` functions return a [`ggplot`][ggplot2::ggplot()] model that is extendible with any `ggplot2` function.
@@ -915,3 +925,192 @@ plot_colours_subtitle_guideline <- function(x, mo, ab, guideline, colours_SIR, f
   
   list(cols = cols, count = as.double(x), sub = sub, guideline = guideline)
 }
+
+#' @rdname plot
+#' @export
+facet_sir <- function(facet = c("interpretation", "antibiotic"), nrow = NULL) {
+  facet <- facet[1]
+  stop_ifnot_installed("ggplot2")
+  meet_criteria(facet, allow_class = "character", has_length = 1)
+  meet_criteria(nrow, allow_class = c("numeric", "integer"), has_length = 1, allow_NULL = TRUE, is_positive = TRUE, is_finite = TRUE)
+  
+  # we work with aes_string later on
+  facet_deparse <- deparse(substitute(facet))
+  if (facet_deparse != "facet") {
+    facet <- facet_deparse
+  }
+  if (facet %like% '".*"') {
+    facet <- substr(facet, 2, nchar(facet) - 1)
+  }
+  
+  if (tolower(facet) %in% tolower(c("SIR", "sir", "interpretations", "result"))) {
+    facet <- "interpretation"
+  } else if (tolower(facet) %in% tolower(c("ab", "abx", "antibiotics"))) {
+    facet <- "antibiotic"
+  }
+  
+  ggplot2::facet_wrap(facets = facet, scales = "free_x", nrow = nrow)
+}
+
+#' @rdname plot
+#' @export
+scale_y_percent <- function(breaks = function(x) seq(0, max(x, na.rm = TRUE), 0.1), limits = NULL) {
+  stop_ifnot_installed("ggplot2")
+  meet_criteria(breaks, allow_class = c("numeric", "integer", "function"))
+  meet_criteria(limits, allow_class = c("numeric", "integer"), has_length = 2, allow_NULL = TRUE, allow_NA = TRUE)
+  
+  if (!is.function(breaks) && all(breaks[breaks != 0] > 1)) {
+    breaks <- breaks / 100
+  }
+  ggplot2::scale_y_continuous(
+    breaks = breaks,
+    labels = if (is.function(breaks)) function(x) percentage(breaks(x)) else percentage(breaks),
+    limits = limits
+  )
+}
+
+#' @rdname plot
+#' @export
+scale_sir_colours <- function(...,
+                              aesthetics = "fill",
+                              colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B")) {
+  stop_ifnot_installed("ggplot2")
+  meet_criteria(aesthetics, allow_class = "character", is_in = c("alpha", "colour", "color", "fill", "linetype", "shape", "size"))
+  meet_criteria(colours_SIR, allow_class = "character", has_length = c(1, 3))
+  if (length(colours_SIR) == 1) {
+    colours_SIR <- rep(colours_SIR, 3)
+  }
+  # behaviour until AMR pkg v1.5.0 and also when coming from ggplot_sir()
+  if ("colours" %in% names(list(...))) {
+    original_cols <- c(
+      S = colours_SIR[1],
+      SI = colours_SIR[1],
+      I = colours_SIR[2],
+      IR = colours_SIR[3],
+      R = colours_SIR[3]
+    )
+    colours <- replace(original_cols, names(list(...)$colours), list(...)$colours)
+    # limits = force is needed in ggplot2 3.3.4 and 3.3.5, see here;
+    # https://github.com/tidyverse/ggplot2/issues/4511#issuecomment-866185530
+    return(ggplot2::scale_fill_manual(values = colours, limits = force))
+  }
+  if (identical(unlist(list(...)), FALSE)) {
+    return(invisible())
+  }
+  
+  names_susceptible <- c(
+    "S", "SI", "IS", "S+I", "I+S", "susceptible", "Susceptible",
+    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Susceptible"),
+                        "replacement",
+                        drop = TRUE
+    ])
+  )
+  names_incr_exposure <- c(
+    "I", "intermediate", "increased exposure", "incr. exposure",
+    "Increased exposure", "Incr. exposure", "Susceptible, incr. exp.",
+    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Intermediate"),
+                        "replacement",
+                        drop = TRUE
+    ]),
+    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Susceptible, incr. exp."),
+                        "replacement",
+                        drop = TRUE
+    ])
+  )
+  names_resistant <- c(
+    "R", "IR", "RI", "R+I", "I+R", "resistant", "Resistant",
+    unique(TRANSLATIONS[which(TRANSLATIONS$pattern == "Resistant"),
+                        "replacement",
+                        drop = TRUE
+    ])
+  )
+  
+  susceptible <- rep(colours_SIR[1], length(names_susceptible))
+  names(susceptible) <- names_susceptible
+  incr_exposure <- rep(colours_SIR[2], length(names_incr_exposure))
+  names(incr_exposure) <- names_incr_exposure
+  resistant <- rep(colours_SIR[3], length(names_resistant))
+  names(resistant) <- names_resistant
+  
+  original_cols <- c(susceptible, incr_exposure, resistant)
+  dots <- c(...)
+  # replace S, I, R as colours: scale_sir_colours(mydatavalue = "S")
+  dots[dots == "S"] <- colours_SIR[1]
+  dots[dots == "I"] <- colours_SIR[2]
+  dots[dots == "R"] <- colours_SIR[3]
+  cols <- replace(original_cols, names(dots), dots)
+  # limits = force is needed in ggplot2 3.3.4 and 3.3.5, see here;
+  # https://github.com/tidyverse/ggplot2/issues/4511#issuecomment-866185530
+  ggplot2::scale_discrete_manual(aesthetics = aesthetics, values = cols, limits = force)
+}
+
+#' @rdname plot
+#' @export
+theme_sir <- function() {
+  stop_ifnot_installed("ggplot2")
+  ggplot2::theme_minimal(base_size = 10) +
+    ggplot2::theme(
+      panel.grid.major.x = ggplot2::element_blank(),
+      panel.grid.minor = ggplot2::element_blank(),
+      panel.grid.major.y = ggplot2::element_line(colour = "grey75"),
+      # center title and subtitle
+      plot.title = ggplot2::element_text(hjust = 0.5),
+      plot.subtitle = ggplot2::element_text(hjust = 0.5)
+    )
+}
+
+#' @rdname plot
+#' @export
+labels_sir_count <- function(position = NULL,
+                             x = "antibiotic",
+                             translate_ab = "name",
+                             minimum = 30,
+                             language = get_AMR_locale(),
+                             combine_SI = TRUE,
+                             datalabels.size = 3,
+                             datalabels.colour = "grey15") {
+  stop_ifnot_installed("ggplot2")
+  meet_criteria(position, allow_class = "character", has_length = 1, is_in = c("fill", "stack", "dodge"), allow_NULL = TRUE)
+  meet_criteria(x, allow_class = "character", has_length = 1)
+  meet_criteria(translate_ab, allow_class = c("character", "logical"), has_length = 1, allow_NA = TRUE)
+  meet_criteria(minimum, allow_class = c("numeric", "integer"), has_length = 1, is_positive_or_zero = TRUE, is_finite = TRUE)
+  language <- validate_language(language)
+  meet_criteria(combine_SI, allow_class = "logical", has_length = 1)
+  meet_criteria(datalabels.size, allow_class = c("numeric", "integer"), has_length = 1, is_positive = TRUE, is_finite = TRUE)
+  meet_criteria(datalabels.colour, allow_class = "character", has_length = 1)
+  
+  if (is.null(position)) {
+    position <- "fill"
+  }
+  if (identical(position, "fill")) {
+    position <- ggplot2::position_fill(vjust = 0.5, reverse = TRUE)
+  }
+  x_name <- x
+  ggplot2::geom_text(
+    mapping = ggplot2::aes_string(
+      label = "lbl",
+      x = x,
+      y = "value"
+    ),
+    position = position,
+    inherit.aes = FALSE,
+    size = datalabels.size,
+    colour = datalabels.colour,
+    lineheight = 0.75,
+    data = function(x) {
+      transformed <- sir_df(
+        data = x,
+        translate_ab = translate_ab,
+        combine_SI = combine_SI,
+        minimum = minimum,
+        language = language
+      )
+      transformed$gr <- transformed[, x_name, drop = TRUE]
+      transformed %pm>%
+        pm_group_by(gr) %pm>%
+        pm_mutate(lbl = paste0("n=", isolates)) %pm>%
+        pm_ungroup() %pm>%
+        pm_select(-gr)
+    }
+  )
+}

data-raw/_generate_python_wrapper.sh

@@ -274,7 +274,7 @@ setup(
         'numpy',
         'pandas',
     ],
-    author='Dr. Matthijs Berends',
+    author='Matthijs Berends',
     author_email='m.s.berends@umcg.nl',
     description='A Python wrapper for the AMR R package',
     long_description=open('README.md').read(),

data-raw/gpt_training_text_v2.1.1.9118.txt

@@ -1,5 +1,5 @@
 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.9117. Remember this whenever someone asks which AMR package version you’re at.
+First and foremost, you are trained on version 2.1.1.9118. Remember this whenever someone asks which AMR package version you’re at.
 --------------------------------
 
 THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'NAMESPACE':
@@ -5365,11 +5365,6 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/ggplot_sir.Rd':
 \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(
@@ -5408,28 +5403,6 @@ geom_sir(
   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()}})}
@@ -5483,23 +5456,20 @@ Use these functions to create bar plots for AMR data analysis. All functions rel
 }
 \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()}}.
+Additional functions include:
-
+\itemize{
-\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()}}.
+\item \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()}}.
-
+\item \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.
+\item \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.
-
+\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
-\code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
+\item \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[=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")) {
@@ -7437,7 +7407,12 @@ THE PART HEREAFTER CONTAINS CONTENTS FROM FILE 'man/plot.Rd':
 \alias{plot.sir}
 \alias{autoplot.sir}
 \alias{fortify.sir}
-\title{Plotting for Classes \code{sir}, \code{mic} and \code{disk}}
+\alias{facet_sir}
+\alias{scale_y_percent}
+\alias{scale_sir_colours}
+\alias{theme_sir}
+\alias{labels_sir_count}
+\title{Plotting Helpers for AMR Data Analysis}
 \usage{
 scale_x_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
 
@@ -7535,6 +7510,32 @@ scale_fill_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
 )
 
 \method{fortify}{sir}(object, ...)
+
+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",
+  colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B")
+)
+
+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{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.}
@@ -7583,6 +7584,17 @@ The interpretation of "I" will be named "Increased exposure" for all EUCAST guid
 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.
+\subsection{Additional \code{ggplot2} Functions}{
+
+This package contains several functions that extend the \code{ggplot2} package, to help in visualising AMR data results. All these functions are internally used by \code{\link[=ggplot_sir]{ggplot_sir()}} too.
+\itemize{
+\item \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()}}.
+\item \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()}}.
+\item \code{\link[=scale_sir_colours]{scale_sir_colours()}} sets colours to the bars (green for S, yellow for I, and red for R). Has 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.
+\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
+\item \code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and number of isolates, using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}.
+}
+}
 }
 \examples{
 some_mic_values <- random_mic(size = 100)

man/ggplot_sir.Rd

@@ -3,11 +3,6 @@
 \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(
@@ -46,28 +41,6 @@ geom_sir(
   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()}})}
@@ -121,23 +94,20 @@ Use these functions to create bar plots for AMR data analysis. All functions rel
 }
 \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()}}.
+Additional functions include:
-
+\itemize{
-\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()}}.
+\item \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()}}.
-
+\item \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.
+\item \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.
-
+\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
-\code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
+\item \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[=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")) {

man/mdro.Rd

@@ -77,7 +77,7 @@ Ordered \link{factor} with levels \code{Negative} < \verb{Positive, unconfirmed}
 }
 }
 \description{
-Determine which isolates are multidrug-resistant organisms (MDRO) according to international, national and custom guidelines.
+Determine which isolates are multidrug-resistant organisms (MDRO) according to international, national, or 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}.
@@ -111,10 +111,17 @@ The international guideline for multi-drug resistant tuberculosis - World Health
 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})
+The Dutch national guideline - Samenwerkingverband Richtlijnen Infectiepreventie (SRI) (2024) "Bijzonder Resistente Micro-Organismen (BRMO)" (\href{https://www.sri-richtlijnen.nl/brmo}{link})
+
+Also:
+\itemize{
+\item \code{guideline = "BRMO 2017"}
+
+The former Dutch national guideline - Werkgroep Infectiepreventie (WIP), RIVM, last revision as of 2017: "Bijzonder Resistente Micro-Organismen (BRMO)"
+}
 }
 
-Please suggest your own (country-specific) guidelines by letting us know: \url{https://github.com/msberends/AMR/issues/new}.
+Please suggest to implement guidelines by letting us know: \url{https://github.com/msberends/AMR/issues/new}.
 }
 
 \section{Using Custom Guidelines}{

man/plot.Rd

@@ -15,7 +15,12 @@
 \alias{plot.sir}
 \alias{autoplot.sir}
 \alias{fortify.sir}
-\title{Plotting for Classes \code{sir}, \code{mic} and \code{disk}}
+\alias{facet_sir}
+\alias{scale_y_percent}
+\alias{scale_sir_colours}
+\alias{theme_sir}
+\alias{labels_sir_count}
+\title{Plotting Helpers for AMR Data Analysis}
 \usage{
 scale_x_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
 
@@ -113,6 +118,32 @@ scale_fill_mic(keep_operators = "edges", mic_range = NULL, drop = FALSE, ...)
 )
 
 \method{fortify}{sir}(object, ...)
+
+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",
+  colours_SIR = c("#3CAEA3", "#F6D55C", "#ED553B")
+)
+
+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{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.}
@@ -161,6 +192,17 @@ The interpretation of "I" will be named "Increased exposure" for all EUCAST guid
 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.
+\subsection{Additional \code{ggplot2} Functions}{
+
+This package contains several functions that extend the \code{ggplot2} package, to help in visualising AMR data results. All these functions are internally used by \code{\link[=ggplot_sir]{ggplot_sir()}} too.
+\itemize{
+\item \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()}}.
+\item \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()}}.
+\item \code{\link[=scale_sir_colours]{scale_sir_colours()}} sets colours to the bars (green for S, yellow for I, and red for R). Has 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.
+\item \code{\link[=theme_sir]{theme_sir()}} is a [ggplot2 theme][\code{\link[ggplot2:theme]{ggplot2::theme()}} with minimal distraction.
+\item \code{\link[=labels_sir_count]{labels_sir_count()}} print datalabels on the bars with percentage and number of isolates, using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}.
+}
+}
 }
 \examples{
 some_mic_values <- random_mic(size = 100)

pkgdown/extra.css

@@ -213,6 +213,11 @@ pre .co, .co {
   color: var(--amr-green-dark) !important;
   font-style: italic !important;
 }
+div.sourceCode  pre .co,
+div.sourceCode .co {
+  /* comments in example sections, since functions are already green too */
+  color: var(--bs-gray-600) !important;
+}
 pre code .r-out,
 pre code .r-msg {
   /* output of functions */