Add parallel computing support to antibiogram() and wisca() (#281) (#282)

* Add parallel computing support to antibiogram() and wisca() (#281)

For WISCA: simulations are distributed across (group, chunk) job pairs
via future.apply::future_lapply(), keeping all workers active even when
the regimen count is smaller than nbrOfWorkers(). Sequential fallback
with progress ticker is preserved when parallel = FALSE or workers = 1.

For grouped antibiograms: each group is processed by a separate worker,
mirroring the row-batch approach in as.sir().

Same gate pattern as as.sir() (PR #280): requires a non-sequential
future::plan() to be active; auto-upgrades to parallel = TRUE when a
parallel plan is detected; throws an informative error otherwise.

https://claude.ai/code/session_01FC43syPbzhGmKgrrVNHjnF

* Fix version to 3.0.1.9055 and update CLAUDE.md version formula

Uses origin/${defaultbranch} (with a fetch) instead of the local
branch ref so the commit count is never stale after a merge.

https://claude.ai/code/session_01FC43syPbzhGmKgrrVNHjnF

* Fix non-ASCII characters in antibiogram.R

Replace en/em dashes and non-breaking spaces with ASCII equivalents
to satisfy R CMD check portability requirement.

https://claude.ai/code/session_01FC43syPbzhGmKgrrVNHjnF

* Update auto-generated Rd files after documentation rebuild

https://claude.ai/code/session_01FC43syPbzhGmKgrrVNHjnF

* Move parallel gate to top of antibiogram.default() like sir.R

The gate was inside the wisca==TRUE block, so parallel=TRUE with a
sequential plan was silently ignored for non-WISCA antibiograms.
Now the gate runs unconditionally at the top of the function,
identical to the as.sir() pattern: error on explicit parallel=TRUE
with sequential plan, auto-upgrade when a non-sequential plan is
already active.

https://claude.ai/code/session_01FC43syPbzhGmKgrrVNHjnF

* Fix parallel WISCA returning all NA; strengthen tests; add sequential hint

Bug: lapply() over a factor yields length-1 factor elements (integer
codes), while for() over a factor yields character strings.  The job
list stored j\$group as a factor integer, but the reassembly loop
compared it with identical(j\$group, g) where g was character -- always
FALSE, so no simulation chunks were ever assembled and coverage stayed
NA throughout.

Fix: convert unique_groups to character before building jobs so both
the job list and the reassembly loop use the same type.

Tests: replaced na.rm = TRUE guards with explicit anyNA() checks so the
test suite would have caught the all-NA result immediately.

Also adds a sequential-mode performance hint (analogous to sir.R
lines 1116-1127) when simulations >= 500 and >= 3 regimens.

https://claude.ai/code/session_01FC43syPbzhGmKgrrVNHjnF

---------

Co-authored-by: Claude <noreply@anthropic.com>

tests/testthat/test-antibiogram.R

@@ -130,6 +130,77 @@ test_that("test-antibiogram.R", {
     expect_equal(colnames(ab9), c("ward", "gender", "Piperacillin/tazobactam", "Piperacillin/tazobactam + Gentamicin", "Piperacillin/tazobactam + Tobramycin"))
   }
 
+  # Parallel computing ----------------------------------------------------
+  # Tests must pass even when only 1 core is available; parallel = TRUE then
+  # silently falls back to sequential, but results must still be correct.
+
+  if (AMR:::pkg_is_available("future.apply")) {
+    set.seed(42)
+
+    # sequential reference for WISCA
+    wisca_seq <- suppressWarnings(suppressMessages(
+      wisca(example_isolates, antimicrobials = c("TZP", "TZP+TOB", "TZP+GEN"), simulations = 100, info = FALSE)
+    ))
+
+    future::plan(future::multicore)
+
+    # 1. parallel = TRUE produces the same antibiogram structure as sequential
+    wisca_par <- suppressWarnings(suppressMessages(
+      wisca(example_isolates, antimicrobials = c("TZP", "TZP+TOB", "TZP+GEN"), simulations = 100, parallel = TRUE, info = FALSE)
+    ))
+    expect_inherits(wisca_par, "antibiogram")
+    expect_equal(colnames(wisca_par), colnames(wisca_seq))
+    expect_true(isTRUE(attributes(wisca_par)$wisca))
+
+    # 2. coverage values are non-NA and fall within [0, 1]
+    ln <- attributes(wisca_par)$long_numeric
+    expect_false(anyNA(ln$coverage))
+    expect_false(anyNA(ln$lower_ci))
+    expect_false(anyNA(ln$upper_ci))
+    expect_true(all(ln$coverage >= 0 & ln$coverage <= 1))
+    expect_true(all(ln$lower_ci <= ln$coverage))
+    expect_true(all(ln$upper_ci >= ln$coverage))
+
+    # 3. a second parallel run gives the same column names
+    wisca_par2 <- suppressWarnings(suppressMessages(
+      wisca(example_isolates, antimicrobials = c("TZP", "TZP+TOB", "TZP+GEN"), simulations = 100, parallel = TRUE, info = FALSE)
+    ))
+    expect_equal(colnames(wisca_par), colnames(wisca_par2))
+
+    # 4. parallel with workers = 1 gives same structure as sequential
+    future::plan(future::multicore, workers = 1)
+    wisca_par1 <- suppressWarnings(suppressMessages(
+      wisca(example_isolates, antimicrobials = c("TZP", "TZP+TOB", "TZP+GEN"), simulations = 100, parallel = TRUE, info = FALSE)
+    ))
+    expect_equal(colnames(wisca_seq), colnames(wisca_par1))
+
+    # 5. grouped antibiogram in parallel yields identical structure to sequential
+    if (AMR:::pkg_is_available("dplyr", min_version = "1.0.0", also_load = TRUE)) {
+      future::plan(future::sequential)
+      ab_grp_seq <- suppressWarnings(suppressMessages(
+        example_isolates %>%
+          group_by(ward) %>%
+          wisca(antimicrobials = c("TZP", "TZP+TOB"), simulations = 50, info = FALSE)
+      ))
+      future::plan(future::multicore)
+      ab_grp_par <- suppressWarnings(suppressMessages(
+        example_isolates %>%
+          group_by(ward) %>%
+          wisca(antimicrobials = c("TZP", "TZP+TOB"), simulations = 50, parallel = TRUE, info = FALSE)
+      ))
+      expect_equal(colnames(ab_grp_seq), colnames(ab_grp_par))
+      expect_equal(nrow(ab_grp_seq), nrow(ab_grp_par))
+    }
+
+    # 6. parallel = TRUE without a plan raises an informative error
+    future::plan(future::sequential)
+    expect_error(
+      suppressWarnings(wisca(example_isolates, antimicrobials = "TZP", parallel = TRUE, info = FALSE)),
+      "non-sequential"
+    )
+
+    future::plan(future::sequential)
+  }
 
   # Generate plots with ggplot2 or base R --------------------------------