(v3.0.1.9034) Add amr_course()

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AMR
 Version: 3.0.1.9034
-Date: 2026-03-09
+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

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)

NEWS.md

@@ -13,10 +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
-* `eucast_rules()` / `interpretive_rules()` gained argument `add_if_missing` (default: `TRUE`). When set to `FALSE`, rules are only applied to cells that already contain an SIR value; `NA` cells are left untouched. This is useful with `overwrite = TRUE` to update reported results without imputing values for drugs that were not tested (#259)
-* 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
@@ -44,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

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, ...)
+}

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, <https://www.eucast.org>), 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*.
@@ -79,7 +74,6 @@ format_eucast_version_nr <- function(version, markdown = TRUE) {
 #' @param only_sir_columns A [logical] to indicate whether only antimicrobial columns must be included that were transformed to class [sir][as.sir()] on beforehand. Defaults to `FALSE` if no columns of `x` have a class [sir][as.sir()].
 #' @param custom_rules Custom rules to apply, created with [custom_eucast_rules()].
 #' @param overwrite A [logical] indicating whether to overwrite existing SIR values (default: `FALSE`). When `FALSE`, only non-SIR values are modified (i.e., any value that is not already S, I or R). To ensure compliance with EUCAST guidelines, **this should remain** `FALSE`, as EUCAST notes often state that an organism "should be tested for susceptibility to individual agents or be reported resistant".
-#' @param add_if_missing A [logical] indicating whether rules should also be applied to missing (`NA`) values (default: `TRUE`). When `FALSE`, rules are only applied to cells that already contain an SIR value; cells with `NA` are left untouched. This is particularly useful when using `overwrite = TRUE` with custom rules and you want to update reported results without imputing values for untested drugs.
 #' @inheritParams first_isolate
 #' @details
 #' **Note:** This function does not translate MIC values to SIR values. Use [as.sir()] for that. \cr
@@ -176,7 +170,6 @@ interpretive_rules <- function(x,
                                only_sir_columns = any(is.sir(x)),
                                custom_rules = NULL,
                                overwrite = FALSE,
-                               add_if_missing = TRUE,
                                ...) {
   meet_criteria(x, allow_class = "data.frame")
   meet_criteria(col_mo, allow_class = "character", has_length = 1, is_in = colnames(x), allow_NULL = TRUE)
@@ -191,7 +184,6 @@ interpretive_rules <- function(x,
   meet_criteria(only_sir_columns, allow_class = "logical", has_length = 1)
   meet_criteria(custom_rules, allow_class = "custom_eucast_rules", allow_NULL = TRUE)
   meet_criteria(overwrite, allow_class = "logical", has_length = 1)
-  meet_criteria(add_if_missing, allow_class = "logical", has_length = 1)
 
   stop_if(
     guideline == "CLSI",
@@ -541,8 +533,7 @@ interpretive_rules <- function(x,
           warned = warned,
           info = info,
           verbose = verbose,
-          overwrite = overwrite,
-          add_if_missing = add_if_missing
+          overwrite = overwrite
         )
         n_added <- n_added + run_changes$added
         n_changed <- n_changed + run_changes$changed
@@ -584,8 +575,7 @@ interpretive_rules <- function(x,
           warned = warned,
           info = info,
           verbose = verbose,
-          overwrite = overwrite,
-          add_if_missing = add_if_missing
+          overwrite = overwrite
         )
         n_added <- n_added + run_changes$added
         n_changed <- n_changed + run_changes$changed
@@ -882,8 +872,7 @@ interpretive_rules <- function(x,
       warned = warned,
       info = info,
       verbose = verbose,
-      overwrite = overwrite,
-      add_if_missing = add_if_missing
+      overwrite = overwrite
     )
     n_added <- n_added + run_changes$added
     n_changed <- n_changed + run_changes$changed
@@ -953,8 +942,7 @@ interpretive_rules <- function(x,
         warned = warned,
         info = info,
         verbose = verbose,
-        overwrite = overwrite,
-        add_if_missing = add_if_missing
+        overwrite = overwrite
       )
       n_added <- n_added + run_changes$added
       n_changed <- n_changed + run_changes$changed
@@ -1146,8 +1134,7 @@ edit_sir <- function(x,
                      warned,
                      info,
                      verbose,
-                     overwrite,
-                     add_if_missing) {
+                     overwrite) {
   cols <- unique(cols[!is.na(cols) & !is.null(cols)])
 
   # for Verbose Mode, keep track of all changes and return them
@@ -1180,15 +1167,13 @@ edit_sir <- function(x,
     if (isFALSE(overwrite) && any(isSIR) && message_not_thrown_before("edit_sir.warning_overwrite")) {
       warning_("Some values had SIR values and were not overwritten, since `overwrite = FALSE`.")
     }
-    # determine which cells to modify based on overwrite and add_if_missing
-    apply_mask <- if (isTRUE(overwrite)) {
-      if (isFALSE(add_if_missing)) !isNA else rep(TRUE, length(isNA))
-    } else {
-      if (isFALSE(add_if_missing)) isSIR else non_SIR
-    }
     tryCatch(
       # insert into original table
-      new_edits[rows, cols][apply_mask] <- to,
+      if (isTRUE(overwrite)) {
+        new_edits[rows, cols] <- to
+      } else {
+        new_edits[rows, cols][non_SIR] <- to
+      },
       warning = function(w) {
         if (w$message %like% "invalid factor level") {
           xyz <- vapply(FUN.VALUE = logical(1), cols, function(col) {
@@ -1198,7 +1183,11 @@ edit_sir <- function(x,
             )
             TRUE
           })
-          suppressWarnings(new_edits[rows, cols][apply_mask] <<- to)
+          if (isTRUE(overwrite)) {
+            suppressWarnings(new_edits[rows, cols] <<- to)
+          } else {
+            suppressWarnings(new_edits[rows, cols][non_SIR] <<- to)
+          }
           warning_(
             "in `eucast_rules()`: value \"", to, "\" added to the factor levels of column",
             ifelse(length(cols) == 1, "", "s"),

_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`"

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()}}
+}

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}.