Example

Overview

VasGBIF provides a reproducible, tracheophyte-optimized, and computationally efficient framework for transforming GBIF records into analysis-ready datasets. The package functions are organized into 8 steps. This basic example demonstrates the complete workflow using the built-in example dataset.

Each step below progressively filters records through taxonomic, quality, and coordinate checks, so the dataset shrinks from the raw download to a high-quality, analysis-ready set.

library(VasGBIF)
library(data.table)
VasGBIF_summary <- list()

Import Records

import_records() reads a GBIF occurrence download ZIP (‘SIMPLE_CSV’ or Darwin Core Archive), extracts the occurrence table, and returns an "import" data.table of the fields required by the workflow. No records are filtered at this stage — the raw issue column is preserved for the next step.

The built-in example dataset is a GBIF download of Medicago sativa (preserved specimens with coordinates, obtained 23 July 2026): https://doi.org/10.15468/dl.nt5exp.

gbif_file <- system.file(
  "extdata", "0003386-260721160103020.zip",
  package = "VasGBIF"
)
occ_import <- import_records(path = gbif_file)
VasGBIF_summary$initial_records <- nrow(occ_import)
VasGBIF_summary$initial_taxa <- uniqueN(occ_import$scientificName)
print(occ_import)

The returned "import" object is a data.table with the GBIF fields used by the workflow (gbifID coerced to character, plus the raw issue column).

Check Taxon Name

check_taxon() submits species- and infraspecific-rank names to the Taxonomic Name Resolution Service (TNRS; Boyle et al. 2013) for resolution against the World Checklist of Vascular Plants (WCVP) or World Flora Online (WFO). Synonyms are resolved to accepted names; records that fail the match-score threshold or lack an accepted/synonym status are excluded from the downstream table and reported in the summary for manual review.

taxa_checked <- check_taxon(occ_import = occ_import, accuracy = 0.85)
VasGBIF_summary$after_taxon_resolved <- nrow(taxa_checked$occ_taxa_checked)
VasGBIF_summary$final_taxa <- uniqueN(taxa_checked$occ_taxa_checked$Accepted_name)
print(taxa_checked)

The occ_taxa object contains:

occ_taxa_checked: records with resolved taxonomy
summary: one row per submitted name, for reviewing match quality
runtime: execution time

Customized Filter

customized_filter() joins the imported records with the resolved taxonomy and the parsed issue flags, then applies the enabled filter rules to retain only high-quality records. By default the countryCode, coordinateUncertainty (<= 10,000 m), and gbif_issues_max (<= 5) rules are enabled; date, identifiedBy, and recordedBy are opt-in. Every step is recorded in the per-rule summary table.

filtered <- customized_filter(
  occ_import = occ_import,
  taxa_checked = taxa_checked
)
VasGBIF_summary$after_customized_filter <- nrow(filtered$occ_filtered)
print(filtered)

The customFiltered object contains:

occ_filtered: the filtered occurrence table
occ_marked: the records failed customized quality rules
summary: per-rule rule, dropped, and remaining counts

Clean Coordinates

par_clean_coordinates() validates coordinates with CoordinateCleaner (Zizka et al. 2019) to flag spatial errors such as centroids, capitals, marine coordinates, and zero coordinates, splitting records into cleaned and problematic tables. Validation is parallelized across user-specified threads.

cleaned_coordinates <- par_clean_coordinates(
  input = filtered$occ_filtered,
  species = 'Accepted_name_id',
  latitude = 'decimalLatitude',
  longitude = 'decimalLongitude',
  threads = 8,tests = c("capitals", "centroids", "equal", "gbif", "institutions", "outliers", "seas", "zeros"))
VasGBIF_summary$cleaned <- nrow(cleaned_coordinates$CoordinateCleaned)
VasGBIF_summary$problematic <- nrow(cleaned_coordinates$CoordinateProblematic)
print(cleaned_coordinates)

The CoordinateRefined object contains:

CoordinateCleaned: records with valid coordinates
CoordinateProblematic: records failing one or more CoordinateCleaner tests (including those lack coordinates)
runtime: execution time

Detect Native Status

detect_native_coord() and detect_native_country() match each record against WCVP distribution data (the internal Distributions dataset) via WGSRPD Level 3 areas to classify it as native, introduced, extinct, location_doubtful, or unknown. Records with validated coordinates are matched spatially by detect_native_coord(); records without coordinates or failed with cleaned_coordinates() are matched through their country code by detect_native_country(). Every classification records how it was obtained in native_status_source.

native_detected_coord <- detect_native_coord(
  input = cleaned_coordinates$CoordinateCleaned,
  species = 'Accepted_name',
  latitude = 'decimalLatitude',
  longitude = 'decimalLongitude', buffer_km = 10, buffer_chunk_size = 2000)
native_detected_country <- detect_native_country(
  input = cleaned_coordinates$CoordinateProblematic,
  country = 'countryCode',
  species = 'Accepted_name')
native_detected <- rbind(
  native_detected_coord,
  native_detected_country[is.na(decimalLatitude) | is.na(decimalLongitude),],
  use.names = TRUE,
  fill = TRUE
)
VasGBIF_summary$native <- native_detected[native_status == "native", .N]
VasGBIF_summary$introduced <- native_detected[native_status == "introduced", .N]
VasGBIF_summary$extinct <- native_detected[native_status == "extinct", .N]
VasGBIF_summary$location_doubtful <- native_detected[
  native_status == "location_doubtful", .N
]
VasGBIF_summary$unknown <- native_detected[native_status == "unknown", .N]
print(native_detected)

The nativeDetected objects are data.tables keyed by gbifID. Each retains every column of the input records and appends LEVEL3_COD, native_status, native_status_source, and buffered. The spatial result (native_detected_coord) carries coordinates for every record and can be passed straight to export_records() and map_records() without joining back to cleaned_coordinates.

Map Visualiztion

map_records() renders the records on an interactive map via mapview, with geohash-based decluttering and colour-coding by native status.

map_records(
  native_detected_coord = native_detected_coord,
  precision = 3,
  cex = 3
)

Export Records

export_records() writes the classified records to disk as two gzip-compressed CSV files:

all_records.csv.gz: all classified records with validated coordinates, with their native status
native_records.csv.gz: the subset classified as native

export_records(
  native_detected_coord = native_detected_coord,
  native_detected_country = native_detected_country,
  export_path = getwd()
)

Summary

The summary statistics provide a quantitative overview of data reduction through the pipeline:

VasGBIF_summary |>
  as.data.frame() |>
  t()

Statistic	Description
`initial_records`	Total GBIF occurrence records imported
`initial_taxa`	Unique scientific names before resolution
`after_taxon_resolved`	Records retained after TNRS resolution (score and status thresholds)
`after_customized_filter`	Records retained after the quality filter rules
`cleaned`	Records with valid coordinates after CoordinateCleaner
`problematic`	Records failing one or more coordinate tests
`native`	Records classified as native
`introduced`	Records classified as introduced
`extinct`	Records classified as extinct
`location_doubtful`	Records classified as location_doubtful
`unknown`	Records with no usable distribution evidence
`final_taxa`	Unique accepted taxon names in the final dataset

The workflow progressively filters the dataset through taxonomic resolution, quality rules, and coordinate validation. The drop from initial_records to after_customized_filter reflects unresolved names and records failing the quality rules; the drop from after_customized_filter to cleaned reflects records that failed the coordinate tests being set aside (records without coordinates are not carried by clean_coordinates()); and the transition from initial_taxa to final_taxa reflects taxonomic resolution.

Performance

VasGBIF achieves its speed through:

C/C++ backends: core operations delegated to data.table, stringi, and terra
Vectorisation: issue-flag detection in extract_issues() and native-status lookups in detect_native_coord() and detect_native_country() process entire columns in compiled calls
Memory-efficient design: in-place modification (:=, set()) avoids unnecessary copies
Selective parallelisation: par_clean_coordinates() distributes CoordinateCleaner validation across threads

On a standard laptop, VasGBIF compiles one million occurrence records within 15 minutes.

References

GBIF.org (23 July 2026) GBIF Occurrence Download https://doi.org/10.15468/dl.nt5exp

Yuxuan Wang

2026-10-11