mirror of https://github.com/msberends/AMR.git
277 lines
13 KiB
R
277 lines
13 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/antibiogram.R
|
|
\name{antibiogram}
|
|
\alias{antibiogram}
|
|
\alias{plot.antibiogram}
|
|
\alias{autoplot.antibiogram}
|
|
\alias{knit_print.antibiogram}
|
|
\title{Generate Antibiogram: Traditional, Combined, Syndromic, or Weighted-Incidence Syndromic Combination (WISCA)}
|
|
\source{
|
|
\itemize{
|
|
\item Klinker KP \emph{et al.} (2021). \strong{Antimicrobial stewardship and antibiograms: importance of moving beyond traditional antibiograms}. \emph{Therapeutic Advances in Infectious Disease}, May 5;8:20499361211011373; \doi{10.1177/20499361211011373}
|
|
\item Barbieri E \emph{et al.} (2021). \strong{Development of a Weighted-Incidence Syndromic Combination Antibiogram (WISCA) to guide the choice of the empiric antibiotic treatment for urinary tract infection in paediatric patients: a Bayesian approach} \emph{Antimicrobial Resistance & Infection Control} May 1;10(1):74; \doi{10.1186/s13756-021-00939-2}
|
|
\item \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/}.
|
|
}
|
|
}
|
|
\usage{
|
|
antibiogram(
|
|
x,
|
|
antibiotics = where(is.sir),
|
|
mo_transform = "shortname",
|
|
ab_transform = NULL,
|
|
syndromic_group = NULL,
|
|
add_total_n = TRUE,
|
|
only_all_tested = FALSE,
|
|
digits = 0,
|
|
col_mo = NULL,
|
|
language = get_AMR_locale(),
|
|
minimum = 30,
|
|
combine_SI = TRUE,
|
|
sep = " + ",
|
|
info = interactive()
|
|
)
|
|
|
|
\method{plot}{antibiogram}(x, ...)
|
|
|
|
\method{autoplot}{antibiogram}(object, ...)
|
|
|
|
\method{knit_print}{antibiogram}(
|
|
x,
|
|
italicise = TRUE,
|
|
na = getOption("knitr.kable.NA", default = ""),
|
|
...
|
|
)
|
|
}
|
|
\arguments{
|
|
\item{x}{a \link{data.frame} containing at least a column with microorganisms and columns with antibiotic results (class 'sir', see \code{\link[=as.sir]{as.sir()}})}
|
|
|
|
\item{antibiotics}{vector of any antibiotic name or code (will be evaluated with \code{\link[=as.ab]{as.ab()}}, column name of \code{x}, or (any combinations of) \link[=antibiotic_class_selectors]{antibiotic selectors} such as \code{\link[=aminoglycosides]{aminoglycosides()}} or \code{\link[=carbapenems]{carbapenems()}}. For combination antibiograms, this can also be set to values separated with \code{"+"}, such as "TZP+TOB" or "cipro + genta", given that columns resembling such antibiotics exist in \code{x}. See \emph{Examples}.}
|
|
|
|
\item{mo_transform}{a character to transform microorganism input - must be "name", "shortname", "gramstain", or one of the column names of the \link{microorganisms} data set: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "oxygen_tolerance", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence", or "snomed". Can also be \code{NULL} to not transform the input.}
|
|
|
|
\item{ab_transform}{a character to transform antibiotic input - must be one of the column names of the \link{antibiotics} data set: "ab", "cid", "name", "group", "atc", "atc_group1", "atc_group2", "abbreviations", "synonyms", "oral_ddd", "oral_units", "iv_ddd", "iv_units", or "loinc". Can also be \code{NULL} to not transform the input.}
|
|
|
|
\item{syndromic_group}{a column name of \code{x}, or values calculated to split rows of \code{x}, e.g. by using \code{\link[=ifelse]{ifelse()}} or \code{\link[dplyr:case_when]{case_when()}}. See \emph{Examples}.}
|
|
|
|
\item{add_total_n}{a \link{logical} to indicate whether total available numbers per pathogen should be added to the table (default is \code{TRUE}). This will add the lowest and highest number of available isolate per antibiotic (e.g, if for \emph{E. coli} 200 isolates are available for ciprofloxacin and 150 for amoxicillin, the returned number will be "150-200").}
|
|
|
|
\item{only_all_tested}{(for combination antibiograms): a \link{logical} to indicate that isolates must be tested for all antibiotics, see \emph{Details}}
|
|
|
|
\item{digits}{number of digits to use for rounding}
|
|
|
|
\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{language}{language to translate text, which defaults to the system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}})}
|
|
|
|
\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{combine_SI}{a \link{logical} to indicate whether all susceptibility should be determined by results of either S or I, instead of only S (default is \code{TRUE})}
|
|
|
|
\item{sep}{a separating character for antibiotic columns in combination antibiograms}
|
|
|
|
\item{info}{a \link{logical} to indicate info should be printed - the default is \code{TRUE} only in interactive mode}
|
|
|
|
\item{...}{when used in \link[knitr:kable]{R Markdown or Quarto}: arguments passed on to \code{\link[knitr:kable]{knitr::kable()}} (otherwise, has no use)}
|
|
|
|
\item{object}{an \code{\link[=antibiogram]{antibiogram()}} object}
|
|
|
|
\item{italicise}{a \link{logical} to indicate whether the microorganism names in the \link[knitr:kable]{knitr} table should be made italic, using \code{\link[=italicise_taxonomy]{italicise_taxonomy()}}.}
|
|
|
|
\item{na}{character to use for showing \code{NA} values}
|
|
}
|
|
\description{
|
|
Generate an antibiogram, and communicate the results in plots or tables. These functions follow the logic of Klinker \emph{et al.} and Barbieri \emph{et al.} (see \emph{Source}), and allow reporting in e.g. R Markdown and Quarto as well.
|
|
}
|
|
\details{
|
|
This function returns a table with values between 0 and 100 for \emph{susceptibility}, not resistance.
|
|
|
|
\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.
|
|
|
|
All types of antibiograms as listed below can be plotted (using \code{\link[ggplot2:autoplot]{ggplot2::autoplot()}} or base \R \code{\link[=plot]{plot()}}/\code{\link[=barplot]{barplot()}}). The \code{antibiogram} object can also be used directly in R Markdown / Quarto (i.e., \code{knitr}) for reports. In this case, \code{\link[knitr:kable]{knitr::kable()}} will be applied automatically and microorganism names will even be printed in italics at default (see argument \code{italicise}). You can also use functions from specific 'table reporting' packages to transform the output of \code{\link[=antibiogram]{antibiogram()}} to your needs, e.g. with \code{flextable::as_flextable()} or \code{gt::gt()}.
|
|
\subsection{Antibiogram Types}{
|
|
|
|
There are four antibiogram types, as proposed by Klinker \emph{et al.} (2021, \doi{10.1177/20499361211011373}), and they are all supported by \code{\link[=antibiogram]{antibiogram()}}:
|
|
\enumerate{
|
|
\item \strong{Traditional Antibiogram}
|
|
|
|
Case example: Susceptibility of \emph{Pseudomonas aeruginosa} to piperacillin/tazobactam (TZP)
|
|
|
|
Code example:
|
|
|
|
\if{html}{\out{<div class="sourceCode r">}}\preformatted{antibiogram(your_data,
|
|
antibiotics = "TZP")
|
|
}\if{html}{\out{</div>}}
|
|
\item \strong{Combination Antibiogram}
|
|
|
|
Case example: Additional susceptibility of \emph{Pseudomonas aeruginosa} to TZP + tobramycin versus TZP alone
|
|
|
|
Code example:
|
|
|
|
\if{html}{\out{<div class="sourceCode r">}}\preformatted{antibiogram(your_data,
|
|
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"))
|
|
}\if{html}{\out{</div>}}
|
|
\item \strong{Syndromic Antibiogram}
|
|
|
|
Case example: Susceptibility of \emph{Pseudomonas aeruginosa} to TZP among respiratory specimens (obtained among ICU patients only)
|
|
|
|
Code example:
|
|
|
|
\if{html}{\out{<div class="sourceCode r">}}\preformatted{antibiogram(your_data,
|
|
antibiotics = penicillins(),
|
|
syndromic_group = "ward")
|
|
}\if{html}{\out{</div>}}
|
|
\item \strong{Weighted-Incidence Syndromic Combination Antibiogram (WISCA)}
|
|
|
|
Case example: Susceptibility of \emph{Pseudomonas aeruginosa} to TZP among respiratory specimens (obtained among ICU patients only) for male patients age >=65 years with heart failure
|
|
|
|
Code example:
|
|
|
|
\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(dplyr)
|
|
your_data \%>\%
|
|
filter(ward == "ICU" & specimen_type == "Respiratory") \%>\%
|
|
antibiogram(antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
|
|
syndromic_group = ifelse(.$age >= 65 &
|
|
.$gender == "Male" &
|
|
.$condition == "Heart Disease",
|
|
"Study Group", "Control Group"))
|
|
}\if{html}{\out{</div>}}
|
|
}
|
|
|
|
Note that for combination antibiograms, it is important to realise that susceptibility can be calculated in two ways, which can be set with the \code{only_all_tested} argument (default is \code{FALSE}). See this example for two antibiotics, Drug A and Drug B, about how \code{\link[=antibiogram]{antibiogram()}} works to calculate the \%SI:
|
|
|
|
\if{html}{\out{<div class="sourceCode">}}\preformatted{--------------------------------------------------------------------
|
|
only_all_tested = FALSE only_all_tested = TRUE
|
|
----------------------- -----------------------
|
|
Drug A Drug B include as include as include as include as
|
|
numerator denominator numerator denominator
|
|
-------- -------- ---------- ----------- ---------- -----------
|
|
S or I S or I X X X X
|
|
R S or I X X X X
|
|
<NA> S or I X X - -
|
|
S or I R X X X X
|
|
R R - X - X
|
|
<NA> R - - - -
|
|
S or I <NA> X X - -
|
|
R <NA> - - - -
|
|
<NA> <NA> - - - -
|
|
--------------------------------------------------------------------
|
|
}\if{html}{\out{</div>}}
|
|
}
|
|
}
|
|
\examples{
|
|
# example_isolates is a data set available in the AMR package.
|
|
# run ?example_isolates for more info.
|
|
example_isolates
|
|
|
|
\donttest{
|
|
# Traditional antibiogram ----------------------------------------------
|
|
|
|
antibiogram(example_isolates,
|
|
antibiotics = c(aminoglycosides(), carbapenems())
|
|
)
|
|
|
|
antibiogram(example_isolates,
|
|
antibiotics = aminoglycosides(),
|
|
ab_transform = "atc",
|
|
mo_transform = "gramstain"
|
|
)
|
|
|
|
antibiogram(example_isolates,
|
|
antibiotics = carbapenems(),
|
|
ab_transform = "name",
|
|
mo_transform = "name"
|
|
)
|
|
|
|
|
|
# Combined antibiogram -------------------------------------------------
|
|
|
|
# combined antibiotics yield higher empiric coverage
|
|
antibiogram(example_isolates,
|
|
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
|
|
mo_transform = "gramstain"
|
|
)
|
|
|
|
# names of antibiotics do not need to resemble columns exactly:
|
|
antibiogram(example_isolates,
|
|
antibiotics = c("Cipro", "cipro + genta"),
|
|
mo_transform = "gramstain",
|
|
ab_transform = "name",
|
|
sep = " & "
|
|
)
|
|
|
|
|
|
# Syndromic antibiogram ------------------------------------------------
|
|
|
|
# the data set could contain a filter for e.g. respiratory specimens
|
|
antibiogram(example_isolates,
|
|
antibiotics = c(aminoglycosides(), carbapenems()),
|
|
syndromic_group = "ward"
|
|
)
|
|
|
|
# now define a data set with only E. coli
|
|
ex1 <- example_isolates[which(mo_genus() == "Escherichia"), ]
|
|
|
|
# with a custom language, though this will be determined automatically
|
|
# (i.e., this table will be in Spanish on Spanish systems)
|
|
antibiogram(ex1,
|
|
antibiotics = aminoglycosides(),
|
|
ab_transform = "name",
|
|
syndromic_group = ifelse(ex1$ward == "ICU",
|
|
"UCI", "No UCI"
|
|
),
|
|
language = "es"
|
|
)
|
|
|
|
|
|
# Weighted-incidence syndromic combination antibiogram (WISCA) ---------
|
|
|
|
# the data set could contain a filter for e.g. respiratory specimens/ICU
|
|
antibiogram(example_isolates,
|
|
antibiotics = c("AMC", "AMC+CIP", "TZP", "TZP+TOB"),
|
|
mo_transform = "gramstain",
|
|
minimum = 10, # this should be >=30, but now just as example
|
|
syndromic_group = ifelse(example_isolates$age >= 65 &
|
|
example_isolates$gender == "M",
|
|
"WISCA Group 1", "WISCA Group 2"
|
|
)
|
|
)
|
|
|
|
|
|
# Print the output for R Markdown / Quarto -----------------------------
|
|
|
|
ureido <- antibiogram(example_isolates,
|
|
antibiotics = ureidopenicillins(),
|
|
ab_transform = "name"
|
|
)
|
|
|
|
# in an Rmd file, you would just need to return `ureido` in a chunk,
|
|
# but to be explicit here:
|
|
if (requireNamespace("knitr")) {
|
|
cat(knitr::knit_print(ureido))
|
|
}
|
|
|
|
|
|
# Generate plots with ggplot2 or base R --------------------------------
|
|
|
|
ab1 <- antibiogram(example_isolates,
|
|
antibiotics = c("AMC", "CIP", "TZP", "TZP+TOB"),
|
|
mo_transform = "gramstain"
|
|
)
|
|
ab2 <- antibiogram(example_isolates,
|
|
antibiotics = c("AMC", "CIP", "TZP", "TZP+TOB"),
|
|
mo_transform = "gramstain",
|
|
syndromic_group = "ward"
|
|
)
|
|
|
|
if (requireNamespace("ggplot2")) {
|
|
ggplot2::autoplot(ab1)
|
|
}
|
|
if (requireNamespace("ggplot2")) {
|
|
ggplot2::autoplot(ab2)
|
|
}
|
|
|
|
plot(ab1)
|
|
plot(ab2)
|
|
}
|
|
}
|