VasGBIF

Fast and Easy Compilation of Vascular Plants Occurrence Records from GBIF

Introduction

Mapping plant distributions is fundamental to understanding biodiversity patterns, accurate distribution data and such information is necessary for researching plant diversity. Global Biodiversity Information Facility, known as GBIF, is a large repository for tracheophyte occurrence records worldwide.

GBIF hosts over 500 million occurrence records of tracheophyte (vascular plants). To deal with them, researchers typically use a suite of packages and scrips, consuming lots of workflows and time, posing significant challenges.

Generally, rgbif, TNRS, CoordinateCleaner, bdc, plantR, NSR and GVS helps a lot. However, for million records datasets, current methods incur substantial computational overhead through manual chaining of disparate packages, necessitating high-performance infrastructure despite advancing computational capabilities.

To rectify this situation, we introduce VasGBIF, an efficient R package that unifies taxonomic resolution, spatial validation, and botanical region annotation within a high-performance framework.

With optimized C/CPP-based dependencies, practical vectorized programming methods leveraging the SIMD instruction sets of modern CPUs and parallelization, VasGBIF compiles one million GBIF occurrence records within 15 minutes.

In a word, VasGBIF resolves challenges in reproducibility, scalability, and spatial-taxonomic integrity without increasing adoption barriers for biodiversity researchers.

Installation

One can install VasGBIF by any ways below:

1. install VasGBIF via official CRAN (Recommend)

install.packages("VasGBIF")

2. install VasGBIF via GitHub (Latest version)

if (!require(pak)) install.packages('pak')
pak::pak('wyx619/VasGBIF@master')

3. install via remotes

if (!require(git2r)) install.packages('git2r')
if (!require(remotes)) install.packages('remotes')
remotes::install_git('https://gh-proxy.org/https://github.com/wyx619/VasGBIF',build_vignettes = T,git = 'git2r',upgrade = 'never')

Wikis & Manuals

Online wikis and manuals are available on https://wyx619.github.io/VasGBIF/.

Typical Workflow

Architecture of VasGBIF. Each step progressively filters records through taxonomic, quality, coordinate and native status checks. After all, more than half of the initial records are retained as high-quality and non-redundant data.

VasGBIF provides a reproducible, vascular plants optimized, and computationally efficient framework for transforming GBIF records into analysis-ready datasets. The package functions are organized into four modules and eight steps.

Data Preparation Module

1. 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 — all diagnostic flags are preserved for later quality scoring.

2. Extract GBIF Issues (extract_gbif_issues): Expands the raw pipe-separated issue column into one logical indicator column per GBIF issue code, plus a companion summary ranking issues by how many records they flag.

3. 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.

Filter & Clean Module

4. Customized Filter (customized_filter): Joins the imported records with the resolved taxonomy and the parsed issue flags, then applies the enabled filter rules (country code, coordinate uncertainty, GBIF issue count, event date, collector and identifier fields) to retain only high-quality records. Every rule is independently toggleable, and each step is recorded in a per-rule audit table.

5. Clean Coordinates (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.

Native Status Detection Module

6. Detect Native Status (detect_native_coord + 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 and failed with clean_coordinates() are matched through their country code by detect_native_country().

Plot & Export Module

7. Map Visualization (map_records): Renders the refined records on an interactive map via mapview, with geohash-based decluttering to reduce visual overlap. Records are colour-coded by native status, and multiple basemap layers are supported (OpenStreetMap, Esri World Imagery, and others).

8. Export Records (export_records): Writes the classified records to disk as two gzip-compressed CSV files: all usable records and the native subset.

Focused exclusively on GBIF plant occurrence records, VasGBIF can compile one million records within 15 minutes without high memory usage.

Overall, VasGBIF integrates these components into a unified, automated workflow that enhances data standardization, accuracy, and usability, which enables robust, reproducible, and scalable compiling of GBIF tracheophyte records for advanced biodiversity research.

Key Points

Precise native-status detection

detect_native_coord() and detect_native_country() are the analytical core of VasGBIF. Together they assign a native, introduced, extinct, location_doubtful, or unknown classification to every occurrence by matching the record's identification and position against authoritative WCVP distribution data (the internal Distributions dataset) organised by WGSRPD Level 3 areas. Classification is split across two functions so that the most precise available evidence always wins:

• Spatial classification (detect_native_coord()). Records with validated coordinates are overlaid on the WGSRPD Level 3 polygon map with terra::extract() — a single vectorised call that assigns every point its area code in compiled code. Each area code is looked up in a distribution table classified from the WCVP flags (introduced, extinct, location_doubtful) with a fixed priority: location_doubtful > introduced > extinct > native > unknown. Records falling in several areas receive the most preferred status, never an arbitrary one.
• Country-code classification (detect_native_country()). Records without coordinates are matched through countryCode mapped to WGSRPD Level 3 areas by the Level3maping table. No geometry is used, so this pass is nearly free.

The system stays precise without sacrificing speed: coastal points just outside a polygon are still matched through a geodesic buffer (buffer_km, applied in metres so its meaning is identical at every latitude), with buffered hits always ranked below exact ones; hybrid markers are normalised so Alnus x pubescens matches the Alnus × pubescens in the distributions; and every classification records how it was obtained in native_status_source, making the whole decision chain auditable.

Flexible and customized filter

customized_filter() turns the raw download into an analysis-ready occurrence table. It joins the three preceding outputs (occ_import, taxa_checked, gbif_issue) into one table, then walks a user-selected set of quality rules — one vectorised data.table pass per rule — with every step audited:

• Fluent rule control. Each rule is an independently toggleable argument. Three rules are on by default (countryCode, coordinateUncertainty ≤ 10,000 m, gbif_issues_max ≤ 5); date, identifiedBy, and recordedBy are opt-in, so no information is discarded without an explicit choice. Numeric thresholds share one uniform "off" convention — NULL, NA, or '' — so any rule can be disabled without restructuring the call.
• Auditable pipeline. Every step, including the taxon_resolved join, is logged in the returned summary table (rule, dropped, remaining), making the effect of each decision visible and reproducible.
• Careful collector and identifier detection. The identifiedBy and recordedBy rules remove only values that contain no named person, using a curated multilingual keyword list and whole-value patterns; name separators protect values that mix a keyword with a real name, and word-boundary matching keeps CJK keywords from splitting genuine names — deliberately conservative so that real records are never dropped.

Minimal Complete Example

The following code demonstrates the complete VasGBIF workflow from data import to records mapping:

library(VasGBIF)

# Import records (built-in example, or use your own ZIP)
gbif_file <- system.file(
  "extdata", "0003386-260721160103020.zip",
  package = "VasGBIF"
)

occ_import <- import_records(path = gbif_file)

# Parse GBIF issue flags
gbif_issue <- extract_gbif_issues(occ_import)

# Resolve taxon names by TNRS
taxa_checked <- check_taxon(occ_import = occ_import, accuracy = 0.85)

# Filter records by quality rules
filtered <- customized_filter(
  occ_import = occ_import,
  taxa_checked = taxa_checked,
  gbif_issue = gbif_issue
)

# Validate coordinates
cleaned_coordinates <- clean_coordinates(
  customized_filtered = filtered,
  threads = 4
)

# Annotate native status
native_detected_coord <- detect_native_coord(
  cleaned_coordinates = cleaned_coordinates
)
native_detected_country <- detect_native_country(
  cleaned_coordinates = cleaned_coordinates
)

# Visualise on an interactive map
map_records(
  native_detected_coord = native_detected_coord,
  precision = 3,
  cex = 3
)

# Export records
export_records(
  native_detected_coord = native_detected_coord,
  export_path = getwd()
)

Performance

VasGBIF achieves outstanding performance through specific technical architectures:

• C/C++ Backend Integration: core operations are delegated to data.table, stringi, and terra, implemented in C/C++ that bypass R's per-iteration interpretive overhead
• Vectorization Over Explicit Loops: issue-flag detection in extract_gbif_issues() and native-status lookups in detect_native_coord() and detect_native_country() process entire columns in compiled calls rather than iterating in R
• SIMD Exploitation: vectorized routines in stringi and terra::extract() enable compiler-level SIMD auto-vectorization (AVX, AVX-512)
• Memory-Efficient Design: in-place modification (:=, set()) avoids intermediate copies
• Selective Parallelization: clean_coordinates() partitions the dataset into chunks and distributes CoordinateCleaner validation across workers via foreach and doParallel — vectorized processing within chunks, parallel execution across chunks

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

Reference

Appelhans, Tim, Florian Detsch, Christoph Reudenbach, and Stefan Woellauer. 2023. “Mapview: Interactive Viewing of Spatial Data in r.” https://CRAN.R-project.org/package=mapview.

Boyle, Brad, Nicole Hopkins, Zhenyuan Lu, Juan Antonio Raygoza Garay, Dmitry Mozzherin, Tony Rees, Naim Matasci, et al. 2013. “The Taxonomic Name Resolution Service: An Online Tool for Automated Standardization of Plant Names.” BMC Bioinformatics 14 (1): 16. https://doi.org/10.1186/1471-2105-14-16.

Chirico, Michael. 2023. “geohashTools: Tools for Working with Geohashes.” https://CRAN.R-project.org/package=geohashTools.

De Melo, Pablo Hendrigo Alves, Nadia Bystriakova, Eve Lucas, and Alexandre K. Monro. 2024. “A New R Package to Parse Plant Species Occurrence Records into Unique Collection Events Efficiently Reduces Data Redundancy.” Scientific Reports 14 (1): 5450. https://doi.org/10.1038/s41598-024-56158-3.

Vilela, Bruno, and Fabricio Villalobos. 2015. “letsR: A New R Package for Data Handling and Analysis in Macroecology.” Edited by Timothée Poisot. Methods in Ecology and Evolution 6 (10): 1229–34. https://doi.org/10.1111/2041-210x.12401.

Zizka, Alexander, Daniele Silvestro, Tobias Andermann, Josué Azevedo, Camila Duarte Ritter, Daniel Edler, Harith Farooq, et al. 2019. “CoordinateCleaner : Standardized Cleaning of Occurrence Records from Biological Collection Databases.” Edited by Tiago Quental. Methods in Ecology and Evolution 10 (5): 744–51. https://doi.org/10.1111/2041-210X.13152.

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