mirror of
https://github.com/msberends/AMR.git
synced 2025-04-22 21:03:57 +02:00
271 lines
14 KiB
R
271 lines
14 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/proportion.R, R/sir_df.R
|
|
\name{proportion}
|
|
\alias{proportion}
|
|
\alias{resistance}
|
|
\alias{portion}
|
|
\alias{susceptibility}
|
|
\alias{sir_confidence_interval}
|
|
\alias{proportion_R}
|
|
\alias{proportion_IR}
|
|
\alias{proportion_I}
|
|
\alias{proportion_SI}
|
|
\alias{proportion_S}
|
|
\alias{proportion_df}
|
|
\alias{sir_df}
|
|
\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/}.
|
|
}
|
|
\usage{
|
|
resistance(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
susceptibility(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
sir_confidence_interval(..., ab_result = "R", minimum = 30,
|
|
as_percent = FALSE, only_all_tested = FALSE, confidence_level = 0.95,
|
|
side = "both", collapse = FALSE)
|
|
|
|
proportion_R(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
proportion_IR(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
proportion_I(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
proportion_SI(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
proportion_S(..., minimum = 30, as_percent = FALSE,
|
|
only_all_tested = FALSE)
|
|
|
|
proportion_df(data, translate_ab = "name", language = get_AMR_locale(),
|
|
minimum = 30, as_percent = FALSE, combine_SI = TRUE,
|
|
confidence_level = 0.95)
|
|
|
|
sir_df(data, translate_ab = "name", language = get_AMR_locale(),
|
|
minimum = 30, as_percent = FALSE, combine_SI = TRUE,
|
|
confidence_level = 0.95)
|
|
}
|
|
\arguments{
|
|
\item{...}{One or more vectors (or columns) with antibiotic interpretations. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. Use multiple columns to calculate (the lack of) co-resistance: the probability where one of two drugs have a resistant or susceptible result. See \emph{Examples}.}
|
|
|
|
\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{as_percent}{A \link{logical} to indicate whether the output must be returned as a hundred fold with \% sign (a character). A value of \code{0.123456} will then be returned as \code{"12.3\%"}.}
|
|
|
|
\item{only_all_tested}{(for combination therapies, i.e. using more than one variable for \code{...}): a \link{logical} to indicate that isolates must be tested for all antimicrobials, see section \emph{Combination Therapy} below.}
|
|
|
|
\item{ab_result}{Antibiotic results to test against, must be one or more values of "S", "SDD", "I", or "R".}
|
|
|
|
\item{confidence_level}{The confidence level for the returned confidence interval. For the calculation, the number of S or SI isolates, and R isolates are compared with the total number of available isolates with R, S, or I by using \code{\link[=binom.test]{binom.test()}}, i.e., the Clopper-Pearson method.}
|
|
|
|
\item{side}{The side of the confidence interval to return. The default is \code{"both"} for a length 2 vector, but can also be (abbreviated as) \code{"min"}/\code{"left"}/\code{"lower"}/\code{"less"} or \code{"max"}/\code{"right"}/\code{"higher"}/\code{"greater"}.}
|
|
|
|
\item{collapse}{A \link{logical} to indicate whether the output values should be 'collapsed', i.e. be merged together into one value, or a character value to use for collapsing.}
|
|
|
|
\item{data}{A \link{data.frame} containing columns with class \code{\link{sir}} (see \code{\link[=as.sir]{as.sir()}}).}
|
|
|
|
\item{translate_ab}{A column name of the \link{antimicrobials} data set to translate the antibiotic abbreviations to, using \code{\link[=ab_property]{ab_property()}}.}
|
|
|
|
\item{language}{Language of the returned text - the default is the current system language (see \code{\link[=get_AMR_locale]{get_AMR_locale()}}) and can also be set with the package option \code{\link[=AMR-options]{AMR_locale}}. Use \code{language = NULL} or \code{language = ""} to prevent translation.}
|
|
|
|
\item{combine_SI}{A \link{logical} to indicate whether all values of S, SDD, and I must be merged into one, so the output only consists of S+SDD+I vs. R (susceptible vs. resistant) - the default is \code{TRUE}.}
|
|
}
|
|
\value{
|
|
A \link{double} or, when \code{as_percent = TRUE}, a \link{character}.
|
|
}
|
|
\description{
|
|
These functions can be used to calculate the (co-)resistance or susceptibility of microbial isolates (i.e. percentage of S, SI, I, IR or R). All functions support quasiquotation with pipes, can be used in \code{summarise()} from the \code{dplyr} package and also support grouped variables, see \emph{Examples}.
|
|
|
|
\code{\link[=resistance]{resistance()}} should be used to calculate resistance, \code{\link[=susceptibility]{susceptibility()}} should be used to calculate susceptibility.\cr
|
|
}
|
|
\details{
|
|
For a more automated and comprehensive analysis, consider using \code{\link[=antibiogram]{antibiogram()}} or \code{\link[=wisca]{wisca()}}, which streamline many aspects of susceptibility reporting and, importantly, also support WISCA. The functions described here offer a more hands-on, manual approach for greater customisation.
|
|
|
|
\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.
|
|
|
|
The function \code{\link[=resistance]{resistance()}} is equal to the function \code{\link[=proportion_R]{proportion_R()}}. The function \code{\link[=susceptibility]{susceptibility()}} is equal to the function \code{\link[=proportion_SI]{proportion_SI()}}. Since AMR v3.0, \code{\link[=proportion_SI]{proportion_SI()}} and \code{\link[=proportion_I]{proportion_I()}} include dose-dependent susceptibility ('SDD').
|
|
|
|
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.
|
|
|
|
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{\link[=count_susceptible]{count_susceptible()}}\code{/}\code{\link[=count_all]{count_all()}}. \emph{Low counts can influence the outcome - the \verb{proportion_*()} functions may camouflage this, since they only return the proportion (albeit dependent on the \code{minimum} argument).}
|
|
|
|
The function \code{\link[=proportion_df]{proportion_df()}} takes any variable from \code{data} that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) and calculates the proportions S, I, and R. It also supports grouped variables. The function \code{\link[=sir_df]{sir_df()}} works exactly like \code{\link[=proportion_df]{proportion_df()}}, but adds the number of isolates.
|
|
}
|
|
\section{Combination Therapy}{
|
|
|
|
When using more than one variable for \code{...} (= combination therapy), use \code{only_all_tested} to only count isolates that are tested for all antimicrobials/variables that you test them for. See this example for two antimicrobials, Drug A and Drug B, about how \code{\link[=susceptibility]{susceptibility()}} works to calculate the \%SI:
|
|
|
|
\if{html}{\out{<div class="sourceCode">}}\preformatted{--------------------------------------------------------------------
|
|
only_all_tested = FALSE only_all_tested = TRUE
|
|
----------------------- -----------------------
|
|
Drug A Drug B considered considered considered considered
|
|
susceptible tested susceptible tested
|
|
-------- -------- ----------- ---------- ----------- ----------
|
|
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>}}
|
|
|
|
Please note that, in combination therapies, for \code{only_all_tested = TRUE} applies that:
|
|
|
|
\if{html}{\out{<div class="sourceCode">}}\preformatted{ count_S() + count_I() + count_R() = count_all()
|
|
proportion_S() + proportion_I() + proportion_R() = 1
|
|
}\if{html}{\out{</div>}}
|
|
|
|
and that, in combination therapies, for \code{only_all_tested = FALSE} applies that:
|
|
|
|
\if{html}{\out{<div class="sourceCode">}}\preformatted{ count_S() + count_I() + count_R() >= count_all()
|
|
proportion_S() + proportion_I() + proportion_R() >= 1
|
|
}\if{html}{\out{</div>}}
|
|
|
|
Using \code{only_all_tested} has no impact when only using one antibiotic as input.
|
|
}
|
|
|
|
\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/newsiandr}).
|
|
|
|
This AMR package follows insight; use \code{\link[=susceptibility]{susceptibility()}} (equal to \code{\link[=proportion_SI]{proportion_SI()}}) to determine antimicrobial susceptibility and \code{\link[=count_susceptible]{count_susceptible()}} (equal to \code{\link[=count_SI]{count_SI()}}) to count susceptible isolates.
|
|
}
|
|
|
|
\examples{
|
|
# example_isolates is a data set available in the AMR package.
|
|
# run ?example_isolates for more info.
|
|
example_isolates
|
|
|
|
|
|
# base R ------------------------------------------------------------
|
|
# determines \%R
|
|
resistance(example_isolates$AMX)
|
|
sir_confidence_interval(example_isolates$AMX)
|
|
sir_confidence_interval(example_isolates$AMX,
|
|
confidence_level = 0.975
|
|
)
|
|
sir_confidence_interval(example_isolates$AMX,
|
|
confidence_level = 0.975,
|
|
collapse = ", "
|
|
)
|
|
|
|
# determines \%S+I:
|
|
susceptibility(example_isolates$AMX)
|
|
sir_confidence_interval(example_isolates$AMX,
|
|
ab_result = c("S", "I")
|
|
)
|
|
|
|
# be more specific
|
|
proportion_S(example_isolates$AMX)
|
|
proportion_SI(example_isolates$AMX)
|
|
proportion_I(example_isolates$AMX)
|
|
proportion_IR(example_isolates$AMX)
|
|
proportion_R(example_isolates$AMX)
|
|
|
|
# dplyr -------------------------------------------------------------
|
|
\donttest{
|
|
if (require("dplyr")) {
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise(
|
|
r = resistance(CIP),
|
|
n = n_sir(CIP)
|
|
) # n_sir works like n_distinct in dplyr, see ?n_sir
|
|
}
|
|
if (require("dplyr")) {
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise(
|
|
cipro_R = resistance(CIP),
|
|
ci_min = sir_confidence_interval(CIP, side = "min"),
|
|
ci_max = sir_confidence_interval(CIP, side = "max"),
|
|
)
|
|
}
|
|
if (require("dplyr")) {
|
|
# scoped dplyr verbs with antimicrobial selectors
|
|
# (you could also use across() of course)
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise_at(
|
|
c(aminoglycosides(), carbapenems()),
|
|
resistance
|
|
)
|
|
}
|
|
if (require("dplyr")) {
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise(
|
|
R = resistance(CIP, as_percent = TRUE),
|
|
SI = susceptibility(CIP, as_percent = TRUE),
|
|
n1 = count_all(CIP), # the actual total; sum of all three
|
|
n2 = n_sir(CIP), # same - analogous to n_distinct
|
|
total = n()
|
|
) # NOT the number of tested isolates!
|
|
|
|
# Calculate co-resistance between amoxicillin/clav acid and gentamicin,
|
|
# so we can see that combination therapy does a lot more than mono therapy:
|
|
example_isolates \%>\% susceptibility(AMC) # \%SI = 76.3\%
|
|
example_isolates \%>\% count_all(AMC) # n = 1879
|
|
|
|
example_isolates \%>\% susceptibility(GEN) # \%SI = 75.4\%
|
|
example_isolates \%>\% count_all(GEN) # n = 1855
|
|
|
|
example_isolates \%>\% susceptibility(AMC, GEN) # \%SI = 94.1\%
|
|
example_isolates \%>\% count_all(AMC, GEN) # n = 1939
|
|
|
|
|
|
# See Details on how `only_all_tested` works. Example:
|
|
example_isolates \%>\%
|
|
summarise(
|
|
numerator = count_susceptible(AMC, GEN),
|
|
denominator = count_all(AMC, GEN),
|
|
proportion = susceptibility(AMC, GEN)
|
|
)
|
|
|
|
example_isolates \%>\%
|
|
summarise(
|
|
numerator = count_susceptible(AMC, GEN, only_all_tested = TRUE),
|
|
denominator = count_all(AMC, GEN, only_all_tested = TRUE),
|
|
proportion = susceptibility(AMC, GEN, only_all_tested = TRUE)
|
|
)
|
|
|
|
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise(
|
|
cipro_p = susceptibility(CIP, as_percent = TRUE),
|
|
cipro_n = count_all(CIP),
|
|
genta_p = susceptibility(GEN, as_percent = TRUE),
|
|
genta_n = count_all(GEN),
|
|
combination_p = susceptibility(CIP, GEN, as_percent = TRUE),
|
|
combination_n = count_all(CIP, GEN)
|
|
)
|
|
|
|
# Get proportions S/I/R immediately of all sir columns
|
|
example_isolates \%>\%
|
|
select(AMX, CIP) \%>\%
|
|
proportion_df(translate = FALSE)
|
|
|
|
# It also supports grouping variables
|
|
# (use sir_df to also include the count)
|
|
example_isolates \%>\%
|
|
select(ward, AMX, CIP) \%>\%
|
|
group_by(ward) \%>\%
|
|
sir_df(translate = FALSE)
|
|
}
|
|
}
|
|
}
|
|
\seealso{
|
|
\code{\link[=count]{count()}} to count resistant and susceptible isolates.
|
|
}
|