In ropensci/rfishbase: R Interface to 'FishBase'

rfishbase

Welcome to rfishbase 5! This is the fourth rewrite of the original rfishbase package described in Boettiger et al. (2012).

Another streamlined re-design following new abilities for data hosting and access. This release relies on a HuggingFace datasets hosting for data and metadata hosting in parquet and schema.org.

Data access is simplified to use the simple HuggingFace datasets API instead of the previous contentid-based resolution. This allows metadata to be defined with directly alongside the data platform independent of the R package.

A simplified access protocol relies on duckdbfs for direct reads of tables. Several functions previously used only to manage connections are now deprecated or removed, along with a significant number of dependencies.

Core use still centers around the same package API using the fb_tbl() function, with legacy helper functions for common tables like species() are still accessible and can still optionally filter by species name where appropriate. As before, loading the full tables and sub-setting manually is still recommended.

Historic helper functions like load_taxa() (combining the taxonomic classification from Species, Genus, Family and Order tables), validate_names(), and common_to_sci() and sci_to_common() should be in working order, all using table-based outputs.

rfishbase 1.0 relied on parsing of XML pages served directly from Fishbase.org.
rfishbase 2.0 relied on calls to a ruby-based API, fishbaseapi, that provided access to SQL snapshots of about 20 of the more popular tables in FishBase or SeaLifeBase.
rfishbase 3.0 side-stepped the API by making queries which directly downloaded compressed csv tables from a static web host. This substantially improved performance a reliability, particularly for large queries. The release largely remained backwards compatible with 2.0, and added more tables.
rfishbase 4.0 extends the static model and interface. Static tables are distributed in parquet and accessed through a provenance-based identifier. While old functions are retained, a new interface is introduced to provide easy access to all fishbase tables.

We welcome any feedback, issues or questions that users may encounter through our issues tracker on GitHub: https://github.com/ropensci/rfishbase/issues

knitr::opts_chunk$set(warning=FALSE, comment=NA)
options("rfishbase_local_db" = FALSE)

Installation

remotes::install_github("ropensci/rfishbase")

library("rfishbase")
library("dplyr") # convenient but not required

Getting started

Generic table interface

All fishbase tables can be accessed by name using the fb_tbl() function:

fb_tbl("ecosystem")

You can see all the tables using fb_tables() to see a list of all the table names (specify sealifebase if desired). Careful, there are a lot of them! The fishbase databases have grown a lot in the decades, and were not intended to be used directly by most end-users, so you may have considerable work to determine what's what. Keep in mind that many variables can be estimated in different ways (e.g. trophic level), and thus may report different values in different tables. Also note that species is name (or SpecCode) is not always the primary key for a table -- many tables are specific to stocks or even individual samples, and some tables are reference lists that are not species focused at all, but meant to be joined to other tables (faoareas, etc). Compare tables against what you see on fishbase.org, or ask on our issues forum for advice!

fish <- c("Oreochromis niloticus", "Salmo trutta")

fb_tbl("species") %>% 
  mutate(sci_name = paste(Genus, Species)) %>%
  filter(sci_name %in% fish) %>% 
  select(sci_name, FBname, Length)

In most tables, species are identified by SpecCode (as per best practices) rather than scientific names. Multiple tables can be joined on the SpecCode to more fully describe a species.

To filter species by taxonomic names, use the taxa table from load_taxa(), which provides a joined table of taxonomy from subspecies up through Class, along with the corresponding FishBase taxon ids codes. Here is an example workflow joining two of the spawning tables and filtering to the grouper family, Epinephelidae:

library(rfishbase)
library(dplyr)

## Get the whole spawning and spawn agg table, joined together:
spawn <- left_join(fb_tbl("spawning"),  
                   fb_tbl("spawnagg"), 
                   relationship = "many-to-many")

# Filter taxa down to the desired species
groupers <- load_taxa() |> filter(Family == "Epinephelidae")

## A "filtering join" (inner join) 
spawn |> inner_join(groupers)

Species Names

Always keep in mind that taxonomy is a dynamic concept. Species can be split or lumped based on new evidence, and naming authorities can disagree over which name is an 'accepted name' or 'synonym' for any given species. When providing your own list of species names, consider first checking that those names are "valid" in the current taxonomy established by FishBase:

validate_names("Abramites ternetzi")

rfishbase can also provide tables of synonyms(), a table of common_names() in multiple languages, and convert common_to_sci() or sci_to_common()

common_to_sci(c("Bicolor cleaner wrasse", "humphead parrotfish"), Language="English")

Note that the results are returned as a table, potentially indicating other common names for the same species, as well as potentially different species that match the provided common name! Please always be careful with names, and use unique SpecCodes to refer to unique species.

SeaLifeBase

SeaLifeBase.org is maintained by the same organization and largely parallels the database structure of Fishbase. As such, almost all rfishbase functions can instead be instructed to address the

fb_tbl("species", "sealifebase")

Versions and importing all tables

By default, tables are downloaded the first time they are used. rfishbase defaults to download the latest available snapshot; be aware that the most recent snapshot may be months behind the latest data on fishbase.org. Check available releases: