mirror of
https://github.com/msberends/AMR.git
synced 2026-11-16 00:10:57 +01:00
dr. M.S. (Matthijs) Berends
53d0704271
- New sir_combine() to combine SIR results of multiple antimicrobials into one variable; antibiogram(), wisca() and the count/proportion functions now use the same engine (antibiogram() and wisca() output unchanged) - With multiple antimicrobials, count_*() and proportion_*() now follow the documented combination therapy rules: resistance() is the proportion of failing combinations, count_all() excludes isolates with an unknown combination result, and WT/NWT/NS/NI are handled correctly - where() is now decided at runtime instead of at installation, fixing antibiogram() and wisca() without tidyselect (e.g. CRAN binaries without dplyr) - Imports from data.table and cli moved to .onLoad(); data.table functions are only used while it is loaded; the like() example no longer unloads data.table, which crashed R - Static test that fails on code outside functions depending on suggested packages - New check-without-dplyr workflow: installs AMR with all suggested packages, removes dplyr (and tidyselect), then runs all unit tests and examples against the installed package - g.test() now returns the degrees of freedom as 'parameter', so they are printed - Fix R CMD check NOTEs (hidden .claude folder, lost braces in inherited g.test and ggplot_pca docs)
202 lines
11 KiB
R
202 lines
11 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/count.R
|
|
\name{count}
|
|
\alias{count}
|
|
\alias{count_resistant}
|
|
\alias{count_susceptible}
|
|
\alias{count_S}
|
|
\alias{count_SI}
|
|
\alias{count_I}
|
|
\alias{count_IR}
|
|
\alias{count_R}
|
|
\alias{count_all}
|
|
\alias{n_sir}
|
|
\alias{count_df}
|
|
\title{Count Available Isolates}
|
|
\usage{
|
|
count_resistant(
|
|
...,
|
|
only_all_tested = FALSE,
|
|
guideline = getOption("AMR_guideline", "EUCAST")
|
|
)
|
|
|
|
count_susceptible(
|
|
...,
|
|
only_all_tested = FALSE,
|
|
guideline = getOption("AMR_guideline", "EUCAST")
|
|
)
|
|
|
|
count_S(..., only_all_tested = FALSE)
|
|
|
|
count_SI(..., only_all_tested = FALSE)
|
|
|
|
count_I(..., only_all_tested = FALSE)
|
|
|
|
count_IR(..., only_all_tested = FALSE)
|
|
|
|
count_R(..., only_all_tested = FALSE)
|
|
|
|
count_all(..., only_all_tested = FALSE)
|
|
|
|
n_sir(..., only_all_tested = FALSE)
|
|
|
|
count_df(
|
|
data,
|
|
translate_ab = "name",
|
|
language = get_AMR_locale(),
|
|
combine_SI = TRUE
|
|
)
|
|
}
|
|
\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.}
|
|
|
|
\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. Use \code{\link[=sir_combine]{sir_combine()}} to create a new variable for a combination therapy.}
|
|
|
|
\item{guideline}{Either \code{"EUCAST"} (default) or \code{"CLSI"}. With EUCAST, the 'I' category will be considered as susceptible (see \href{https://www.eucast.org/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}{EUCAST website}), but with with CLSI, it will be considered resistant. Therefore:
|
|
\itemize{
|
|
\item EUCAST: \code{\link[=count_susceptible]{count_susceptible()}} \eqn{= N_{S} + N_{I}}, \code{\link[=count_resistant]{count_resistant()}} \eqn{= N_{R}}
|
|
\item CLSI: \code{\link[=count_susceptible]{count_susceptible()}} \eqn{= N_{S} + N_{SDD}}, \code{\link[=count_resistant]{count_resistant()}} \eqn{= N_{I} + N_{R}}
|
|
}
|
|
|
|
You can also use e.g. \code{\link[=count_R]{count_R()}} or \code{\link[=count_S]{count_S()}} instead, to be explicit.}
|
|
|
|
\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{
|
|
An \link{integer}
|
|
}
|
|
\description{
|
|
These functions can be used to count resistant/susceptible microbial isolates. 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[=count_resistant]{count_resistant()}} should be used to count resistant isolates, \code{\link[=count_susceptible]{count_susceptible()}} should be used to count susceptible isolates.
|
|
}
|
|
\details{
|
|
These functions are meant to count isolates. Use the \code{\link[=resistance]{resistance()}}/\code{\link[=susceptibility]{susceptibility()}} functions to calculate microbial resistance/susceptibility.
|
|
|
|
The function \code{\link[=n_sir]{n_sir()}} is an alias of \code{\link[=count_all]{count_all()}}. They can be used to count all available isolates, i.e. where the input antimicrobial has an available result (S, I or R), or for multiple antimicrobials, where the result of the combination is available (see \emph{Combination Therapy} below). Their use is equal to \code{dplyr}'s \code{n_distinct()}. Their function is equal to \code{count_susceptible(...) + count_resistant(...)}.
|
|
|
|
The function \code{\link[=count_df]{count_df()}} takes any variable from \code{data} that has an \code{\link{sir}} class (created with \code{\link[=as.sir]{as.sir()}}) and counts the number of S's, I's and R's. It also supports grouped variables. The function \code{\link[=sir_df]{sir_df()}} works exactly like \code{\link[=count_df]{count_df()}}, but adds the percentage of S, I and R.
|
|
}
|
|
\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/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}).
|
|
|
|
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.
|
|
}
|
|
|
|
\section{Combination Therapy}{
|
|
|
|
A combination of antimicrobials is considered as good as its most active antimicrobial. Results are ranked as follows, from best to worst:
|
|
\enumerate{
|
|
\item \code{"S"} and \code{"WT"}
|
|
\item \code{"SDD"}
|
|
\item \code{"I"}
|
|
\item \code{"R"}, \code{"NWT"}, and \code{"NS"}
|
|
}
|
|
|
|
The result of the combination is the best result of the antimicrobials, i.e., the result keeps its original category instead of being reduced to only S or R. If antimicrobials have an equally ranked result, \code{"S"} is preferred over \code{"WT"}, and \code{"R"} over \code{"NWT"} and \code{"NS"}. The value \code{"NI"} (non-interpretable) is considered a missing result.
|
|
|
|
A missing result can only be ignored if the result of the combination is susceptible regardless of the missing result, which depends on the \code{only_all_tested} argument and on the guideline: under EUCAST, the 'I' category is considered susceptible (\emph{susceptible, increased exposure}), and under CLSI, it is not. This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter):
|
|
|
|
\if{html}{\out{<div class="sourceCode">}}\preformatted{-------------------------------------------------------------------------
|
|
Result of the combination
|
|
-----------------------------------------------------
|
|
Drug A Drug B only_all_tested = FALSE only_all_tested = TRUE
|
|
-------- -------- ---------------------------- ----------------------
|
|
S S, I, R S S
|
|
I I, R I I
|
|
R R R R
|
|
S <NA> S <NA>
|
|
I <NA> I (EUCAST), <NA> (CLSI) <NA>
|
|
R <NA> <NA> <NA>
|
|
<NA> <NA> <NA> <NA>
|
|
-------------------------------------------------------------------------
|
|
}\if{html}{\out{</div>}}
|
|
|
|
The \code{\link[=count]{count_*()}} and \code{\link[=proportion]{proportion_*()}} functions, such as \code{\link[=susceptibility]{susceptibility()}} and \code{\link[=resistance]{resistance()}}, apply exactly these rules when more than one variable is used: an isolate is considered tested if the result of the combination is not \code{NA}, and is then counted by the result of the combination. Consequently, \code{\link[=count_susceptible]{count_susceptible()}} \code{+} \code{\link[=count_resistant]{count_resistant()}} \code{=} \code{\link[=count_all]{count_all()}}, and \code{\link[=susceptibility]{susceptibility()}} \code{+} \code{\link[=resistance]{resistance()}} \verb{= 1}, for both values of \code{only_all_tested}. The guideline is taken from their \code{guideline} argument if they have one, and otherwise from the \code{AMR_guideline} option.
|
|
|
|
In \code{\link[=antibiogram]{antibiogram()}} and \code{\link[=wisca]{wisca()}}, the 'I' and 'SDD' categories are considered susceptible if \code{combine_SI = TRUE} (default), and the result of the combination is then reduced to S or R.
|
|
}
|
|
|
|
\examples{
|
|
# example_isolates is a data set available in the AMR package.
|
|
# run ?example_isolates for more info.
|
|
|
|
# base R ------------------------------------------------------------
|
|
count_resistant(example_isolates$AMX) # counts "R"
|
|
count_susceptible(example_isolates$AMX) # counts "S" and "I"
|
|
count_all(example_isolates$AMX) # counts "S", "I" and "R"
|
|
|
|
# be more specific
|
|
count_S(example_isolates$AMX)
|
|
count_SI(example_isolates$AMX)
|
|
count_I(example_isolates$AMX)
|
|
count_IR(example_isolates$AMX)
|
|
count_R(example_isolates$AMX)
|
|
|
|
# Count all available isolates
|
|
count_all(example_isolates$AMX)
|
|
n_sir(example_isolates$AMX)
|
|
|
|
# n_sir() is an alias of count_all().
|
|
# Since it counts all available isolates, you can
|
|
# calculate back to count e.g. susceptible isolates.
|
|
# These results are the same:
|
|
count_susceptible(example_isolates$AMX)
|
|
susceptibility(example_isolates$AMX) * n_sir(example_isolates$AMX)
|
|
|
|
# dplyr -------------------------------------------------------------
|
|
\donttest{
|
|
if (require("dplyr")) {
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise(
|
|
R = count_R(CIP),
|
|
I = count_I(CIP),
|
|
S = count_S(CIP),
|
|
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!
|
|
|
|
# Number of available isolates for a whole antibiotic class
|
|
# (i.e., in this data set columns GEN, TOB, AMK, KAN)
|
|
example_isolates \%>\%
|
|
group_by(ward) \%>\%
|
|
summarise(across(aminoglycosides(), n_sir))
|
|
|
|
# Count co-resistance between amoxicillin/clav acid and gentamicin,
|
|
# so we can see that combination therapy does a lot more than mono therapy.
|
|
# Please mind that `susceptibility()` calculates percentages right away instead.
|
|
example_isolates \%>\% count_susceptible(AMC) # 1433
|
|
example_isolates \%>\% count_all(AMC) # 1879
|
|
|
|
example_isolates \%>\% count_susceptible(GEN) # 1399
|
|
example_isolates \%>\% count_all(GEN) # 1855
|
|
|
|
example_isolates \%>\% count_susceptible(AMC, GEN) # 1764
|
|
example_isolates \%>\% count_all(AMC, GEN) # 1936
|
|
|
|
# Get number of S+I vs. R immediately of selected columns
|
|
example_isolates \%>\%
|
|
select(AMX, CIP) \%>\%
|
|
count_df(translate = FALSE)
|
|
|
|
# It also supports grouping variables
|
|
example_isolates \%>\%
|
|
select(ward, AMX, CIP) \%>\%
|
|
group_by(ward) \%>\%
|
|
count_df(translate = FALSE)
|
|
}
|
|
}
|
|
}
|
|
\seealso{
|
|
\code{\link[=proportion]{proportion_*}} to calculate microbial resistance and susceptibility.
|
|
}
|