Fix guard ordering and over-broad grep in native_anywhere_in_australia() (#288)

Closes #280.

## 1. `is.null(resources)` guard ran too late

The guard sat *below* the call to
`create_species_state_origin_matrix()`. Because that function has its
own guard, an offline call didn't error outright — it did a pointless
call and then printed *"Not finding taxonomic resources; check internet
connection?"* twice, once from each function giving up. Moving the guard
to the top of the function makes it one message and no wasted work.

## 2. `apply(..., grepl("native", x))` scanned every column

`apply(full_lookup, 1, ...)` coerces the whole frame to a character
matrix, so the grep ran over `family`, `species` and `taxon_ID` as well
as the state columns. Any taxon whose name contained the substring
"native" would have been classified native regardless of its actual
distribution.

That is not hypothetical: APC 2024-10-11 has three taxa with a
`nativitatis` epithet — *Flickingeria nativitatis*, *Pittosporum
nativitatis* and *Ischaemum nativitatis*, all Christmas Island endemics.
All three happen to be genuinely native, so **no results change**, but
the check shouldn't depend on that coincidence.

The logic now lives in a small internal `is_native_anywhere()` that
selects the state columns explicitly and tests them column-wise.
Column-wise `grepl` also avoids the frame-to-matrix coercion, which
matters over the 30k+ rows of the infrataxa matrix.

## Verification

- Confirmed old and new native flags are `identical()` over the full
2024-10-11 state-origin matrix, so `benchmarks/native_check.csv` is
untouched.
- New test `is_native_anywhere() reads only the state columns` (in
`test-state_diversity.R`) uses a synthetic lookup with a `nativitatis`
name marked `naturalised`, which the old code got wrong. Needs no
resources.
- New test in `test-connection.R` pins the guard: `resources = NULL`
returns `NULL` with exactly one message.
- `test-state_diversity.R` and `test-connection.R` pass: 36 passing, 0
failures.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: dfalster

NEWS.md

@@ -1,5 +1,6 @@
 # APCalign 2.0.0
 
+- `native_anywhere_in_australia()` now checks for missing taxonomic resources before building the state-origin matrix, so an offline call reports the problem once instead of once per function that gives up. Its native/introduced test also now reads only the state columns, so a taxon whose name contains "native" (e.g. the `nativitatis` epithets) can no longer be misclassified.
 - New function `synonyms_for_accepted_names()` to list synonyms for currently accepted taxon names.
 - `load_taxonomic_resources()` now caches results in memory for the duration of the R session, so repeated calls with the same version return immediately without re-downloading or re-processing data.
 - New function `clear_cached_resources()` to remove the session cache and force a reload.

R/native_anywhere_in_australia.R

@@ -29,25 +29,23 @@
 #' \donttest{native_anywhere_in_australia(c("Eucalyptus globulus","Pinus radiata","Banksis notaspecies"))}
 
 native_anywhere_in_australia <- function(species, resources = load_taxonomic_resources()) {
-  
-  # Create lookup tables  
-  full_lookup <- create_species_state_origin_matrix(resources = resources, include_infrataxa = TRUE)
-  
+
   if(is.null(resources)){
     message("Not finding taxonomic resources; check internet connection?")
     return(NULL)
   }
-  
+
+  # Create lookup tables
+  full_lookup <- create_species_state_origin_matrix(resources = resources, include_infrataxa = TRUE)
+
   if (any(!species %in% full_lookup$species)) {
     warning("At least one input not found in APC; consider using `create_taxonomic_update_lookup` first and ensure you've correctly specified the `include_infrataxa` parameter.")
   }
-  
+
   # Filter for native species
-  full_lookup$native_anywhere <-
-    apply(full_lookup, 1, function(x)
-      any(grepl("native", x)))
-  native_only<-dplyr::filter(full_lookup, native_anywhere)
-  
+  full_lookup$native_anywhere <- is_native_anywhere(full_lookup)
+  native_only <- dplyr::filter(full_lookup, native_anywhere)
+
   # Check membership
   natives <- species %in% native_only$species
   fulllist <- species %in% full_lookup$species
@@ -65,3 +63,18 @@ native_anywhere_in_australia <- function(species, resources = load_taxonomic_res
   return(result)
 }
 
+#' For each row of a species-by-state origin matrix, is the taxon native in at
+#' least one state or territory?
+#'
+#' Only the state/territory columns hold an origin status; the identifying
+#' columns (`family`, `species`, `taxon_ID`) must be excluded, or a taxon whose
+#' name happens to contain "native" would be read as a native record.
+#'
+#' @noRd
+is_native_anywhere <- function(state_origin_matrix) {
+  states <- dplyr::select(state_origin_matrix, -dplyr::any_of(c("family", "species", "taxon_ID")))
+
+  Reduce(`|`, lapply(states, grepl, pattern = "native"),
+         init = rep(FALSE, nrow(state_origin_matrix)))
+}
+

tests/testthat/test-connection.R

@@ -80,6 +80,17 @@ test_that("get_versions() messages and returns NULL when offline", {
   })
 })
 
+test_that("native_anywhere_in_australia() bails out before doing any work", {
+  # The missing-resources guard runs first, so the user gets one message rather
+  # than one per downstream function that also has to give up.
+  msgs <- capture_messages(
+    result <- native_anywhere_in_australia("Eucalyptus globulus", resources = NULL)
+  )
+
+  expect_null(result)
+  expect_length(msgs, 1)
+})
+
 test_that("functions return visibly when online", {
   skip_on_ci()
   skip_on_cran()

tests/testthat/test-state_diversity.R

@@ -65,6 +65,21 @@ test_that("native_anywhere_in_australia() works", {
 })
 
 
+test_that("is_native_anywhere() reads only the state columns", {
+  # `nativitatis` is a real APC epithet (three Christmas Island taxa), so the
+  # taxon name must never be allowed to decide native status on its own.
+  lookup <- dplyr::tibble(
+    family = c("Orchidaceae", "Poaceae", "Pittosporaceae"),
+    species = c("Flickingeria nativitatis", "Ischaemum nativitatis", "Pittosporum undulatum"),
+    taxon_ID = c("id-1", "id-2", "id-3"),
+    ChI = c("native", "naturalised", "not present"),
+    NSW = c("not present", "not present", "native and naturalised")
+  )
+
+  expect_equal(is_native_anywhere(lookup), c(TRUE, FALSE, TRUE))
+})
+
+
 test_that("get_apc_genus_family_lookup() works", {
   expect_warning(family_check <-
                    get_apc_genus_family_lookup(