% Generated by roxygen2: do not edit by hand % Please edit documentation in R/sir_combine.R \name{sir_combine} \alias{sir_combine} \title{Combine SIR Results of Multiple Antimicrobials} \usage{ sir_combine( ..., method = c("most_susceptible", "most_resistant"), only_all_tested = FALSE, guideline = getOption("AMR_guideline", "EUCAST") ) } \arguments{ \item{...}{Two or more vectors (or columns) with antimicrobial interpretations, or a data frame with such columns. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. All vectors must be of the same length.} \item{method}{Either \code{"most_susceptible"} (default) to return the most susceptible result, as for combination therapy, or \code{"most_resistant"} to return the most resistant result, as for resistance within a group of antimicrobials. See \emph{Combination Therapy} below.} \item{only_all_tested}{A \link{logical} to indicate that isolates must be tested for all antimicrobials. If \code{TRUE}, the result is \code{NA} for isolates with a missing result for any of the antimicrobials. If \code{FALSE} (default), a missing result only leads to \code{NA} if a result for the missing antimicrobial could have changed the result, see \emph{Combination Therapy} below.} \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). This only affects isolates with a missing result for any of the antimicrobials when \code{only_all_tested = FALSE}, see \emph{Combination Therapy} below. The default is the package option \code{\link[=AMR-options]{AMR_guideline}}, or \code{"EUCAST"} if it is not set. See section \emph{Interpretation of SIR} below.} } \value{ A \code{\link{sir}} vector with the same length as the input. } \description{ Combine the SIR results of two or more antimicrobials into one SIR result per isolate. This can answer two different questions, set with the \code{method} argument: \itemize{ \item \code{"most_susceptible"} (default): \emph{Is at least one of these antimicrobials expected to work?} This is the result of a combination therapy, e.g. piperacillin/tazobactam with gentamicin, which covers the isolate if any of its antimicrobials is active. \item \code{"most_resistant"}: \emph{Is resistance demonstrated to any of these antimicrobials?} This is the result for a group of antimicrobials, e.g. resistance to third-generation cephalosporins if an isolate is resistant to ceftazidime or ceftriaxone, as used in surveillance reports. } See \emph{Combination Therapy} below for the exact rules. The same rules are used by \code{\link[=antibiogram]{antibiogram()}} and \code{\link[=wisca]{wisca()}} for combination antibiograms, and by the \code{\link[=count]{count_*()}} and \code{\link[=proportion]{proportion_*()}} functions when more than one variable is used. } \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. } \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{ drug_a <- as.sir(c("S", "R", "R", "I", "I", NA, "R", "SDD")) drug_b <- as.sir(c("R", "S", "R", "R", NA, NA, NA, "I")) # combination therapy: is at least one of them expected to work? sir_combine(drug_a, drug_b) sir_combine(drug_a, drug_b, guideline = "CLSI") sir_combine(drug_a, drug_b, only_all_tested = TRUE) # resistance within a group: is resistance demonstrated to any of them? sir_combine(drug_a, drug_b, method = "most_resistant") # the count and proportion functions use the same rules susceptibility(drug_a, drug_b, minimum = 0) susceptibility(sir_combine(drug_a, drug_b), minimum = 0) resistance(drug_a, drug_b, minimum = 0) resistance(sir_combine(drug_a, drug_b, method = "most_resistant"), minimum = 0) \donttest{ if (require("dplyr")) { # create a new variable for piperacillin/tazobactam + gentamicin example_isolates \%>\% filter(!is.na(TZP)) \%>\% mutate(TZP_GEN = sir_combine(TZP, GEN)) \%>\% select(mo, TZP, GEN, TZP_GEN) } if (require("dplyr")) { # resistance to third-generation cephalosporins example_isolates \%>\% mutate(cephalosporins_3rd = sir_combine(CAZ, CRO, method = "most_resistant")) \%>\% count(cephalosporins_3rd) } if (require("dplyr")) { # combine any number of antimicrobials example_isolates \%>\% mutate(any_aminoglycoside = sir_combine(GEN, TOB, AMK, KAN)) \%>\% count(any_aminoglycoside) } if (require("dplyr")) { # use the new variable in further analyses # THOUGH CONSIDER wisca() FOR RELIABLE ESTIMATES example_isolates \%>\% mutate(TZP_GEN = sir_combine(TZP, GEN)) \%>\% group_by(ward) \%>\% summarise( TZP_mono = susceptibility(TZP), GEN_mono = susceptibility(GEN), TZP_GEN = susceptibility(TZP_GEN), # or directly, without combining first: TZP_GEN2 = susceptibility(TZP, GEN) ) } } } \seealso{ \code{\link[=count]{count()}} and \code{\link[=proportion]{proportion()}} for counting and calculating susceptibility of (combinations of) antimicrobials, and \code{\link[=antibiogram]{antibiogram()}} for combination antibiograms. }