mirror of
https://github.com/msberends/AMR.git
synced 2025-07-08 12:31:58 +02:00
use dplyr where available, new antibiogram() for WISCA, fixed Salmonella Typhi/Paratyphi
This commit is contained in:
230
man/antibiogram.Rd
Normal file
230
man/antibiogram.Rd
Normal file
@ -0,0 +1,230 @@
|
||||
% 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{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 = " + "
|
||||
)
|
||||
|
||||
\method{plot}{antibiogram}(x, ...)
|
||||
|
||||
\method{autoplot}{antibiogram}(object, ...)
|
||||
|
||||
\method{print}{antibiogram}(x, as_kable = !interactive(), ...)
|
||||
}
|
||||
\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 column names, 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 column names separated with \code{"+"}, such as "TZP+TOB" given that the data set contains columns "TZP" and "TOB". 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", "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 (defaults to \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()}}), defaults to 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 (defaults to \code{TRUE})}
|
||||
|
||||
\item{sep}{a separating character for antibiotic columns in combination antibiograms}
|
||||
|
||||
\item{as_kable}{a \link{logical} to indicate whether the printing should be done using \code{\link[knitr:kable]{knitr::kable()}} (which is the default in non-interactive sessions)}
|
||||
}
|
||||
\description{
|
||||
Generate an antibiogram, and communicate the results in plots or tables. These functions follow the logic of Klinker \emph{et al.} (2021, \doi{10.1177/20499361211011373}) and Barbieri \emph{et al.} (2021, \doi{10.1186/s13756-021-00939-2}), 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.
|
||||
|
||||
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{antibiogram(your_data,
|
||||
antibiotics = c("TZP", "TZP+TOB", "TZP+GEN"),
|
||||
syndromic_group = ifelse(your_data$age >= 65 & your_data$gender == "Male",
|
||||
"Group 1", "Group 2"))
|
||||
}\if{html}{\out{</div>}}
|
||||
}
|
||||
|
||||
All types of antibiograms can be generated with the functions as described on this page, and can be plotted (using \code{\link[ggplot2:autoplot]{ggplot2::autoplot()}} or base \R \code{\link[=plot]{plot()}}/\code{\link[=barplot]{barplot()}}) or printed into R Markdown / Quarto formats for reports. Use functions from specific 'table reporting' packages to transform the output of \code{\link[=antibiogram]{antibiogram()}} to your needs, e.g. \code{flextable::as_flextable()} or \code{gt::gt()}.
|
||||
|
||||
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 (defaults to \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>}}
|
||||
|
||||
Printing the antibiogram in non-interactive sessions will be done by \code{\link[knitr:kable]{knitr::kable()}}, with support for \link[knitr:kable]{all their implemented formats}, such as "markdown". The knitr format will be automatically determined if printed inside a knitr document (LaTeX, HTML, etc.).
|
||||
}
|
||||
\examples{
|
||||
# example_isolates is a data set available in the AMR package.
|
||||
# run ?example_isolates for more info.
|
||||
example_isolates
|
||||
|
||||
|
||||
# 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")
|
||||
|
||||
antibiogram(example_isolates,
|
||||
antibiotics = c("TZP", "TZP+TOB"),
|
||||
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")
|
||||
|
||||
# with a custom language, though this will be determined automatically
|
||||
# (i.e., this table will be in Spanish on Spanish systems)
|
||||
ex1 <- example_isolates[which(mo_genus() == "Escherichia"), ]
|
||||
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
|
||||
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"))
|
||||
|
||||
|
||||
# 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")
|
||||
|
||||
plot(ab1)
|
||||
|
||||
if (requireNamespace("ggplot2")) {
|
||||
ggplot2::autoplot(ab1)
|
||||
}
|
||||
|
||||
plot(ab2)
|
||||
|
||||
if (requireNamespace("ggplot2")) {
|
||||
ggplot2::autoplot(ab2)
|
||||
}
|
||||
}
|
||||
@ -1,21 +0,0 @@
|
||||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/antibiogram.R
|
||||
\name{antibiogram_wisca}
|
||||
\alias{antibiogram_wisca}
|
||||
\title{Generate Antibiogram: Traditional, Combined, Syndromic, or Weighted (WISCA)}
|
||||
\usage{
|
||||
antibiogram_wisca(
|
||||
x,
|
||||
...,
|
||||
antibiotics = where(is.sir),
|
||||
type = c("traditional", "combined", "syndromic", "WISCA"),
|
||||
col_mo = NULL,
|
||||
minimum = 30
|
||||
)
|
||||
}
|
||||
\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()}})}
|
||||
}
|
||||
\description{
|
||||
Generate Antibiogram: Traditional, Combined, Syndromic, or Weighted (WISCA)
|
||||
}
|
||||
@ -110,7 +110,7 @@ not_intrinsic_resistant(
|
||||
|
||||
\item{filter}{an \link{expression} to be evaluated in the \link{antibiotics} data set, such as \code{name \%like\% "trim"}}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\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".}
|
||||
}
|
||||
|
||||
@ -94,7 +94,7 @@ sir_interpretation_history(clean = FALSE)
|
||||
|
||||
\item{include_PKPD}{a \link{logical} to indicate that PK/PD clinical breakpoints must be applied as a last resort, defaults to \code{TRUE}. Can also be set with the option \code{\link[=AMR-options]{AMR_include_PKPD}}.}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\item{clean}{a \link{logical} to indicate whether previously stored results should be forgotten after returning the 'logbook' with results}
|
||||
}
|
||||
@ -156,7 +156,7 @@ After using \code{\link[=as.sir]{as.sir()}}, you can use the \code{\link[=eucast
|
||||
|
||||
\subsection{Machine-Readable Interpretation Guidelines}{
|
||||
|
||||
The repository of this package \href{https://github.com/msberends/AMR/blob/main/data-raw/clinical_breakpoints.txt}{contains a machine-readable version} of all guidelines. This is a CSV file consisting of 18,308 rows and 11 columns. This file is machine-readable, since it contains one row for every unique combination of the test method (MIC or disk diffusion), the antimicrobial drug and the microorganism. \strong{This allows for easy implementation of these rules in laboratory information systems (LIS)}. Note that it only contains interpretation guidelines for humans - interpretation guidelines from CLSI for animals were removed.
|
||||
The repository of this package \href{https://github.com/msberends/AMR/blob/main/data-raw/clinical_breakpoints.txt}{contains a machine-readable version} of all guidelines. This is a CSV file consisting of 18 308 rows and 11 columns. This file is machine-readable, since it contains one row for every unique combination of the test method (MIC or disk diffusion), the antimicrobial drug and the microorganism. \strong{This allows for easy implementation of these rules in laboratory information systems (LIS)}. Note that it only contains interpretation guidelines for humans - interpretation guidelines from CLSI for animals were removed.
|
||||
}
|
||||
|
||||
\subsection{Other}{
|
||||
|
||||
@ -16,14 +16,14 @@ bug_drug_combinations(x, col_mo = NULL, FUN = mo_shortname, ...)
|
||||
add_ab_group = TRUE,
|
||||
remove_intrinsic_resistant = FALSE,
|
||||
decimal.mark = getOption("OutDec"),
|
||||
big.mark = ifelse(decimal.mark == ",", ".", ","),
|
||||
big.mark = ifelse(decimal.mark == ",", " ", ","),
|
||||
...
|
||||
)
|
||||
}
|
||||
\arguments{
|
||||
\item{x}{a data set with antibiotic columns, such as \code{amox}, \code{AMX} and \code{AMC}}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\item{FUN}{the function to call on the \code{mo} column to transform the microorganism codes, defaults to \code{\link[=mo_shortname]{mo_shortname()}}}
|
||||
|
||||
@ -59,6 +59,10 @@ The function \code{\link[=format]{format()}} calculates the resistance per bug-d
|
||||
}
|
||||
\examples{
|
||||
\donttest{
|
||||
#' # example_isolates is a data set available in the AMR package.
|
||||
# run ?example_isolates for more info.
|
||||
example_isolates
|
||||
|
||||
x <- bug_drug_combinations(example_isolates)
|
||||
head(x)
|
||||
format(x, translate_ab = "name (atc)")
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
\alias{clinical_breakpoints}
|
||||
\title{Data Set with Clinical Breakpoints for SIR Interpretation}
|
||||
\format{
|
||||
A \link[tibble:tibble]{tibble} with 18,308 observations and 11 variables:
|
||||
A \link[tibble:tibble]{tibble} with 18 308 observations and 11 variables:
|
||||
\itemize{
|
||||
\item \code{guideline}\cr Name of the guideline
|
||||
\item \code{method}\cr Either "DISK" or "MIC"
|
||||
|
||||
@ -38,7 +38,7 @@ eucast_dosage(ab, administration = "iv", version_breakpoints = 12)
|
||||
\arguments{
|
||||
\item{x}{a data set with antibiotic columns, such as \code{amox}, \code{AMX} and \code{AMC}}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\item{info}{a \link{logical} to indicate whether progress should be printed to the console, defaults to only print while in interactive sessions}
|
||||
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
\docType{data}
|
||||
\name{example_isolates}
|
||||
\alias{example_isolates}
|
||||
\title{Data Set with 2,000 Example Isolates}
|
||||
\title{Data Set with 2 000 Example Isolates}
|
||||
\format{
|
||||
A \link[tibble:tibble]{tibble} with 2,000 observations and 46 variables:
|
||||
A \link[tibble:tibble]{tibble} with 2 000 observations and 46 variables:
|
||||
\itemize{
|
||||
\item \code{date}\cr Date of receipt at the laboratory
|
||||
\item \code{patient}\cr ID of the patient
|
||||
@ -20,7 +20,7 @@ A \link[tibble:tibble]{tibble} with 2,000 observations and 46 variables:
|
||||
example_isolates
|
||||
}
|
||||
\description{
|
||||
A data set containing 2,000 microbial isolates with their full antibiograms. This data set contains randomised fictitious data, but reflects reality and can be used to practise AMR data analysis. For examples, please read \href{https://msberends.github.io/AMR/articles/AMR.html}{the tutorial on our website}.
|
||||
A data set containing 2 000 microbial isolates with their full antibiograms. This data set contains randomised fictitious data, but reflects reality and can be used to practise AMR data analysis. For examples, please read \href{https://msberends.github.io/AMR/articles/AMR.html}{the tutorial on our website}.
|
||||
}
|
||||
\details{
|
||||
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. 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}.
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
\alias{example_isolates_unclean}
|
||||
\title{Data Set with Unclean Data}
|
||||
\format{
|
||||
A \link[tibble:tibble]{tibble} with 3,000 observations and 8 variables:
|
||||
A \link[tibble:tibble]{tibble} with 3 000 observations and 8 variables:
|
||||
\itemize{
|
||||
\item \code{patient_id}\cr ID of the patient
|
||||
\item \code{date}\cr date of receipt at the laboratory
|
||||
@ -18,7 +18,7 @@ A \link[tibble:tibble]{tibble} with 3,000 observations and 8 variables:
|
||||
example_isolates_unclean
|
||||
}
|
||||
\description{
|
||||
A data set containing 3,000 microbial isolates that are not cleaned up and consequently not ready for AMR data analysis. This data set can be used for practice.
|
||||
A data set containing 3 000 microbial isolates that are not cleaned up and consequently not ready for AMR data analysis. This data set can be used for practice.
|
||||
}
|
||||
\details{
|
||||
Like all data sets in this package, this data set is publicly available for download in the following formats: R, MS Excel, Apache Feather, Apache Parquet, SPSS, SAS, and Stata. 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}.
|
||||
|
||||
@ -52,7 +52,7 @@ filter_first_isolate(
|
||||
|
||||
\item{col_patient_id}{column name of the unique IDs of the patients, defaults to the first column that starts with 'patient' or 'patid' (case insensitive)}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\item{col_testcode}{column name of the test codes. Use \code{col_testcode = NULL} to \strong{not} exclude certain test codes (such as test codes for screening). In that case \code{testcodes_exclude} will be ignored.}
|
||||
|
||||
@ -109,17 +109,14 @@ All mentioned methods are covered in the \code{\link[=first_isolate]{first_isola
|
||||
\strong{Isolate-based} \tab \code{first_isolate(x, method = "isolate-based")} \cr
|
||||
\emph{(= all isolates)} \tab \cr
|
||||
\tab \cr
|
||||
\tab \cr
|
||||
\strong{Patient-based} \tab \code{first_isolate(x, method = "patient-based")} \cr
|
||||
\emph{(= first isolate per patient)} \tab \cr
|
||||
\tab \cr
|
||||
\tab \cr
|
||||
\strong{Episode-based} \tab \code{first_isolate(x, method = "episode-based")}, or: \cr
|
||||
\emph{(= first isolate per episode)} \tab \cr
|
||||
- 7-Day interval from initial isolate \tab - \code{first_isolate(x, method = "e", episode_days = 7)} \cr
|
||||
- 30-Day interval from initial isolate \tab - \code{first_isolate(x, method = "e", episode_days = 30)} \cr
|
||||
\tab \cr
|
||||
\tab \cr
|
||||
\strong{Phenotype-based} \tab \code{first_isolate(x, method = "phenotype-based")}, or: \cr
|
||||
\emph{(= first isolate per phenotype)} \tab \cr
|
||||
- Major difference in any antimicrobial result \tab - \code{first_isolate(x, type = "points")} \cr
|
||||
@ -168,7 +165,7 @@ The default method is phenotype-based (using \code{type = "points"}) and episode
|
||||
# `example_isolates` is a data set available in the AMR package.
|
||||
# See ?example_isolates.
|
||||
|
||||
example_isolates[first_isolate(), ]
|
||||
example_isolates[first_isolate(info = TRUE), ]
|
||||
\donttest{
|
||||
# get all first Gram-negatives
|
||||
example_isolates[which(first_isolate(info = FALSE) & mo_is_gram_negative()), ]
|
||||
@ -176,7 +173,7 @@ example_isolates[which(first_isolate(info = FALSE) & mo_is_gram_negative()), ]
|
||||
if (require("dplyr")) {
|
||||
# filter on first isolates using dplyr:
|
||||
example_isolates \%>\%
|
||||
filter(first_isolate())
|
||||
filter(first_isolate(info = TRUE))
|
||||
}
|
||||
if (require("dplyr")) {
|
||||
# short-hand version:
|
||||
@ -187,7 +184,7 @@ if (require("dplyr")) {
|
||||
# flag the first isolates per group:
|
||||
example_isolates \%>\%
|
||||
group_by(ward) \%>\%
|
||||
mutate(first = first_isolate()) \%>\%
|
||||
mutate(first = first_isolate(info = FALSE)) \%>\%
|
||||
select(ward, date, patient, mo, first)
|
||||
}
|
||||
}
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/episode.R
|
||||
% Please edit documentation in R/get_episode.R
|
||||
\name{get_episode}
|
||||
\alias{get_episode}
|
||||
\alias{is_new_episode}
|
||||
@ -23,19 +23,19 @@ is_new_episode(x, episode_days, ...)
|
||||
}
|
||||
}
|
||||
\description{
|
||||
These functions determine which items in a vector can be considered (the start of) a new episode, based on the argument \code{episode_days}. This can be used to determine clinical episodes for any epidemiological analysis. The \code{\link[=get_episode]{get_episode()}} function returns the index number of the episode per group, while the \code{\link[=is_new_episode]{is_new_episode()}} function returns values \code{TRUE}/\code{FALSE} to indicate whether an item in a vector is the start of a new episode.
|
||||
These functions determine which items in a vector can be considered (the start of) a new episode, based on the argument \code{episode_days}. This can be used to determine clinical episodes for any epidemiological analysis. The \code{\link[=get_episode]{get_episode()}} function returns the index number of the episode per group, while the \code{\link[=is_new_episode]{is_new_episode()}} function returns values \code{TRUE}/\code{FALSE} for where \code{\link[=get_episode]{get_episode()}} returns 1, and is thus equal to \code{get_episode(...) == 1}.
|
||||
}
|
||||
\details{
|
||||
Dates are first sorted from old to new. The oldest date will mark the start of the first episode. After this date, the next date will be marked that is at least \code{episode_days} days later than the start of the first episode. From that second marked date on, the next date will be marked that is at least \code{episode_days} days later than the start of the second episode which will be the start of the third episode, and so on. Before the vector is being returned, the original order will be restored.
|
||||
|
||||
The \code{\link[=first_isolate]{first_isolate()}} function is a wrapper around the \code{\link[=is_new_episode]{is_new_episode()}} function, but is more efficient for data sets containing microorganism codes or names and allows for different isolate selection methods.
|
||||
|
||||
The \code{dplyr} package is not required for these functions to work, but these functions do support \link[dplyr:group_by]{variable grouping} and work conveniently inside \code{dplyr} verbs such as \code{\link[dplyr:filter]{filter()}}, \code{\link[dplyr:mutate]{mutate()}} and \code{\link[dplyr:summarise]{summarise()}}.
|
||||
The \code{dplyr} package is not required for these functions to work, but these episode functions do support \link[dplyr:group_by]{variable grouping} and work conveniently inside \code{dplyr} verbs such as \code{\link[dplyr:filter]{filter()}}, \code{\link[dplyr:mutate]{mutate()}} and \code{\link[dplyr:summarise]{summarise()}}.
|
||||
}
|
||||
\examples{
|
||||
# `example_isolates` is a data set available in the AMR package.
|
||||
# See ?example_isolates
|
||||
df <- example_isolates[sample(seq_len(2000), size = 200), ]
|
||||
df <- example_isolates[sample(seq_len(2000), size = 100), ]
|
||||
|
||||
get_episode(df$date, episode_days = 60) # indices
|
||||
is_new_episode(df$date, episode_days = 60) # TRUE/FALSE
|
||||
@ -44,13 +44,9 @@ is_new_episode(df$date, episode_days = 60) # TRUE/FALSE
|
||||
df[which(get_episode(df$date, 60) == 3), ]
|
||||
|
||||
# the functions also work for less than a day, e.g. to include one per hour:
|
||||
get_episode(
|
||||
c(
|
||||
Sys.time(),
|
||||
Sys.time() + 60 * 60
|
||||
),
|
||||
episode_days = 1 / 24
|
||||
)
|
||||
get_episode(c(Sys.time(),
|
||||
Sys.time() + 60 * 60),
|
||||
episode_days = 1 / 24)
|
||||
|
||||
\donttest{
|
||||
if (require("dplyr")) {
|
||||
@ -66,6 +62,7 @@ if (require("dplyr")) {
|
||||
mutate(new_episode = is_new_episode(date, 365)) \%>\%
|
||||
select(patient, date, condition, new_episode)
|
||||
}
|
||||
|
||||
if (require("dplyr")) {
|
||||
df \%>\%
|
||||
group_by(ward, patient) \%>\%
|
||||
@ -75,6 +72,7 @@ if (require("dplyr")) {
|
||||
new_logical = is_new_episode(date, 60)
|
||||
)
|
||||
}
|
||||
|
||||
if (require("dplyr")) {
|
||||
df \%>\%
|
||||
group_by(ward) \%>\%
|
||||
@ -85,25 +83,10 @@ if (require("dplyr")) {
|
||||
n_episodes_30 = sum(is_new_episode(date, episode_days = 30))
|
||||
)
|
||||
}
|
||||
if (require("dplyr")) {
|
||||
# grouping on patients and microorganisms leads to the same
|
||||
# results as first_isolate() when using 'episode-based':
|
||||
x <- df \%>\%
|
||||
filter_first_isolate(
|
||||
include_unknown = TRUE,
|
||||
method = "episode-based"
|
||||
)
|
||||
|
||||
y <- df \%>\%
|
||||
group_by(patient, mo) \%>\%
|
||||
filter(is_new_episode(date, 365)) \%>\%
|
||||
ungroup()
|
||||
|
||||
identical(x, y)
|
||||
}
|
||||
if (require("dplyr")) {
|
||||
# but is_new_episode() has a lot more flexibility than first_isolate(),
|
||||
# since you can now group on anything that seems relevant:
|
||||
# is_new_episode() has a lot more flexibility than first_isolate(),
|
||||
# since you can group on anything that seems relevant:
|
||||
df \%>\%
|
||||
group_by(patient, mo, ward) \%>\%
|
||||
mutate(flag_episode = is_new_episode(date, 365)) \%>\%
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
\alias{intrinsic_resistant}
|
||||
\title{Data Set with Bacterial Intrinsic Resistance}
|
||||
\format{
|
||||
A \link[tibble:tibble]{tibble} with 134,634 observations and 2 variables:
|
||||
A \link[tibble:tibble]{tibble} with 134 634 observations and 2 variables:
|
||||
\itemize{
|
||||
\item \code{mo}\cr Microorganism ID
|
||||
\item \code{ab}\cr Antibiotic ID
|
||||
|
||||
@ -35,7 +35,7 @@ antimicrobials_equal(
|
||||
\arguments{
|
||||
\item{x}{a \link{data.frame} with antibiotics columns, like \code{AMX} or \code{amox}. Can be left blank to determine automatically}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\item{universal}{names of \strong{broad-spectrum} antimicrobial drugs, case-insensitive. Set to \code{NULL} to ignore. See \emph{Details} for the default antimicrobial drugs}
|
||||
|
||||
|
||||
@ -48,7 +48,7 @@ eucast_exceptional_phenotypes(x = NULL, only_sir_columns = FALSE, ...)
|
||||
|
||||
\item{guideline}{a specific guideline to follow, see sections \emph{Supported international / national guidelines} and \emph{Using Custom Guidelines} below. When left empty, the publication by Magiorakos \emph{et al.} (see below) will be followed.}
|
||||
|
||||
\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()}}.}
|
||||
\item{col_mo}{column name of the names or codes 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()}}.}
|
||||
|
||||
\item{info}{a \link{logical} to indicate whether progress should be printed to the console, defaults to only print while in interactive sessions}
|
||||
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
\docType{data}
|
||||
\name{microorganisms}
|
||||
\alias{microorganisms}
|
||||
\title{Data Set with 52,141 Microorganisms}
|
||||
\title{Data Set with 52 142 Microorganisms}
|
||||
\format{
|
||||
A \link[tibble:tibble]{tibble} with 52,141 observations and 22 variables:
|
||||
A \link[tibble:tibble]{tibble} with 52 142 observations and 22 variables:
|
||||
\itemize{
|
||||
\item \code{mo}\cr ID of microorganism as used by this package
|
||||
\item \code{fullname}\cr Full name, like \code{"Escherichia coli"}. For the taxonomic ranks genus, species and subspecies, this is the 'pasted' text of genus, species, and subspecies. For all taxonomic ranks higher than genus, this is the name of the taxon.
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
\docType{data}
|
||||
\name{microorganisms.codes}
|
||||
\alias{microorganisms.codes}
|
||||
\title{Data Set with 5,910 Common Microorganism Codes}
|
||||
\title{Data Set with 5 910 Common Microorganism Codes}
|
||||
\format{
|
||||
A \link[tibble:tibble]{tibble} with 5,910 observations and 2 variables:
|
||||
A \link[tibble:tibble]{tibble} with 5 910 observations and 2 variables:
|
||||
\itemize{
|
||||
\item \code{code}\cr Commonly used code of a microorganism
|
||||
\item \code{mo}\cr ID of the microorganism in the \link{microorganisms} data set
|
||||
|
||||
@ -278,7 +278,7 @@ mo_property(
|
||||
|
||||
\item{open}{browse the URL using \code{\link[utils:browseURL]{browseURL()}}}
|
||||
|
||||
\item{property}{one of the column names of the \link{microorganisms} data set: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence" or "snomed", or must be \code{"shortname"}}
|
||||
\item{property}{one of the column names of the \link{microorganisms} data set: "mo", "fullname", "status", "kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies", "rank", "ref", "source", "lpsn", "lpsn_parent", "lpsn_renamed_to", "gbif", "gbif_parent", "gbif_renamed_to", "prevalence" or "snomed"}
|
||||
}
|
||||
\value{
|
||||
\itemize{
|
||||
|
||||
@ -13,7 +13,7 @@
|
||||
\alias{proportion_S}
|
||||
\alias{proportion_df}
|
||||
\alias{sir_df}
|
||||
\title{Calculate Microbial Resistance}
|
||||
\title{Calculate Antimicrobial Resistance}
|
||||
\source{
|
||||
\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/}.
|
||||
}
|
||||
@ -98,7 +98,7 @@ The function \code{\link[=resistance]{resistance()}} is equal to the function \c
|
||||
|
||||
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.
|
||||
|
||||
\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.
|
||||
\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.
|
||||
|
||||
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{count_susceptible() / count_all()}. \emph{Low counts can influence the outcome - the \code{proportion} functions may camouflage this, since they only return the proportion (albeit being dependent on the \code{minimum} argument).}
|
||||
|
||||
@ -162,6 +162,7 @@ This AMR package honours this insight. Use \code{\link[=susceptibility]{suscepti
|
||||
\examples{
|
||||
# example_isolates is a data set available in the AMR package.
|
||||
# run ?example_isolates for more info.
|
||||
example_isolates
|
||||
|
||||
# base R ------------------------------------------------------------
|
||||
# determines \%R
|
||||
|
||||
Reference in New Issue
Block a user