(v3.0.1.9034) Add amr_course()

2026-03-15 17:27:53 +01:00 · 2026-03-11 16:07:31 +01:00
parent 353eaa3f38
commit 4dc3ec0008
8 changed files with 110 additions and 17 deletions
--- a/4
+++ b/4
@@ -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
--- a/1
+++ b/1
@@ -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)
--- 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
--- a/R/amr_course.R
+++ 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, ...)
+}
--- 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, <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*.
--- 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`"
--- a/man/amr_course.Rd
+++ 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()}}
+}
--- 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}.