Introduction

Curated biological databases are critical to research because they consolidate observations, provide consistent data structures, and make large bodies of evidence computable [1]. In biodiversity science, the value of such infrastructure is especially clear: DNA barcode records are most informative when sequences are connected to specimen metadata, taxonomic interpretation, and collection context, allowing results to be revisited as names change, reference libraries expand, and sampling gaps are filled. DNA barcoding has accordingly become a practical, scalable method for specimen identification and biodiversity monitoring with applications that now extend across ecological networks, conservation, and broad-scale assessments [2,3].

The Barcode of Life Data Systems (BOLD) was built to support this lifecycle. Beyond being a repository, BOLD functions as a web workbench for assembling, validating, analyzing, and publishing DNA barcode data under controlled access [4]. It enables collaborative data assembly and curation within permissioned projects and includes publication workflows that create the durable datasets associated with citable DOIs. Critically, much of the scientific work occurs before release: records are iteratively cleaned, reconciled, and reviewed while they remain private within a project before being packaged into datasets suitable for publication.

While BOLD provides API access, most existing client tools such as ‘bold’ and ‘BOLDigger’ are designed for accessing and working with public data; they lack built-in support for authenticated access to private, pre-publication data into reproducible analytical workflows [5,6]. This limits a common need in barcode research: the ability to run scripted, scalable, organization-specific pipelines for curation and analysis prior to dataset publication. Such pipelines are increasingly important for teams and research networks that must harmonize metadata across contributors and labs, perform targeted diagnostics, and generate publication-ready summaries/exports that accompany dataset release and aid manuscript preparation [7,8].

Here we present BOLDconnectR, an R package that provides access to public records and authenticated, permission-respecting access to private records. BOLDconnectR retrieves records in a structured format based on BOLD’s core data model (https://github.com/boldsystems-central/BCDM) and performs automated transformation into R objects for sequence, spatial, and biodiversity analyses. By doing so, it extends BOLD’s interactive workbench into the R ecosystem, enabling custom pipelines.

Implementation and overview

BOLDconnectR is implemented in R (≥4.0) and distributed through CRAN and GitHub (https://github.com/boldsystems-central/BOLDconnectR). The package is intentionally compact, focusing on a small number of operations that recur across barcode projects: selecting candidate records, retrieving them, transforming them into analysis-ready objects, and exporting results for reuse. This design reflects the practical lifecycle in BOLD.

Access to authorized private records is enabled through token-based authentication while public records remain accessible without authentication. Tokens are generated by users through their BOLD profile and are designed to rotate periodically. Consequently, scripts should be written with plans to refresh tokens rather than embed long-lived credentials, reducing the risk of inadvertent dissemination through shared code, notebooks, or logs. Users incorporate a current token via bold.apikey(), after which retrieval and search functions operate on both public data and private records within the user’s authorization scope.

Retrieved records are returned in the Barcode Core Data Model (BCDM), preserving the links between sequences and the specimen metadata, taxonomy, identifiers, and geography. From this representation, BOLDconnectR performs transformation to the input structures required for downstream analyses in R (Fig 1 ‘Auto Conversion’). Importantly, the package provides translations to three widely used analytical ecosystems: ape [9] (sequence handling and phylogenetic workflows), vegan [10] (biodiversity measures and community summaries), and sf [11] (spatial representations and mapping). These packages are among the most broadly adopted tools for analysis of DNA and biodiversity data in R, and BOLDconnectR facilitates their use by converting BOLD records into the specific object classes required by each analysis step based on user-provided parameters.

Download:

• PNG
  larger image
• TIFF
  original image

Fig 1. High-level overview of the functionality of BOLDconnectR.

The package retrieves data in the BCDM format via token-authenticated APIs (https://boldsystems.org/data/api/), automatically formatting it for downstream analysis. Users can also export datasets in different formats to use within custom pipelines or third-party analytical workflows.

https://doi.org/10.1371/journal.pone.0355496.g001

Functions are organized into four groups. Search functions enable the selection of candidate records based on taxonomy, geography, institution, marker, and collection date, returning identifiers for subsequent record retrieval, with bold.public.search (using the portal API) targeting publicly available data and bold.full.search (using the Data API search) extending searches to include both public and authorized private records (Fig 1 ‘Search’). Retrieval functions download complete records based on identifiers, BINs, or dataset/project codes, with optional filters to refine the returned set (using Data API retrieve). The download function makes requests in batches to avoid straining BOLD servers. After downloading, analysis helper functions provide sequence alignment, distance calculations, biodiversity measures, and mapping via calls to ape, vegan, and sf (and associated dependencies) (Fig 1 ‘Phylogenies’, ’Biodiversity Measures’, ‘Mapping’). Export functions write BCDM and derived products to standard formats (CSV/TSV/FASTA), including parameters to customize FASTA headers assembled from selected record fields (Fig 1 ‘Export’).

BOLDconnectR has been evaluated against two public BOLD datasets spanning approximately 10³ (n = 847; DS-LONO2 – [12]) – 10⁴ (n = 9087; DS-SPHD2401- [13]) records. The package is under active development, and future work will aim to extend its functionality to support additional workflows as BOLD evolves and as community needs emerge. Planned extensions will emphasize publication oriented pipeline components that support dataset preparation while enabling analyses on private data.

Conclusion

BOLD provides a secure, collaborative workbench for assembling, curating, analyzing, and publishing DNA barcode data within private projects. BOLDconnectR complements this environment by enabling permissioned programmatic access to BOLD records in R while preserving structured links among sequences, specimens, taxonomy, and geography. By automating conversion to formats used by widely adopted analytical tools it reduces data handling overhead. The package bridges an important gap by providing the first programmatic interface to access and analyze both public and permissioned Barcode data on BOLD. The package is under active development, with the aim of expanding support for additional workflows and interoperability as BOLD and community needs evolve.

Acknowledgments

We thank Catherine Wei and Chris Ho for helpful discussions.