% Generated by roxygen2: do not edit by hand % Please edit documentation in R/proportion.R, R/sir_df.R \name{proportion} \alias{proportion} \alias{resistance} \alias{portion} \alias{susceptibility} \alias{sir_confidence_interval} \alias{proportion_R} \alias{proportion_IR} \alias{proportion_I} \alias{proportion_SI} \alias{proportion_S} \alias{proportion_df} \alias{sir_df} \title{Calculate Antimicrobial Resistance} \usage{ resistance( ..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE, guideline = getOption("AMR_guideline", "EUCAST") ) susceptibility( ..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE, guideline = getOption("AMR_guideline", "EUCAST") ) sir_confidence_interval( ..., ab_result = "R", minimum = 30, as_percent = FALSE, only_all_tested = FALSE, confidence_level = 0.95, side = "both", collapse = FALSE ) proportion_R(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE) proportion_IR(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE) proportion_I(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE) proportion_SI(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE) proportion_S(..., minimum = 30, as_percent = FALSE, only_all_tested = FALSE) proportion_df( data, translate_ab = "name", language = get_AMR_locale(), minimum = 30, as_percent = FALSE, combine_SI, confidence_level = 0.95, guideline = getOption("AMR_guideline", "EUCAST") ) sir_df( data, translate_ab = "name", language = get_AMR_locale(), minimum = 30, as_percent = FALSE, combine_SI, confidence_level = 0.95, guideline = getOption("AMR_guideline", "EUCAST") ) } \arguments{ \item{...}{One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See \emph{Examples}.} \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{as_percent}{A \link{logical} to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.} \item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below. Use \code{\link[=sir_combine]{sir_combine()}} to create a new variable for a combination therapy.} \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{ab_result}{Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R".} \item{confidence_level}{The confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.} \item{side}{The side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.} \item{collapse}{A \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing.} \item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}}).} \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{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{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.} } \value{ A \link{double} or, when \code{as_percent = TRUE}, a \link{character}. } \description{ These functions can be used to calculate the (co-)resistance or susceptibility of microbial isolates (i.e. percentage of S, SI, I, IR or R). All functions support quasiquotation with pipes, can be used in \code{summarise()} from the \code{dplyr} package and also support grouped variables, see \emph{Examples}. \code{\link[=resistance]{resistance()}} should be used to calculate resistance, \code{\link[=susceptibility]{susceptibility()}} should be used to calculate susceptibility.\cr } \details{ For a more automated and comprehensive analysis, consider using \code{\link[=antibiogram]{antibiogram()}} or \code{\link[=wisca]{wisca()}}, which streamline many aspects of susceptibility reporting and, importantly, also support WISCA. The functions described here offer a more hands-on, manual approach for greater customisation. \strong{Remember that you should filter your data to let it contain only first isolates!} This is needed to exclude duplicates and to reduce selection bias. Use \code{\link[=first_isolate]{first_isolate()}} to determine them in your data set with one of the four available algorithms. The function \code{\link[=resistance]{resistance()}} is equal to the function \code{\link[=proportion_R]{proportion_R()}}. The function \code{\link[=susceptibility]{susceptibility()}} is equal to the function \code{\link[=proportion_SI]{proportion_SI()}}. Since AMR v3.0, \code{\link[=proportion_SI]{proportion_SI()}} and \code{\link[=proportion_I]{proportion_I()}} include dose-dependent susceptibility ('SDD'). Use \code{\link[=sir_confidence_interval]{sir_confidence_interval()}} to calculate the confidence interval, which relies on \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method. This function returns a vector of length 2 at default for antimicrobial \emph{resistance}. Change the \code{side} argument to "left"/"min" or "right"/"max" to return a single value, and change the \code{ab_result} argument to e.g. \code{c("S", "I")} to test for antimicrobial \emph{susceptibility}, see Examples. These functions are not meant to count isolates, but to calculate the proportion of resistance/susceptibility. Use the \code{\link[=count]{count_*()}} functions to count isolates. The function \code{\link[=susceptibility]{susceptibility()}} is essentially equal to \code{\link[=count_susceptible]{count_susceptible()}}\code{/}\code{\link[=count_all]{count_all()}}. \emph{Low counts can influence the outcome - the \verb{proportion_*()} functions may camouflage this, since they only return the proportion (albeit dependent on the \code{minimum} argument).} The function \code{\link[=proportion_df]{proportion_df()}} takes any variable from \code{data} that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) and calculates the proportions S, I, and R. It also supports grouped variables. The function \code{\link[=sir_df]{sir_df()}} works exactly like \code{\link[=proportion_df]{proportion_df()}}, but adds the number of isolates. } \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}. } \section{Combination Therapy}{ Results are ordered from susceptible to resistant: S (and WT), SDD, I, R (and NWT, NS). With \code{method = "most_susceptible"} (in \code{\link[=sir_combine]{sir_combine()}}), the most susceptible result of the antimicrobials is returned, and with \code{method = "most_resistant"}, the most resistant result. The value \code{"NI"} (non-interpretable) is considered a missing result. A missing result can only be ignored if it cannot change the conclusion: a susceptible result for \code{"most_susceptible"}, and a non-susceptible result for \code{"most_resistant"}. Under EUCAST, the 'I' category is considered susceptible (\emph{susceptible, increased exposure}), and under CLSI, it is not. With \code{only_all_tested = TRUE}, any missing result leads to \code{NA}. This is an example for two antimicrobials, Drug A and Drug B, under EUCAST (the order of the antimicrobials does not matter): \if{html}{\out{
}}\preformatted{------------------------------------------------------------------------- Result of method = Result of method = "most_susceptible" "most_resistant" ----------------------- ----------------------------- only_all_tested = only_all_tested = Drug A Drug B FALSE TRUE FALSE TRUE -------- -------- --------- --------- ----------- ------------- S S S S S S S I S S I I S R S S R R I R I I R R R R R R R R S S I I R R ------------------------------------------------------------------------- }\if{html}{\out{
}} Under CLSI, the combination of I with a missing result is \verb{} for \code{"most_susceptible"} and I for \code{"most_resistant"}. The \code{\link[=count]{count_*()}} and \code{\link[=proportion]{proportion_*()}} functions apply these rules when more than one variable is used. With \code{only_all_tested = FALSE} (default), the functions for susceptibility, such as \code{\link[=susceptibility]{susceptibility()}} and \code{\link[=count_susceptible]{count_susceptible()}}, count an isolate as susceptible if any of the antimicrobials is susceptible (\code{"most_susceptible"}), and the functions for resistance, such as \code{\link[=resistance]{resistance()}} and \code{\link[=count_resistant]{count_resistant()}}, count an isolate as resistant if any of the antimicrobials is resistant (\code{"most_resistant"}). An isolate is considered tested if it has such a result, or if it was tested for all antimicrobials. Therefore, for combinations with \code{only_all_tested = FALSE}: \if{html}{\out{
}}\preformatted{ count_S() + count_I() + count_R() >= count_all() proportion_S() + proportion_I() + proportion_R() >= 1 }\if{html}{\out{
}} With \code{only_all_tested = TRUE}, all these functions count the result of the combination therapy (\code{"most_susceptible"}) of isolates tested for all antimicrobials, so that: \if{html}{\out{
}}\preformatted{ count_S() + count_I() + count_R() = count_all() proportion_S() + proportion_I() + proportion_R() = 1 }\if{html}{\out{
}} In \code{\link[=antibiogram]{antibiogram()}} and \code{\link[=wisca]{wisca()}}, the result of the combination therapy (\code{"most_susceptible"}) is used, the 'I' category is considered susceptible or not following the \code{guideline} argument ('SDD' is always considered susceptible), and the result is then reduced to S or R. } \examples{ # example_isolates is a data set available in the AMR package. # run ?example_isolates for more info. example_isolates # base R ------------------------------------------------------------ # determines \%R resistance(example_isolates$AMX) sir_confidence_interval(example_isolates$AMX) sir_confidence_interval(example_isolates$AMX, confidence_level = 0.975 ) sir_confidence_interval(example_isolates$AMX, confidence_level = 0.975, collapse = ", " ) # determines \%S+I: susceptibility(example_isolates$AMX) sir_confidence_interval(example_isolates$AMX, ab_result = c("S", "I") ) # be more specific proportion_S(example_isolates$AMX) proportion_SI(example_isolates$AMX) proportion_I(example_isolates$AMX) proportion_IR(example_isolates$AMX) proportion_R(example_isolates$AMX) # dplyr ------------------------------------------------------------- \donttest{ if (require("dplyr")) { example_isolates \%>\% group_by(ward) \%>\% summarise( r = resistance(CIP), n = n_sir(CIP) ) # n_sir works like n_distinct in dplyr, see ?n_sir } if (require("dplyr")) { example_isolates \%>\% group_by(ward) \%>\% summarise( cipro_R = resistance(CIP), ci_min = sir_confidence_interval(CIP, side = "min"), ci_max = sir_confidence_interval(CIP, side = "max"), ) } if (require("dplyr")) { # scoped dplyr verbs with antimicrobial selectors # (you could also use across() of course) example_isolates \%>\% group_by(ward) \%>\% summarise_at( c(aminoglycosides(), carbapenems()), resistance ) } if (require("dplyr")) { example_isolates \%>\% group_by(ward) \%>\% summarise( R = resistance(CIP, as_percent = TRUE), SI = susceptibility(CIP, as_percent = TRUE), n1 = count_all(CIP), # the actual total; sum of all three n2 = n_sir(CIP), # same - analogous to n_distinct total = n() ) # NOT the number of tested isolates! # Calculate co-resistance between amoxicillin/clav acid and gentamicin, # so we can see that combination therapy does a lot more than mono therapy: example_isolates \%>\% susceptibility(AMC) # \%SI = 76.3\% example_isolates \%>\% count_all(AMC) # n = 1879 example_isolates \%>\% susceptibility(GEN) # \%SI = 75.4\% example_isolates \%>\% count_all(GEN) # n = 1855 example_isolates \%>\% susceptibility(AMC, GEN) # \%SI = 94.1\% example_isolates \%>\% count_all(AMC, GEN) # n = 1939 # See Details on how `only_all_tested` works. Example: example_isolates \%>\% summarise( numerator = count_susceptible(AMC, GEN), denominator = count_all(AMC, GEN), proportion = susceptibility(AMC, GEN) ) example_isolates \%>\% summarise( numerator = count_susceptible(AMC, GEN, only_all_tested = TRUE), denominator = count_all(AMC, GEN, only_all_tested = TRUE), proportion = susceptibility(AMC, GEN, only_all_tested = TRUE) ) example_isolates \%>\% group_by(ward) \%>\% summarise( cipro_p = susceptibility(CIP, as_percent = TRUE), cipro_n = count_all(CIP), genta_p = susceptibility(GEN, as_percent = TRUE), genta_n = count_all(GEN), combination_p = susceptibility(CIP, GEN, as_percent = TRUE), combination_n = count_all(CIP, GEN) ) # Get proportions S/I/R immediately of all sir columns example_isolates \%>\% select(AMX, CIP) \%>\% proportion_df(translate = FALSE) # It also supports grouping variables # (use sir_df to also include the count) example_isolates \%>\% select(ward, AMX, CIP) \%>\% group_by(ward) \%>\% sir_df(translate = FALSE) } } } \references{ \strong{M39 Analysis and Presentation of Cumulative Antimicrobial Susceptibility Test Data, 5th Edition}, 2022, \emph{Clinical and Laboratory Standards Institute (CLSI)}. \url{https://clsi.org/standards/products/microbiology/documents/m39/}. } \seealso{ \code{\link[=count]{count()}} to count resistant and susceptible isolates. }