--- title: "Matching within a region" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Matching within a region} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- This article shows how to make fuzzy matching prefer the species recorded where the data were collected, by naming a region or giving coordinates. Plant ranges come from the World Checklist of Vascular Plants (WCVP, Govaerts et al. [2021](https://doi.org/10.1038/s41597-021-00997-6)) on the regions of the World Geographical Scheme for Recording Plant Distributions (WGSRPD, Brummitt [2001](https://github.com/tdwg/wgsrpd)). Marine ranges come from the distribution records of the World Register of Marine Species (WoRMS), grouped into the Marine Ecoregions of the World (MEOW, Spalding et al. [2007](https://doi.org/10.1641/B570707)). Installation is covered in [Get started](taxify.html). 1. **Declare** the region by name or code with `region`. 2. **Locate** the records by coordinates with `coords`. 3. **Narrow** to native or introduced records with `range`. 4. **Look up** region names and codes with `taxify_regions()`. ``` r library(taxify) ``` ## A misspelling with two candidates A misspelt name can be close to two species of different continents. *Cirsium acule* is a misspelling of *Cirsium acaule*, the European stemless thistle, which WCVP lists as *Cirsium acaulon*. The misspelling is closer to *Cirsium edule*, a North American thistle: ``` r thistle <- c("Cirsium acule", "Gentiana acaulis", "Primula elatour") res <- taxify(thistle, backbone = "wcvp", verbose = FALSE) res[, c("input_name", "matched_name", "accepted_name", "fuzzy_dist")] #> input_name matched_name accepted_name fuzzy_dist #> 1 Cirsium acule Cirsium edule Cirsium edule 0.1538462 #> 2 Gentiana acaulis Gentiana acaulis Gentiana acaulis NA #> 3 Primula elatour Primula elatior Primula elatior 0.1333333 #> Sources: WCVP 2026.08 | cite() for full citations ``` With `region = "Europe"`, fuzzy matching prefers the candidates WCVP records in Europe: ``` r eu <- taxify(thistle, backbone = "wcvp", region = "Europe", verbose = FALSE) eu[, c("input_name", "matched_name", "accepted_name", "fuzzy_dist")] #> input_name matched_name accepted_name fuzzy_dist #> 1 Cirsium acule Cirsium acaulon Cirsium acaulon 0.2000000 #> 2 Gentiana acaulis Gentiana acaulis Gentiana acaulis NA #> 3 Primula elatour Primula elatior Primula elatior 0.1333333 #> Sources: WCVP 2026.08 | cite() for full citations ``` The thistle now matches *Cirsium acaulon*, at a larger distance that is still within the threshold. The other two rows stay as they were: *Gentiana acaulis* matches exactly, and exact matches are never filtered; *Primula elatour* matches the European *Primula elatior* in both runs. ## How the region filter decides When a region changes a match, as it did for the thistle, one rule decides it. For each name, the fuzzy candidates are looked up in the range data of the region, and a candidate outside the region is dropped when another candidate is inside it. Three rules follow: - Exact matches, including those with capitals ignored, are never filtered. - A candidate with no range data is kept. - When every candidate of a name lies outside the region, all are kept. WCVP covers vascular plants and WoRMS marine species; a name outside both is matched as without a region, so a list of several groups can carry a region. ## Naming the region A region name is matched regardless of capitals and accents at any of the three WGSRPD levels: a continent (`"Europe"`), a region within it (`"Middle Europe"`) or a country or smaller unit (`"Belgium"`). Several regions are combined. `taxify_regions()` lists the names and codes, searching all three levels: ``` r taxify_regions("Belgium", scheme = "wgsrpd") #> code name level2_name level1_name scheme #> 1 BGM Belgium Middle Europe EUROPE wgsrpd ``` A code is read directly, so `region = "BGM"` and `region = "Belgium"` are the same region. A name or code that matches no region is dropped with a warning, and the call runs without it: ``` r x <- taxify("Cirsium acule", backbone = "wcvp", region = "GRE", verbose = FALSE) #> Warning: Unrecognized region(s) dropped: GRE. See taxify_regions() for valid #> codes and names. ``` Greece is `GRC`, not `GRE`. With no search term, `taxify_regions()` returns every region `region` accepts; the table counts the country-level regions in each continent: ``` r wgsrpd <- taxify_regions(scheme = "wgsrpd") table(wgsrpd$level1_name) #> #> AFRICA ANTARCTIC ASIA-TEMPERATE ASIA-TROPICAL #> 71 12 52 31 #> AUSTRALASIA EUROPE NORTHERN AMERICA PACIFIC #> 13 41 73 28 #> SOUTHERN AMERICA #> 48 ``` The same codes appear in the native range that `add_wcvp()` attaches. ## Coordinates `coords` gives the place as longitude and latitude, in that order. Each point is placed in its WGSRPD region: ``` r brussels <- taxify(thistle, backbone = "wcvp", coords = c(4.35, 50.85), verbose = FALSE) brussels[, c("input_name", "matched_name")] #> input_name matched_name #> 1 Cirsium acule Cirsium acaulon #> 2 Gentiana acaulis Gentiana acaulis #> 3 Primula elatour Primula elatior #> Sources: WCVP 2026.08 | cite() for full citations ``` The Brussels point lies in Belgium, so the thistle resolves to *Cirsium acaulon*, as it did with `region = "Europe"`. A two-column matrix or data frame of points works too, as do an sf object and a terra `SpatVector`, which are reprojected to longitude and latitude. Points and a region name can be combined. The WGSRPD boundary polygons that place a point are downloaded once. The point-in-polygon test uses terra or sf when one is installed and its own code otherwise; `options(taxify.pip_engine = "terra")`, `"sf"` or `"native"` chooses. ## Native or introduced records By default a species counts as present in a region with any WCVP record there, native or introduced. `range = "native"` counts only native records, so a species introduced to the region does not take precedence over a native candidate elsewhere. `range = "introduced"` counts only introduced records, for work on invasions. `range` has no effect without a region. ``` r taxify(thistle, backbone = "wcvp", region = "Europe", range = "native") ``` ## Marine regions Marine names use the `marine_distribution` dataset, downloaded on first use. From then on `region` also takes MEOW ecoregion, province and realm names and codes, and a province or realm stands for its ecoregions: ``` r head(taxify_regions("Temperate Northern Atlantic", scheme = "meow")) #> code name level2_name #> 1 20030 Adriatic Sea Mediterranean Sea #> 2 25033 Tunisian Plateau/Gulf of Sidra Mediterranean Sea #> 3 20021 Faroe Plateau Northern European Seas #> 4 25036 Alboran Sea Mediterranean Sea #> 5 20025 North Sea Northern European Seas #> 6 20044 Black Sea Black Sea #> level1_name scheme #> 1 Temperate Northern Atlantic meow #> 2 Temperate Northern Atlantic meow #> 3 Temperate Northern Atlantic meow #> 4 Temperate Northern Atlantic meow #> 5 Temperate Northern Atlantic meow #> 6 Temperate Northern Atlantic meow ``` Searching the realm name returns its ecoregions, with the province in `level2_name`, so `region = "Temperate Northern Atlantic"` covers all of them. A point at sea is placed in the MEOW ecoregion that contains it, as well as in a WGSRPD region on land, so one `coords` argument serves a list of plants and marine animals. MEOW covers coastal and shelf waters; a point over the deep ocean lies in no ecoregion and leaves marine names unconstrained. A WoRMS distribution record is as precise as the locality it was recorded against, which ranges from a bay to an ocean basin. ## Where next - [Checking a name list](inspecting-names.html): the check that reports matched species with no record in the declared region. - [How names are matched](fuzzy-matching.html): the fuzzy matching the region filter acts on. ## References Brummitt RK (2001). *World Geographical Scheme for Recording Plant Distributions*, Edition 2. Govaerts R, Nic Lughadha E, Black N, Turner R, Paton A (2021). The World Checklist of Vascular Plants, a continuously updated resource for exploring global plant diversity. *Scientific Data* 8: 215. Spalding MD, Fox HE, Allen GR, Davidson N, Ferdana ZA, Finlayson M, Halpern BS, Jorge MA, Lombana A, Lourie SA, Martin KD, McManus E, Molnar J, Recchia CA, Robertson J (2007). Marine Ecoregions of the World: a bioregionalization of coastal and shelf areas. *BioScience* 57: 573-583.