From a species name to Criterion B metrics

What this vignette covers

A common task in a Red List assessment is to take a species, gather its occurrence records, clean them, and compute the Criterion B range metrics (extent of occurrence and area of occupancy). The main difficulty is that the IUCN Red List and GBIF often use different accepted names for the same species, so a name that is correct on one side may return nothing on the other.

The workflow below goes from a name to the two metrics in five steps. The code chunks are not run here because they call the IUCN and GBIF web services, but each one shows the kind of output you can expect.

Before you start, the IUCN steps need an API key. See rl_set_api() for how to store it. The GBIF steps need no account or password, since they use the public search service.

1. Get the IUCN taxonomy

We begin with rl_scientific_name(), which returns the IUCN assessment for a species given its genus and species.

sp <- rl_scientific_name(
  genus_name = "Corvinella",
  species_name = "corvina",
  resolve = TRUE
)

The resolve argument is the useful part here. GBIF lists this bird as Corvinella corvina, but the IUCN Red List files it under Lanius corvinus. A plain request with the GBIF name would return a 404. With resolve = TRUE, rl_scientific_name() notices the 404 and calls rl_name_resolve() behind the scenes to find the name the IUCN actually uses, then retries. You can also run that resolution yourself:

rl_name_resolve("Corvinella", "corvina")
#> currentCanonicalSimple: "Lanius corvinus"   isSynonym: TRUE   matchType: "Exact"

So sp now holds the IUCN assessment for Lanius corvinus.

2. A note on the name bridge

Step 2 in the plan is to move from the IUCN name back to the GBIF backbone. In practice you do not need a separate call for this: rl_occurrences() handles it for you. When you pass it the IUCN result, it reads the name, looks it up in the GBIF backbone, and follows the synonym to the accepted taxon. GBIF indexes all records under the accepted taxon, so this is also how records filed under other synonyms come along.

For Lanius corvinus this means the query resolves to GBIF’s accepted Corvinella corvina, and the records come back under that name.

3. Fetch the occurrence records

occ <- rl_occurrences(
  sp,
  year = ">2025",
  basis_of_record = c("HUMAN_OBSERVATION", "MACHINE_OBSERVATION"),
  limit = 500
)
nrow(occ)
#> [1] 500

The arguments worth knowing:

x (here sp) is what you want records for. It can be the IUCN result from step 1, a plain name such as "Corvinella corvina", or a GBIF taxon key.
year filters by date. A single year (2000), a range as one comma string ("2000,2020", open ended as "2000,*"), or a comparator (">2025", ">=2025", "<2000"). Note that ">2025" means strictly after 2025, so 2026 onward.
basis_of_record limits the kinds of records. Pass several as a vector and they are matched as OR, so the line above keeps human and machine observations.
limit caps how many records are returned. Use Inf to fetch every record, up to the service ceiling of 100000.
country restricts by ISO2 country code, and also takes a vector for several countries.
correct runs the quality checks from step 4 straight after the download. It is NULL here so we can look at the raw records first.
Any other GBIF search filter can be passed by name through ..., for example continent or institutionCode.

The result is an sf points object with the GBIF fields kept as columns, so it is ready to map or to feed to the metric functions. Records with missing or plainly invalid coordinates are dropped for you; everything else is left alone until you ask for a check.

4. Check data quality and clean

Raw occurrence data usually carries a few problems that would distort the metrics, such as points in the sea, country centroids, or clear outliers. rl_check_occurrences() reports these, and can also remove them.

occ_check <- rl_check_occurrences(
  x = occ,
  correct = c("duplicates", "outliers", "country", "ocean_points", "centroids"),
  terrestrial = FALSE
)
nrow(occ_check)

What the arguments do:

correct chooses what to act on. With FALSE the function only reports and returns the report table. With a character vector, it removes the records flagged by those checks and returns the cleaned sf, with the report kept in its "report" attribute. TRUE corrects every clear error check.
The checks you can name are duplicates, coordinate_precision, outliers, country, ocean_points, and centroids, plus the report only checks unique_localities, institution_diversity, and recency.
terrestrial controls the ocean check. Corvinella corvina is a bird that can legitimately be recorded near or over water, so we set it to FALSE to avoid dropping coastal records. For a strictly land species, leave it TRUE.

Two checks deserve a note. coordinate_precision flags records too coarse for the 2 km grid, but it is deliberately left out of the automatic corrections, because removing imprecise yet real records can quietly shrink the sample and bias the result. If you do want to apply it, name it explicitly:

occ_precise <- rl_check_occurrences(occ, correct = "coordinate_precision")

The other checks that rely on geographic references (outliers, country, ocean_points, centroids) need the CoordinateCleaner package. If it is not installed, those checks are skipped with a note rather than failing.

You can run the same cleaning as part of the download by passing correct straight to rl_occurrences():

occ <- rl_occurrences(
  sp,
  year = ">2025",
  correct = c("duplicates", "outliers")
)

5. Compute the metrics

With clean records in hand, compute the metrics on the cleaned object.

aoo <- rl_aoo(occ_check)
aoo
#> metric area_km2 n_records n_occupied_cells cell_size_km category_b2
#>    AOO      ...       ...              ...            2         ...

eoo <- rl_eoo(occ_check)

rl_aoo() counts the occupied cells of a 2 by 2 km grid and multiplies by the cell area, following the IUCN guidelines. rl_eoo() measures the area of the convex hull around the points. Both return a one row sf object: the metric and its supporting counts, plus the polygon in the geometry column, so you can map the result directly.

The category_b1 and category_b2 columns give the most threatened band the value reaches ("CR", "EN", or "VU"), or NA when it reaches none. Keep in mind that this is the range threshold only. A full Criterion B listing also needs the subconditions (fragmentation, decline, or fluctuation), so the column is a guide, not a verdict.

plot(sf::st_geometry(eoo), border = "steelblue")
plot(sf::st_geometry(occ_check), pch = 20, cex = 0.5, add = TRUE)

Putting it together

sp <- rl_scientific_name("Corvinella", "corvina", resolve = TRUE)

occ <- rl_occurrences(
  sp,
  year = ">2025",
  basis_of_record = c("HUMAN_OBSERVATION", "MACHINE_OBSERVATION"),
  limit = 500
)

occ_check <- rl_check_occurrences(
  occ,
  correct = c("duplicates", "outliers", "country", "ocean_points", "centroids"),
  terrestrial = FALSE
)

rl_aoo(occ_check)
rl_eoo(occ_check)