Package 'biofetchR'

Description

Record the processing outcome for one species x region combination and append it to a summary table created by initialize_summary().

Usage

append_summary_row(
  summary_tbl,
  species,
  region_id,
  region_type,
  n_total,
  n_cleaned,
  n_thinned,
  output_file,
  status,
  quiet = FALSE
)

Arguments

Details

This helper performs light type coercion for the count fields so that summary tables remain stable when upstream pipeline steps return numeric, integer or missing values. It does not validate that n_cleaned <= n_total or n_thinned <= n_cleaned, because some workflows may report values from different stages or use specialised cleaning/thinning backends.

When quiet = FALSE, the helper prints a short success message using cli::cli_alert_success(). Set quiet = TRUE in batch tests, package checks or non-interactive workflows where console output should be suppressed.

Value

A tibble containing the existing rows in summary_tbl plus one appended processing-summary row. The appended row records the supplied species, region_id, region_type, record counts, output_file and status. Count fields are coerced to integer so the summary schema remains stable across pipeline steps. The returned table is used to accumulate one row per processed species x spatial-recipient combination in terrestrial/freshwater and marine GBIF workflows.

See Also

Other processing summary helpers: initialize_summary()

Examples

summary_tbl <- initialize_summary()

summary_tbl <- append_summary_row(
  summary_tbl = summary_tbl,
  species = "Rattus norvegicus",
  region_id = "GB",
  region_type = "GADM",
  n_total = 100,
  n_cleaned = 90,
  n_thinned = 25,
  output_file = "Rattus_norvegicus__GB.csv",
  status = "success",
  quiet = TRUE
)

summary_tbl

Description

Apply manual taxonomy name and rank fixes to a data frame

Usage

bf_apply_manual_taxonomy_fixes(
  x,
  manual_fixes,
  name_col = "species",
  overwrite_names = TRUE,
  overwrite_ranks = FALSE,
  rank_cols = c("kingdom", "phylum", "class", "order", "family", "genus", "species_rank")
)

Arguments

Value

A data frame with the same rows as x and with manual taxonomy fixes applied where matching keys are found. If overwrite_names = TRUE, values in name_col are replaced by matched manual replacement names. If overwrite_ranks = TRUE, matching rank columns are also updated from manual_fixes; otherwise rank values are filled only where the input value is missing or blank. If no usable manual fixes are supplied, the original input data frame is returned unchanged.

Description

Attach GBIF taxonomy to a data frame

Usage

bf_attach_gbif_taxonomy(x, name_col = "species", prefix = "tax_", ...)

Arguments

Value

A data frame with the same rows as x and GBIF taxonomy-resolution columns joined by name_col. The attached columns are produced by bf_resolve_gbif_taxonomy_batch() and, by default, are prefixed with prefix. They include resolved names, GBIF usage keys, rank, classification fields, match diagnostics and resolver provenance. The output is used to keep original records together with their taxonomy audit information.

Description

Adds GRIIS listing and invasive-status evidence to an input table. The function can join by species + country for terrestrial/freshwater workflows or by species only for marine/global workflows.

Usage

bf_attach_griis_status(
  df,
  species_col = "species",
  iso2c_col = NULL,
  iso3c_col = NULL,
  country_col = NULL,
  griis = NULL,
  cache_dir = NULL,
  force_refresh = FALSE,
  require_country = TRUE,
  quiet = FALSE
)

Arguments

Details

When require_country = TRUE, at least one of iso2c_col, iso3c_col or country_col must identify the recipient country. These fields are resolved to ISO3 and joined against a species x country GRIIS lookup.

When require_country = FALSE, no country parsing is attempted and the join is species-only. This is important for marine pipelines where the input table may contain only species names before marine spatial overlays are assigned.

The function appends:

• griis_listed: whether the species/country or species-only record appears in GRIIS;

• griis_invasive: whether any matching GRIIS row is flagged invasive;

• griis_status: a compact categorical summary of the match.

Value

A tibble containing the input rows with GRIIS evidence columns appended. The returned object preserves the input columns and adds fields such as griis_listed, griis_invasive, griis_status, griis_any_invasive_field_present, griis_n_matches and supporting matched-name/status metadata where available. griis_status is a character summary with values such as "listed_invasive", "listed_introduced_or_alien" and "not_listed_or_no_match". These columns provide GRIIS evidence for filtering and auditing; non-matches should not be interpreted as confirmed native status, absence or lack of impact.

Interpretation

GRIIS columns appended by this helper are evidence fields for filtering and audit. A row with griis_listed = FALSE means no matching GRIIS evidence was found under the selected matching mode; it should not be interpreted as proof that the species is native, absent or harmless in that recipient region.

See Also

Other GRIIS origin-evidence helpers: bf_download_griis(), bf_filter_griis_invasive(), bf_find_griis_table(), bf_griis_lookup(), bf_read_griis(), bf_standardise_griis(), bf_unpack_griis()

Examples

raw <- data.frame(
  species = "Example species",
  scientificName = "Example species",
  countryCode_alpha2 = "GB",
  countryCode_alpha3 = "GBR",
  isInvasive = "yes",
  stringsAsFactors = FALSE
)
input <- data.frame(species = "Example species", iso2c = "GB")
bf_attach_griis_status(input, iso2c_col = "iso2c", griis = raw)

Description

Joins species-level native-origin evidence to an input table and, when a recipient country is available, classifies each row as native, non-native or origin-unknown for that recipient.

Usage

bf_attach_native_status(
  df,
  species_col = "species",
  iso2c_col = NULL,
  iso3c_col = NULL,
  country_col = NULL,
  native_ranges = NULL,
  native_species_col = "species",
  origin_iso3_col = NULL,
  require_country = TRUE,
  strategy = c("tiered", "union"),
  native_filter_mode = c("audit_only", "non_native_only", "keep_non_native",
    "non_native_or_unknown", "keep_non_native_or_unknown", "native_only", "keep_native"),
  max_origins = 100L,
  use_native_web = FALSE,
  native_web_sources = c("sinas", "gbif", "worms"),
  native_web_cache_dir = NULL,
  native_web_force_refresh = FALSE,
  native_web_sleep_sec = 0.25,
  native_web_quiet = quiet,
  native_web_sinas_main_path = NULL,
  native_web_sinas_alllocations_path = NULL,
  native_web_sinas_fulltaxa_path = NULL,
  export_native_web_audit = FALSE,
  native_web_audit_dir = NULL,
  native_web_audit_prefix = "native_web",
  quiet = FALSE
)

Arguments

Details

This is the core classifier used by the terrestrial/freshwater and marine pipelines. With require_country = TRUE, the helper resolves recipient country information to ISO3 and compares it with each species' native-origin ISO3 set. With require_country = FALSE, it attaches species-level origin availability without making recipient-level native/non-native claims.

If native_ranges = NULL and use_native_web = TRUE, provider evidence is compiled through bf_fetch_native_ranges_web() before classification. This allows SInAS/GBIF/WoRMS evidence to be generated inside the helper, while still keeping the classification logic centralised here.

Value

A tibble containing the input rows with native-origin and recipient-status columns attached. The returned object preserves the input columns and adds fields such as native_name_key, native_name, native_origin_iso3, native_has_origin, native_sources_used, native_recipient_iso3, native_is_native_recipient, native_is_non_native_recipient, native_status, native_filter_keep and native_filter_rejection_reason. When require_country = TRUE, native_status classifies each row as "native_recipient", "non_native_recipient" or "origin_unknown" by comparing the recipient ISO3 code with the species-level native-origin ISO3 set. When require_country = FALSE, the function attaches species-level origin availability without making recipient-level native/non-native claims. Strict ⁠*_only⁠ filter modes return only retained rows; ⁠keep_*⁠ modes annotate retention decisions without dropping rows.

Interpretation

origin_unknown means that the available native-origin evidence did not confirm a usable origin set for that species. It should not be interpreted as proof that the species is native, non-native, absent or data-deficient in an ecological sense.

Data source and attribution

This function classifies evidence supplied by other sources. If evidence is generated from SInAS, GBIF, WoRMS or another provider, cite the exact source, version/release and access date used to create native_ranges.

See Also

Other native-origin status helpers: bf_filter_native(), bf_filter_non_native(), bf_native_range_lookup(), bf_native_status_summary(), bf_reconcile_griis_native_status(), bf_standardise_native_ranges()

Description

Returns the marine spatial overlays that biofetchR can load through its package-managed Marine Regions workflow.

Usage

bf_available_marine_overlays(include_aliases = FALSE, include_extended = FALSE)

Arguments

Details

By default, this helper returns the core overlays that are expected to be resolvable in most mregions2/Marine Regions installations: eez, meow, lme and iho. Set include_extended = TRUE to list the full registry of supported extended overlays used by the marine pipeline and release-gate checks.

The returned overlay names can be supplied to process_gbif_marine_pipeline() through its marine overlay argument. Aliases can also be inspected with include_aliases = TRUE.

Value

A data frame listing marine overlays registered by biofetchR. The returned object contains overlay, a character canonical overlay name; description, a character description of the spatial unit type; and workflow, a character label identifying the overlay as part of the marine workflow. When include_aliases = TRUE, the returned data frame also contains aliases, a list-column of accepted aliases and candidate Marine Regions product identifiers. The table is used to inspect valid overlay names before loading or passing them to marine processing workflows.

Scope

This helper only lists overlay names registered by biofetchR. It does not download or cache Marine Regions products. Data access happens in bf_load_marine_regions_overlay().

See Also

Other marine overlay loaders: bf_load_marine_regions_overlay(), bf_marine_overlay_canonical()

Examples

bf_available_marine_overlays()
bf_available_marine_overlays(include_extended = TRUE)

Description

Returns the web/API sources currently implemented by bf_fetch_native_ranges_web(). These are optional enrichment sources used to compile species-level native-origin evidence when a complete local native range table is not available.

Usage

bf_available_native_web_sources()

Value

A data frame listing native-origin web/API evidence sources supported by biofetchR. The returned table contains source, the source identifier accepted by bf_fetch_native_ranges_web(); description, a short explanation of the evidence provider; access_type, the way the source is accessed or cached; and default, a logical flag indicating whether the source is included in the default source set. The table is intended for inspecting valid source names before requesting web-derived native-origin evidence.

Relationship to other helpers

This function lists optional evidence providers only. The returned sources are consumed by bf_fetch_native_ranges_web() and then passed to the core native-status classifier in bf_attach_native_status().

See Also

Other native-range web-source helpers: bf_fetch_native_ranges_web(), bf_web_native_gbif(), bf_web_native_worms(), bf_write_native_web_outputs()

Examples

bf_available_native_web_sources()

Description

Bind a list of GBIF result chunks into a single spatial object while standardising geometry handling and reducing mixed-column type conflicts.

Usage

bf_bind_gbif_chunks(x_list, coerce_all_to_character = TRUE)

Arguments

Details

GBIF imports can produce chunks with heterogeneous columns, missing fields or incompatible column classes across species, countries, downloads or publishing datasets. bf_bind_gbif_chunks() keeps only non-empty chunks, converts plain data frames with decimalLongitude and decimalLatitude columns into sf point objects, standardises the geometry column name to "geometry", and transforms spatial inputs to WGS84 when needed.

The helper then aligns the union of all non-geometry columns across valid chunks and, by default, coerces those attributes to character before binding. This conservative coercion avoids common row-binding failures caused by GBIF fields switching between integer, numeric, logical, factor and character classes across chunks.

The function intentionally avoids relying on sf::st_geometry_name() so that it remains compatible with older sf versions used on some Windows or HPC installations.

Value

An sf point object when at least one valid GBIF chunk is supplied. The returned object contains the union of non-geometry columns across valid chunks, a standardised geometry column, and WGS84 point geometries derived from existing sf geometries or from decimalLongitude and decimalLatitude columns. When coerce_all_to_character = TRUE, all non-geometry columns are coerced to character before binding to avoid mixed type failures across GBIF chunks. If no valid chunks are available, the function returns an empty tibble.

Relationship to older helpers

This function replaces the older, ambiguous harmonize_column_types() helper for GBIF result chunks. It is named explicitly to show that it returns one bound object, not a harmonised list.

Examples

x1 <- data.frame(
  species = "Example species",
  decimalLongitude = -6.26,
  decimalLatitude = 53.35,
  individualCount = 1
)

x2 <- data.frame(
  species = "Example species",
  decimalLongitude = -6.30,
  decimalLatitude = 53.40,
  basisOfRecord = "HUMAN_OBSERVATION"
)

if (requireNamespace("sf", quietly = TRUE)) {
  bf_bind_gbif_chunks(list(x1, x2))
}

Description

This helper returns a cache directory (creating it if needed) where biofetchR can store downloaded spatial layers (zips + extracted shapefiles). Users are not expected to download or manage raw data files themselves.

Usage

bf_cache_dir(cache_dir = NULL, subdir = NULL)

Arguments

Value

A character vector of length one giving the normalised path to a writable cache directory. The directory is created if it does not already exist, so the function is also called for the side effect of preparing a cache location for downloaded spatial layers. If subdir is supplied, the returned path points to that subdirectory inside the cache root.

Description

Check taxonomic resolution quality

Usage

bf_check_taxonomic_resolution(taxonomy_tbl, min_confidence = 90)

Arguments

Value

A tibble containing the subset of rows from taxonomy_tbl with potential taxonomy-resolution issues. The output preserves the available taxonomy columns and adds an issue column describing the detected problem, such as "non_taxon_skipped", "unresolved", "missing_gbif_taxon_key", "low_confidence", "non_exact_match" or "higher_rank_match". An empty tibble indicates that no rows were flagged by the selected checks.

Description

Applies conservative string cleaning before GBIF or WoRMS lookup. The helper removes simple authorship fragments, parenthetical notes, selected descriptor words and implausible non-taxonomic strings while retaining plausible genus, binomial and trinomial names for downstream auditing.

Usage

bf_clean_taxon_names(x, max_tokens = 3, keep_genus_for_open_names = TRUE)

Arguments

Value

A character vector with the same length as x. Each element contains a cleaned taxon-name candidate after whitespace, authority, punctuation, descriptor and open-name handling. Blank, non-taxonomic or implausible entries are returned as NA_character_. The returned names are intended for GBIF or WoRMS taxonomy resolution and for audit columns in downstream pipelines.

Description

Downloads the country-level Global Register of Introduced and Invasive Species (GRIIS) compendium and stores it in a local cache. The downloader is designed to be robust on Windows: files are first downloaded to a .tmp path and then promoted to the final cache path by rename or copy.

Usage

bf_download_griis(
  cache_dir = NULL,
  force_refresh = FALSE,
  source_url = .bf_griis_default_source_url(),
  quiet = FALSE
)

Arguments

Details

biofetchR requires the country-level GRIIS table because the terrestrial and freshwater workflows use species x recipient-country evidence. The helper therefore rejects the griis_meta_recoded metadata/DwC-A archive, which lacks the required country-level fields used by the GRIIS gate.

If a previous run left a valid temporary file in the cache, the helper attempts to finalise that file before downloading again. This avoids unnecessary repeated downloads when a prior session succeeded but file finalisation failed.

Value

A character vector of length one giving the normalised path to the cached GRIIS country compendium file, using forward slashes. The path points to either an existing valid cached file or a newly downloaded file. The function is also called for the side effect of downloading, validating and caching the external GRIIS source file.

Data source and attribution

This function downloads the external GRIIS country compendium into a local user cache. biofetchR does not redistribute or claim ownership of the source data. Users should cite the GRIIS data source, version/record and associated provider guidance used in their analysis.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_filter_griis_invasive(), bf_find_griis_table(), bf_griis_lookup(), bf_read_griis(), bf_standardise_griis(), bf_unpack_griis()

Examples

if (interactive()) {
  path <- bf_download_griis(
    cache_dir = file.path(tempdir(), "biofetchR_griis"),
    quiet = FALSE
  )

  file.exists(path)
}

Description

Downloads, caches and resolves the SInAS 3.1.1 resources required by the biofetchR native-evidence workflow. Existing local files can be supplied to bypass downloading. Otherwise, the function downloads the main SInAS table, extracts AllLocations.xlsx from the configuration archive, and recovers SInAS_3.1.1_FullTaxaList.csv from the output archive for the default record.

Usage

bf_download_sinas_resources(
  cache_dir = NULL,
  force_refresh = FALSE,
  quiet = FALSE,
  main_path = NULL,
  allloc_path = NULL,
  fulltaxa_path = NULL,
  record_id = "18220953",
  main_url = bf_sinas_default_urls(record_id)[["main_csv"]],
  fulltaxa_url = NULL,
  config_zip_url = bf_sinas_default_urls(record_id)[["config_zip"]],
  output_zip_url = bf_sinas_default_urls(record_id)[["output_zip"]]
)

Arguments

Value

A named list of normalised local file paths to the SInAS resources required by biofetchR native-origin evidence workflows. The list always contains main_csv, the local path to SInAS_3.1.1.csv; alllocations_xlsx, the local path to AllLocations.xlsx or an equivalent location table found in the extracted configuration archive; fulltaxa_csv, the local path to SInAS_3.1.1_FullTaxaList.csv or a matching FullTaxaList file recovered from the output archive; config_zip, the cached configuration archive path; and config_dir, the extracted configuration directory path. When FullTaxaList is recovered from All_Output_Files_SInAS_v3.1.1.zip, the list also contains output_zip and output_dir. User-supplied local paths are returned in normalised form when provided and valid; otherwise paths point to files downloaded or extracted inside cache_dir.

Cache behaviour

Cached files are reused when present and above the minimum size threshold. Set force_refresh = TRUE to re-download archives and rebuild extracted directories. User-supplied local paths always take precedence over downloads.

Data access and attribution

biofetchR does not ship or redistribute SInAS resources. This function only downloads files into a user-managed local cache. Users should check the relevant SInAS/Zenodo record for licence, citation and attribution requirements before publishing, redistributing or archiving derived outputs.

See Also

Other SInAS resource helpers: bf_sinas_default_urls()

Examples

if (interactive()) {
  sinas_paths <- bf_download_sinas_resources(
    cache_dir = file.path(tempdir(), "biofetchR_sinas"),
    quiet = FALSE
  )

  names(sinas_paths)
  sinas_paths$main_csv
}

Description

Adds raster-derived covariates to an sf point object. Supported contexts are currently WorldCover, SoilGrids and Human Footprint. Raster files are prepared through remote-first helper functions unless local sources are supplied.

Usage

bf_enrich_raster_context(
  sf_points,
  raster_context = character(0),
  cache_dir = NULL,
  worldcover_source = NULL,
  worldcover_year = 2020,
  worldcover_buffer_m = 0,
  soilgrids_sources = NULL,
  soilgrids_vars = NULL,
  soilgrids_buffer_m = 0,
  human_footprint_source = NULL,
  human_footprint_buffer_m = 0,
  quiet = TRUE
)

Arguments

Value

An sf object with the same rows and geometry as sf_points, with additional raster-context columns appended for the requested contexts. When "worldcover" is requested, the returned object includes a ⁠worldcover_<year>⁠ column containing extracted WorldCover class values for the selected worldcover_year. When "soilgrids" is requested, one column is added for each prepared SoilGrids variable, using names of the form ⁠soilgrids_<variable>⁠. When "human_footprint" is requested, the returned object includes a human_footprint column. Raster values are extracted directly at point locations when the relevant buffer distance is 0; otherwise they are summarised within buffers using modal extraction for WorldCover and mean extraction for SoilGrids and Human Footprint. Empty inputs, non-sf inputs or calls with no requested raster contexts are returned unchanged.

Data licensing and attribution

This function can download or extract values from third-party raster products, including WorldCover, SoilGrids and Human Footprint layers. biofetchR does not ship, redistribute or modify these raster datasets. Users are responsible for checking the licence, citation and attribution requirements of each raster source before use in analysis, publication or redistribution. Always cite the specific product, version, year and provider used in the workflow.

See Also

Other raster context helpers: bf_enrich_raster_context_from_sources()

Examples

if (
  requireNamespace("sf", quietly = TRUE) &&
  requireNamespace("terra", quietly = TRUE)
) {
  gbif_points <- sf::st_as_sf(
    data.frame(
      species = "Example species",
      decimalLongitude = -5,
      decimalLatitude = 55
    ),
    coords = c("decimalLongitude", "decimalLatitude"),
    crs = 4326,
    remove = FALSE
  )

  r <- terra::rast(
    nrows = 2,
    ncols = 2,
    xmin = -10,
    xmax = 0,
    ymin = 50,
    ymax = 60,
    crs = "EPSG:4326"
  )
  terra::values(r) <- c(10, 20, 30, 40)

  raster_path <- file.path(tempdir(), "worldcover_example.tif")
  terra::writeRaster(r, raster_path, overwrite = TRUE)

  enriched <- bf_enrich_raster_context(
    sf_points = gbif_points,
    raster_context = "worldcover",
    cache_dir = tempdir(),
    worldcover_source = raster_path,
    worldcover_year = 2020
  )

  names(enriched)
}

Description

Adds one or more raster-derived contextual variables to an input point sf object using raster sources supplied directly by the user. This helper is intended for biofetchR occurrence-enrichment workflows where environmental or anthropogenic raster covariates need to be attached to GBIF-derived point records before downstream modelling, mapping, filtering or summary steps.

Usage

bf_enrich_raster_context_from_sources(
  sf_points,
  raster_context = c("worldcover", "soilgrids", "human_footprint"),
  cache_dir = NULL,
  worldcover_source = NULL,
  worldcover_year = 2021,
  worldcover_buffer_m = 0,
  soilgrids_sources = NULL,
  soilgrids_vars = NULL,
  soilgrids_buffer_m = 0,
  human_footprint_source = NULL,
  human_footprint_buffer_m = 0,
  force_refresh = FALSE,
  quiet = TRUE
)

Arguments

Details

bf_enrich_raster_context_from_sources() is the source-explicit companion to bf_enrich_raster_context(). Use this function when the raster products are already available locally, when you want to provide custom raster URLs, or when you want to control the exact raster versions used in the analysis.

For package-managed/default raster downloads, use bf_enrich_raster_context() instead.

This function currently supports three optional raster-context groups:

"worldcover"

Extracts an ESA WorldCover-style categorical raster, returning worldcover_class, worldcover_label and worldcover_year.

"soilgrids"

Extracts one or more named continuous SoilGrids-style rasters and stores them as ⁠soilgrids_<variable>⁠ columns.

"human_footprint"

Extracts a continuous Human Footprint-style raster and stores it as human_footprint.

Raster sources may be local file paths, URLs or pre-loaded terra::SpatRaster objects. URL sources are downloaded into cache_dir and reused on later runs unless force_refresh = TRUE.

Extraction is performed directly at point coordinates when the relevant buffer argument is 0. If a positive buffer radius is supplied, raster values are summarised within buffered geometries: modal class for WorldCover and mean value for SoilGrids and Human Footprint.

Value

An sf object with the same rows and geometry as sf_points, with additional raster-context columns appended for the requested contexts. When "worldcover" is requested, the returned object includes worldcover_class, worldcover_label and worldcover_year. When "soilgrids" is requested, one numeric column is added for each requested SoilGrids variable, using names of the form ⁠soilgrids_<variable>⁠. When "human_footprint" is requested, the returned object includes a numeric human_footprint column. Raster values are extracted directly at point locations when the relevant buffer distance is 0; otherwise they are summarised within buffers using modal extraction for categorical WorldCover data and mean extraction for continuous SoilGrids and Human Footprint data. No rows are intentionally added or removed by this enrichment helper.

Output columns

Depending on the requested raster contexts, the returned object may include:

worldcover_class

Integer categorical class extracted from the supplied WorldCover-style raster.

worldcover_label

Human-readable land-cover label corresponding to worldcover_class, where the class is recognised.

worldcover_year

Year or label supplied through worldcover_year.

⁠soilgrids_<variable>⁠

Continuous raster values extracted from each named SoilGrids-style raster.

human_footprint

Continuous Human Footprint-style raster values.

Data licensing and attribution

This function extracts values from user-supplied raster products, including ESA WorldCover, SoilGrids and Human Footprint-style layers. biofetchR does not ship, redistribute or modify these raster datasets. Users are responsible for checking the licence, citation and attribution requirements of each raster source before use in analysis, publication or redistribution.

Commonly used sources include ESA WorldCover and SoilGrids, which are commonly distributed under Creative Commons Attribution licences, and Human Footprint products, whose terms vary by dataset and provider. Always cite the specific raster product, version, year and provider used in your workflow.

See Also

Other raster context helpers: bf_enrich_raster_context()

Examples

if (
  requireNamespace("sf", quietly = TRUE) &&
  requireNamespace("terra", quietly = TRUE)
) {
  occ_sf <- sf::st_as_sf(
    data.frame(
      species = "Example species",
      decimalLongitude = -5,
      decimalLatitude = 55
    ),
    coords = c("decimalLongitude", "decimalLatitude"),
    crs = 4326,
    remove = FALSE
  )

  r <- terra::rast(
    nrows = 2,
    ncols = 2,
    xmin = -10,
    xmax = 0,
    ymin = 50,
    ymax = 60,
    crs = "EPSG:4326"
  )
  terra::values(r) <- c(10, 20, 30, 40)

  worldcover_path <- file.path(tempdir(), "worldcover_example.tif")
  footprint_path <- file.path(tempdir(), "human_footprint_example.tif")

  terra::writeRaster(r, worldcover_path, overwrite = TRUE)
  terra::writeRaster(r, footprint_path, overwrite = TRUE)

  enriched <- bf_enrich_raster_context_from_sources(
    sf_points = occ_sf,
    raster_context = c("worldcover", "human_footprint"),
    cache_dir = tempdir(),
    worldcover_source = worldcover_path,
    human_footprint_source = footprint_path,
    worldcover_year = 2021
  )

  names(enriched)
}

Description

Reads SInAS 3.1.1 native-location records, converts SInAS locationID values to ISO3 countries using AllLocations, and returns native-origin evidence in the same structure as the optional native web/API helpers. When local paths are not supplied, the function uses bf_download_sinas_resources() to resolve package-managed cached copies from Zenodo.

Usage

bf_fetch_native_ranges_sinas(
  species,
  species_col = "species",
  cache_dir = NULL,
  force_refresh = FALSE,
  quiet = FALSE,
  main_path = NULL,
  alllocations_path = NULL,
  fulltaxa_path = NULL,
  record_id = "18220953",
  main_url = NULL,
  fulltaxa_url = NULL,
  config_zip_url = NULL,
  return = c("long", "species", "list")
)

Arguments

Details

This is a provider-specific helper. It extracts native-origin evidence from SInAS and returns species-level origin countries, but it does not decide whether a recipient country is native or non-native. Pass the returned species-level table to bf_attach_native_status() for recipient-level classification.

SInAS 3.1.1 can use a quoted whitespace-delimited text format despite the .csv extension. The internal reader therefore tries a SInAS-aware parser before falling back to more conventional CSV, TSV and pipe-delimited readers.

Value

The returned object depends on return. If return = "long", the function returns a tibble with one row per retained SInAS native-origin evidence record, including species, source, accepted_name, source_taxon_id, raw_native_area, raw_status, origin_iso3, evidence_type and source_url. If return = "species", the function returns a species-level tibble with collapsed native-origin evidence, including species, native_origin_iso3, native_sources_used, native_web_unmapped_strings, native_web_n_records and native_has_origin. If return = "list", the function returns a named list with long, species, unmapped and summary elements. The unmapped element contains long-format evidence rows without resolved ISO3 origin codes, and summary is a one-row tibble reporting input species counts, matched SInAS records, ISO3-resolved species and unmapped records. These outputs provide species-level native-origin evidence only; recipient- level native/non-native classification is performed by bf_attach_native_status().

Relationship to utils_native_range.R

Keep this script alongside utils_native_range.R. This file provides the SInAS evidence source; utils_native_range.R provides the general standardisation, attachment, filtering and reconciliation logic used by the terrestrial/freshwater and marine pipelines.

Data source and attribution

biofetchR resolves and standardises SInAS resources but does not own or redistribute the underlying data. Users should cite the exact SInAS release, Zenodo record, version and access date used in their workflow, and should follow the licence terms attached to that release.

See Also

bf_attach_native_status(), bf_download_sinas_resources()

Examples

if (interactive()) {
  sinas_native <- bf_fetch_native_ranges_sinas(
    species = c("Carcinus maenas", "Ficopomatus enigmaticus"),
    cache_dir = file.path(tempdir(), "biofetchR_sinas"),
    return = "species",
    quiet = FALSE
  )

  sinas_native
}

Description

Queries one or more web/API sources for species-level native-origin evidence, caches raw responses, converts source locality/country strings to ISO3 where possible, and returns both long evidence and species-level collapsed outputs.

Usage

bf_fetch_native_ranges_web(
  species,
  species_col = "species",
  sources = c("sinas", "gbif", "worms"),
  cache_dir = NULL,
  force_refresh = FALSE,
  sleep_sec = 0.25,
  quiet = FALSE,
  sinas_main_path = NULL,
  sinas_alllocations_path = NULL,
  sinas_fulltaxa_path = NULL,
  sinas_record_id = "18220953",
  sinas_main_url = NULL,
  sinas_fulltaxa_url = NULL,
  sinas_config_zip_url = NULL,
  return = c("list", "species", "long")
)

Arguments

Details

This helper is designed as an optional complement to curated native-range tables. Its collapsed species output can be passed to bf_attach_native_status() as native_ranges, because it includes a species column and a semicolon-delimited native_origin_iso3 column.

Value

The returned object depends on return. If return = "list", the function returns a named list with four elements: long, a tibble with one row per retained source evidence record using the standard columns species, source, accepted_name, source_taxon_id, raw_native_area, raw_status, origin_iso3, evidence_type and source_url; species, a collapsed species-level tibble containing species, native_origin_iso3, native_sources_used, native_web_unmapped_strings, native_web_n_records and native_has_origin; unmapped, the subset of long-format native-like evidence rows whose locality or area string could not be resolved to ISO3; and summary, a one-row tibble reporting input species counts, matched web records, ISO3-resolved species, unmapped records and sources used. If return = "species", only the collapsed species-level tibble is returned. If return = "long", only the long evidence tibble is returned. These outputs provide species-level native-origin evidence for downstream use in bf_attach_native_status() and do not themselves classify recipient records as native or non-native.

Relationship to SInAS

SInAS support is now part of this canonical web-source aggregator. When sources includes "sinas", this function delegates provider-specific parsing to bf_fetch_native_ranges_sinas(). Keep that SInAS provider file in the package, but do not also keep a duplicate ⁠*_with_sinas⁠ aggregator file.

Data source and interpretation

The returned evidence is web/API-derived and source-dependent. Treat it as an auditable native-origin evidence layer rather than proof that a species is native, non-native or absent from any place.

See Also

Other native-range web-source helpers: bf_available_native_web_sources(), bf_web_native_gbif(), bf_web_native_worms(), bf_write_native_web_outputs()

Examples

if (interactive()) {
  native_web <- bf_fetch_native_ranges_web(
    species = c("Carcinus maenas", "Ficopomatus enigmaticus"),
    sources = c("gbif", "worms"),
    cache_dir = file.path(tempdir(), "biofetchR_native_web"),
    return = "species",
    quiet = FALSE
  )

  native_web
}

Description

Convenience wrapper around bf_attach_griis_status() that attaches GRIIS evidence and then retains only rows where griis_invasive is TRUE.]

Usage

bf_filter_griis_invasive(
  df,
  species_col = "species",
  iso2c_col = NULL,
  iso3c_col = NULL,
  country_col = NULL,
  griis = NULL,
  cache_dir = NULL,
  force_refresh = FALSE,
  require_country = TRUE,
  quiet = FALSE
)

Arguments

Value

A tibble containing the subset of input rows for which attached GRIIS evidence has griis_invasive == TRUE. The returned object includes the original input columns plus the GRIIS evidence columns added by bf_attach_griis_status(), including griis_listed, griis_invasive, griis_status and supporting matched-name/status metadata where available. Rows excluded by this filter are not necessarily native or impact-free; they simply lack a matching invasive GRIIS flag under the selected matching mode.

Interpretation

This is a conservative convenience filter based only on GRIIS invasive-status evidence available under the selected matching mode. Rows removed by the filter are not necessarily native or impact-free; they simply lack a matching invasive GRIIS flag under the supplied criteria.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_download_griis(), bf_find_griis_table(), bf_griis_lookup(), bf_read_griis(), bf_standardise_griis(), bf_unpack_griis()

Examples

raw <- data.frame(
  species = "Example species",
  scientificName = "Example species",
  countryCode_alpha2 = "GB",
  countryCode_alpha3 = "GBR",
  isInvasive = "yes",
  stringsAsFactors = FALSE
)
input <- data.frame(species = "Example species", iso2c = "GB")
bf_filter_griis_invasive(input, iso2c_col = "iso2c", griis = raw)

Description

Filter a data frame to confirmed native recipient records

Usage

bf_filter_native(
  df,
  species_col = "species",
  iso2c_col = NULL,
  iso3c_col = NULL,
  country_col = NULL,
  native_ranges,
  native_species_col = "species",
  origin_iso3_col = NULL,
  require_country = TRUE,
  strategy = c("tiered", "union"),
  max_origins = 100L,
  quiet = FALSE
)

Arguments

Value

A tibble containing only rows classified by bf_attach_native_status() as confirmed native recipients under the supplied native-origin evidence and recipient-country settings. The returned object includes the original input columns plus the native-origin/status columns added by bf_attach_native_status(), including native_is_native_recipient, native_status, native_filter_keep and native_filter_rejection_reason. Rows excluded by this filter are not necessarily non-native; they simply lack confirmed native recipient evidence under the selected criteria.

See Also

Other native-origin status helpers: bf_attach_native_status(), bf_filter_non_native(), bf_native_range_lookup(), bf_native_status_summary(), bf_reconcile_griis_native_status(), bf_standardise_native_ranges()

Description

Filter a data frame to confirmed non-native recipient records

Usage

bf_filter_non_native(
  df,
  species_col = "species",
  iso2c_col = NULL,
  iso3c_col = NULL,
  country_col = NULL,
  native_ranges,
  native_species_col = "species",
  origin_iso3_col = NULL,
  require_country = TRUE,
  strategy = c("tiered", "union"),
  max_origins = 100L,
  quiet = FALSE
)

Arguments

Value

A tibble containing only rows classified by bf_attach_native_status() as confirmed non-native recipients under the supplied native-origin evidence and recipient-country settings. The returned object includes the original input columns plus the native-origin/status columns added by bf_attach_native_status(), including native_is_non_native_recipient, native_status, native_filter_keep and native_filter_rejection_reason. Rows excluded by this filter are not necessarily native; they simply lack confirmed non-native recipient evidence under the selected criteria.

See Also

Other native-origin status helpers: bf_attach_native_status(), bf_filter_native(), bf_native_range_lookup(), bf_native_status_summary(), bf_reconcile_griis_native_status(), bf_standardise_native_ranges()

Description

Searches an unpacked GRIIS directory for CSV, TSV, TXT or TAB files and selects the most likely data table using filename and file-size heuristics. Metadata, readme and citation files are down-weighted.

Usage

bf_find_griis_table(exdir)

Arguments

Value

A character vector of length one giving the path to the selected GRIIS table file within exdir. The selected file is chosen from CSV, TSV, TXT or TAB files using filename and file-size heuristics that favour likely species or compendium data tables and down-weight metadata, readme and citation files.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_download_griis(), bf_filter_griis_invasive(), bf_griis_lookup(), bf_read_griis(), bf_standardise_griis(), bf_unpack_griis()

Examples

exdir <- tempfile("griis_example_")
dir.create(exdir)

write.csv(
  data.frame(species = "Example species"),
  file.path(exdir, "griis_country_compendium.csv"),
  row.names = FALSE
)

table_path <- bf_find_griis_table(exdir)
basename(table_path)

Description

Creates a deduplicated lookup table from a raw or standardised GRIIS table. The lookup can be built either at species x country resolution or at species-only resolution.

Usage

bf_griis_lookup(griis, require_country = TRUE)

Arguments

Details

Use require_country = TRUE for terrestrial and freshwater species-country workflows, where invasive status should be matched against the recipient country. Use require_country = FALSE for marine or global workflows that only need species-level GRIIS evidence before GBIF download submission.

The lookup combines accepted-name and scientific-name keys, then summarises all matching GRIIS rows into a compact evidence table.

Value

A deduplicated tibble used as a compact GRIIS lookup table. When require_country = TRUE, each row represents a species-name key by ISO3 country-code combination. When require_country = FALSE, each row represents species-level GRIIS evidence without country matching. The output includes griis_listed, griis_invasive, griis_any_invasive_field_present, griis_n_matches and collapsed supporting fields such as matched names, countries, establishment means, occurrence status and taxon rank. These fields summarise matching GRIIS evidence for downstream joins and filters.

Interpretation

The lookup reports whether a supplied name/country combination matches GRIIS evidence and whether any matched GRIIS row is flagged invasive. Non-matches should be treated as not_listed_or_no_match, not as confirmed absence of introduction or impact.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_download_griis(), bf_filter_griis_invasive(), bf_find_griis_table(), bf_read_griis(), bf_standardise_griis(), bf_unpack_griis()

Examples

raw <- data.frame(
  species = "Example species",
  scientificName = "Example species",
  countryCode_alpha2 = "GB",
  countryCode_alpha3 = "GBR",
  isInvasive = "yes",
  stringsAsFactors = FALSE
)
lookup <- bf_griis_lookup(raw, require_country = TRUE)
lookup

Description

Downloads selected regional tiles at a chosen Pfafstetter level (L1-L12), caches once, and returns polygons with canonical fields: hybas_id, next_down, next_sink, main_bas, sub_area, up_area, endo, order.

Usage

bf_load_basins(level = 12, with_lakes = FALSE, cache_dir = NULL, quiet = TRUE)

Arguments

Value

An sf polygon object containing HydroBASINS catchments for the requested Pfafstetter level, in WGS84 longitude/latitude coordinates. The returned object includes canonical basin attributes such as hybas_id, next_down, next_sink, main_bas, sub_area, up_area, endo and order, where available. Each row represents a basin polygon used for assigning occurrence records to freshwater catchment units.

See Also

Other freshwater overlay loaders: bf_load_feow(), bf_load_lakes(), bf_load_rivers(), bf_name_rivers_osm()

Description

Downloads, caches and reads a UNESCO biosphere reserve CSV, then converts recognised longitude/latitude columns to an sf point object. The function is remote-first but accepts local or alternate remote sources for reproducible workflows and tests.

Usage

bf_load_biosphere_reserve(
  cache_dir = NULL,
  force_refresh = FALSE,
  iso2c = NULL,
  clip_to_countries = TRUE,
  source_path = NULL,
  source_url = NULL,
  quiet = TRUE
)

Arguments

Value

An sf point object in WGS84 longitude/latitude coordinates containing UNESCO biosphere reserve locations. The returned object includes biosphere_id, a stable reserve or row identifier; biosphere_name, a human-readable reserve label where available; the original longitude and latitude columns used to create point geometry; and the active geometry column. If clip_to_countries = TRUE and iso2c is supplied, the returned object is filtered to biosphere reserve points intersecting the requested countries where possible.

Data licensing and attribution

biofetchR does not redistribute UNESCO biosphere reserve data. Users are responsible for checking and following the licence, citation and attribution requirements of the source used in their workflow.

See Also

Other remote overlay loaders: bf_load_gdw_barriers(), bf_load_gloric()

Examples

if (interactive()) {
  biosphere <- bf_load_biosphere_reserve(
    iso2c = "FR",
    cache_dir = file.path(tempdir(), "biofetchR_biosphere"),
    clip_to_countries = TRUE
  )

  biosphere
}

Description

Loads the Freshwater Ecoregions of the World (FEOW) polygon layer, standardises key fields, and caches the result as a single GeoPackage. The default method = "auto" first attempts a direct ArcGIS FeatureServer query, then falls back to a downloadable archive if available.

Usage

bf_load_feow(
  force_refresh = FALSE,
  quiet = TRUE,
  cache_dir = NULL,
  method = "auto",
  source_url = NULL,
  ...
)

Arguments

Value

An sf polygon object containing Freshwater Ecoregions of the World features in WGS84 longitude/latitude coordinates. The returned object includes standardised columns such as feow_id, ecoregion, biome and realm, where these fields are available from the source layer. Each row represents a freshwater ecoregion polygon used for assigning occurrence records to freshwater spatial units.

Data access and attribution

FEOW is a third-party freshwater ecoregion product. biofetchR only downloads and caches the layer locally for the user. Users should cite FEOW and check the provider's licence and redistribution requirements before using outputs in publications or shared data products.

See Also

Other freshwater overlay loaders: bf_load_basins(), bf_load_lakes(), bf_load_rivers(), bf_name_rivers_osm()

Examples

if (interactive()) {
  feow <- bf_load_feow(
    cache_dir = file.path(tempdir(), "biofetchR_feow"),
    quiet = TRUE
  )

  names(feow)
}

Description

Downloads, caches and reads the Global Dam Watch barrier layer, then returns a standardised point sf object. By default, the function uses the public Figshare article metadata to locate the Global Dam Watch v1.0 shapefile archive. Local files or alternate URLs can be supplied with source_path or source_url for testing, mirrors or manually downloaded data.

Usage

bf_load_gdw_barriers(
  cache_dir = NULL,
  force_refresh = FALSE,
  iso2c = NULL,
  clip_to_countries = TRUE,
  source_path = NULL,
  source_url = NULL,
  quiet = TRUE
)

Arguments

Value

An sf point object in WGS84 longitude/latitude coordinates containing Global Dam Watch barrier features. The returned object includes gdw_barrier_id, a stable barrier, dam or feature identifier; gdw_barrier_name, a human-readable barrier or dam label where available; and the active geometry column. If the selected source layer is not already point geometry, centroids are returned so occurrence points can be assigned to nearby barrier features by downstream workflows. If clip_to_countries = TRUE and iso2c is supplied, the returned object is filtered to the requested countries where possible. The function stops if no rows remain after processing or clipping.

Data licensing and attribution

biofetchR does not redistribute Global Dam Watch data. Users are responsible for checking and following the licence, citation and attribution requirements of the specific Global Dam Watch release used in their workflow.

See Also

Other remote overlay loaders: bf_load_biosphere_reserve(), bf_load_gloric()

Examples

if (interactive()) {
  gdw <- bf_load_gdw_barriers(
    iso2c = c("GB", "IE"),
    cache_dir = file.path(tempdir(), "biofetchR_gdw_barriers"),
    clip_to_countries = TRUE
  )

  gdw
}

Description

Downloads, caches, reads, and standardises Global Dam Watch reservoir polygon data for use as a terrestrial/freshwater context overlay. The returned object contains stable columns used by the GBIF processing pipeline: gdw_reservoir_id, gdw_reservoir_name, and geometry.

Usage

bf_load_gdw_reservoirs(
  cache_dir = NULL,
  force_refresh = FALSE,
  iso2c = NULL,
  clip_to_countries = TRUE,
  source_path = NULL,
  source_url = NULL,
  quiet = TRUE
)

Arguments

Value

An sf polygon object in WGS84 longitude/latitude coordinates containing Global Dam Watch reservoir features. The returned object includes gdw_reservoir_id, a stable reservoir identifier; gdw_reservoir_name, a human-readable reservoir or dam label where available; and the active geometry column. Each row represents one reservoir polygon or multipolygon used for assigning occurrence records to reservoir context. If clip_to_countries = TRUE and iso2c is supplied, the returned object is cropped to the requested countries where possible.

Data access and attribution

This loader can download Global Dam Watch reservoir data from provider-hosted metadata/download services or read a user-supplied local/source URL. Users should cite the Global Dam Watch data release and associated publication for the exact version used. biofetchR caches the source locally for reproducible processing but does not redistribute Global Dam Watch data.

See Also

Other additional context overlay loaders: bf_load_global_mining(), bf_load_hydrowaste()

Examples

if (interactive()) {
  reservoirs <- bf_load_gdw_reservoirs(
    iso2c = "GB",
    cache_dir = file.path(tempdir(), "biofetchR_gdw_reservoirs"),
    clip_to_countries = TRUE
  )

  reservoirs
}

Description

Downloads, caches, reads, and standardises global mining polygon data for use as a terrestrial context overlay. The returned object contains stable columns used by the GBIF processing pipeline: global_mining_id, global_mining_name, and geometry.

Usage

bf_load_global_mining(
  cache_dir = NULL,
  force_refresh = FALSE,
  iso2c = NULL,
  clip_to_countries = TRUE,
  source_path = NULL,
  source_url = NULL,
  quiet = TRUE
)

Arguments

Value

An sf polygon object in WGS84 longitude/latitude coordinates containing global mining-area features. The returned object includes global_mining_id, a stable mining-feature identifier; global_mining_name, a human-readable mine, country or feature label where available; and the active geometry column. Each row represents one mining polygon or multipolygon used for assigning occurrence records to mining-area context. If clip_to_countries = TRUE and iso2c is supplied, the returned object is cropped to the requested countries where possible.

Data access and attribution

This loader can download the global-scale mining polygons from PANGAEA or read a user-supplied local/source URL. Users should cite the PANGAEA dataset DOI, version and associated publication and follow the dataset licence attached to the downloaded file. biofetchR caches the source locally for reproducible processing but does not redistribute the mining dataset.

See Also

Other additional context overlay loaders: bf_load_gdw_reservoirs(), bf_load_hydrowaste()

Examples

if (interactive()) {
  mines <- bf_load_global_mining(
    iso2c = "ZA",
    cache_dir = file.path(tempdir(), "biofetchR_global_mining"),
    clip_to_countries = TRUE
  )

  mines
}

Description

Downloads, caches and reads the Global River Classification (GloRiC) line layer, then standardises core identifier/class columns for use as a terrestrial/freshwater context overlay.

Usage

bf_load_gloric(
  cache_dir = NULL,
  force_refresh = FALSE,
  iso2c = NULL,
  clip_to_countries = TRUE,
  source_path = NULL,
  source_url = NULL,
  quiet = TRUE
)

Arguments

Value

An sf line object in WGS84 longitude/latitude coordinates containing GloRiC river-reach features. The returned object includes gloric_id, a stable reach identifier; gloric_class, the selected GloRiC reach-type or classification label where available; and the active geometry column. Each row represents one river reach line or multiline feature used as terrestrial/freshwater context. If clip_to_countries = TRUE and iso2c is supplied, the returned object is cropped to the requested countries where possible. The function stops if no rows remain after processing or clipping.

Data licensing and attribution

biofetchR does not redistribute GloRiC data. Users are responsible for checking and following the licence, citation and attribution requirements of the GloRiC version used in their workflow.

See Also

Other remote overlay loaders: bf_load_biosphere_reserve(), bf_load_gdw_barriers()

Examples

if (interactive()) {
  rivers <- bf_load_gloric(
    iso2c = "GB",
    cache_dir = file.path(tempdir(), "biofetchR_gloric"),
    clip_to_countries = TRUE
  )

  rivers
}

Description

Downloads, caches, reads, and standardises the HydroWASTE wastewater treatment plant layer for use as a terrestrial/freshwater context overlay. The returned object contains stable columns used by the GBIF processing pipeline: hydrowaste_id, hydrowaste_name, hydrowaste_level, and geometry.

Usage

bf_load_hydrowaste(
  cache_dir = NULL,
  force_refresh = FALSE,
  iso2c = NULL,
  clip_to_countries = TRUE,
  source_path = NULL,
  source_url = NULL,
  quiet = TRUE
)

Arguments

Details

HydroWASTE is treated as a point overlay. If the source is not already point geometry, centroids are used so occurrence points can be assigned to the nearest treatment-plant feature by the main pipeline.

Value

An sf point object in WGS84 longitude/latitude coordinates containing HydroWASTE wastewater-treatment plant features. The returned object includes hydrowaste_id, a stable treatment-plant identifier; hydrowaste_name, a human-readable plant or feature label; hydrowaste_level, the treatment-level attribute where available; and the active geometry column. If the source layer is not already point geometry, centroids are returned so occurrence points can be assigned to the nearest HydroWASTE feature by downstream workflows. If clip_to_countries = TRUE and iso2c is supplied, the returned object is cropped to the requested countries where possible.

Data access and attribution

This loader can download HydroWASTE v1.0 from a package-managed public mirror or read a user-supplied local/source URL. HydroWASTE should be cited using the original dataset publication and any provider guidance associated with the exact file/version used. biofetchR caches the source locally for reproducible processing but does not redistribute HydroWASTE.

See Also

Other additional context overlay loaders: bf_load_gdw_reservoirs(), bf_load_global_mining()

Examples

if (interactive()) {
  hydrowaste <- bf_load_hydrowaste(
    iso2c = c("GB", "IE"),
    cache_dir = file.path(tempdir(), "biofetchR_hydrowaste"),
    clip_to_countries = TRUE
  )

  hydrowaste
}

Description

Downloads HydroLAKES once (RAW), standardizes key fields, then applies optional filters in-memory on each call. Cached as a single GeoPackage.

Usage

bf_load_lakes(
  force_refresh = FALSE,
  quiet = TRUE,
  cache_dir = NULL,
  lakes_only = TRUE,
  min_area_km2 = NULL
)

Arguments

Value

An sf polygon object containing HydroLAKES features in WGS84 longitude/latitude coordinates. The returned object includes standardised columns lake_id, name, is_reservoir and area_km2, alongside any retained source attributes. Each row represents a lake polygon. If lakes_only or min_area_km2 is used, the returned object contains only the lakes retained by those filters.

See Also

Other freshwater overlay loaders: bf_load_basins(), bf_load_feow(), bf_load_rivers(), bf_name_rivers_osm()

Description

Loads one supported marine spatial overlay, caches the source product locally, and returns a standardised sf object for use in the marine GBIF processing pipeline.

Usage

bf_load_marine_regions_overlay(
  region_source = "eez",
  cache_dir = NULL,
  force_refresh = FALSE,
  quiet = TRUE
)

Arguments

Details

The loader first resolves region_source to a canonical biofetchR overlay name, then attempts to load the corresponding Marine Regions product through mregions2. Candidate product identifiers are tried in order because product names may differ between Marine Regions releases.

The returned object is transformed to EPSG:4326, repaired where possible and standardised to include:

• marine_region_id

• marine_region_name

• marine_region_source

• marine_regions_layer

• geoname

These columns are used by process_gbif_marine_pipeline() when assigning occurrence records to marine spatial units and exporting grouped CSV outputs.

Value

An sf polygon object in WGS84 longitude/latitude coordinates containing the requested Marine Regions overlay. The returned object includes canonical columns used by downstream marine workflows: marine_region_id, a character identifier for each spatial unit; marine_region_name, a character region label; marine_region_source, the canonical biofetchR overlay name; marine_regions_layer, the Marine Regions product identifier used to load the data; and geoname, a standardised human-readable region name. Source attributes may also be retained after these canonical columns. Each row represents one marine polygon or multipolygon used for assigning occurrence records to marine contextual regions. The source overlay is cached locally as an RDS file for reuse.

Caching

Loaded overlays are cached as RDS files under cache_dir using one subfolder per canonical overlay. Set force_refresh = TRUE to ignore the cached object and request a fresh copy through mregions2.

Data source, licensing and attribution

Marine overlays are retrieved from Marine Regions data products through mregions2. biofetchR only standardises and caches those products for local processing; it does not redistribute them as package data. Users should cite Marine Regions and the specific product loaded, using the marine_regions_layer output column and the license / citation fields in mregions2::mrp_list where available.

See Also

Other marine overlay loaders: bf_available_marine_overlays(), bf_marine_overlay_canonical()

Examples

if (interactive()) {
  meow <- bf_load_marine_regions_overlay(
    region_source = "meow",
    cache_dir = file.path(tempdir(), "biofetchR_marine_regions")
  )

  meow
}

Description

Creates:

• id_ne_admin1: stable polygon identifier

• geoname_ne_admin1: admin-1 name

Usage

bf_load_ne_admin1(
  cache_dir,
  scale = c("50m", "10m"),
  force_refresh = FALSE,
  clip_to_countries = TRUE,
  iso2c = NULL,
  quiet = TRUE,
  url = NULL
)

Arguments

Value

An sf polygon object containing Natural Earth Admin-1 state/province features in WGS84 longitude/latitude coordinates. The returned object contains id_ne_admin1, a character identifier for each administrative unit; geoname_ne_admin1, a character state/province name where available from the source layer or a generated fallback label otherwise; and the active geometry column. Each row represents one first-level administrative polygon or multipolygon used for assigning occurrence records to subnational Natural Earth administrative units. If clip_to_countries = TRUE and iso2c is supplied, the object is filtered to the requested countries where country-identifying attributes are available, with a bounding-box crop used as a fallback.

Data source and attribution

Downloads Natural Earth Admin-1 state/province polygons from the Natural Earth public distribution endpoint unless url is overridden. biofetchR caches and standardises the layer but does not redistribute or own the data. Cite Natural Earth and the scale used in any downstream analysis.

See Also

Other Natural Earth and RESOLVE overlay loaders: bf_load_ne_urban(), bf_load_resolve2017()

Description

Creates two columns:

• id_ne_urban: stable ID per polygon

• geoname_ne_urban: urban area name (if available)

Usage

bf_load_ne_urban(
  cache_dir,
  scale = c("10m"),
  force_refresh = FALSE,
  clip_to_countries = TRUE,
  iso2c = NULL,
  quiet = TRUE,
  url = NULL
)

Arguments

Value

An sf polygon object containing Natural Earth urban-area features in WGS84 longitude/latitude coordinates. The returned object contains id_ne_urban, a character identifier assigned by biofetchR; geoname_ne_urban, a character urban-area name where available from the source layer or a generated fallback label otherwise; and the active geometry column. Each row represents one urban-area polygon or multipolygon used for assigning occurrence records to Natural Earth urban-context overlays. If clip_to_countries = TRUE and iso2c is supplied, the object is cropped to a buffered bounding box around the requested countries.

Data source and attribution

Downloads Natural Earth urban-area polygons from the Natural Earth public distribution endpoint unless url is overridden. biofetchR caches and standardises the layer but does not redistribute or own the data. Cite Natural Earth and the scale used in any downstream analysis.

See Also

Other Natural Earth and RESOLVE overlay loaders: bf_load_ne_admin1(), bf_load_resolve2017()

Description

This downloads the Natural Earth "Urban Areas" polygons (10m cultural vectors), caches the zip, extracts it, and returns an sf object in EPSG:4326 with a consistent ID + label column for downstream point-tagging.

Usage

bf_load_ne_urban_areas(
  cache_dir = NULL,
  url = "http://www.naturalearthdata.com/download/10m/cultural/ne_10m_urban_areas.zip",
  force_refresh = FALSE,
  quiet = TRUE
)

Arguments

Details

Users do not need to pre-download shapefiles; biofetchR handles retrieval and caching.

Value

An sf polygon object containing Natural Earth urban-area features in WGS84 longitude/latitude coordinates. The returned object contains urban_id, a character identifier for each feature; urban_name, a character label for the urban area; and the active geometry column. Each row represents one urban-area polygon or multipolygon used for assigning occurrence records to urban contextual overlays.

See Also

Other terrestrial overlay loaders: bf_load_resolve_ecoregions2017(), bf_load_teow(), bf_teow_cache_info(), bf_teow_clear_cache()

Description

Downloads, standardises and caches Ramsar-designated polygon features for one or more countries. Ramsar features are obtained as a designation subset of WDPA, which keeps provenance, licensing, geometry handling and update cadence consistent with the WDPA overlay workflow.

Usage

bf_load_ramsar(
  iso2c,
  cache_dir = NULL,
  force_refresh = FALSE,
  quiet = TRUE,
  require_opt_in = TRUE,
  opt_in = FALSE
)

Arguments

Details

The function is deliberately opt-in because Ramsar features are queried through the WDPA/Protected Planet service. By default, require_opt_in = TRUE and users must explicitly set opt_in = TRUE after confirming that their intended use complies with the relevant terms. Cached files are written as one GeoPackage per ISO3 country code.

Value

An sf polygon object in WGS84 longitude/latitude coordinates containing Ramsar wetland features for the requested countries. The returned object uses the standard biofetchR Ramsar schema: ramsar_id, a stable Ramsar or WDPA-derived site identifier; ramsar_name, the Ramsar site name; ramsar_iso3, the ISO3 country code associated with the feature; ramsar_desig_eng, the English designation label where available; and the active geometry column. If no valid country codes are supplied, or if no Ramsar features are returned for the requested countries, a zero-row sf object with the same standard columns is returned.

Data licensing

Ramsar records returned here are derived from the WDPA/Protected Planet service and remain subject to the relevant external licensing and attribution requirements. Do not redistribute downloaded geometries through biofetchR, package examples, tests, or derived cache folders.

See Also

Other overlay loaders: bf_load_wdpa()

Examples

if (interactive()) {
  ramsar_gb <- bf_load_ramsar(
    iso2c = "GB",
    cache_dir = file.path(tempdir(), "biofetchR_ramsar"),
    opt_in = TRUE,
    quiet = FALSE
  )

  ramsar_gb
}

Description

Downloads the RESOLVE terrestrial ecoregions dataset (2017 update), caches and extracts it, and returns an sf object in EPSG:4326 with consistent ID + label columns.

Usage

bf_load_resolve_ecoregions2017(
  cache_dir = NULL,
  url = "https://storage.googleapis.com/teow2016/Ecoregions2017.zip",
  force_refresh = FALSE,
  quiet = TRUE
)

Arguments

Details

Users do not need to pre-download shapefiles; biofetchR handles retrieval and caching.

Value

An sf polygon object containing RESOLVE 2017 terrestrial ecoregion features in WGS84 longitude/latitude coordinates. The returned object contains resolve_eco_id, a character ecoregion identifier; resolve_eco_name, a character ecoregion label; resolve_biome, the biome name where available; resolve_realm, the realm name where available; and the active geometry column. Each row represents one ecoregion polygon or multipolygon used for terrestrial contextual assignment.

See Also

Other terrestrial overlay loaders: bf_load_ne_urban_areas(), bf_load_teow(), bf_teow_cache_info(), bf_teow_clear_cache()

Examples

if (interactive()) {
  resolve <- bf_load_resolve_ecoregions2017(
    cache_dir = file.path(tempdir(), "biofetchR_resolve_ecoregions")
  )

  names(resolve)
}

Description

RESOLVE ecoregions provide a modern, consistent terrestrial biogeographic layer that is frequently used in biodiversity and macroecology workflows. We access the UNEP-WCMC ArcGIS service, download a country-bbox subset (by default), cache it as a GeoPackage, and return it as an sf object ready for point-in-polygon tagging.

Usage

bf_load_resolve2017(
  cache_dir,
  force_refresh = FALSE,
  clip_to_countries = TRUE,
  iso2c = NULL,
  quiet = TRUE,
  service_url = NULL,
  max_allowable_offset = 0.01,
  geometry_precision = 5,
  chunk_size = 200
)

Arguments

Details

Output columns:

• id_resolve2017 (stable ID)

• geoname_resolve2017 (ecoregion name)

• biome_resolve2017 (biome name if available)

• realm_resolve2017 (realm if available)

Value

An sf polygon object containing RESOLVE 2017 terrestrial ecoregion features in WGS84 longitude/latitude coordinates, or NULL when the provider query returns no readable features for the requested extent. When features are returned, the object contains id_resolve2017, a character ecoregion identifier; geoname_resolve2017, a character ecoregion name; biome_resolve2017, the biome name where available; realm_resolve2017, the realm name where available; and the active geometry column. Each row represents one ecoregion polygon or multipolygon used for assigning occurrence records to RESOLVE terrestrial ecoregion context. The returned subset is also cached locally as a GeoPackage for reuse.

Data source and attribution

Queries the UNEP-WCMC ArcGIS FeatureServer for the RESOLVE 2017 terrestrial ecoregions layer and caches the returned subset as a GeoPackage. biofetchR does not redistribute or own the service data. Cite the RESOLVE ecoregions data source/service and record the access date and query settings used.

See Also

Other Natural Earth and RESOLVE overlay loaders: bf_load_ne_admin1(), bf_load_ne_urban()

Description

Downloads + standardizes HydroRIVERS. If cache="disk", writes an RDS cache (and optionally a GPKG). If cache="memory", returns in-memory only. Filters (min_strahler, min_discharge_cms) are applied on read, not baked into cache.

Usage

bf_load_rivers(
  force_refresh = FALSE,
  quiet = TRUE,
  cache_dir = NULL,
  cache = c("disk", "memory"),
  cache_format = c("rds", "gpkg", "both"),
  regions = NULL,
  min_strahler = NULL,
  min_discharge_cms = NULL
)

Arguments

Value

An sf line object containing HydroRIVERS reaches in WGS84 longitude/latitude coordinates. The returned object includes canonical reach attributes hyriv_id, ord_stra, ord_clas, ord_flow, dis_av_cms, length_km and hybas_l12. Each row represents a river reach. If min_strahler or min_discharge_cms is supplied, the returned object contains only reaches retained by those filters.

See Also

Other freshwater overlay loaders: bf_load_basins(), bf_load_feow(), bf_load_lakes(), bf_name_rivers_osm()

Description

Downloads (once) and caches the WWF terrestrial ecoregions as an sf object. Prefer method = "mapme" if the mapme.biodiversity package is installed; otherwise, use method = "direct" with a source_url to the official TEOW ZIP.

Usage

bf_load_teow(
  cache_dir = NULL,
  method = c("auto", "mapme", "direct"),
  source_url = NULL,
  aoi = NULL,
  bbox = NULL,
  force_refresh = FALSE,
  simplify = FALSE,
  simplify_tolerance = 0.01,
  quiet = FALSE
)

Arguments

Details

The cached, normalized layer is written to ⁠<cache_dir>/teow/teow.gpkg⁠ with the ecoregion name exposed as geoname and the geometry column standardized to "geometry".

Value

An sf polygon object containing Terrestrial Ecoregions of the World features in WGS84 longitude/latitude coordinates. The returned object includes a standard geoname column and, where available, original ecoregion, biome and realm attributes. If aoi or bbox is supplied, the returned layer is clipped to that area; otherwise it contains the cached or freshly loaded global layer. The normalised layer is also cached locally as a GeoPackage for reuse.

Data access and attribution

TEOW is a third-party terrestrial ecoregion product. biofetchR downloads and caches it locally for user-side analysis only. Users should cite the original provider and check licence and redistribution terms before sharing derived products.

See Also

Other terrestrial overlay loaders: bf_load_ne_urban_areas(), bf_load_resolve_ecoregions2017(), bf_teow_cache_info(), bf_teow_clear_cache()

Examples

if (interactive()) {
  teow <- bf_load_teow(
    cache_dir = file.path(tempdir(), "biofetchR_teow"),
    quiet = TRUE
  )

  names(teow)
}

Description

Downloads, standardises and caches country-level WDPA protected-area polygons from the UNEP-WCMC/Protected Planet licensed ArcGIS service. biofetchR does not redistribute WDPA data; this function creates local user-side cache files that can be reused in later overlay runs.

Usage

bf_load_wdpa(
  iso2c,
  cache_dir = NULL,
  force_refresh = FALSE,
  quiet = TRUE,
  exclude_marine = TRUE,
  extra_where = NULL,
  require_opt_in = TRUE,
  opt_in = FALSE
)

Arguments

Details

The function is deliberately opt-in because WDPA data are licensed. By default, require_opt_in = TRUE and users must explicitly set opt_in = TRUE after confirming that their intended use complies with WDPA/Protected Planet terms. Cached files are written as one GeoPackage per ISO3 country code.

When exclude_marine = TRUE, features whose WDPA realm is exactly "Marine" are excluded from the service query. Mixed or terrestrial records are retained.

Value

An sf polygon object in WGS84 longitude/latitude coordinates containing WDPA protected-area features for the requested countries. The returned object uses the standard biofetchR WDPA schema: wdpa_id, a stable protected-area identifier; wdpa_name, the protected-area name; wdpa_desig_eng, the English designation label where available; wdpa_iucn_cat, the IUCN protected-area category where available; wdpa_iso3, the ISO3 country code associated with the feature; wdpa_area_km2, the reported GIS area in square kilometres where available; and the active geometry column. If no valid country codes are supplied, or if no features are returned for the requested countries, a zero-row sf object with the same standard columns is returned.

Data licensing

WDPA/Protected Planet data are subject to external licensing and attribution requirements. Do not redistribute downloaded WDPA geometries through biofetchR, package examples, tests, or derived cache folders.

See Also

Other overlay loaders: bf_load_ramsar()

Examples

if (interactive()) {
  wdpa_gb <- bf_load_wdpa(
    iso2c = "GB",
    cache_dir = file.path(tempdir(), "biofetchR_wdpa"),
    opt_in = TRUE,
    quiet = FALSE
  )

  wdpa_gb
}

Description

Converts a user-supplied overlay name or accepted alias to the canonical biofetchR overlay name used internally.

Usage

bf_marine_overlay_canonical(region_source)

Arguments

Details

Marine Regions product names can vary across data releases and package versions. biofetchR therefore keeps a registry of accepted aliases. This function performs the alias lookup and returns the canonical name used by the marine pipeline and overlay loader.

Value

A character vector of length one containing the canonical biofetchR marine overlay name corresponding to region_source. The returned value is one of the registered overlay identifiers used internally by the marine pipeline and by bf_load_marine_regions_overlay(). The function errors if region_source cannot be matched to a supported overlay or alias.

See Also

Other marine overlay loaders: bf_available_marine_overlays(), bf_load_marine_regions_overlay()

Examples

bf_marine_overlay_canonical("eez")
bf_marine_overlay_canonical("iho_seas")

Description

Annotate HydroRIVERS reaches with OSM river names

Usage

bf_name_rivers_osm(rivers, iso2c, max_snap_m = 500, quiet = TRUE)

Arguments

Value

An sf line object with the same river reaches as rivers, returned in WGS84 longitude/latitude coordinates, with an added character column river_name. The river_name column contains the nearest accepted OpenStreetMap waterway name within max_snap_m, or NA_character_ when no suitable named waterway is found. The output is used to add human-readable river labels to HydroRIVERS features.

See Also

Other freshwater overlay loaders: bf_load_basins(), bf_load_feow(), bf_load_lakes(), bf_load_rivers()

Description

Thin wrapper around bf_standardise_native_ranges() retained for readability in pipelines and tests.

Usage

bf_native_range_lookup(
  native_ranges,
  species_col = "species",
  origin_iso3_col = NULL,
  strategy = c("tiered", "union"),
  max_origins = 100L,
  quiet = FALSE
)

Arguments

Value

A tibble with the same structure as bf_standardise_native_ranges(): one row per standardised species-name key and columns describing species-level native-origin evidence, including native_name, native_name_key, native_origin_iso3, native_origin_flag, native_has_origin and native_sources_used. This function is a wrapper around bf_standardise_native_ranges() and returns the lookup table used by downstream native-status joins.

See Also

Other native-origin status helpers: bf_attach_native_status(), bf_filter_native(), bf_filter_non_native(), bf_native_status_summary(), bf_reconcile_griis_native_status(), bf_standardise_native_ranges()

Description

Summarise native-origin status columns

Usage

bf_native_status_summary(x)

Arguments

Value

A tibble summarising the native_status column in x. The output contains one row per native-status class and two columns: native_status, the character status label, and n, the number of rows assigned to that status. Rows are ordered from the most frequent status to the least frequent, then alphabetically by status label. The summary is intended for quick auditing of native-origin classification outcomes.

See Also

Other native-origin status helpers: bf_attach_native_status(), bf_filter_native(), bf_filter_non_native(), bf_native_range_lookup(), bf_reconcile_griis_native_status(), bf_standardise_native_ranges()

Description

Applies manual fixes first, then cleans names, removes obvious non-taxa, blocks genus-level/open/abbreviated names, and returns accepted, rejected, audit and summary tables.

Usage

bf_prepare_taxa_for_gbif(
  df,
  name_col = "species",
  iso2_col = NULL,
  manual_fixes = NULL,
  require_species_level = TRUE,
  deduplicate = TRUE
)

Arguments

Value

A named list with four elements: accepted, a tibble/data frame of cleaned taxon records retained for GBIF download workflows; rejected, a tibble/data frame of records removed before GBIF submission with rejection diagnostics; audit, a tibble recording raw names, fixed names, cleaned names, genus values, acceptance flags and rejection reasons for every input row; and summary, a one-row tibble with counts and percentages describing the preparation outcome. The output separates records suitable for download from records rejected as non-taxonomic, open-name or non-species-level candidates.

Description

Downloads or reuses the cached GRIIS country compendium, reads the selected table and converts it to biofetchR's standard GRIIS schema. This is the main entry point used by the pipeline origin-evidence gates when a pre-read GRIIS table is not supplied.

Usage

bf_read_griis(cache_dir = NULL, force_refresh = FALSE, quiet = FALSE)

Arguments

Value

A tibble returned by bf_standardise_griis() containing the standardised GRIIS country-compendium fields used by biofetchR. The output includes stable species-name keys, country identifiers, ISO2 and ISO3 codes, invasive-status evidence and optional taxonomic/status metadata. Each row represents a standardised GRIIS species-country evidence record.

Data source and attribution

This helper reads the external GRIIS country compendium after download/caching and standardises it for biofetchR joins. Users remain responsible for citing the GRIIS source, version/record and any associated data publication in downstream outputs.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_download_griis(), bf_filter_griis_invasive(), bf_find_griis_table(), bf_griis_lookup(), bf_standardise_griis(), bf_unpack_griis()

Examples

if (interactive()) {
  griis <- bf_read_griis(
    cache_dir = file.path(tempdir(), "biofetchR_griis"),
    quiet = FALSE
  )

  names(griis)
}

Description

Reconcile GRIIS and native-origin evidence

Usage

bf_reconcile_griis_native_status(x)

Arguments

Value

A tibble containing the input rows with one additional character column, biofetchr_origin_evidence_status. The added column summarises agreement, conflict or missingness between available GRIIS evidence and native-origin recipient evidence, with labels such as "griis_invasive_native_origin_supported", "griis_invasive_native_origin_conflict", "native_origin_non_native_only" and "origin_unknown". The returned table preserves the input columns and should be interpreted as an audit table for evidence consistency, not as an independent biological classification.

Interpretation

Reconciliation labels describe agreement or conflict between available GRIIS and native-origin evidence. They are audit labels, not independent biological proof of invasion status.

See Also

Other native-origin status helpers: bf_attach_native_status(), bf_filter_native(), bf_filter_non_native(), bf_native_range_lookup(), bf_native_status_summary(), bf_standardise_native_ranges()

Description

Resolve one taxon name against GBIF

Usage

bf_resolve_gbif_taxonomy(
  name,
  strict = FALSE,
  use_gbif_parse = TRUE,
  use_gbif_suggest = TRUE,
  use_genus_fallback = TRUE,
  use_worms_fallback = FALSE,
  manual_overrides = NULL,
  retries = 3,
  sleep_sec = 0.15,
  quiet = TRUE
)

Arguments

Value

A one-row tibble describing the taxonomy-resolution outcome for name. The output contains the original and cleaned names, the query name, GBIF usage keys, the taxon key selected for downloads, resolved scientific and canonical names, rank, status, match type, confidence, standard classification columns from kingdom to species, resolver provenance, taxon_match_status, any warning text, and logical flags for genus-level or non-taxonomic inputs. Unresolved or skipped names are returned in the same schema with missing key fields and diagnostic status values.

Description

Resolve a vector of taxon names against GBIF

Usage

bf_resolve_gbif_taxonomy_batch(
  names,
  cache_dir = NULL,
  cache_file = "bf_gbif_taxonomy_cache.rds",
  refresh_cache = FALSE,
  strict = FALSE,
  strict_taxonomy = FALSE,
  quiet = TRUE,
  ...
)

Arguments

Value

A tibble with one row per input name, preserving input order and using the same taxonomy-resolution columns returned by bf_resolve_gbif_taxonomy(). The output includes cleaned names, GBIF keys, resolved names, rank and classification fields, resolver provenance, diagnostic status columns and flags for genus-level or non-taxonomic inputs. When a cache is used, cached and newly resolved rows are combined into the same output schema.

Description

Constructs the direct Zenodo file URLs used by bf_download_sinas_resources(). The default record is the SInAS 3.1.1 record used by the biofetchR native-evidence workflow.

Usage

bf_sinas_default_urls(record_id = "18220953")

Arguments

Value

A named character vector of direct Zenodo file URLs used by the SInAS downloader. The vector contains four entries: main_csv, the URL for SInAS_3.1.1.csv; config_zip, the URL for All_Config_Files_SInAS_v3.1.1.zip, which contains AllLocations.xlsx; output_zip, the URL for All_Output_Files_SInAS_v3.1.1.zip, which contains SInAS_3.1.1_FullTaxaList.csv for the default record; and fulltaxa_csv, a legacy-style standalone FullTaxaList URL returned for completeness. The function only constructs URLs and does not download, cache, read or validate any SInAS files.

Data access

This function only constructs URLs. It does not download, cache, read or redistribute SInAS data.

See Also

Other SInAS resource helpers: bf_download_sinas_resources()

Examples

bf_sinas_default_urls()

Description

Converts a raw country-level GRIIS table into the stable column names used by biofetchR. The function identifies accepted/scientific name fields, country/ISO fields, invasive-status fields and optional taxonomic metadata using flexible column-name matching.

Usage

bf_standardise_griis(griis_raw)

Arguments

Details

The returned table includes both accepted-name and scientific-name join keys. Downstream lookup construction uses both keys so that records can match either the accepted GRIIS name or a reported scientific-name field.

This helper deliberately checks that the table resembles the country-level GRIIS compendium. If required country-level fields are missing, it stops rather than silently producing a species-only table with empty country or invasive-status evidence.

Value

A tibble with stable ⁠griis_*⁠ columns used by biofetchR lookup and origin-evidence workflows. The output includes griis_scientific_name, griis_accepted_name, griis_name_key, griis_scientific_name_key, griis_country, griis_iso2c, griis_iso3c and griis_is_invasive, plus optional occurrence, establishment and taxonomic metadata where available. Each row represents a standardised GRIIS species-country evidence record. The invasive-status fields should be interpreted as GRIIS evidence, not as proof of absence where no match exists.

Interpretation

Standardised columns are evidence fields derived from GRIIS records. They should be interpreted as GRIIS-listed status evidence, not as proof that a species is absent from countries where no match is found.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_download_griis(), bf_filter_griis_invasive(), bf_find_griis_table(), bf_griis_lookup(), bf_read_griis(), bf_unpack_griis()

Examples

raw <- data.frame(
  species = "Example species",
  scientificName = "Example species",
  countryCode_alpha2 = "GB",
  countryCode_alpha3 = "GBR",
  isInvasive = "yes",
  stringsAsFactors = FALSE
)
std <- bf_standardise_griis(raw)
names(std)

Description

Converts one or more native-origin ISO3 columns into a compact, one-row-per- species lookup table. This is the normal entry point for provider outputs from SInAS/GBIF/WoRMS helpers or for user-supplied native-range tables.

Usage

bf_standardise_native_ranges(
  native_raw,
  species_col = "species",
  origin_iso3_col = NULL,
  strategy = c("tiered", "union"),
  max_origins = 100L,
  quiet = FALSE
)

Arguments

Details

The output is species-level evidence only. Recipient-level native/non-native classification is performed by bf_attach_native_status(), which compares the recipient ISO3 code against the native-origin ISO3 set.

Value

A tibble with one row per standardised species-name key. The output contains native_name, the cleaned species label; native_name_key, the normalised name used for joins; native_origin_iso3, a semicolon-delimited character string of ISO3 native-origin country codes; native_origin_flag, a character flag indicating whether usable origin evidence was found; native_has_origin, a logical indicator of origin-evidence availability; and native_sources_used, a semicolon-delimited provenance field where source information is available. The table represents species-level native-origin evidence only; recipient-level native/non-native classification is performed by bf_attach_native_status().

See Also

Other native-origin status helpers: bf_attach_native_status(), bf_filter_native(), bf_filter_non_native(), bf_native_range_lookup(), bf_native_status_summary(), bf_reconcile_griis_native_status()

Description

Extract the genus component from a taxon name

Usage

bf_tax_extract_genus(x)

Arguments

Value

A character vector with the same length as x. Each element contains the extracted genus name from the corresponding cleaned taxon string, or NA_character_ when no plausible genus component can be identified. The output is used for genus-level diagnostics and fallback taxonomy matching.

Description

Detect genus-level or open-nomenclature names

Usage

bf_tax_is_genus_level(x)

Arguments

Value

A logical vector with the same length as x. Values are TRUE for names that appear to be genus-level, higher-level or open-nomenclature strings, including single-token genus names, sp./spp. names, cf./aff. names, groups, complexes or abbreviated epithets. Values are FALSE for names that are not flagged by these rules.

Flag genus-level, higher-level, or open-name taxonomic strings

Description

Flags common environmental variables, habitat descriptors, measurement names, and other strings that should not be submitted to taxonomy APIs.

Usage

bf_tax_looks_non_taxon(x)

Arguments

Value

A logical vector with the same length as x. Values are TRUE for missing values, placeholders, measurement-like strings, environmental variables or other inputs that are unlikely to be biological taxon names. Values are FALSE for strings that remain plausible taxonomic names after the conservative screening rules.

Detect strings that are unlikely to be biological taxon names

Description

Summarise taxonomy resolution outcomes

Usage

bf_taxonomic_summary(taxonomy_tbl)

Arguments

Value

A one-row tibble summarising taxonomy-resolution outcomes. The output contains n_input, n_matched, n_unresolved, n_non_taxon, n_higher_rank, pct_matched, resolved_by and match_types. These fields report the number of input rows, how many received usable GBIF taxon keys, how many were unresolved or skipped, and which resolver and match-type categories were present.

Description

Return cache path/info for TEOW

Usage

bf_teow_cache_info(cache_dir = NULL)

Arguments

Value

A named list describing the Terrestrial Ecoregions of the World cache. The list contains path, a character string giving the expected GeoPackage cache path; exists, a logical value indicating whether the cache file is present; size_bytes, a numeric file size in bytes or NA_real_ when the file is absent; and modified, a POSIXct modification time or NA when the file is absent. The values are intended for cache diagnostics and do not load the spatial layer itself.

See Also

Other terrestrial overlay loaders: bf_load_ne_urban_areas(), bf_load_resolve_ecoregions2017(), bf_load_teow(), bf_teow_clear_cache()

Description

Clear the cached TEOW dataset

Usage

bf_teow_clear_cache(cache_dir = NULL, ask = interactive())

Arguments

Value

Invisibly returns TRUE when the Terrestrial Ecoregions of the World cache directory does not exist or is successfully removed. Invisibly returns FALSE when deletion is cancelled after an interactive prompt. The function is called primarily for its side effect of removing cached TEOW files.

See Also

Other terrestrial overlay loaders: bf_load_ne_urban_areas(), bf_load_resolve_ecoregions2017(), bf_load_teow(), bf_teow_cache_info()

Description

Unpacks a downloaded GRIIS archive into a cache directory. This helper is kept for archive-style GRIIS sources, although the default biofetchR source is now a country-level CSV that can be read directly without unpacking.

Usage

bf_unpack_griis(
  archive_path,
  exdir = NULL,
  force_refresh = FALSE,
  quiet = FALSE
)

Arguments

Value

A character vector of length one giving the normalised path to the directory containing the unpacked GRIIS archive, using forward slashes. If the archive has already been unpacked and force_refresh = FALSE, the existing directory path is returned. The function is also called for the side effect of creating or refreshing the unpacked cache directory.

See Also

Other GRIIS origin-evidence helpers: bf_attach_griis_status(), bf_download_griis(), bf_filter_griis_invasive(), bf_find_griis_table(), bf_griis_lookup(), bf_read_griis(), bf_standardise_griis()

Examples

archive_root <- file.path(tempdir(), "biofetchR_griis_unpack_example")
unlink(archive_root, recursive = TRUE, force = TRUE)
dir.create(archive_root, recursive = TRUE, showWarnings = FALSE)

archive_src <- file.path(archive_root, "src")
dir.create(archive_src, recursive = TRUE, showWarnings = FALSE)

griis_file <- file.path(archive_src, "griis_country_compendium.csv")

write.csv(
  data.frame(species = "Example species"),
  griis_file,
  row.names = FALSE
)

archive_path <- file.path(archive_root, "griis_example.tar")

utils::tar(
  tarfile = archive_path,
  files = griis_file,
  tar = "internal"
)

unpacked <- bf_unpack_griis(
  archive_path = archive_path,
  exdir = file.path(archive_root, "unpacked"),
  quiet = TRUE
)

dir.exists(unpacked)

Description

Matches species names to GBIF taxon keys, retrieves checklist distribution records, keeps distribution rows with native-like establishment/status wording, and attempts to convert reported areas or country codes to ISO3.

Usage

bf_web_native_gbif(
  species,
  cache_dir = NULL,
  force_refresh = FALSE,
  sleep_sec = 0.25,
  user_agent = "biofetchR native-range web helper (academic use)",
  quiet = FALSE
)

Arguments

Value

A tibble with one row per retained native-like GBIF Species API distribution record. The output uses the standard long native-evidence schema: species, the requested species name; source, set to "GBIF"; accepted_name, the matched GBIF scientific or canonical name; source_taxon_id, the GBIF taxon key; raw_native_area, the source country, area, locality or location string; raw_status, the establishment or status text used for native-like screening; origin_iso3, the resolved ISO3 country code where available; evidence_type, usually "native_distribution"; and source_url, the GBIF API endpoint used. If no native-like records are retained, an empty tibble with the same columns is returned.

Data source and interpretation

This helper uses GBIF Species API checklist-distribution records, not GBIF occurrence downloads. Retained rows are evidence of native-like distribution language in the API response and should be audited before being treated as a definitive native range.

See Also

Other native-range web-source helpers: bf_available_native_web_sources(), bf_fetch_native_ranges_web(), bf_web_native_worms(), bf_write_native_web_outputs()

Examples

if (interactive()) {
  gbif_native <- bf_web_native_gbif(
    species = "Carcinus maenas",
    cache_dir = file.path(tempdir(), "biofetchR_native_web"),
    quiet = FALSE
  )

  gbif_native
}

Description

Resolves species names to valid AphiaIDs through the WoRMS REST API, retrieves Aphia distribution records, keeps native-like distribution/status rows, and attempts to map reported localities to ISO3 countries.

Usage

bf_web_native_worms(
  species,
  cache_dir = NULL,
  force_refresh = FALSE,
  sleep_sec = 0.25,
  marine_only = FALSE,
  user_agent = "biofetchR native-range web helper (academic use)",
  quiet = FALSE
)

Arguments

Value

A tibble with one row per retained native-like WoRMS Aphia distribution record. The output uses the standard long native-evidence schema: species, the requested species name; source, set to "WoRMS"; accepted_name, the valid or accepted WoRMS name; source_taxon_id, the AphiaID; raw_native_area, the source locality, area or geounit string; raw_status, the status, origin or establishment text used for native-like screening; origin_iso3, the resolved ISO3 country code where available; evidence_type, usually "native_distribution"; and source_url, the WoRMS REST endpoint used. If no native-like records are retained, an empty tibble with the same columns is returned.

Data source and interpretation

This helper uses WoRMS REST Aphia name and distribution endpoints. Retained rows are native-like distribution evidence and may remain unmapped when the source locality cannot be resolved to an ISO3 country code.

See Also

Other native-range web-source helpers: bf_available_native_web_sources(), bf_fetch_native_ranges_web(), bf_web_native_gbif(), bf_write_native_web_outputs()

Examples

if (interactive()) {
  worms_native <- bf_web_native_worms(
    species = "Carcinus maenas",
    cache_dir = file.path(tempdir(), "biofetchR_native_web"),
    quiet = FALSE
  )

  worms_native
}

Description

Writes the list returned by bf_fetch_native_ranges_web() to CSV files so the web-derived native-origin evidence can be audited and reused.

Usage

bf_write_native_web_outputs(x, output_dir, prefix = "native_web")

Arguments

Value

Invisibly returns a named character vector of file paths written to output_dir. The vector contains paths named long, species, unmapped and summary, corresponding to the CSV files written from the matching elements of x. The function is called primarily for its side effect of writing auditable native-web evidence tables to disk.

Audit role

Writing these outputs preserves the exact web-derived evidence used by a pipeline run, including unmapped source strings. This is useful for later manual checking and for reporting which sources contributed native-origin evidence.

See Also

Other native-range web-source helpers: bf_available_native_web_sources(), bf_fetch_native_ranges_web(), bf_web_native_gbif(), bf_web_native_worms()

Examples

native_web <- list(
  long = data.frame(
    species = "Example species",
    source = "example",
    accepted_name = "Example species",
    source_taxon_id = "example_id",
    raw_native_area = "Exampleland",
    raw_status = "native",
    origin_iso3 = "GBR",
    evidence_type = "native_distribution",
    source_url = NA_character_
  ),
  species = data.frame(
    species = "Example species",
    native_origin_iso3 = "GBR",
    native_sources_used = "example",
    native_web_unmapped_strings = NA_character_,
    native_web_n_records = 1L,
    native_has_origin = TRUE
  ),
  unmapped = data.frame(),
  summary = data.frame(
    n_species_input = 1L,
    n_species_with_origin = 1L,
    n_records_long = 1L,
    n_records_unmapped = 0L
  )
)

out_dir <- tempfile("native_web_outputs_")
paths <- bf_write_native_web_outputs(native_web, output_dir = out_dir)
names(paths)

Description

Check for NCBI Entrez API Key

Usage

check_entrez_key()

Value

Invisibly returns a logical value of length one. The value is TRUE when the ENTREZ_KEY environment variable is present and non-empty, and FALSE otherwise. The function is called primarily for its side effect of reporting whether an NCBI Entrez API key is available for optional taxonomy-related workflows.

Description

Query the GBIF occurrence-search API through rgbif::occ_search() and return a simple TRUE/FALSE flag indicating whether at least one coordinate-bearing record is available for a species. The helper is intended as a lightweight pre-check before running heavier GBIF download workflows.

Usage

check_gbif_presence(
  species,
  region_id = NULL,
  use_eez_for_marine = FALSE,
  verbose = FALSE
)

Arguments

Details

By default, region_id is passed to GBIF as an ISO2 country filter. When use_eez_for_marine = TRUE and the package-level is_marine_species() helper identifies the species as marine, the country predicate is skipped so the query behaves as a global marine pre-check.

This function only checks record availability. It does not submit or import a GBIF occurrence download and therefore does not generate a download DOI.

Value

A logical value of length one. The value is TRUE when the GBIF occurrence-search query returns at least one coordinate-bearing record for the supplied species and region settings. The value is FALSE when no matching coordinate-bearing record is returned or when the query fails. This result is an availability pre-check only and does not represent a GBIF occurrence download or download DOI.

GBIF data use

This helper uses GBIF's occurrence-search API for a quick availability check. Records used in analyses should still be cited through an appropriate GBIF download DOI, derived dataset, or dataset-level citation workflow.

See Also

Other GBIF helpers: get_taxon_key(), wait_and_import_gbif()

Examples

if (interactive()) {
  has_records <- check_gbif_presence(
    species = "Carcinus maenas"
  )

  has_records
}

Description

Submit one GBIF occurrence download per species without applying a GBIF country predicate. This backend is primarily used by the marine pipeline, where occurrences are first retrieved globally and then assigned to marine overlays such as EEZs, LMEs, MEOW ecoregions, IHO seas, FAO regions, or other package-managed marine polygons.

Usage

download_gbif_batch(
  batch = NULL,
  user,
  pwd,
  email,
  species = NULL,
  predicate_extra = list(),
  quiet = FALSE,
  ...
)

Arguments

Details

Each species name is resolved with rgbif::name_backbone() and submitted to GBIF using a conservative occurrence predicate requiring:

• the resolved GBIF taxonKey;

• hasCoordinate = TRUE;

• hasGeospatialIssue = FALSE;

• occurrenceStatus = "PRESENT".

Additional GBIF predicates can be appended through predicate_extra, allowing callers to add date, basis-of-record, dataset, licence or other GBIF filters without changing the backend.

Value

A named character vector of GBIF occurrence-download keys. Each value is the download key returned by GBIF for one successfully submitted species-level download, and each name is the corresponding submitted species name. The returned keys are used by downstream import helpers and should be retained in summaries or manifests as the link to GBIF download metadata and citation DOI(s). The function stops if no usable download key can be extracted for a submitted species.

GBIF data use and citation

This function submits live GBIF occurrence downloads and returns GBIF download keys. GBIF-mediated data are free to access, but users who use GBIF downloads in research, reporting or policy should cite the DOI generated for each GBIF download, or an appropriate derived dataset DOI where applicable. Individual records may also originate from datasets with their own licences and citation requirements. biofetchR does not redistribute GBIF data or replace GBIF's data-use and citation requirements.

Side effects

Submits live GBIF occurrence download jobs through rgbif::occ_download(). The function returns download keys only; it does not wait for, import, clean, thin, or spatially join downloaded occurrence records.

Errors

The function stops if no valid species names are supplied, if GBIF credentials are missing, if predicate_extra is not a list, if a species cannot be resolved to a GBIF usage key, or if GBIF does not return an extractable download key.

See Also

download_gbif_batch_gadm(), wait_and_import_gbif_safe()

Other GBIF download backends: download_gbif_batch_gadm(), wait_and_import_gbif_safe()

Examples

gbif_env <- c("GBIF_USER", "GBIF_PWD", "GBIF_EMAIL")

if (interactive() && all(nzchar(Sys.getenv(gbif_env)))) {
  keys <- download_gbif_batch(
    species = c("Ficopomatus enigmaticus", "Carcinus maenas"),
    user = Sys.getenv("GBIF_USER"),
    pwd = Sys.getenv("GBIF_PWD"),
    email = Sys.getenv("GBIF_EMAIL")
  )
}

Description

Submit one GBIF occurrence download per ISO2 country for a single species. This backend is used by the terrestrial/freshwater pipeline, where inputs are organised as species x country combinations and GBIF records should be restricted to recipient countries before spatial overlay assignment.

Usage

download_gbif_batch_gadm(species, iso2_codes, user, pwd, email)

Arguments

Details

The function resolves the species to a GBIF taxon key, then submits one download per country using the predicates:

• ⁠taxonKey = <resolved GBIF taxon key>⁠;

• hasCoordinate = TRUE;

• ⁠country = <ISO2 country code>⁠.

Download submission is retried up to three times per country. Successful submissions are returned as a named list, with names equal to the ISO2 country codes.

Value

A named list of GBIF occurrence-download keys, with one element for each ISO2 country code where download submission succeeds. List names are the submitted ISO2 country codes and values are the corresponding GBIF download keys. These keys are used by downstream import helpers and should be retained in workflow summaries or manifests as the link to GBIF download metadata and citation DOI(s). Returns NULL when no valid species or country input is supplied, when the species cannot be resolved to a GBIF taxon key, or when all country-level submissions fail.

GBIF data use and citation

This function submits live GBIF occurrence downloads and returns GBIF download keys. Users should retain those keys and cite the GBIF download DOI(s) for occurrence records used in research, reports or policy outputs. Because GBIF aggregates records from many data publishers, individual datasets may carry their own licence and attribution requirements. biofetchR does not redistribute GBIF records and does not replace those obligations.

Side effects

Submits live GBIF occurrence download jobs through rgbif::occ_download() and prints submission/retry messages through cli.

Notes

If a package-visible get_taxon_key() helper exists, it is used for GBIF name resolution. Otherwise the function falls back to rgbif::name_backbone() directly. Download-key extraction is delegated to .bf_extract_gbif_download_key() when available.

See Also

download_gbif_batch(), wait_and_import_gbif_safe()

Other GBIF download backends: download_gbif_batch(), wait_and_import_gbif_safe()

Examples

gbif_env <- c("GBIF_USER", "GBIF_PWD", "GBIF_EMAIL")

if (interactive() && all(nzchar(Sys.getenv(gbif_env)))) {
  keys <- download_gbif_batch_gadm(
    species = "Hydrocotyle ranunculoides",
    iso2_codes = c("GB", "IE"),
    user = Sys.getenv("GBIF_USER"),
    pwd = Sys.getenv("GBIF_PWD"),
    email = Sys.getenv("GBIF_EMAIL")
  )
}

Description

Loads or caches Exclusive Economic Zone (EEZ) polygons via mregions2, repairs invalid geometries where possible, harmonises common EEZ attribute names across Marine Regions releases, and joins each occurrence-point sf object in results_list to an EEZ polygon.

Usage

eez_join(results_list, use_planar = TRUE, eez_cache_file = NULL)

Arguments

Details

The function returns the same named list structure as the input and appends standardised EEZ metadata used by downstream native-status and marine-overlay workflows. When a point does not fall strictly within an EEZ polygon, the function attempts a nearest-feature fallback so that points lying close to polygon boundaries can still be assigned cautiously.

EEZ source attributes differ across Marine Regions releases. This helper uses case-insensitive matching to find common territory, sovereign and ISO-code fields, then derives best-effort ISO3 and ISO2 codes for downstream matching. If countrycode is installed, missing ISO codes are inferred from cleaned territory, sovereign or EEZ names where possible.

Value

A named list with the same names as results_list. Each element is an sf point object containing the original occurrence records plus standardised Exclusive Economic Zone attributes where a spatial match could be made. Added columns include geoname, mrgid, territory1, sovereign1, iso3_best and iso2_best. These columns identify the matched marine region and provide best-effort country codes for downstream filtering, summarisation and export. Records that cannot be assigned retain the input geometry and receive missing values in the added fields.

Data access and attribution

EEZ polygons are retrieved from Marine Regions through mregions2 and cached locally. biofetchR does not redistribute Marine Regions data. Users should cite Marine Regions and check the applicable data licence and attribution requirements for the version used in their analysis.

See Also

Other marine overlay joins: overlay_join()

Examples

if (interactive()) {
  pts <- data.frame(
    decimalLongitude = c(-5, 10),
    decimalLatitude = c(50, 35)
  )

  pts_sf <- sf::st_as_sf(
    pts,
    coords = c("decimalLongitude", "decimalLatitude"),
    crs = 4326,
    remove = FALSE
  )

  joined <- eez_join(
    list("Carcinus maenas" = pts_sf),
    eez_cache_file = file.path(tempdir(), "biofetchR_eez_cache.gpkg")
  )

  names(joined[["Carcinus maenas"]])
}

Description

Normalise a provider-specific origin, establishment or alien-status column to biofetchR's canonical status classes and optionally filter rows to a supported preset.

Usage

filter_by_status(
  data,
  status_col = "alien_status",
  preset = "all",
  values = NULL,
  normalize_only = FALSE,
  verbose = TRUE
)

Arguments

Details

The function adds or updates a status_norm column using the internal status mapper. When normalize_only = TRUE, no rows are removed. Otherwise, rows are retained when status_norm belongs to the classes resolved from preset or values.

This helper is deliberately tolerant of missing status columns. If status_col is absent, the input data are returned unchanged. A warning is emitted only when a real filtering request was made.

Value

A data frame or tibble of the same general type as data, with a status_norm column added or updated when status_col is present. status_norm contains canonical biofetchR status classes such as "native", "introduced", "naturalized", "invasive", "cryptogenic", "managed" or "unknown". If normalize_only = TRUE, all input rows are returned with the normalised status column. Otherwise, rows are filtered to the classes selected by preset or values. If status_col is absent, the input data are returned unchanged.

See Also

Other status helpers: list_status_presets()

Examples

x <- data.frame(
  species = c("Species a", "Species b", "Species c"),
  alien_status = c("native", "introduced", "cryptogenic")
)

filter_by_status(x, preset = "non_native", verbose = FALSE)
filter_by_status(x, normalize_only = TRUE, verbose = FALSE)

Description

Join point records to GADM polygons and append one set of GADM identifier/name columns to each point. The join is intentionally one-to-one: if a point intersects multiple polygons, only the first polygon hit is used, which avoids accidental row multiplication during GBIF export.

Usage

gadm_join(
  pts_sf,
  gadm,
  level = 1,
  id_out = "id_gadm",
  name_out = "name_gadm",
  geoname_out = "geoname_gadm",
  quiet = TRUE
)

Arguments

Details

gadm_join() accepts either the named list returned by load_gadm() or a single pre-bound GADM sf polygon layer. Both points and polygons are transformed to WGS84 where possible before the intersection test. When no valid polygon layer is available, the output columns are still created and filled with NA_character_, keeping the downstream schema stable.

Value

An sf point object with the same rows as the input pts_sf and with three GADM assignment columns appended. The column named by id_out contains the matched GADM identifier, the column named by name_out contains the matched administrative-unit name, and the column named by geoname_out contains the human-readable GADM label used by downstream exports. Points with no polygon match receive NA_character_ in the added columns. The function performs a one-to-one assignment and does not duplicate point rows when polygons overlap.

See Also

Other GADM spatial helpers: load_all_gadm(), load_gadm()

Examples

if (requireNamespace("sf", quietly = TRUE)) {
  pts <- sf::st_as_sf(
    data.frame(
      species = "Example species",
      decimalLongitude = -5.93,
      decimalLatitude = 54.60
    ),
    coords = c("decimalLongitude", "decimalLatitude"),
    crs = 4326,
    remove = FALSE
  )

  poly <- sf::st_sf(
    gid_1 = "GBR.1_1",
    name_1 = "Example region",
    GID = "GBR.1_1",
    GADM_name = "Example region",
    geometry = sf::st_sfc(
      sf::st_polygon(list(rbind(
        c(-7, 53),
        c(-4, 53),
        c(-4, 56),
        c(-7, 56),
        c(-7, 53)
      ))),
      crs = 4326
    )
  )

  joined <- gadm_join(pts, poly, level = 1)
  names(joined)
}

Description

Resolve a supplied name against the GBIF backbone taxonomy using rgbif::name_backbone() and return the matched usageKey when available.

Usage

get_taxon_key(species, verbose = FALSE)