Generalise interpretive rules for multi-guideline support (#268) (#283)

* Generalise interpretive rules for multi-guideline support (#268) - Rename data-raw/eucast_rules.tsv → interpretive_rules.tsv; add rule.provider column (value: "EUCAST") to distinguish future CLSI rows - Rename EUCAST_RULES_DF → INTERPRETIVE_RULES_DF in _pre_commit_checks.R; filter by rule.provider == guideline when applying rules in interpretive_rules() - Rename custom_eucast_rules() → custom_interpretive_rules() with new S3 class "custom_interpretive_rules"; old function becomes a deprecated wrapper in zz_deprecated.R; backward-compat S3 dispatch shims added for old class - Remove stop_if(guideline == "CLSI", ...) so clsi_rules() no longer errors - Add .onLoad shim in zzz.R to create INTERPRETIVE_RULES_DF from EUCAST_RULES_DF for transitional compatibility until sysdata.rda is regenerated https://claude.ai/code/session_01D46BTsfJSPo3HnLWp3PRkP * Fix namespace load failure: remove assignInNamespace from .onLoad (#268) assignInNamespace cannot add NEW bindings to a locked package namespace (R locks namespace bindings before .onLoad runs). Replace the .onLoad shim with a runtime fallback inside interpretive_rules(): if INTERPRETIVE_RULES_DF is absent (pre-regeneration sysdata.rda), derive it from EUCAST_RULES_DF by adding the rule.provider column. This also fixes the screening_abx line to reuse the already-resolved interpretive_rules_df_total instead of a bare INTERPRETIVE_RULES_DF reference. https://claude.ai/code/session_01D46BTsfJSPo3HnLWp3PRkP * fixes * fixes --------- Co-authored-by: Claude <noreply@anthropic.com>
2026-05-14 03:50:49 +02:00 · 2026-05-01 18:38:51 +01:00
parent f7e9294bea
commit 24f24ecaf8
26 changed files with 1770 additions and 183 deletions
--- a/man/AMR-deprecated.Rd
+++ b/man/AMR-deprecated.Rd
@@ -2,10 +2,13 @@
 % Please edit documentation in R/zz_deprecated.R
 \name{AMR-deprecated}
 \alias{AMR-deprecated}
+\alias{custom_eucast_rules}
 \alias{ab_class}
 \alias{ab_selector}
 \title{Deprecated Functions, Arguments, or Datasets}
 \usage{
+custom_eucast_rules(...)
+
 ab_class(...)

 ab_selector(...)
--- a/man/custom_interpretive_rules.Rd
+++ b/man/custom_interpretive_rules.Rd
@@ -1,10 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/custom_eucast_rules.R
-\name{custom_eucast_rules}
-\alias{custom_eucast_rules}
-\title{Define Custom EUCAST Rules}
+% Please edit documentation in R/custom_interpretive_rules.R
+\name{custom_interpretive_rules}
+\alias{custom_interpretive_rules}
+\title{Define Custom Interpretive Rules}
 \usage{
-custom_eucast_rules(...)
+custom_interpretive_rules(...)
 }
 \arguments{
 \item{...}{Rules in \link[base:tilde]{formula} notation, see below for instructions, and in \emph{Examples}.}
@@ -13,22 +13,22 @@ custom_eucast_rules(...)
 A \link{list} containing the custom rules
 }
 \description{
-Define custom EUCAST rules for your organisation or specific analysis and use the output of this function in \code{\link[=eucast_rules]{eucast_rules()}}.
+Define custom interpretive rules for your organisation or specific analysis and use the output of this function in \code{\link[=interpretive_rules]{interpretive_rules()}}.
 }
 \details{
-Some organisations have their own adoption of EUCAST rules. This function can be used to define custom EUCAST rules to be used in the \code{\link[=eucast_rules]{eucast_rules()}} function.
+Some organisations have their own adoption of interpretive rules. This function can be used to define custom rules to be used in the \code{\link[=interpretive_rules]{interpretive_rules()}} function.
 \subsection{Basics}{

 If you are familiar with the \code{\link[dplyr:case-and-replace-when]{case_when()}} function of the \code{dplyr} package, you will recognise the input method to set your own rules. Rules must be set using what \R considers to be the 'formula notation'. The rule itself is written \emph{before} the tilde (\code{~}) and the consequence of the rule is written \emph{after} the tilde:

-\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(TZP == "S" ~ aminopenicillins == "S",
-                         TZP == "R" ~ aminopenicillins == "R")
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_interpretive_rules(TZP == "S" ~ aminopenicillins == "S",
+                               TZP == "R" ~ aminopenicillins == "R")
 }\if{html}{\out{</div>}}

-These are two custom EUCAST rules: if TZP (piperacillin/tazobactam) is "S", all aminopenicillins (ampicillin and amoxicillin) must be made "S", and if TZP is "R", aminopenicillins must be made "R". These rules can also be printed to the console, so it is immediately clear how they work:
+These are two custom interpretive rules: if TZP (piperacillin/tazobactam) is "S", all aminopenicillins (ampicillin and amoxicillin) must be made "S", and if TZP is "R", aminopenicillins must be made "R". These rules can also be printed to the console, so it is immediately clear how they work:

 \if{html}{\out{<div class="sourceCode r">}}\preformatted{x
-#> A set of custom EUCAST rules:
+#> A set of custom interpretive rules:
 #>
 #>   1. If TZP is "S" then set to  S :
 #>      amoxicillin (AMX), ampicillin (AMP)
@@ -48,11 +48,11 @@ df
 #> 1      Escherichia coli   R    S     S
 #> 2 Klebsiella pneumoniae   R    S     S

-eucast_rules(df,
-             rules = "custom",
-             custom_rules = x,
-             info = FALSE,
-             overwrite = TRUE)
+interpretive_rules(df,
+                   rules = "custom",
+                   custom_rules = x,
+                   info = FALSE,
+                   overwrite = TRUE)
 #>                      mo TZP ampi cipro
 #> 1      Escherichia coli   R    R     S
 #> 2 Klebsiella pneumoniae   R    R     S
@@ -63,16 +63,16 @@ eucast_rules(df,

 There is one exception in columns used for the rules: all column names of the \link{microorganisms} data set can also be used, but do not have to exist in the data set. These column names are: \code{"mo"}, \code{"fullname"}, \code{"status"}, \code{"kingdom"}, \code{"phylum"}, \code{"class"}, \code{"order"}, \code{"family"}, \code{"genus"}, \code{"species"}, \code{"subspecies"}, \code{"rank"}, \code{"ref"}, \code{"oxygen_tolerance"}, \code{"source"}, \code{"lpsn"}, \code{"lpsn_parent"}, \code{"lpsn_renamed_to"}, \code{"mycobank"}, \code{"mycobank_parent"}, \code{"mycobank_renamed_to"}, \code{"gbif"}, \code{"gbif_parent"}, \code{"gbif_renamed_to"}, \code{"prevalence"}, and \code{"snomed"}. Thus, this next example will work as well, despite the fact that the \code{df} data set does not contain a column \code{genus}:

-\if{html}{\out{<div class="sourceCode r">}}\preformatted{y <- custom_eucast_rules(
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{y <- custom_interpretive_rules(
  TZP == "S" & genus == "Klebsiella" ~ aminopenicillins == "S",
  TZP == "R" & genus == "Klebsiella" ~ aminopenicillins == "R"
 )

-eucast_rules(df,
-             rules = "custom",
-             custom_rules = y,
-             info = FALSE,
-             overwrite = TRUE)
+interpretive_rules(df,
+                   rules = "custom",
+                   custom_rules = y,
+                   info = FALSE,
+                   overwrite = TRUE)
 #>                      mo TZP ampi cipro
 #> 1      Escherichia coli   R    S     S
 #> 2 Klebsiella pneumoniae   R    R     S
@@ -90,9 +90,9 @@ You can define antimicrobial groups instead of single antimicrobials for the rul

 Rules can also be applied to multiple antimicrobials and antimicrobial groups simultaneously. Use the \code{c()} function to combine multiple antimicrobials. For instance, the following example sets all aminopenicillins and ureidopenicillins to "R" if column TZP (piperacillin/tazobactam) is "R":

-\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(TZP == "R" ~ c(aminopenicillins, ureidopenicillins) == "R")
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_interpretive_rules(TZP == "R" ~ c(aminopenicillins, ureidopenicillins) == "R")
 x
-#> A set of custom EUCAST rules:
+#> A set of custom interpretive rules:
 #>
 #>   1. If TZP is "R" then set to "R":
 #>      amoxicillin (AMX), ampicillin (AMP), azlocillin (AZL), mezlocillin (MEZ), piperacillin (PIP), piperacillin/tazobactam (TZP)
@@ -147,7 +147,7 @@ These 43 antimicrobial groups are allowed in the rules (case-insensitive) and ca
 }
 }
 \examples{
-x <- custom_eucast_rules(
+x <- custom_interpretive_rules(
  AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
  AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I"
 )
@@ -165,7 +165,7 @@ eucast_rules(example_isolates,
 # combine rule sets
 x2 <- c(
  x,
-  custom_eucast_rules(TZP == "R" ~ carbapenems == "R")
+  custom_interpretive_rules(TZP == "R" ~ carbapenems == "R")
 )
 x2
 }
--- a/man/g.test.Rd
+++ b/man/g.test.Rd
@@ -45,8 +45,9 @@ A list with class \code{"htest"} containing the following
  \item{residuals}{the Pearson residuals,
    \code{(observed - expected) / sqrt(expected)}.}
  \item{stdres}{standardized residuals,
-    \code{(observed - expected) / sqrt(V)}, where \code{V} is the residual cell variance (Agresti, 2007,
-    section 2.4.5 for the case where \code{x} is a matrix, \code{n * p * (1 - p)} otherwise).}
+    \code{(observed - expected) / sqrt(V)}, where \code{V} is the
+    residual cell variance (Agresti, 2007, section 2.4.5
+    for the case where \code{x} is a matrix, \code{n * p * (1 - p)} otherwise).}
 }
 \description{
 \code{\link[=g.test]{g.test()}} performs chi-squared contingency table tests and goodness-of-fit tests, just like \code{\link[=chisq.test]{chisq.test()}} but is more reliable (1). A \emph{G}-test can be used to see whether the number of observations in each category fits a theoretical expectation (called a \strong{\emph{G}-test of goodness-of-fit}), or to see whether the proportions of one variable are different for different values of the other variable (called a \strong{\emph{G}-test of independence}).
--- a/man/interpretive_rules.Rd
+++ b/man/interpretive_rules.Rd
@@ -46,7 +46,7 @@ eucast_dosage(ab, administration = "iv", version_breakpoints = 15)

 \item{info}{A \link{logical} to indicate whether progress should be printed to the console - the default is only print while in interactive sessions.}

-\item{rules}{A \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_interpretive_rules}}: \code{options(AMR_interpretive_rules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.}
+\item{rules}{A \link{character} vector that specifies which rules should be applied. Must be one or more of \code{"breakpoints"}, \code{"expected_phenotypes"}, \code{"expert"}, \code{"other"}, \code{"custom"}, \code{"all"}, and defaults to \code{c("breakpoints", "expected_phenotypes")}. The default value can be set to another value using the package option \code{\link[=AMR-options]{AMR_interpretive_rules}}: \code{options(AMR_interpretive_rules = "all")}. If using \code{"custom"}, be sure to fill in argument \code{custom_rules} too. Custom rules can be created with \code{\link[=custom_interpretive_rules]{custom_interpretive_rules()}}.}

 \item{guideline}{A guideline name, either "EUCAST" (default) or "CLSI". This can be set with the package option \code{\link[=AMR-options]{AMR_guideline}}.}

@@ -62,7 +62,7 @@ eucast_dosage(ab, administration = "iv", version_breakpoints = 15)

 \item{only_sir_columns}{A \link{logical} to indicate whether only antimicrobial columns must be included that were transformed to class \link[=as.sir]{sir} on beforehand. Defaults to \code{FALSE} if no columns of \code{x} have a class \link[=as.sir]{sir}.}

-\item{custom_rules}{Custom rules to apply, created with \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}.}
+\item{custom_rules}{Custom rules to apply, created with \code{\link[=custom_interpretive_rules]{custom_interpretive_rules()}}.}

 \item{overwrite}{A \link{logical} indicating whether to overwrite existing SIR values (default: \code{FALSE}). When \code{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, \strong{this should remain} \code{FALSE}, as EUCAST notes often state that an organism "should be tested for susceptibility to individual agents or be reported resistant".}

@@ -86,15 +86,15 @@ To improve the interpretation of the antibiogram before CLSI/EUCAST interpretive
 \strong{Note:} This function does not translate MIC or disk values to SIR values. Use \code{\link[=as.sir]{as.sir()}} for that. \cr
 \strong{Note:} When ampicillin (AMP, J01CA01) is not available but amoxicillin (AMX, J01CA04) is, the latter will be used for all rules where there is a dependency on ampicillin. These drugs are interchangeable when it comes to expression of antimicrobial resistance. \cr

-The file containing all EUCAST rules is located here: \url{https://github.com/msberends/AMR/blob/main/data-raw/eucast_rules.tsv}.  \strong{Note:} Old taxonomic names are replaced with the current taxonomy where applicable. For example, \emph{Ochrobactrum anthropi} was renamed to \emph{Brucella anthropi} in 2020; the original EUCAST rules v3.1 and v3.2 did not yet contain this new taxonomic name. The \code{AMR} package contains the full microbial taxonomy updated until June 24th, 2024, see \link{microorganisms}.
+The file containing all interpretive rules is located here: \url{https://github.com/msberends/AMR/blob/main/data-raw/interpretive_rules.tsv}.  \strong{Note:} Old taxonomic names are replaced with the current taxonomy where applicable. For example, \emph{Ochrobactrum anthropi} was renamed to \emph{Brucella anthropi} in 2020; the original EUCAST rules v3.1 and v3.2 did not yet contain this new taxonomic name. The \code{AMR} package contains the full microbial taxonomy updated until June 24th, 2024, see \link{microorganisms}.
 \subsection{Custom Rules}{

-Custom rules can be created using \code{\link[=custom_eucast_rules]{custom_eucast_rules()}}, e.g.:
+Custom rules can be created using \code{\link[=custom_interpretive_rules]{custom_interpretive_rules()}}, e.g.:

-\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_eucast_rules(AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
-                         AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I")
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{x <- custom_interpretive_rules(AMC == "R" & genus == "Klebsiella" ~ aminopenicillins == "R",
+                               AMC == "I" & genus == "Klebsiella" ~ aminopenicillins == "I")

-eucast_rules(example_isolates, rules = "custom", custom_rules = x)
+interpretive_rules(example_isolates, rules = "custom", custom_rules = x)
 }\if{html}{\out{</div>}}
 }

@@ -108,7 +108,7 @@ Before further processing, two non-EUCAST rules about drug combinations can be a

 Important examples include amoxicillin and amoxicillin/clavulanic acid, and trimethoprim and trimethoprim/sulfamethoxazole. Needless to say, for these rules to work, both drugs must be available in the data set.

-Since these rules are not officially approved by EUCAST, they are not applied at default. To use these rules, include \code{"other"} to the \code{rules} argument, or use \code{eucast_rules(..., rules = "all")}. You can also set the package option \code{\link[=AMR-options]{AMR_interpretive_rules}}, i.e. run \code{options(AMR_interpretive_rules = "all")}.
+Since these rules are not officially approved by EUCAST, they are not applied at default. To use these rules, include \code{"other"} to the \code{rules} argument, or use \code{interpretive_rules(..., rules = "all")}. You can also set the package option \code{\link[=AMR-options]{AMR_interpretive_rules}}, i.e. run \code{options(AMR_interpretive_rules = "all")}.
 }
 }
 \section{Download Our Reference Data}{
--- a/man/pca.Rd
+++ b/man/pca.Rd
@@ -32,7 +32,7 @@ pca(x, ..., retx = TRUE, center = TRUE, scale. = TRUE, tol = NULL,
    standard deviations are less than or equal to \code{tol} times the
    standard deviation of the first component.)  With the default null
    setting, no components are omitted (unless \code{rank.} is specified
-    less than \code{min(dim(x))}.).  Other settings for tol could be
+    less than \code{min(dim(x))}.).  Other settings for \code{tol} could be
    \code{tol = 0} or \code{tol = sqrt(.Machine$double.eps)}, which
    would omit essentially constant components.}