diff --git a/DESCRIPTION b/DESCRIPTION index de8d80492..3f0643be7 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 3.0.1.9033 -Date: 2026-03-09 +Version: 3.0.1.9034 +Date: 2026-03-11 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) data analysis and to work with microbial and antimicrobial properties by diff --git a/NAMESPACE b/NAMESPACE index 91808bf54..c8e953a0d 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -172,6 +172,7 @@ export(all_sir_predictors) export(aminoglycosides) export(aminopenicillins) export(amr_class) +export(amr_course) export(amr_distance_from_row) export(amr_selector) export(anti_join_microorganisms) diff --git a/NEWS.md b/NEWS.md index c6ecbb237..26fa78716 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 3.0.1.9033 +# AMR 3.0.1.9034 ### New * Integration with the **tidymodels** framework to allow seamless use of SIR, MIC and disk data in modelling pipelines via `recipes` @@ -13,9 +13,9 @@ - `as.sir()` gained an argument `as_wt_nwt`, which defaults to `TRUE` only when `breakpoint_type = "ECOFF"` (#254) - This transforms the output from S/R to WT/NWT - Functions such as `susceptibility()` count WT as S and NWT as R -* `interpretive_rules()`, which allows future implementation of CLSI interpretive rules (#235) +* Function `interpretive_rules()`, which allows future implementation of CLSI interpretive rules (#235) - `eucast_rules()` has become a wrapper around that function -* Two new `NA` objects, `NA_ab_` and `NA_mo_`, analogous to base R's `NA_character_` and `NA_integer_`, for use in pipelines that require typed missing values +* Function `amr_course()`, which allows for automated download and unpacking of a GitHub repository for e.g. webinar use ### Fixes * Fixed a bug in `as.sir()` where values that were purely numeric (e.g., `"1"`) and matched the broad SIR-matching regex would be incorrectly stripped of all content by the Unicode letter filter @@ -43,6 +43,7 @@ * This results in more reliable behaviour compared to previous versions for capped MIC values * Removed the `"inverse"` option, which has now become redundant * `ab_group()` now returns values consist with the AMR selectors (#246) +* Added two new `NA` objects, `NA_ab_` and `NA_mo_`, analogous to base R's `NA_character_` and `NA_integer_`, for use in pipelines that require typed missing values # AMR 3.0.1 diff --git a/R/amr_course.R b/R/amr_course.R new file mode 100644 index 000000000..e188e3afb --- /dev/null +++ b/R/amr_course.R @@ -0,0 +1,62 @@ +# ==================================================================== # +# TITLE: # +# AMR: An R Package for Working with Antimicrobial Resistance Data # +# # +# SOURCE CODE: # +# https://github.com/msberends/AMR # +# # +# PLEASE CITE THIS SOFTWARE AS: # +# Berends MS, Luz CF, Friedrich AW, et al. (2022). # +# AMR: An R Package for Working with Antimicrobial Resistance Data. # +# Journal of Statistical Software, 104(3), 1-31. # +# https://doi.org/10.18637/jss.v104.i03 # +# # +# Developed at the University of Groningen and the University Medical # +# Center Groningen in The Netherlands, in collaboration with many # +# colleagues from around the world, see our website. # +# # +# This R package is free software; you can freely use and distribute # +# it for both personal and commercial purposes under the terms of the # +# GNU General Public License version 2.0 (GNU GPL-2), as published by # +# the Free Software Foundation. # +# We created this package for both routine data analysis and academic # +# research and it was publicly released in the hope that it will be # +# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY. # +# # +# Visit our website for the full manual and a complete tutorial about # +# how to conduct AMR data analysis: https://amr-for-r.org # +# ==================================================================== # + +#' Download and Unpack an AMR Course Repository +#' +#' Downloads and unpacks a GitHub repository containing course materials, using [usethis::use_course()]. This is a convenience wrapper intended for use in educational settings, such as workshops or tutorials associated with the AMR package. +#' @param github_repo A character string specifying the GitHub repository with username and repo name, e.g. `"https://github.com/username/repo"`. +#' @param branch A character string specifying the branch to download. Defaults to `"main"`. +#' @param ... Additional arguments passed on to [usethis::use_course()]. +#' @details +#' This function constructs a ZIP archive URL from the provided `github_repo` and `branch`, then delegates to [usethis::use_course()] to handle the download and extraction. +#' +#' The function is designed for interactive use in course or workshop settings and is not intended for use in non-interactive or automated pipelines. +#' @return +#' Called for its side effect. [usethis::use_course()] will prompt the user to choose a destination and open the extracted project. Returns invisibly whatever [usethis::use_course()] returns. +#' @seealso [usethis::use_course()] +#' @export +#' @examples +#' \dontrun{ +#' +#' # Let this run by users, e.g., webinar participants +#' amr_course("https://github.com/my_user_name/our_AMR_course") +#' } +amr_course <- function(github_repo, branch = "main", ...) { + if (!"usethis" %in% rownames(utils::installed.packages())) { + if ("rlang" %in% rownames(utils::installed.packages())) { + rlang::check_installed("usethis") + } else { + stop("Package usethis is not installed. Please run: install.packages(\"usethis\")", call. = FALSE) + } + } + url <- paste0(github_repo, "/archive/refs/heads/", branch, ".zip") + use_course <- import_fn("use_course", "usethis") + message("This will download and unpack the contents of a repository.\n") + use_course(url, ...) +} diff --git a/R/interpretive_rules.R b/R/interpretive_rules.R index 02b3094ae..ce0555c13 100755 --- a/R/interpretive_rules.R +++ b/R/interpretive_rules.R @@ -56,11 +56,6 @@ format_eucast_version_nr <- function(version, markdown = TRUE) { #' Apply Interpretive Rules #' #' @description -#' **WORK IN PROGRESS** -#' -# TODO Remove this remark before next release -#' **The `interpretive_rules()` function is new, to allow CLSI 'rules' too. The old `eucast_rules()` function will stay as a wrapper, but we need to generalise more parts of the underlying code to allow more than just EUCAST.** -#' #' Apply rules from clinical breakpoints notes and expected resistant phenotypes as defined by e.g. the European Committee on Antimicrobial Susceptibility Testing (EUCAST, ), see *Source*. Use [eucast_dosage()] to get a [data.frame] with advised dosages of a certain bug-drug combination, which is based on the [dosage] data set. #' #' To improve the interpretation of the antibiogram before CLSI/EUCAST interpretive rules are applied, some AMR-specific rules can be applied at default, see *Details*. diff --git a/_pkgdown.yml b/_pkgdown.yml index e6a9e4a2b..b819487bc 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -245,12 +245,14 @@ reference: - title: "Other: miscellaneous functions" desc: > - These functions are mostly for internal use, but some of - them may also be suitable for your analysis. Especially the - 'like' function can be useful: `if (x %like% y) {...}`. + Miscellaneous functions that support various parts of an AMR analysis, + such as working with ages, joining tables, principal component analysis, + and other utilities. Especially the 'like' function can be useful: + `if (x %like% y) {...}`. contents: - "`age_groups`" - "`age`" + - "`amr_course`" - "`export_ncbi_biosample`" - "`availability`" - "`get_AMR_locale`" diff --git a/man/amr_course.Rd b/man/amr_course.Rd new file mode 100644 index 000000000..9678f886c --- /dev/null +++ b/man/amr_course.Rd @@ -0,0 +1,36 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/amr_course.R +\name{amr_course} +\alias{amr_course} +\title{Download and Unpack an AMR Course Repository} +\usage{ +amr_course(github_repo, branch = "main", ...) +} +\arguments{ +\item{github_repo}{A character string specifying the GitHub repository with username and repo name, e.g. \code{"https://github.com/username/repo"}.} + +\item{branch}{A character string specifying the branch to download. Defaults to \code{"main"}.} + +\item{...}{Additional arguments passed on to \code{\link[usethis:zip-utils]{usethis::use_course()}}.} +} +\value{ +Called for its side effect. \code{\link[usethis:zip-utils]{usethis::use_course()}} will prompt the user to choose a destination and open the extracted project. Returns invisibly whatever \code{\link[usethis:zip-utils]{usethis::use_course()}} returns. +} +\description{ +Downloads and unpacks a GitHub repository containing course materials, using \code{\link[usethis:zip-utils]{usethis::use_course()}}. This is a convenience wrapper intended for use in educational settings, such as workshops or tutorials associated with the AMR package. +} +\details{ +This function constructs a ZIP archive URL from the provided \code{github_repo} and \code{branch}, then delegates to \code{\link[usethis:zip-utils]{usethis::use_course()}} to handle the download and extraction. + +The function is designed for interactive use in course or workshop settings and is not intended for use in non-interactive or automated pipelines. +} +\examples{ +\dontrun{ + +# Let this run by users, e.g., webinar participants +amr_course("https://github.com/my_user_name/our_AMR_course") +} +} +\seealso{ +\code{\link[usethis:zip-utils]{usethis::use_course()}} +} diff --git a/man/interpretive_rules.Rd b/man/interpretive_rules.Rd index da41a05cc..e08412fcf 100644 --- a/man/interpretive_rules.Rd +++ b/man/interpretive_rules.Rd @@ -76,10 +76,6 @@ eucast_dosage(ab, administration = "iv", version_breakpoints = 15) The input of \code{x}, possibly with edited values of antimicrobials. Or, if \code{verbose = TRUE}, a \link{data.frame} with all original and new values of the affected bug-drug combinations. } \description{ -\strong{WORK IN PROGRESS} - -\strong{The \code{interpretive_rules()} function is new, to allow CLSI 'rules' too. The old \code{eucast_rules()} function will stay as a wrapper, but we need to generalise more parts of the underlying code to allow more than just EUCAST.} - Apply rules from clinical breakpoints notes and expected resistant phenotypes as defined by e.g. the European Committee on Antimicrobial Susceptibility Testing (EUCAST, \url{https://www.eucast.org}), see \emph{Source}. Use \code{\link[=eucast_dosage]{eucast_dosage()}} to get a \link{data.frame} with advised dosages of a certain bug-drug combination, which is based on the \link{dosage} data set. To improve the interpretation of the antibiogram before CLSI/EUCAST interpretive rules are applied, some AMR-specific rules can be applied at default, see \emph{Details}.