(v3.0.1.9116) New sir_combine() for combination therapy as one engine for antibiogram(), wisca(), count_*() and proportion_*() (#321), and make all suggested packages runtime-only with a new CI workflow without dplyr

- 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)
This commit is contained in:
dr. M.S. (Matthijs) Berends committed 2026-10-11 20:36:31 +02:00
1 parent 80afedeb8c
commit 53d0704271
30 files changed
+939 -268

No files matched your search

+35 -19
View File
@@ -243,25 +243,7 @@ your_data \%>\%
\subsection{Inclusion in Combination Antibiograms}{
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 antimicrobials, 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 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>}}
For combination antibiograms, the results of the antimicrobials are combined using the same rules as \code{\link[=sir_combine]{sir_combine()}}, see the section \emph{Combination Therapy} below. Whether isolates must be tested for all antimicrobials can be set with the \code{only_all_tested} argument (default is \code{FALSE}). The 'I' and 'SDD' categories are considered susceptible if \code{combine_SI = TRUE} (default), which also determines whether a missing result can be ignored. To use a combination in other analyses as well, create a new variable with \code{\link[=sir_combine]{sir_combine()}}.
}
\subsection{Plotting}{
@@ -287,6 +269,40 @@ It does so by combining two quantities: the relative incidence of each pathogen
For the full mathematical derivation and worked examples, see the \href{https://amr-for-r.org/articles/WISCA.html}{WISCA vignette}.
}
\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.
+28 -31
View File
@@ -50,7 +50,7 @@ count_df(
\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.}
\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{
@@ -79,7 +79,7 @@ These functions can be used to count resistant/susceptible microbial isolates. A
\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 all input antimicrobials have an available result (S, I or R). 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[=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.
}
@@ -92,39 +92,36 @@ This AMR package follows insight; use \code{\link[=susceptibility]{susceptibilit
\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:
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"}
}
\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> - - - -
--------------------------------------------------------------------
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>}}
Please note that, in combination therapies, for \code{only_all_tested = TRUE} applies that:
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.
\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.
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{
+13 -19
View File
@@ -29,25 +29,18 @@ g.test(x, y = NULL, p = rep(1/length(x), length(x)), rescale.p = FALSE)
\code{p} does not sum to 1, an error is given.}
}
\value{
A list with class \code{"htest"} containing the following
components:
\item{statistic}{the value the chi-squared test statistic.}
\item{parameter}{the degrees of freedom of the approximate
chi-squared distribution of the test statistic, \code{NA} if the
p-value is computed by Monte Carlo simulation.}
\item{p.value}{the p-value for the test.}
\item{method}{a character string indicating the type of test
performed, and whether Monte Carlo simulation or continuity
correction was used.}
\item{data.name}{a character string giving the name(s) of the data.}
\item{observed}{the observed counts.}
\item{expected}{the expected counts under the null hypothesis.}
\item{residuals}{the Pearson residuals,
\code{(observed - expected) / sqrt(expected)}.}
\item{stdres}{standardized residuals,
\code{(observed - expected) / sqrt(V)}, where \code{V} is the
residual cell variance {(\if{html}{\out{<a href="#reference+chisq.test.Rd+R+3AAgresti+3A2007" class="citation">}}Agresti 2007\if{html}{\out{</a>}}, section 2.4.5)}
for the case where \code{x} is a matrix, \code{n * p * (1 - p)} otherwise).}
A \link{list} with class \code{"htest"} containing the following components:
\itemize{
\item \code{statistic}: the value of the test statistic
\item \code{parameter}: the degrees of freedom of the approximate chi-squared distribution of the test statistic, \code{NA} if the p-value is computed by Monte Carlo simulation
\item \code{p.value}: the p-value for the test
\item \code{method}: a character string indicating the type of test performed, and whether Monte Carlo simulation was used
\item \code{data.name}: a character string giving the name(s) of the data
\item \code{observed}: the observed counts
\item \code{expected}: the expected counts under the null hypothesis
\item \code{residuals}: the Pearson residuals, \code{(observed - expected) / sqrt(expected)}
\item \code{stdres}: standardised residuals, \code{(observed - expected) / sqrt(V)}, where \code{V} is the residual cell variance (Agresti 2007, section 2.4.5) for the case where \code{x} is a matrix, \code{n * p * (1 - p)} otherwise
}
}
\description{
\code{\link[=g.test]{g.test()}} performs chi-squared contingency table tests and goodness-of-fit tests, just like \code{\link[=chisq.test]{chisq.test()}} but is more reliable (1). A \emph{G}-test can be used to see whether the number of observations in each category fits a theoretical expectation (called a \strong{\emph{G}-test of goodness-of-fit}), or to see whether the proportions of one variable are different for different values of the other variable (called a \strong{\emph{G}-test of independence}).
@@ -134,6 +127,7 @@ g.test(x)
\references{
\enumerate{
\item McDonald, J.H. 2014. \strong{Handbook of Biological Statistics (3rd ed.)}. Sparky House Publishing, Baltimore, Maryland.
\item Agresti, A. 2007. \strong{An Introduction to Categorical Data Analysis (2nd ed.)}. Wiley, New York.
}
}
\seealso{
+4 -8
View File
@@ -58,14 +58,7 @@ ggplot_pca(
will be issued if the specified \code{scale} is outside this range.
}
\item{pc.biplot}{
If true, use what {\if{html}{\cite{}\out{<a href="#reference+biplot.princomp.Rd+R+3AGabriel+3A1971" class="citation">}}Gabriel (1971)\if{html}{\out{</a>}}} refers to as a
\dQuote{principal component biplot},
with \code{lambda = 1} and observations scaled up by sqrt(n) and
variables scaled down by sqrt(n). Then inner products between
variables approximate covariances and distances between observations
approximate Mahalanobis distance.
}
\item{pc.biplot}{If \code{TRUE}, use what Gabriel (1971) refers to as a 'principal component biplot', with \code{lambda = 1} and observations scaled up by \code{sqrt(n)} and variables scaled down by \code{sqrt(n)}. Then inner products between variables approximate covariances and distances between observations approximate Mahalanobis distance.}
\item{labels}{An optional vector of labels for the observations. If set, the labels will be placed below their respective points. When using the \code{\link[=pca]{pca()}} function as input for \code{x}, this will be determined automatically based on the attribute \code{non_numeric_cols}, see \code{\link[=pca]{pca()}}.}
@@ -147,3 +140,6 @@ if (require("dplyr")) {
}
}
}
\references{
Gabriel, K.R. 1971. \strong{The biplot graphical display of matrices with application to principal component analysis}. \emph{Biometrika} 58(3):453-467. \doi{10.1093/biomet/58.3.453}
}
+2 -2
View File
@@ -46,8 +46,8 @@ These \code{\link[=like]{like()}} and \verb{\%like\%}/\verb{\%unlike\%} function
Using RStudio? The \verb{\%like\%}/\verb{\%unlike\%} functions can also be directly inserted in your code from the Addins menu and can have its own keyboard shortcut like \code{Shift+Ctrl+L} or \code{Shift+Cmd+L} (see menu \code{Tools} > \verb{Modify Keyboard Shortcuts...}). If you keep pressing your shortcut, the inserted text will be iterated over \verb{\%like\%} -> \verb{\%unlike\%} -> \verb{\%like_case\%} -> \verb{\%unlike_case\%}.
}
\examples{
# data.table has a more limited version of \%like\%, so unload it:
try(detach("package:data.table", unload = TRUE), silent = TRUE)
# data.table has a more limited version of \%like\%, so detach it (without unloading it, as data.table does not support being unloaded):
try(detach("package:data.table"), silent = TRUE)
a <- "This is a test"
b <- "TEST"
+35 -38
View File
@@ -79,7 +79,7 @@ sir_df(
\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{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{
@@ -126,43 +126,6 @@ These functions are not meant to count isolates, but to calculate the proportion
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/bacteria/clinical-breakpoints-and-interpretation/definition-of-s-i-and-r/}).
@@ -170,6 +133,40 @@ In 2019, the European Committee on Antimicrobial Susceptibility Testing (EUCAST)
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.
+101
View File
@@ -0,0 +1,101 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sir_combine.R
\name{sir_combine}
\alias{sir_combine}
\title{Combine SIR Results of Multiple Antimicrobials}
\usage{
sir_combine(
...,
only_all_tested = FALSE,
guideline = getOption("AMR_guideline", "EUCAST")
)
}
\arguments{
\item{...}{Two or more vectors (or columns) with antimicrobial interpretations, or a data frame with such columns. They will be transformed internally with \code{\link[=as.sir]{as.sir()}} if needed. All vectors must be of the same length.}
\item{only_all_tested}{A \link{logical} to indicate that isolates must be tested for all antimicrobials. If \code{TRUE}, the result is \code{NA} for isolates with a missing result for any of the antimicrobials. If \code{FALSE} (default), a missing result only leads to \code{NA} if a result for the missing antimicrobial could have changed the result of the combination, see \emph{Combination Therapy} below.}
\item{guideline}{Either \code{"EUCAST"} (default) or \code{"CLSI"}, to determine whether the 'I' category is considered susceptible. This only affects isolates with a missing result for any of the antimicrobials when \code{only_all_tested = FALSE}, see \emph{Combination Therapy} below. The default can be changed with the \code{AMR_guideline} option, see \link{AMR-options}.}
}
\value{
A \code{\link{sir}} vector with the same length as the input.
}
\description{
Combine the SIR results of two or more antimicrobials into one SIR result per isolate, e.g. to create a variable \code{TZP_GEN} for the combination therapy of piperacillin/tazobactam with gentamicin. The result is the best result of the antimicrobials, as a combination therapy covers the isolate if any of its antimicrobials is active. See \emph{Combination Therapy} below for the exact rules.
The same rules are used by \code{\link[=antibiogram]{antibiogram()}} and \code{\link[=wisca]{wisca()}} for combination antibiograms, and by the \code{\link[=count]{count_*()}} and \code{\link[=proportion]{proportion_*()}} functions when more than one variable is used, so the result of \code{\link[=sir_combine]{sir_combine()}} can be used in any further analysis.
}
\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{
drug_a <- as.sir(c("S", "R", "R", "I", "I", NA, "R", "SDD"))
drug_b <- as.sir(c("R", "S", "R", "R", NA, NA, NA, "I"))
sir_combine(drug_a, drug_b)
sir_combine(drug_a, drug_b, guideline = "CLSI")
sir_combine(drug_a, drug_b, only_all_tested = TRUE)
# the count and proportion functions use the same rules
susceptibility(drug_a, drug_b, minimum = 0)
susceptibility(sir_combine(drug_a, drug_b), minimum = 0)
\donttest{
if (require("dplyr")) {
# create a new variable for piperacillin/tazobactam + gentamicin
example_isolates \%>\%
mutate(TZP_GEN = sir_combine(TZP, GEN)) \%>\%
select(mo, TZP, GEN, TZP_GEN)
}
if (require("dplyr")) {
# combine any number of antimicrobials
example_isolates \%>\%
mutate(any_aminoglycoside = sir_combine(GEN, TOB, AMK, KAN)) \%>\%
count(any_aminoglycoside)
}
if (require("dplyr")) {
# use the new variable in further analyses
example_isolates \%>\%
mutate(TZP_GEN = sir_combine(TZP, GEN)) \%>\%
group_by(ward) \%>\%
summarise(
TZP = susceptibility(TZP),
TZP_GEN = susceptibility(TZP_GEN)
)
}
}
}
\seealso{
\code{\link[=count]{count()}} and \code{\link[=proportion]{proportion()}} for counting and calculating susceptibility of (combinations of) antimicrobials, and \code{\link[=antibiogram]{antibiogram()}} for combination antibiograms.
}