AMR/man/eucast_rules.Rd

157 lines
34 KiB
Plaintext
Raw Normal View History

2018-02-21 11:52:31 +01:00
% Generated by roxygen2: do not edit by hand
2018-11-16 20:50:50 +01:00
% Please edit documentation in R/eucast_rules.R
\name{eucast_rules}
\alias{eucast_rules}
2019-11-06 14:43:23 +01:00
\alias{EUCAST}
\alias{eucast_dosage}
\title{Apply EUCAST Rules}
2018-02-21 11:52:31 +01:00
\source{
2018-10-17 17:32:34 +02:00
\itemize{
\item EUCAST Expert Rules. Version 2.0, 2012.\cr
2021-01-06 11:16:17 +01:00
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)}
2022-08-21 16:37:20 +02:00
\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)}
}
2018-02-21 11:52:31 +01:00
}
\usage{
eucast_rules(
x,
col_mo = NULL,
info = interactive(),
2020-09-24 00:30:11 +02:00
rules = getOption("AMR_eucastrules", default = c("breakpoints", "expert")),
verbose = FALSE,
version_breakpoints = 11,
version_expertrules = 3.3,
ampc_cephalosporin_resistance = NA,
only_rsi_columns = FALSE,
2021-04-07 08:37:42 +02:00
custom_rules = NULL,
...
)
eucast_dosage(ab, administration = "iv", version_breakpoints = 11)
2018-02-21 11:52:31 +01:00
}
\arguments{
2022-08-27 20:49:37 +02:00
\item{x}{a data set with antibiotic columns, such as \code{amox}, \code{AMX} and \code{AMC}}
2018-02-21 11:52:31 +01:00
\item{col_mo}{column name of the IDs of the microorganisms (see \code{\link[=as.mo]{as.mo()}}), defaults to the first column of class \code{\link{mo}}. Values will be coerced using \code{\link[=as.mo]{as.mo()}}.}
2018-02-21 11:52:31 +01:00
2021-05-12 18:15:03 +02:00
\item{info}{a \link{logical} to indicate whether progress should be printed to the console, defaults to only print while in interactive sessions}
2018-02-21 11:52:31 +01:00
2021-05-12 18:15:03 +02:00
\item{rules}{a \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expert")}. The default value can be set to another value, e.g. using \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()}}.}
2018-10-18 12:10:10 +02:00
2020-09-24 00:30:11 +02:00
\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 either "11.0" or "10.0".}
2020-09-24 00:30:11 +02:00
\item{version_expertrules}{the version number to use for the EUCAST Expert Rules and Intrinsic Resistance guideline. Can be either "3.3", "3.2" or "3.1".}
2018-11-01 20:23:33 +01:00
2021-12-09 10:48:25 +01:00
\item{ampc_cephalosporin_resistance}{a \link{character} value that should be applied to cefotaxime, ceftriaxone and ceftazidime for AmpC de-repressed cephalosporin-resistant mutants, defaults to \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 agents. A value of \code{NA} (the default) for this argument will remove results for these three agents, while e.g. a value of \code{"R"} will make the results for these agents resistant. Use \code{NULL} or \code{FALSE} to not alter results for these three agents 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}.}
2022-10-19 11:47:57 +02:00
\item{only_rsi_columns}{a \link{logical} to indicate whether only antibiotic columns must be detected that were transformed to class \code{rsi} (see \code{\link[=as.rsi]{as.rsi()}}) on beforehand (defaults to \code{FALSE})}
2021-04-07 08:37:42 +02:00
\item{custom_rules}{custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}}
\item{...}{column name of an antibiotic, see section \emph{Antibiotics} below}
\item{ab}{any (vector of) text that can be coerced to a valid antibiotic code with \code{\link[=as.ab]{as.ab()}}}
\item{administration}{route of administration, either "im", "iv" or "oral"}
2018-02-21 11:52:31 +01:00
}
2018-02-22 20:48:48 +01:00
\value{
The input of \code{x}, possibly with edited values of antibiotics. Or, if \code{verbose = TRUE}, a \link{data.frame} with all original and new values of the affected bug-drug combinations.
2018-02-22 20:48:48 +01:00
}
2018-02-21 11:52:31 +01:00
\description{
2022-10-05 09:12:22 +02:00
Apply rules for clinical breakpoints and intrinsic resistance 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.
2019-11-15 15:25:03 +01:00
To improve the interpretation of the antibiogram before EUCAST rules are applied, some non-EUCAST rules can applied at default, see \emph{Details}.
2018-02-21 11:52:31 +01:00
}
2019-04-05 18:47:39 +02:00
\details{
\strong{Note:} This function does not translate MIC values to RSI values. Use \code{\link[=as.rsi]{as.rsi()}} 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
2019-04-09 14:59:17 +02:00
2022-10-05 09:12:22 +02:00
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 12 September, 2022, see \link{microorganisms}.
2021-04-07 08:37:42 +02:00
\subsection{Custom Rules}{
Custom rules can be created using \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}, e.g.:
2022-10-05 09:12:22 +02:00
\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
2021-04-07 08:37:42 +02:00
AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I")
2022-10-05 09:12:22 +02:00
eucast_rules(example_isolates, rules = "custom", custom_rules = x)
}\if{html}{\out{</div>}}
2021-04-07 08:37:42 +02:00
}
\subsection{'Other' Rules}{
2020-09-24 00:30:11 +02:00
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{
2020-09-24 00:30:11 +02:00
\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
}
2019-11-15 15:25:03 +01:00
2020-09-24 00:30:11 +02:00
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.
2020-01-26 20:20:00 +01:00
2021-01-06 11:16:17 +01:00
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 option \code{AMR_eucastrules}, i.e. run \code{options(AMR_eucastrules = "all")}.
2020-09-24 00:30:11 +02:00
}
2019-04-05 18:47:39 +02:00
}
2018-08-31 13:36:19 +02:00
\section{Antibiotics}{
2018-07-26 16:30:42 +02:00
To define antibiotics 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.
2019-05-10 16:44:59 +02:00
2021-05-18 11:29:31 +02:00
The following antibiotics 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://www.whocc.no/atc/structure_and_principles/}{ATC code})', sorted alphabetically:
2020-09-24 00:30:11 +02:00
2021-12-13 10:18:28 +01:00
Amikacin (\code{AMK}, \href{https://www.whocc.no/atc_ddd_index/?code=J01GB06&showdescription=no}{S01AE08}), amoxicillin (\code{AMX}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA04&showdescription=no}{J01MA02}), amoxicillin/clavulanic acid (\code{AMC}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CR02&showdescription=no}{J01MA23}), ampicillin (\code{AMP}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA01&showdescription=no}{J01MA04}), ampicillin/sulbactam (\code{SAM}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CR01&showdescription=no}{J01MA08}), arbekacin (\code{ARB}, \href{https://www.whocc.no/atc_ddd_index/?code=J01GB12&showdescription=no}{J01MA19}), aspoxicillin (\code{APX}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA19&showdescription=no}{J01MA16}), azidocillin (\code{AZD}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CE04&showdescription=no}{J01MA15}), azithromycin (\code{AZM}, \href{https://www.whocc.no/atc_ddd_index/?code=J01FA10&showdescription=no}{J01MA11}), azlocillin (\code{AZL}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA09&showdescription=no}{J01MA12}), aztreonam (\code{ATM}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DF01&showdescription=no}{J01MA24}), bacampicillin (\code{BAM}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA06&showdescription=no}{J01MA07}), bekanamycin (\code{BEK}, \href{https://www.whocc.no/atc_ddd_index/?code=J01GB13&showdescription=no}{J01MA14}), benzathine benzylpenicillin (\code{BNB}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CE08&showdescription=no}{D10AF05}), benzathine phenoxymethylpenicillin (\code{BNP}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CE10&showdescription=no}{J01MA06}), benzylpenicillin (\code{PEN}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CE01&showdescription=no}{J01MA01}), besifloxacin (\code{BES}, \href{https://www.whocc.no/atc_ddd_index/?code=S01AE08&showdescription=no}{J01MA18}), biapenem (\code{BIA}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DH05&showdescription=no}{J01MA03}), carbenicillin (\code{CRB}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA03&showdescription=no}{J01MA17}), carindacillin (\code{CRN}, \href{https://www.whocc.no/atc_ddd_index/?code=J01CA05&showdescription=no}{J01MA10}), cefacetrile (\code{CAC}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DB10&showdescription=no}{J01MA21}), cefaclor (\code{CEC}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DC04&showdescription=no}{J01MA09}), cefadroxil (\code{CFR}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DB05&showdescription=no}{J01MA05}), cefaloridine (\code{RID}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DB02&showdescription=no}{P01AA05}), cefamandole (\code{MAN}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DC03&showdescription=no}{J01MA22}), cefatrizine (\code{CTZ}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DB07&showdescription=no}{J01MA13}), cefazedone (\code{CZD}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DB06&showdescription=no}{J01CA01}), cefazolin (\code{CZO}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DB04&showdescription=no}{J01CA04}), cefcapene (\code{CCP}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DD17&showdescription=no}{J01CA12}), cefdinir (\code{CDR}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DD15&showdescription=no}{J01CR05}), cefditoren (\code{DIT}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DD16&showdescription=no}{J01CA13}), cefepime (\code{FEP}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DE01&showdescription=no}{J01AA02}), cefetamet (\code{CAT}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DD10&showdescription=no}{J01FA10}), cefixime (\code{CFM}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DD08&showdescription=no}{J01FA09}), cefmenoxime (\code{CMX}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DD05&showdescription=no}{J01CR02}), cefmetazole (\code{CMZ}, \href{https://www.whocc.no/atc_ddd_index/?code=J01DC09&showdescription=no}{J01AA08}), cefodizime (\code{DIZ}, \href{https://www.whocc.no/at
2018-07-26 16:30:42 +02:00
}
\section{Reference Data Publicly Available}{
2020-08-21 11:40:13 +02:00
2022-08-27 20:49:37 +02:00
All data sets in this \code{AMR} package (about microorganisms, antibiotics, R/SI interpretation, EUCAST rules, etc.) are publicly and freely available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, 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}.
2020-08-21 11:40:13 +02:00
}
2018-02-21 11:52:31 +01:00
\examples{
\donttest{
2022-08-28 10:31:50 +02:00
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
)
2018-10-18 12:10:10 +02:00
2022-08-21 16:37:20 +02:00
head(a)
2018-10-18 12:10:10 +02:00
2019-02-08 16:06:54 +01:00
2020-09-24 00:30:11 +02:00
# apply EUCAST rules: some results wil be changed
2019-02-08 16:06:54 +01:00
b <- eucast_rules(a)
2018-02-22 21:37:10 +01:00
2022-08-21 16:37:20 +02:00
head(b)
2019-02-08 16:06:54 +01:00
2019-07-30 13:12:40 +02:00
# do not apply EUCAST rules, but rather get a data.frame
2020-09-24 00:30:11 +02:00
# containing all details about the transformations:
2019-02-08 16:06:54 +01:00
c <- eucast_rules(a, verbose = TRUE)
2022-08-21 16:37:20 +02:00
head(c)
2018-02-21 11:52:31 +01:00
}
2022-08-21 16:37:20 +02:00
# Dosage guidelines:
eucast_dosage(c("tobra", "genta", "cipro"), "iv")
2022-08-21 16:37:20 +02:00
eucast_dosage(c("tobra", "genta", "cipro"), "iv", version_breakpoints = 10)
}