diff --git a/DESCRIPTION b/DESCRIPTION index 922e073a..4d502314 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: AMR -Version: 2.1.1.9053 +Version: 2.1.1.9054 Date: 2024-06-17 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) diff --git a/NEWS.md b/NEWS.md index 0e83e61f..7b1b9f28 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,6 @@ -# AMR 2.1.1.9053 +# AMR 2.1.1.9054 -*(this beta version will eventually become v3.0. We're happy to reach a new major milestone soon, which will be all about the new One Health support!)* +*(this beta version will eventually become v3.0. We're happy to reach a new major milestone soon, which will be all about the new One Health support! Install this beta using [the instructions here](https://msberends.github.io/AMR/#latest-development-version).)* #### A New Milestone: One Health Support (= Human + Veterinary + Environmental) This package now supports not only tools for AMR data analysis in clinical settings, but also for veterinary and environmental microbiology. This was made possible through a collaboration with the [University of Prince Edward Island](https://www.upei.ca/avc), Canada. To celebrate this great improvement of the package, we also updated the package logo to reflect this change. @@ -15,11 +15,11 @@ This package now supports not only tools for AMR data analysis in clinical setti * The `antibiotics` data set contains all veterinary antibiotics, such as pradofloxacin and enrofloxacin. All WHOCC codes for veterinary use have been added as well. * `ab_atc()` now supports ATC codes of veterinary antibiotics (that all start with "Q") * `ab_url()` now supports retrieving the WHOCC url of their ATCvet pages +* EUCAST 2024 and CLSI 2024 are now supported, by adding all of their over 4,000 clinical breakpoints to the `clinical_breakpoints` data set for usage in `as.sir()`. EUCAST 2024 (v14.0) is now the new default guideline for all MIC and disks diffusion interpretations. * `as.sir()` now brings additional factor levels: "NI" for non-interpretable and "SDD" for susceptible dose-dependent. Users can now set their own criteria (using regular expressions) as to what should be considered S, I, R, SDD, and NI. Also, to get quantitative values, `as.double()` or a `sir` object will return 1 for S, 2 for SDD/I, and 3 for R (NI will become `NA`). Other functions using `sir` classes (e.g., `summary()`) are updated to reflect the change to contain NI and SDD. * The function group `scale_*_mic()`, namely: `scale_x_mic()`, `scale_y_mic()`, `scale_colour_mic()` and `scale_fill_mic()`. They are advanced ggplot2 extensions to allow easy plotting of MIC values. They allow for manual range definition and plotting missing intermediate log2 levels. * Function `rescale_mic()`, which allows to rescale MIC values to a manually set range. This is the powerhouse behind the `scale_*_mic()` functions, but it can be used by users directly to e.g. compare equality in MIC distributions by rescaling them to the same range first. * Function `mo_group_members()` to retrieve the member microorganisms of a microorganism group. For example, `mo_group_members("Strep group C")` returns a vector of all microorganisms that are in that group. -* Clinical breakpoints and intrinsic resistance of EUCAST 2024 and CLSI 2024 have been added to the `clinical_breakpoints` data set for usage in `as.sir()`. EUCAST 2024 (v14.0) is now the new default guideline for all MIC and disks diffusion interpretations. ## Changed * For SIR interpretation, it is now possible to use column names for argument `ab`, `mo`, and `uti`: `as.sir(..., ab = "column1", mo = "column2", uti = "column3")`. This greatly improves the flexibility for users. diff --git a/R/sir.R b/R/sir.R index b9779964..8c58e4d0 100755 --- a/R/sir.R +++ b/R/sir.R @@ -158,33 +158,89 @@ #' summary(example_isolates) # see all SIR results at a glance #' #' # For INTERPRETING disk diffusion and MIC values ----------------------- +#' +#' # example data sets, with combined MIC values and disk zones +#' df_wide <- data.frame( +#' microorganism = "Escherichia coli", +#' AMP = as.mic(8), +#' CIP = as.mic(0.256), +#' GEN = as.disk(18), +#' TOB = as.disk(16), +#' ERY = "R" +#' ) +#' df_long <- data.frame( +#' bacteria = rep("Escherichia coli", 3), +#' antibiotic = c("amoxicillin", "cipro", "tobra", "genta"), +#' mics = as.mic(c(0.01, 1, 4, 8)), +#' disks = as.disk(c(6, 10, 14, 18)) +#' ) #' #' \donttest{ #' ## Using dplyr ------------------------------------------------- #' if (require("dplyr")) { #' # approaches that all work without additional arguments: -#' df %>% mutate_if(is.mic, as.sir) -#' df %>% mutate_if(function(x) is.mic(x) | is.disk(x), as.sir) -#' df %>% mutate(across(where(is.mic), as.sir)) -#' df %>% mutate_at(vars(AMP:TOB), as.sir) -#' df %>% mutate(across(AMP:TOB, as.sir)) +#' df_wide %>% mutate_if(is.mic, as.sir) +#' df_wide %>% mutate_if(function(x) is.mic(x) | is.disk(x), as.sir) +#' df_wide %>% mutate(across(where(is.mic), as.sir)) +#' df_wide %>% mutate_at(vars(AMP:TOB), as.sir) +#' df_wide %>% mutate(across(AMP:TOB, as.sir)) #' #' # approaches that all work with additional arguments: -#' df %>% mutate_if(is.mic, as.sir, mo = "column1", guideline = "CLSI") -#' df %>% mutate(across(where(is.mic), -#' function(x) as.sir(x, mo = "column1", guideline = "CLSI"))) -#' df %>% mutate_at(vars(AMP:TOB), as.sir, mo = "column1", guideline = "CLSI") -#' df %>% mutate(across(AMP:TOB, -#' function(x) as.sir(x, mo = "column1", guideline = "CLSI"))) +#' df_long %>% +#' # given a certain data type, e.g. MIC values +#' mutate_if(is.mic, as.sir, +#' mo = "bacteria", +#' ab = "antibiotic", +#' guideline = "CLSI") +#' df_long %>% +#' mutate(across(where(is.mic), +#' function(x) as.sir(x, +#' mo = "bacteria", +#' ab = "antibiotic", +#' guideline = "CLSI"))) +#' df_long %>% +#' # given certain columns, e.g. from AMP to TOB +#' mutate_at(vars(AMP:TOB), as.sir, +#' mo = "bacteria", +#' ab = "antibiotic", +#' guideline = "CLSI") +#' df_long %>% +#' mutate(across(AMP:TOB, +#' function(x) as.sir(x, +#' mo = "bacteria", +#' ab = "antibiotic", +#' guideline = "CLSI"))) #' #' # for veterinary breakpoints, add 'host': -#' df %>% mutate_if(is.mic, as.sir, guideline = "CLSI", host = "species_column") -#' df %>% mutate_if(is.mic, as.sir, guideline = "CLSI", host = "horse") -#' df %>% mutate(across(where(is.mic), -#' function(x) as.sir(x, guideline = "CLSI", host = "species_column"))) -#' df %>% mutate_at(vars(AMP:TOB), as.sir, guideline = "CLSI", host = "species_column") -#' df %>% mutate(across(AMP:TOB, -#' function(x) as.sir(x, mo = "column1", guideline = "CLSI"))) +#' df_long$animal_species <- c("cats", "dogs", "horses", "cattle") +#' df_long %>% +#' # given a certain data type, e.g. MIC values +#' mutate_if(is.mic, as.sir, +#' mo = "bacteria", +#' ab = "antibiotic", +#' host = "animal_species", +#' guideline = "CLSI") +#' df_long %>% +#' mutate(across(where(is.mic), +#' function(x) as.sir(x, +#' mo = "bacteria", +#' ab = "antibiotic", +#' host = "animal_species", +#' guideline = "CLSI"))) +#' df_long %>% +#' # given certain columns, e.g. from AMP to TOB +#' mutate_at(vars(AMP:TOB), as.sir, +#' mo = "bacteria", +#' ab = "antibiotic", +#' host = "animal_species", +#' guideline = "CLSI") +#' df_long %>% +#' mutate(across(AMP:TOB, +#' function(x) as.sir(x, +#' mo = "bacteria", +#' ab = "antibiotic", +#' host = "animal_species", +#' guideline = "CLSI"))) #' #' # to include information about urinary tract infections (UTI) #' data.frame(mo = "E. coli", @@ -197,23 +253,14 @@ #' specimen = c("urine", "blood")) %>% #' as.sir() # automatically determines urine isolates #' -#' df %>% +#' df_wide %>% #' mutate_at(vars(AMP:TOB), as.sir, mo = "E. coli", uti = TRUE) #' } #' #' #' ## Using base R ------------------------------------------------ #' -#' # a whole data set, even with combined MIC values and disk zones -#' df <- data.frame( -#' microorganism = "Escherichia coli", -#' AMP = as.mic(8), -#' CIP = as.mic(0.256), -#' GEN = as.disk(18), -#' TOB = as.disk(16), -#' ERY = "R" -#' ) -#' as.sir(df) +#' as.sir(df_wide) #' #' # return a 'logbook' about the results: #' sir_interpretation_history() diff --git a/man/as.sir.Rd b/man/as.sir.Rd index bca720b2..d579cfe7 100644 --- a/man/as.sir.Rd +++ b/man/as.sir.Rd @@ -256,32 +256,88 @@ summary(example_isolates) # see all SIR results at a glance # For INTERPRETING disk diffusion and MIC values ----------------------- +# example data sets, with combined MIC values and disk zones +df_wide <- data.frame( + microorganism = "Escherichia coli", + AMP = as.mic(8), + CIP = as.mic(0.256), + GEN = as.disk(18), + TOB = as.disk(16), + ERY = "R" +) +df_long <- data.frame( + bacteria = rep("Escherichia coli", 3), + antibiotic = c("amoxicillin", "cipro", "tobra", "genta"), + mics = as.mic(c(0.01, 1, 4, 8)), + disks = as.disk(c(6, 10, 14, 18)) +) + \donttest{ ## Using dplyr ------------------------------------------------- if (require("dplyr")) { # approaches that all work without additional arguments: - df \%>\% mutate_if(is.mic, as.sir) - df \%>\% mutate_if(function(x) is.mic(x) | is.disk(x), as.sir) - df \%>\% mutate(across(where(is.mic), as.sir)) - df \%>\% mutate_at(vars(AMP:TOB), as.sir) - df \%>\% mutate(across(AMP:TOB, as.sir)) + df_wide \%>\% mutate_if(is.mic, as.sir) + df_wide \%>\% mutate_if(function(x) is.mic(x) | is.disk(x), as.sir) + df_wide \%>\% mutate(across(where(is.mic), as.sir)) + df_wide \%>\% mutate_at(vars(AMP:TOB), as.sir) + df_wide \%>\% mutate(across(AMP:TOB, as.sir)) # approaches that all work with additional arguments: - df \%>\% mutate_if(is.mic, as.sir, mo = "column1", guideline = "CLSI") - df \%>\% mutate(across(where(is.mic), - function(x) as.sir(x, mo = "column1", guideline = "CLSI"))) - df \%>\% mutate_at(vars(AMP:TOB), as.sir, mo = "column1", guideline = "CLSI") - df \%>\% mutate(across(AMP:TOB, - function(x) as.sir(x, mo = "column1", guideline = "CLSI"))) + df_long \%>\% + # given a certain data type, e.g. MIC values + mutate_if(is.mic, as.sir, + mo = "bacteria", + ab = "antibiotic", + guideline = "CLSI") + df_long \%>\% + mutate(across(where(is.mic), + function(x) as.sir(x, + mo = "bacteria", + ab = "antibiotic", + guideline = "CLSI"))) + df_long \%>\% + # given certain columns, e.g. from AMP to TOB + mutate_at(vars(AMP:TOB), as.sir, + mo = "bacteria", + ab = "antibiotic", + guideline = "CLSI") + df_long \%>\% + mutate(across(AMP:TOB, + function(x) as.sir(x, + mo = "bacteria", + ab = "antibiotic", + guideline = "CLSI"))) # for veterinary breakpoints, add 'host': - df \%>\% mutate_if(is.mic, as.sir, guideline = "CLSI", host = "species_column") - df \%>\% mutate_if(is.mic, as.sir, guideline = "CLSI", host = "horse") - df \%>\% mutate(across(where(is.mic), - function(x) as.sir(x, guideline = "CLSI", host = "species_column"))) - df \%>\% mutate_at(vars(AMP:TOB), as.sir, guideline = "CLSI", host = "species_column") - df \%>\% mutate(across(AMP:TOB, - function(x) as.sir(x, mo = "column1", guideline = "CLSI"))) + df_long$animal_species <- c("cats", "dogs", "horses", "cattle") + df_long \%>\% + # given a certain data type, e.g. MIC values + mutate_if(is.mic, as.sir, + mo = "bacteria", + ab = "antibiotic", + host = "animal_species", + guideline = "CLSI") + df_long \%>\% + mutate(across(where(is.mic), + function(x) as.sir(x, + mo = "bacteria", + ab = "antibiotic", + host = "animal_species", + guideline = "CLSI"))) + df_long \%>\% + # given certain columns, e.g. from AMP to TOB + mutate_at(vars(AMP:TOB), as.sir, + mo = "bacteria", + ab = "antibiotic", + host = "animal_species", + guideline = "CLSI") + df_long \%>\% + mutate(across(AMP:TOB, + function(x) as.sir(x, + mo = "bacteria", + ab = "antibiotic", + host = "animal_species", + guideline = "CLSI"))) # to include information about urinary tract infections (UTI) data.frame(mo = "E. coli", @@ -294,23 +350,14 @@ if (require("dplyr")) { specimen = c("urine", "blood")) \%>\% as.sir() # automatically determines urine isolates - df \%>\% + df_wide \%>\% mutate_at(vars(AMP:TOB), as.sir, mo = "E. coli", uti = TRUE) } ## Using base R ------------------------------------------------ -# a whole data set, even with combined MIC values and disk zones -df <- data.frame( - microorganism = "Escherichia coli", - AMP = as.mic(8), - CIP = as.mic(0.256), - GEN = as.disk(18), - TOB = as.disk(16), - ERY = "R" -) -as.sir(df) +as.sir(df_wide) # return a 'logbook' about the results: sir_interpretation_history()