(v3.1.0.9022) Document grouped first isolates (#345)

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AMR
-Version: 3.1.0.9021
-Date: 2026-11-09
+Version: 3.1.0.9022
+Date: 2026-11-14
 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
@@ -73,4 +73,4 @@ License: GPL-2 | file LICENSE
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-Config/roxygen2/version: 8.1.0
+Config/roxygen2/version: 8.1.1

NEWS.md

@@ -1,4 +1,4 @@
-# AMR 3.1.0.9021
+# AMR 3.1.0.9022
 
 This version fixes a critical bug in WISCA that biased all coverage estimates of `wisca()` and `antibiogram(..., wisca = TRUE)` downwards since AMR 3.0.0. Users are strongly advised to re-run their WISCA analyses.
 
@@ -35,6 +35,7 @@ This version fixes a critical bug in WISCA that biased all coverage estimates of
   * Species groups and complexes are now listed for every antimicrobial to which all their species are intrinsically resistant. This adds 62 bug-drug combinations for the *Burkholderia cepacia* complex, coryneform bacteria, the *Enterobacter cloacae* complex (e.g., amoxicillin and amoxicillin/clavulanic acid), the *Klebsiella pneumoniae* complex, and coagulase-negative staphylococci, which affects `mo_is_intrinsic_resistant()`, `not_intrinsic_resistant()`, and the priors of `wisca()` (#338)
 
 ### Other
+* The documentation of `first_isolate()` now explains how to determine first isolates per any additional variable using `dplyr::group_by()`, and the bias this introduces when that variable is related to resistance (#345)
 * The manual index on the website was rewritten to improve findability, with sections ordered by task and a filter field
 * Fixed the link to the copyright section and added MycoBank as a taxonomy source in the *Welcome to AMR* vignette (#325)
 

R/first_isolate.R

@@ -130,6 +130,18 @@
 #'
 #'
 #' The default method is phenotype-based (using `type = "points"`) and episode-based (using `episode_days = 365`). This makes sure that every genus-species combination is selected per patient once per year, while taking into account all antimicrobial test results. If no antimicrobial test results are available in the data set, only the episode-based method is applied at default.
+#'
+#' ## First isolates per additional variable
+#'
+#' To determine first isolates separately for the values of any additional variable, such as a ward, a specimen group, a molecular marker or a locally defined classification, group the data with [dplyr::group_by()] before calling [first_isolate()]. Every group is then handled as a separate data set, so the selection, including the start of every episode, is determined per patient, genus-species combination and group value. This works with all methods described above:
+#'
+#' ```r
+#' your_data %>%
+#'   group_by(ward) %>%
+#'   mutate(first = first_isolate())
+#' ```
+#'
+#' Be aware that grouping on a variable that is related to antimicrobial resistance, such as a resistance mechanism or the output of [mdro()], retains more isolates of patients whose isolates change category. This deviates from CLSI M39 and generally leads to an overestimation of resistance, as the selection then depends on the outcome that is being estimated.
 #' @rdname first_isolate
 #' @seealso [key_antimicrobials()]
 #' @export

man/first_isolate.Rd

@@ -162,6 +162,18 @@ Key antimicrobials are internally selected using the \code{\link[=key_antimicrob
 
 The default method is phenotype-based (using \code{type = "points"}) and episode-based (using \code{episode_days = 365}). This makes sure that every genus-species combination is selected per patient once per year, while taking into account all antimicrobial test results. If no antimicrobial test results are available in the data set, only the episode-based method is applied at default.
 }
+
+\subsection{First isolates per additional variable}{
+
+To determine first isolates separately for the values of any additional variable, such as a ward, a specimen group, a molecular marker or a locally defined classification, group the data with \code{\link[dplyr:group_by]{dplyr::group_by()}} before calling \code{\link[=first_isolate]{first_isolate()}}. Every group is then handled as a separate data set, so the selection, including the start of every episode, is determined per patient, genus-species combination and group value. This works with all methods described above:
+
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{your_data \%>\%
+  group_by(ward) \%>\%
+  mutate(first = first_isolate())
+}\if{html}{\out{</div>}}
+
+Be aware that grouping on a variable that is related to antimicrobial resistance, such as a resistance mechanism or the output of \code{\link[=mdro]{mdro()}}, retains more isolates of patients whose isolates change category. This deviates from CLSI M39 and generally leads to an overestimation of resistance, as the selection then depends on the outcome that is being estimated.
+}
 }
 \examples{
 # `example_isolates` is a data set available in the AMR package.