% Generated by roxygen2: do not edit by hand % Please edit documentation in R/ggplot_sir.R, R/plotting.R \name{ggplot_sir} \alias{ggplot_sir} \alias{geom_sir} \alias{labels_sir_count} \title{AMR Plots with \code{ggplot2}} \usage{ ggplot_sir( data, position = NULL, x = "antibiotic", fill = "interpretation", facet = NULL, breaks = seq(0, 1, 0.1), limits = NULL, translate_ab = "name", combine_SI, minimum = 30, language = get_AMR_locale(), guideline = getOption("AMR_guideline", "EUCAST"), nrow = NULL, colours = c(S = "#3CAEA3", SDD = "#8FD6C4", SI = "#3CAEA3", I = "#F6D55C", IR = "#ED553B", R = "#ED553B"), datalabels = TRUE, datalabels.size = 2.5, datalabels.colour = "grey15", title = NULL, subtitle = NULL, caption = NULL, x.title = "Antimicrobial", y.title = "Proportion", ... ) geom_sir( position = NULL, x = c("antibiotic", "interpretation"), fill = "interpretation", translate_ab = "name", minimum = 30, language = get_AMR_locale(), combine_SI, guideline = getOption("AMR_guideline", "EUCAST"), ... ) labels_sir_count( position = NULL, x = "antibiotic", fill = "interpretation", translate_ab = "name", minimum = 30, language = get_AMR_locale(), combine_SI, guideline = getOption("AMR_guideline", "EUCAST"), datalabels.size = 3, datalabels.colour = "grey15" ) } \arguments{ \item{data}{A \link{data.frame} with column(s) of class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}}).} \item{position}{Position adjustment of bars, either \code{"fill"}, \code{"stack"} or \code{"dodge"}.} \item{x}{Variable to show on x axis, either \code{"antibiotic"} (default) or \code{"interpretation"} or a grouping variable.} \item{fill}{Variable to categorise using the plots legend, either \code{"interpretation"} (default) or \code{"antibiotic"} or a grouping variable. For \code{\link[=labels_sir_count]{labels_sir_count()}}, this must be the same as the \code{fill} of \code{\link[=geom_sir]{geom_sir()}}, so that the labels are placed on the right bars. If the interpretation is not shown in the plot (i.e., neither in \code{x}, \code{fill}, nor \code{facet}), only the susceptible proportion is plotted, which follows the guideline (see \code{guideline}): S+SDD+I for EUCAST, S+SDD for CLSI, and S if \code{guideline = NULL}.} \item{facet}{Variable to split plots by, either \code{"interpretation"} or \code{"antibiotic"} or a grouping variable. If there is more than one antimicrobial and the antimicrobial is not shown in the plot (i.e., neither in \code{x}, \code{fill}, nor \code{facet}), \code{\link[=ggplot_sir]{ggplot_sir()}} splits the plot by antimicrobial, as their bars would otherwise be stacked: using \code{facet = "antibiotic"} if \code{facet} is not set, and otherwise using a grid of \code{facet} by antimicrobial. Note that \code{\link[=geom_sir]{geom_sir()}} cannot do this, so add \code{\link[=facet_sir]{facet_sir()}} in that case.} \item{breaks}{A \link{numeric} vector of positions.} \item{limits}{A \link{numeric} vector of length two providing limits of the scale, use \code{NA} to refer to the existing minimum or maximum.} \item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}.} \item{combine_SI}{\emph{(deprecated in favour of \code{guideline})} A \link{logical}. If set, it takes precedence over \code{guideline}: \code{TRUE} merges S, SDD, and I into \code{"SI"} vs. \code{"R"}, and \code{FALSE} keeps S, I, and R separate.} \item{minimum}{The minimum allowed number of available (tested) isolates. Any isolate count lower than \code{minimum} will return \code{NA} with a warning. The default number of \code{30} isolates is advised by the Clinical and Laboratory Standards Institute (CLSI) as best practice, see \emph{Source}.} \item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.} \item{guideline}{A guideline name, \code{"EUCAST"} or \code{"CLSI"} (or any version thereof, e.g. \code{"CLSI 2025"}), to determine whether the 'I' category is considered susceptible (EUCAST) or resistant (CLSI). The default is the package option \code{\link[=AMR-options]{AMR_guideline}}, or \code{"EUCAST"} if it is not set. For functions that return results per category, i.e., \code{\link[=count_df]{count_df()}}, \code{\link[=proportion_df]{proportion_df()}}, \code{\link[=sir_df]{sir_df()}}, \code{\link[=ggplot_sir]{ggplot_sir()}}, \code{\link[=geom_sir]{geom_sir()}}, and \code{\link[=labels_sir_count]{labels_sir_count()}}, this can also be \code{NULL} or \code{FALSE} to keep S, I, and R separate. See section \emph{Interpretation of SIR} below.} \item{nrow}{(when using \code{facet}) number of rows.} \item{colours}{A named vactor with colour to be used for filling. The default colours are colour-blind friendly.} \item{datalabels}{Show datalabels using \code{\link[=labels_sir_count]{labels_sir_count()}}.} \item{datalabels.size}{Size of the datalabels.} \item{datalabels.colour}{Colour of the datalabels.} \item{title}{Text to show as title of the plot.} \item{subtitle}{Text to show as subtitle of the plot.} \item{caption}{Text to show as caption of the plot.} \item{x.title}{Text to show as x axis description.} \item{y.title}{Text to show as y axis description.} \item{...}{Other arguments passed on to \code{\link[=geom_sir]{geom_sir()}} or, in case of \code{\link[=scale_sir_colours]{scale_sir_colours()}}, named values to set colours. The default colours are colour-blind friendly, while maintaining the convention that e.g. 'susceptible' should be green and 'resistant' should be red. See \emph{Examples}.} } \description{ Use these functions to create bar plots for AMR data analysis. All functions rely on \link[ggplot2:ggplot]{ggplot2} functions. } \details{ At default, the names of antimicrobials 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()}}. \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 antimicrobials on the x axis. Additional functions include: \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_y_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). 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 \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[=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}. } \section{Interpretation of SIR}{ In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST) has decided to change the definitions of susceptibility testing categories S, I, and R (\url{https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}). In aggregated analyses, such as proportions, counts, antibiograms, and plots, the 'I' category must be considered either susceptible or resistant. In epidemiological AMR data analysis, this follows the guideline: EUCAST considers 'I' susceptible, while CLSI considers 'I' resistant. The dose-dependent susceptibility of CLSI ('SDD') is always considered susceptible, as it equals what EUCAST defines as 'I'. All functions with a \code{guideline} argument for this purpose use these categories:\tabular{lll}{ \code{guideline} \tab Susceptible \tab Resistant \cr \code{"EUCAST"} \tab S, SDD, I, WT \tab R, NWT, NS \cr \code{"CLSI"} \tab S, SDD, WT \tab I, R, NWT, NS \cr } The values 'WT' (wild type) and 'NWT' (non-wild type) result from epidemiological cut-off values (ECOFFs) instead of clinical breakpoints. Since they are no clinical categories, 'WT' is always considered susceptible and 'NWT' always resistant, regardless of the guideline. The value 'NS' (non-susceptible) is always considered resistant, and 'NI' (non-interpretable) is always considered a missing result. The \code{guideline} argument can be: \itemize{ \item \strong{Left unset}, to use the package option \code{\link[=AMR-options]{AMR_guideline}}, or \code{"EUCAST"} if this option is not set. In the latter case, a message is shown once per session (but not in R Markdown or Quarto documents); set the option to silence it. \item \strong{\code{"EUCAST"}}, or any EUCAST version such as \code{"EUCAST 2025"}, to consider 'I' susceptible, e.g., to return \code{"SI"} vs. \code{"R"} in \code{\link[=proportion_df]{proportion_df()}}. \item \strong{\code{"CLSI"}}, or any CLSI version such as \code{"CLSI 2025"}, to consider 'I' resistant, e.g., to return \code{"S"} vs. \code{"IR"} in \code{\link[=proportion_df]{proportion_df()}}. \item \strong{\code{NULL} or \code{FALSE}}, to keep S, I, and R separate. This is only possible in functions that return results per category: \code{\link[=count_df]{count_df()}}, \code{\link[=proportion_df]{proportion_df()}}, \code{\link[=sir_df]{sir_df()}}, \code{\link[=ggplot_sir]{ggplot_sir()}}, \code{\link[=geom_sir]{geom_sir()}}, \code{\link[=labels_sir_count]{labels_sir_count()}}, and \code{\link[=bug_drug_combinations]{bug_drug_combinations()}}. Functions that return a single proportion or count, such as \code{\link[=susceptibility]{susceptibility()}}, \code{\link[=count_resistant]{count_resistant()}}, \code{\link[=antibiogram]{antibiogram()}}, \code{\link[=wisca]{wisca()}}, and \code{\link[=format]{format()}} on the result of \code{\link[=bug_drug_combinations]{bug_drug_combinations()}}, require 'I' to be considered either susceptible or resistant, and return an error. } Use \code{\link[=susceptibility]{susceptibility()}} and \code{\link[=resistance]{resistance()}} (or \code{\link[=count_susceptible]{count_susceptible()}} and \code{\link[=count_resistant]{count_resistant()}}) to follow the guideline, or e.g. \code{\link[=proportion_SI]{proportion_SI()}} and \code{\link[=proportion_R]{proportion_R()}} to be explicit regardless of the guideline. The \code{combine_SI} argument of the functions that return results per category, \code{\link[=antibiogram]{antibiogram()}}, and \code{\link[=wisca]{wisca()}} is deprecated in favour of \code{guideline}. If set, it is followed literally and takes precedence over \code{guideline}. } \examples{ \donttest{ if (require("ggplot2") && require("dplyr")) { # get antimicrobial results for drugs against a UTI: ggplot(example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP)) + geom_sir() } if (require("ggplot2") && require("dplyr")) { # prettify the plot using some additional functions: df <- example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP) ggplot(df) + geom_sir() + scale_y_percent() + scale_sir_colours(aesthetics = "fill") + labels_sir_count() + theme_sir() } if (require("ggplot2") && require("dplyr")) { # or better yet, simplify this using the wrapper function - a single command: example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP) \%>\% ggplot_sir() } if (require("ggplot2") && require("dplyr")) { # get only proportions and no counts: example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP) \%>\% ggplot_sir(datalabels = FALSE) } if (require("ggplot2") && require("dplyr")) { # add other ggplot2 arguments as you like: example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP) \%>\% ggplot_sir( width = 0.5, colour = "black", size = 1, linetype = 2, alpha = 0.25 ) } if (require("ggplot2") && require("dplyr")) { # you can alter the colours with colour names: example_isolates \%>\% select(AMX) \%>\% ggplot_sir(colours = c(SI = "yellow")) } if (require("ggplot2") && require("dplyr")) { # but you can also use the built-in colour-blind friendly colours for # your plots, where "S" is green, "I" is yellow and "R" is red: data.frame( x = c("Value1", "Value2", "Value3"), y = c(1, 2, 3), z = c("Value4", "Value5", "Value6") ) \%>\% ggplot() + geom_col(aes(x = x, y = y, fill = z)) + scale_sir_colours( aesthetics = "fill", Value4 = "S", Value5 = "I", Value6 = "R" ) } if (require("ggplot2") && require("dplyr")) { # resistance of ciprofloxacine per age group example_isolates \%>\% mutate(first_isolate = first_isolate()) \%>\% filter( first_isolate == TRUE, mo == as.mo("Escherichia coli") ) \%>\% # age_groups() is also a function in this AMR package: group_by(age_group = age_groups(age)) \%>\% select(age_group, CIP) \%>\% ggplot_sir(x = "age_group") } if (require("ggplot2") && require("dplyr")) { # a shorter version which also adjusts data label colours: example_isolates \%>\% select(AMX, NIT, FOS, TMP, CIP) \%>\% ggplot_sir(colours = FALSE) } if (require("ggplot2") && require("dplyr")) { # it also supports groups (don't forget to use the group var on `x` or `facet`): example_isolates \%>\% filter(mo_is_gram_negative(), ward != "Outpatient") \%>\% # select only UTI-specific drugs select(ward, AMX, NIT, FOS, TMP, CIP) \%>\% group_by(ward) \%>\% ggplot_sir( x = "ward", facet = "antibiotic", nrow = 1, title = "AMR of Anti-UTI Drugs Per Ward", x.title = "Ward", datalabels = FALSE ) } } }