A simple workflow using BOLDconnectR

Retrieval and Analysis of BOLD Data for the Fairy Shrimp Genus Streptocephalus (Crustacea: Anostraca)

The following vignette presents a workflow to demonstrate the main functionality of the BOLDconnectR package (i.e., search, fetch and analyze).

Specifically, the workflow will show:

  1. Searching and fetching all public Streptocephlaus records available on BOLD in the BCDM format.
  2. Obtaining a concise summary of the downloaded data.
  3. Visualizing their occurrence distribution.
  4. Aligning the COI-5P sequences using muscle and visualizing the resulting NJ tree.
  5. Calculating BIN richness estimates and multisite beta diversity measure between different countries.

BOLDconnectR can be installed either by install.packages (for a stable CRAN version) or the devtools package (for the development version from GitHub)

Installation and Import

Suggested packages

The sequence alignment and NJ tree functions require additional Bioconductor based packages to be installed and imported.

API key

bold.fetch() requires an API key to retrieve the BCDM data.

Please note

The example dataset test.data2 is used here for demonstrating the BOLDconnectR functionality due to the API key requirement for downloading data. The dataset represents a snapshot of public BOLD records obtained from the BOLD public data package released on June 30, 2026 (https://doi.org/10.5883/DP-BOLD_Public.30-Jun-2026). When reproducing this workflow at a later date using an API key, the query may return a different number of records because the underlying BOLD database is continuously updated.

1. Searching and fetching

bold.public.search() is used to retrieve public record IDs. bold.full.search can also be used instead in cases where user has private data stored. The ids returned using the bold.public.search are used in the bold.fetch to get the BCDM data. Here the search is also filtered based on the amplicon basepair number (bold.fetch not used here as it requires an API key. A test dataset test.data2 used instead).

# Search
data_ids <- bold.public.search(taxonomy = list("Streptocephalus"))
#>  Downloading ids.  
# Fetch
# streptocephalus_data <- bold.fetch(
#   get_by = "processid",
#   identifiers = data_ids$processid,
#   filt_basecount = c(500, 670)
# )
streptocephalus_data <- test.data2

DT::datatable((head(streptocephalus_data, 10)))

2. Concise summary of the data

A concise summary of the result is generated to get an idea of what all the data contains (Note: The Amplicon_lenght_range is now between 500-670)

bcdm_summary <- bold.data.summarize(
  bold_df = streptocephalus_data,
  summary_type = "concise_summary"
)

DT::datatable(bcdm_summary$concise_summary)

3. Visualizing their occurrence distribution

map_res <- bold.analyze.map(bold_df = streptocephalus_data)

4. Alignment and visualization

4a. Sequence alignment

A muscle algorithm is run on the Streptocephalus sequence data to get a multiple sequence alignment. The headers for each sequence are customized so as to contain processid and bin_uri of each sequence. Please note: the library Biostrings, muscle and msa need to be imported in the R session prior to sequence alignment.

seq_align <- bold.analyze.align(
  bold_df = streptocephalus_data,
  marker = "COI-5P",
  cols_for_seq_names = c("processid", "bin_uri"),
  align_method = "Muscle"
)
DT::datatable(
  seq_align[, c("aligned_seq", "msa.seq.name")],
  options = list(pageLength = 10, scrollX = TRUE)
)

4b. Neighbor Joining Tree

The aligned sequences are then visualized via Neighbor Joining Tree. The output from bold.analyze.align is directly used for the visualization. Please note: the library Biostrings, muscle and msa need to be imported in the R session prior to sequence alignment

seq_tree <- bold.analyze.tree(
  bold_df = seq_align,
  dist_model = "K80",
  clus_method = "nj",
  tree_plot = TRUE,
  tree_plot_type = "p",
  save_dist_mat = TRUE,
  pairwise.deletion = TRUE
)


seq_tree$base_freq
#>         a         c         g         t 
#> 0.2436683 0.2062330 0.1878957 0.3622029

5. Calculating BIN richness estimates and multisite beta diversity measure between different countries

5a. BIN richness

diversity_res <- bold.analyze.diversity(
  bold_df = streptocephalus_data,
  taxon_rank = "species",
  site_type = "locations",
  location_type = "country.ocean",
  diversity_profile = "richness"
)
#>   |                                                                              |                                                                      |   0%  |                                                                              |=                                                                     |   1%  |                                                                              |=                                                                     |   2%  |                                                                              |==                                                                    |   3%  |                                                                              |===                                                                   |   4%  |                                                                              |====                                                                  |   5%  |                                                                              |====                                                                  |   6%  |                                                                              |=====                                                                 |   7%  |                                                                              |======                                                                |   8%  |                                                                              |======                                                                |   9%  |                                                                              |=======                                                               |  10%  |                                                                              |========                                                              |  11%  |                                                                              |========                                                              |  12%  |                                                                              |=========                                                             |  13%  |                                                                              |==========                                                            |  14%  |                                                                              |==========                                                            |  15%  |                                                                              |===========                                                           |  16%  |                                                                              |============                                                          |  17%  |                                                                              |=============                                                         |  18%  |                                                                              |=============                                                         |  19%  |                                                                              |==============                                                        |  20%  |                                                                              |===============                                                       |  21%  |                                                                              |===============                                                       |  22%  |                                                                              |================                                                      |  23%  |                                                                              |=================                                                     |  24%  |                                                                              |==================                                                    |  25%  |                                                                              |==================                                                    |  26%  |                                                                              |===================                                                   |  27%  |                                                                              |====================                                                  |  28%  |                                                                              |====================                                                  |  29%  |                                                                              |=====================                                                 |  30%  |                                                                              |======================                                                |  31%  |                                                                              |======================                                                |  32%  |                                                                              |=======================                                               |  33%  |                                                                              |========================                                              |  34%  |                                                                              |========================                                              |  35%  |                                                                              |=========================                                             |  36%  |                                                                              |==========================                                            |  37%  |                                                                              |===========================                                           |  38%  |                                                                              |===========================                                           |  39%  |                                                                              |============================                                          |  40%  |                                                                              |=============================                                         |  41%  |                                                                              |=============================                                         |  42%  |                                                                              |==============================                                        |  43%  |                                                                              |===============================                                       |  44%  |                                                                              |================================                                      |  45%  |                                                                              |================================                                      |  46%  |                                                                              |=================================                                     |  47%  |                                                                              |==================================                                    |  48%  |                                                                              |==================================                                    |  49%  |                                                                              |===================================                                   |  50%  |                                                                              |====================================                                  |  51%  |                                                                              |====================================                                  |  52%  |                                                                              |=====================================                                 |  53%  |                                                                              |======================================                                |  54%  |                                                                              |======================================                                |  55%  |                                                                              |=======================================                               |  56%  |                                                                              |========================================                              |  57%  |                                                                              |=========================================                             |  58%  |                                                                              |=========================================                             |  59%  |                                                                              |==========================================                            |  60%  |                                                                              |===========================================                           |  61%  |                                                                              |===========================================                           |  62%  |                                                                              |============================================                          |  63%  |                                                                              |=============================================                         |  64%  |                                                                              |==============================================                        |  65%  |                                                                              |==============================================                        |  66%  |                                                                              |===============================================                       |  67%  |                                                                              |================================================                      |  68%  |                                                                              |================================================                      |  69%  |                                                                              |=================================================                     |  70%  |                                                                              |==================================================                    |  71%  |                                                                              |==================================================                    |  72%  |                                                                              |===================================================                   |  73%  |                                                                              |====================================================                  |  74%  |                                                                              |====================================================                  |  75%  |                                                                              |=====================================================                 |  76%  |                                                                              |======================================================                |  77%  |                                                                              |=======================================================               |  78%  |                                                                              |=======================================================               |  79%  |                                                                              |========================================================              |  80%  |                                                                              |=========================================================             |  81%  |                                                                              |=========================================================             |  82%  |                                                                              |==========================================================            |  83%  |                                                                              |===========================================================           |  84%  |                                                                              |============================================================          |  85%  |                                                                              |============================================================          |  86%  |                                                                              |=============================================================         |  87%  |                                                                              |==============================================================        |  88%  |                                                                              |==============================================================        |  89%  |                                                                              |===============================================================       |  90%  |                                                                              |================================================================      |  91%  |                                                                              |================================================================      |  92%  |                                                                              |=================================================================     |  93%  |                                                                              |==================================================================    |  94%  |                                                                              |==================================================================    |  95%  |                                                                              |===================================================================   |  96%  |                                                                              |====================================================================  |  97%  |                                                                              |===================================================================== |  98%  |                                                                              |===================================================================== |  99%  |                                                                              |======================================================================| 100%
DT::datatable(diversity_res$richness)

5b. Beta diversity

beta_diversity_res <- bold.analyze.diversity(
  bold_df = streptocephalus_data,
  taxon_rank = "species",
  site_type = "locations",
  location_type = "country.ocean",
  diversity_profile = "beta",
  beta_index = "jaccard"
)

beta_diversity_res$total.beta
#>               Australia India United States
#> India               1.0                    
#> United States       0.5   1.0              
#> Unrecoverable       1.0   1.0           1.0

Export data

Data can also be exported as a FASTA file, a multiple sequence alignment file (in FASTA format) or customized datasets of BCDM based on certain presets (e.g.,preset = taxonomy will export only taxonomy based information from all the BCDM data)

bold.export(
  bold_df = streptocephalus_data,
  export_type = "fas",
  cols_for_fas_names = c("bin_uri", "genus", "species"),
  export = "~/Desktop/boldconnectr_sequences.fas"
)

Additional notes

In addition, several analysis functions return commonly used R data structures as part of their outputs, including an occurrence matrix, sf object, DNABin object containing unaligned sequences, and a phylo object generated from aligned sequences. These outputs can be readily integrated into workflows from other R packages for downstream analyses (e.g., using an occurrence matrix for ecological or biodiversity analyses with packages such as vegan and betapart).

For more/detailed information, please visit (https://github.com/boldsystems-central/BOLDconnectR) or use the help function in R.