mirror of
https://github.com/msberends/AMR.git
synced 2025-04-17 19:10:38 +02:00
154 lines
12 KiB
R
154 lines
12 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/eucast_rules.R
|
|
\name{eucast_rules}
|
|
\alias{eucast_rules}
|
|
\alias{EUCAST}
|
|
\alias{eucast_dosage}
|
|
\title{Apply EUCAST Rules}
|
|
\source{
|
|
\itemize{
|
|
\item EUCAST Expert Rules. Version 2.0, 2012.\cr
|
|
Leclercq et al. \strong{EUCAST expert rules in antimicrobial susceptibility testing.} \emph{Clin Microbiol Infect.} 2013;19(2):141-60; \doi{https://doi.org/10.1111/j.1469-0691.2011.03703.x}
|
|
\item EUCAST Expert Rules, Intrinsic Resistance and Exceptional Phenotypes Tables. Version 3.1, 2016. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/Expert_rules_intrinsic_exceptional_V3.1.pdf}{(link)}
|
|
\item EUCAST Intrinsic Resistance and Unusual Phenotypes. Version 3.2, 2020. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2020/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.2_20200225.pdf}{(link)}
|
|
\item EUCAST Intrinsic Resistance and Unusual Phenotypes. Version 3.3, 2021. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Expert_Rules/2021/Intrinsic_Resistance_and_Unusual_Phenotypes_Tables_v3.3_20211018.pdf}{(link)}
|
|
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 9.0, 2019. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_9.0_Breakpoint_Tables.xlsx}{(link)}
|
|
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 10.0, 2020. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_10.0_Breakpoint_Tables.xlsx}{(link)}
|
|
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 11.0, 2021. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_11.0_Breakpoint_Tables.xlsx}{(link)}
|
|
\item EUCAST Breakpoint tables for interpretation of MICs and zone diameters. Version 12.0, 2022. \href{https://www.eucast.org/fileadmin/src/media/PDFs/EUCAST_files/Breakpoint_tables/v_12.0_Breakpoint_Tables.xlsx}{(link)}
|
|
}
|
|
}
|
|
\usage{
|
|
eucast_rules(x, col_mo = NULL, info = interactive(),
|
|
rules = getOption("AMR_eucastrules", default = c("breakpoints",
|
|
"expected_phenotypes")), verbose = FALSE, version_breakpoints = 14,
|
|
version_expected_phenotypes = 1.2, version_expertrules = 3.3,
|
|
ampc_cephalosporin_resistance = NA, only_sir_columns = FALSE,
|
|
custom_rules = NULL, overwrite = FALSE, ...)
|
|
|
|
eucast_dosage(ab, administration = "iv", version_breakpoints = 12)
|
|
}
|
|
\arguments{
|
|
\item{x}{a data set with antimicrobials columns, such as \code{amox}, \code{AMX} and \code{AMC}}
|
|
|
|
\item{col_mo}{column name of the names or codes of the microorganisms (see \code{\link[=as.mo]{as.mo()}}) - the default is the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
|
|
|
|
\item{info}{a \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions}
|
|
|
|
\item{rules}{a \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_eucastrules}}: \code{options(AMR_eucastrules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.}
|
|
|
|
\item{verbose}{a \link{logical} to turn Verbose mode on and off (default is off). In Verbose mode, the function does not apply rules to the data, but instead returns a data set in logbook form with extensive info about which rows and columns would be effected and in which way. Using Verbose mode takes a lot more time.}
|
|
|
|
\item{version_breakpoints}{the version number to use for the EUCAST Clinical Breakpoints guideline. Can be "14.0", "13.1", "12.0", "11.0", or "10.0".}
|
|
|
|
\item{version_expected_phenotypes}{the version number to use for the EUCAST Expected Phenotypes. Can be "1.2".}
|
|
|
|
\item{version_expertrules}{the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be "3.3", "3.2", or "3.1".}
|
|
|
|
\item{ampc_cephalosporin_resistance}{a \link{character} value that should be applied to cefotaxime, ceftriaxone and ceftazidime for AmpC de-repressed cephalosporin-resistant mutants - the default is \code{NA}. Currently only works when \code{version_expertrules} is \code{3.2} and higher; these version of '\emph{EUCAST Expert Rules on Enterobacterales}' state that results of cefotaxime, ceftriaxone and ceftazidime should be reported with a note, or results should be suppressed (emptied) for these three drugs. A value of \code{NA} (the default) for this argument will remove results for these three drugs, while e.g. a value of \code{"R"} will make the results for these drugs resistant. Use \code{NULL} or \code{FALSE} to not alter results for these three drugs of AmpC de-repressed cephalosporin-resistant mutants. Using \code{TRUE} is equal to using \code{"R"}. \cr For \emph{EUCAST Expert Rules} v3.2, this rule applies to: \emph{Citrobacter braakii}, \emph{Citrobacter freundii}, \emph{Citrobacter gillenii}, \emph{Citrobacter murliniae}, \emph{Citrobacter rodenticum}, \emph{Citrobacter sedlakii}, \emph{Citrobacter werkmanii}, \emph{Citrobacter youngae}, \emph{Enterobacter}, \emph{Hafnia alvei}, \emph{Klebsiella aerogenes}, \emph{Morganella morganii}, \emph{Providencia}, and \emph{Serratia}.}
|
|
|
|
\item{only_sir_columns}{a \link{logical} to indicate whether only antimicrobial columns must be detected that were transformed to class \code{sir} (see \code{\link[=as.sir]{as.sir()}}) on beforehand (default is \code{FALSE})}
|
|
|
|
\item{custom_rules}{custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}}
|
|
|
|
\item{overwrite}{A \link{logical} indicating whether to overwrite non-\code{NA} values (default: \code{FALSE}). When \code{FALSE}, only \code{NA} values are modified. To ensure compliance with EUCAST guidelines, \strong{this should remain} \code{FALSE}, as EUCAST notes often state that an organism "should be tested for susceptibility to individual agents or be reported resistant."}
|
|
|
|
\item{...}{column name of an antimicrobial, see section \emph{Antimicrobials} below}
|
|
|
|
\item{ab}{any (vector of) text that can be coerced to a valid antimicrobial drug code with \code{\link[=as.ab]{as.ab()}}}
|
|
|
|
\item{administration}{route of administration, either "im", "iv", or "oral"}
|
|
}
|
|
\value{
|
|
The input of \code{x}, possibly with edited values of antimicrobials. Or, if \code{verbose = TRUE}, a \link{data.frame} with all original and new values of the affected bug-drug combinations.
|
|
}
|
|
\description{
|
|
Apply rules from clinical breakpoints notes and expected resistant phenotypes as defined by the European Committee on Antimicrobial Susceptibility Testing (EUCAST, \url{https://www.eucast.org}), see \emph{Source}. Use \code{\link[=eucast_dosage]{eucast_dosage()}} to get a \link{data.frame} with advised dosages of a certain bug-drug combination, which is based on the \link{dosage} data set.
|
|
|
|
To improve the interpretation of the antibiogram before EUCAST rules are applied, some non-EUCAST rules can applied at default, see \emph{Details}.
|
|
}
|
|
\details{
|
|
\strong{Note:} This function does not translate MIC values to SIR values. Use \code{\link[=as.sir]{as.sir()}} for that. \cr
|
|
\strong{Note:} When ampicillin (AMP, J01CA01) is not available but amoxicillin (AMX, J01CA04) is, the latter will be used for all rules where there is a dependency on ampicillin. These drugs are interchangeable when it comes to expression of antimicrobial resistance. \cr
|
|
|
|
The file containing all EUCAST rules is located here: \url{https://github.com/msberends/AMR/blob/main/data-raw/eucast_rules.tsv}. \strong{Note:} Old taxonomic names are replaced with the current taxonomy where applicable. For example, \emph{Ochrobactrum anthropi} was renamed to \emph{Brucella anthropi} in 2020; the original EUCAST rules v3.1 and v3.2 did not yet contain this new taxonomic name. The \code{AMR} package contains the full microbial taxonomy updated until June 24th, 2024, see \link{microorganisms}.
|
|
\subsection{Custom Rules}{
|
|
|
|
Custom rules can be created using \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}, e.g.:
|
|
|
|
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
|
|
AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I")
|
|
|
|
eucast_rules(example_isolates, rules = "custom", custom_rules = x)
|
|
}\if{html}{\out{</div>}}
|
|
}
|
|
|
|
\subsection{'Other' Rules}{
|
|
|
|
Before further processing, two non-EUCAST rules about drug combinations can be applied to improve the efficacy of the EUCAST rules, and the reliability of your data (analysis). These rules are:
|
|
\enumerate{
|
|
\item A drug \strong{with} enzyme inhibitor will be set to S if the same drug \strong{without} enzyme inhibitor is S
|
|
\item A drug \strong{without} enzyme inhibitor will be set to R if the same drug \strong{with} enzyme inhibitor is R
|
|
}
|
|
|
|
Important examples include amoxicillin and amoxicillin/clavulanic acid, and trimethoprim and trimethoprim/sulfamethoxazole. Needless to say, for these rules to work, both drugs must be available in the data set.
|
|
|
|
Since these rules are not officially approved by EUCAST, they are not applied at default. To use these rules, include \code{"other"} to the \code{rules} argument, or use \code{eucast_rules(..., rules = "all")}. You can also set the package option \code{\link[=AMR-options]{AMR_eucastrules}}, i.e. run \code{options(AMR_eucastrules = "all")}.
|
|
}
|
|
}
|
|
\section{Antimicrobials}{
|
|
|
|
To define antimicrobials column names, leave as it is to determine it automatically with \code{\link[=guess_ab_col]{guess_ab_col()}} or input a text (case-insensitive), or use \code{NULL} to skip a column (e.g. \code{TIC = NULL} to skip ticarcillin). Manually defined but non-existing columns will be skipped with a warning.
|
|
|
|
The following antimicrobials are eligible for the functions \code{\link[=eucast_rules]{eucast_rules()}} and \code{\link[=mdro]{mdro()}}. These are shown below in the format 'name (\verb{antimicrobial ID}, \href{https://atcddd.fhi.no/atc/structure_and_principles/}{ATC code})', sorted alphabetically:
|
|
|
|
\verb{r create_eucast_ab_documentation()}
|
|
}
|
|
|
|
\section{Reference Data Publicly Available}{
|
|
|
|
All data sets in this \code{AMR} package (about microorganisms, antimicrobials, SIR interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, and Stata. We also provide tab-separated plain text files that are machine-readable and suitable for input in any software program, such as laboratory information systems. Please visit \href{https://msberends.github.io/AMR/articles/datasets.html}{our website for the download links}. The actual files are of course available on \href{https://github.com/msberends/AMR/tree/main/data-raw}{our GitHub repository}.
|
|
}
|
|
|
|
\examples{
|
|
\donttest{
|
|
a <- data.frame(
|
|
mo = c(
|
|
"Staphylococcus aureus",
|
|
"Enterococcus faecalis",
|
|
"Escherichia coli",
|
|
"Klebsiella pneumoniae",
|
|
"Pseudomonas aeruginosa"
|
|
),
|
|
VAN = "-", # Vancomycin
|
|
AMX = "-", # Amoxicillin
|
|
COL = "-", # Colistin
|
|
CAZ = "-", # Ceftazidime
|
|
CXM = "-", # Cefuroxime
|
|
PEN = "S", # Benzylpenicillin
|
|
FOX = "S", # Cefoxitin
|
|
stringsAsFactors = FALSE
|
|
)
|
|
|
|
head(a)
|
|
|
|
|
|
# apply EUCAST rules: some results wil be changed
|
|
b <- eucast_rules(a, overwrite = TRUE)
|
|
|
|
head(b)
|
|
|
|
|
|
# do not apply EUCAST rules, but rather get a data.frame
|
|
# containing all details about the transformations:
|
|
c <- eucast_rules(a, overwrite = TRUE, verbose = TRUE)
|
|
head(c)
|
|
}
|
|
|
|
# Dosage guidelines:
|
|
|
|
eucast_dosage(c("tobra", "genta", "cipro"), "iv")
|
|
|
|
eucast_dosage(c("tobra", "genta", "cipro"), "iv", version_breakpoints = 10)
|
|
}
|