Skip to contents

Count GBIF occurrences of taxa in each WWF/TNC terrestrial ecoregion

Source: R/tax_ecoregion_occur.R
tax_ecoregion_occur.Rd

<a href="https://adrientaudiere.github.io/MiscMetabar/articles/Rules.html#lifecycle"> <img src="https://img.shields.io/badge/lifecycle-experimental-orange" alt="lifecycle-experimental"></a>

For each name in `taxnames`, retrieves GBIF occurrence coordinates ([tax_gbif_occur_coords()]), maps them to WWF/TNC terrestrial ecoregions in a single spatial join and returns a long tibble with the number and the proportion of occurrences per (taxon, ecoregion). Use [tax_ecoregion_occur_pq()] for the phyloseq wrapper, and [tax_check_ecoregion()] to compare the profile to specific GPS points.

Usage

tax_ecoregion_occur(
  taxnames,
  n_occur = 1000,
  method = "search",
  min_nb_occur = 0,
  min_proportion = 0,
  clean_coord = FALSE,
  verbose = TRUE,
  time_to_sleep = 0.3
)

Arguments

taxnames

(character vector) Scientific names of the taxa to query.

n_occur

(numeric, default `1000`). Maximum number of occurrences to keep per taxon. With `method = "search"` this is a server-side limit; with the download methods it is applied as a local sample after import (a warning is issued when a taxon exceeded `n_occur`).

method

(character, default `"search"`). How GBIF occurrences are fetched, passed to [tax_gbif_occur_coords()]. Ecoregion profiling defaults to the credential-free, per-taxon-capped `"search"` path; set `"download"` (or `"download_sql"`) to use the Download API (**requires GBIF credentials**).

min_nb_occur

(numeric, default `0`). Keep only (taxon, ecoregion) pairs with at least this many occurrences.

min_proportion

(numeric, default `0`). Keep only (taxon, ecoregion) pairs whose share of the taxon's total occurrences is `>= min_proportion` (a number in `[0, 1]`). Combined with `min_nb_occur` via AND.

clean_coord

(logical, default `FALSE`). If `TRUE`, run [CoordinateCleaner::clean_coordinates()] on the result (requires the `CoordinateCleaner` package).

verbose

(logical, default `TRUE`). If `TRUE`, print progress messages.

time_to_sleep

(numeric, default `0.3`). Seconds to pause between [rgbif::occ_search()] calls to avoid GBIF rate-limiting. Only used when `method = "search"`.

Value

A tibble with columns `taxon_name`, `ECO_NAME`, `biome`, `realm`, `n_occur`, `prop_occur`. Taxa with zero retrievable occurrences appear once with `NA` in the ecoregion columns and `n_occur = 0L`, so downstream joins do not silently drop them.

See also

[tax_gbif_occur_coords()], [tax_check_ecoregion()], [tax_ecoregion_occur_pq()]

Author

Adrien Taudiere

Examples

if (FALSE) { # \dontrun{
tax_ecoregion_occur(
  c("Xylobolus subpileatus", "Amanita muscaria"),
  n_occur = 200
)
} # }