From 36e63888685b2a8672def07062829765f538a5e0 Mon Sep 17 00:00:00 2001 From: Matthijs Berends Date: Sun, 11 Oct 2026 22:32:15 +0200 Subject: [PATCH] (v3.0.1.9118) update doc --- DESCRIPTION | 2 +- NEWS.md | 2 +- R/sir_combine.R | 20 +++++++++----------- index.md | 26 +++++++++++++++----------- man/antibiogram.Rd | 12 +++--------- man/count.Rd | 12 +++--------- man/proportion.Rd | 12 +++--------- man/sir_combine.Rd | 20 +++++++++----------- 8 files changed, 44 insertions(+), 62 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 611efe354..0cea5e2bc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: AMR -Version: 3.0.1.9117 +Version: 3.0.1.9118 Date: 2026-10-11 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) diff --git a/NEWS.md b/NEWS.md index 987de529c..e43c93b75 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 3.0.1.9117 +# AMR 3.0.1.9118 Planned as v3.1.0, mid October 2026. diff --git a/R/sir_combine.R b/R/sir_combine.R index 14cbf67ad..7897728f6 100644 --- a/R/sir_combine.R +++ b/R/sir_combine.R @@ -27,26 +27,20 @@ # how to conduct AMR data analysis: https://amr-for-r.org # # ==================================================================== # - #' Combine SIR Results of Multiple Antimicrobials #' -#' @description Combine the SIR results of two or more antimicrobials into one SIR result per isolate, e.g. to create a variable `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 *Combination Therapy* below for the exact rules. +#' @description Combine the SIR results of two or more antimicrobials into one SIR result per isolate, e.g. to create a variable 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 *Combination Therapy* below for the exact rules. #' #' The same rules are used by [antibiogram()] and [wisca()] for combination antibiograms, and by the [`count_*()`][count()] and [`proportion_*()`][proportion()] functions when more than one variable is used, so the result of [sir_combine()] can be used in any further analysis. #' @param ... Two or more vectors (or columns) with antimicrobial interpretations, or a data frame with such columns. They will be transformed internally with [as.sir()] if needed. All vectors must be of the same length. #' @param only_all_tested A [logical] to indicate that isolates must be tested for all antimicrobials. If `TRUE`, the result is `NA` for isolates with a missing result for any of the antimicrobials. If `FALSE` (default), a missing result only leads to `NA` if a result for the missing antimicrobial could have changed the result of the combination, see *Combination Therapy* below. #' @param guideline Either `"EUCAST"` (default) or `"CLSI"`, to determine whether the 'I' category is considered susceptible. This only affects isolates with a missing result for any of the antimicrobials when `only_all_tested = FALSE`, see *Combination Therapy* below. The default can be changed with the `AMR_guideline` option, see [AMR-options]. #' @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: +#' A combination of antimicrobials is considered as good as its most active antimicrobial: `"S"` is preferred over `"WT"`, and `"R"` over `"NWT"` and `"NS"`. The value `"NI"` (non-interpretable) is considered a missing result. #' -#' 1. `"S"` and `"WT"` -#' 2. `"SDD"` -#' 3. `"I"` -#' 4. `"R"`, `"NWT"`, and `"NS"` +#' A missing result can only be ignored if the result of the combination is susceptible regardless of the missing result, which depends on the `only_all_tested` argument and on the guideline: under EUCAST, the 'I' category is considered susceptible (*susceptible, increased exposure*), and under CLSI, it is not. #' -#' 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, `"S"` is preferred over `"WT"`, and `"R"` over `"NWT"` and `"NS"`. The value `"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 `only_all_tested` argument and on the guideline: under EUCAST, the 'I' category is considered susceptible (*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): +#' This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter): #' #' ``` #' ------------------------------------------------------------------------- @@ -86,6 +80,7 @@ #' if (require("dplyr")) { #' # create a new variable for piperacillin/tazobactam + gentamicin #' example_isolates %>% +#' filter(!is.na(TZP)) %>% #' mutate(TZP_GEN = sir_combine(TZP, GEN)) %>% #' select(mo, TZP, GEN, TZP_GEN) #' } @@ -102,7 +97,10 @@ #' group_by(ward) %>% #' summarise( #' TZP = susceptibility(TZP), -#' TZP_GEN = susceptibility(TZP_GEN) +#' GEN = susceptibility(GEN), +#' TZP_GEN = susceptibility(TZP_GEN), +#' # or directly, without combining first: +#' TZP_GEN2 = susceptibility(TZP, GEN) #' ) #' } #' } diff --git a/index.md b/index.md index 49be060f7..4f4ab3797 100644 --- a/index.md +++ b/index.md @@ -170,11 +170,13 @@ example_isolates %>% #> ℹ Using column mo as input for `mo_fullname()` #> ℹ Using column mo as input for `mo_is_gram_negative()` #> ℹ Using column mo as input for `mo_is_intrinsic_resistant()` -#> ℹ Determining intrinsic resistance based on 'EUCAST Expected Resistant Phenotypes' v1.2 (2023). -#> This note will be shown once per session. -#> ℹ For `aminoglycosides()` using columns GEN (gentamicin), TOB (tobramycin), AMK (amikacin), and KAN -#> (kanamycin) -#> ℹ For `carbapenems()` using columns IPM (imipenem) and MEM (meropenem) +#> ℹ Determining intrinsic resistance based on 'EUCAST Expected +#> Resistant Phenotypes' v1.2 (2023). This note will be shown +#> once per session. +#> ℹ For `aminoglycosides()` using columns GEN (gentamicin), TOB +#> (tobramycin), AMK (amikacin), and KAN (kanamycin) +#> ℹ For `carbapenems()` using columns IPM (imipenem) and MEM +#> (meropenem) #> # A tibble: 35 × 7 #> bacteria GEN TOB AMK KAN IPM MEM #> @@ -251,7 +253,8 @@ for tracking resistance per species over time: antibiogram(example_isolates, mo_transform = "gramstain", antimicrobials = c("AMC", carbapenems(), "TZP")) -#> ℹ For `carbapenems()` using columns IPM (imipenem) and MEM (meropenem) +#> ℹ For `carbapenems()` using columns IPM (imipenem) and MEM +#> (meropenem) ``` | Pathogen | Amoxicillin/clavulanic acid | Imipenem | Meropenem | Piperacillin/tazobactam | @@ -366,15 +369,16 @@ out <- example_isolates %>% # calculate AMR using resistance(), over all aminoglycosides and polymyxins: summarise(across(c(aminoglycosides(), polymyxins()), resistance)) -#> ℹ For `aminoglycosides()` using columns GEN (gentamicin), TOB (tobramycin), AMK (amikacin), and KAN -#> (kanamycin) +#> ℹ For `aminoglycosides()` using columns GEN (gentamicin), TOB +#> (tobramycin), AMK (amikacin), and KAN (kanamycin) #> ℹ For `polymyxins()` using column COL (colistin) #> Warning: There was 1 warning in `summarise()`. -#> ℹ In argument: `across(c(aminoglycosides(), polymyxins()), resistance)`. +#> ℹ In argument: `across(c(aminoglycosides(), polymyxins()), +#> resistance)`. #> ℹ In group 3: `ward = "Outpatient"`. #> Caused by warning: -#> ! Introducing NA: only 23 results available for KAN in group: ward = "Outpatient" (whilst `minimum = -#> 30`). +#> ! Introducing NA: only 23 results available for KAN in group: +#> ward = "Outpatient" (whilst `minimum = 30`). out #> # A tibble: 3 × 6 #> ward GEN TOB AMK KAN COL diff --git a/man/antibiogram.Rd b/man/antibiogram.Rd index 20da01b24..1124b92e7 100644 --- a/man/antibiogram.Rd +++ b/man/antibiogram.Rd @@ -271,17 +271,11 @@ For the full mathematical derivation and worked examples, see the \href{https:// \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"} -} +A combination of antimicrobials is considered as good as its most active antimicrobial: \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. -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. -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): +This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter): \if{html}{\out{
}}\preformatted{------------------------------------------------------------------------- Result of the combination diff --git a/man/count.Rd b/man/count.Rd index 81bc6af2f..d747cc7ce 100644 --- a/man/count.Rd +++ b/man/count.Rd @@ -92,17 +92,11 @@ This AMR package follows insight; use \code{\link[=susceptibility]{susceptibilit \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"} -} +A combination of antimicrobials is considered as good as its most active antimicrobial: \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. -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. -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): +This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter): \if{html}{\out{
}}\preformatted{------------------------------------------------------------------------- Result of the combination diff --git a/man/proportion.Rd b/man/proportion.Rd index 56ef028ce..8f08d00b5 100644 --- a/man/proportion.Rd +++ b/man/proportion.Rd @@ -135,17 +135,11 @@ This AMR package follows insight; use \code{\link[=susceptibility]{susceptibilit \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"} -} +A combination of antimicrobials is considered as good as its most active antimicrobial: \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. -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. -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): +This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter): \if{html}{\out{
}}\preformatted{------------------------------------------------------------------------- Result of the combination diff --git a/man/sir_combine.Rd b/man/sir_combine.Rd index efc159575..b65d6cb26 100644 --- a/man/sir_combine.Rd +++ b/man/sir_combine.Rd @@ -21,23 +21,17 @@ sir_combine( 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. +Combine the SIR results of two or more antimicrobials into one SIR result per isolate, e.g. to create a variable 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"} -} +A combination of antimicrobials is considered as good as its most active antimicrobial: \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. -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. -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): +This is an example for two antimicrobials, Drug A and Drug B (the order of the antimicrobials does not matter): \if{html}{\out{
}}\preformatted{------------------------------------------------------------------------- Result of the combination @@ -75,6 +69,7 @@ susceptibility(sir_combine(drug_a, drug_b), minimum = 0) if (require("dplyr")) { # create a new variable for piperacillin/tazobactam + gentamicin example_isolates \%>\% + filter(!is.na(TZP)) \%>\% mutate(TZP_GEN = sir_combine(TZP, GEN)) \%>\% select(mo, TZP, GEN, TZP_GEN) } @@ -91,7 +86,10 @@ if (require("dplyr")) { group_by(ward) \%>\% summarise( TZP = susceptibility(TZP), - TZP_GEN = susceptibility(TZP_GEN) + GEN = susceptibility(GEN), + TZP_GEN = susceptibility(TZP_GEN), + # or directly, without combining first: + TZP_GEN2 = susceptibility(TZP, GEN) ) } }