Enrich Taxa with FishBase and SeaLifeBase Biological Data

Main pipeline function that downloads the taxa metadata from cloud storage, expands each record to matching FishBase / SeaLifeBase species (restricted to the configured FAO major fishing areas — 51 and 57, the Western and Eastern Indian Ocean, by default), and joins biological attributes including vulnerability, trophic level, feeding guild, and nutrient composition. The final dataset is uploaded as a versioned Parquet file to the shared coasts bucket.

Usage

enrich_taxa(log_threshold = logger::DEBUG, fao_areas = NULL, version = NULL)

Arguments

log_threshold: Logging threshold passed to logger::log_threshold(). Defaults to logger::DEBUG.
fao_areas: Optional numeric vector of FAO major fishing area codes to restrict species to. If NULL (default) the value is resolved from the metadata.fishbase.fao_areas configuration key, falling back to c(51, 57) (Western and Eastern Indian Ocean). Timor-Leste is Area 71. Pass 57 to reproduce pre-4.6.0 output — see resolve_fao_areas() for why 57 alone was never right for the Western Indian Ocean.
version: FishBase / SeaLifeBase release to read. If NULL (default) it is resolved from the metadata.fishbase.db_version configuration key, falling back to "latest". Resolved once and used for every read, so one run cannot mix snapshots. See resolve_db_version().

Value

Invisible NULL. Called for its side effect of uploading the enriched taxa Parquet file to cloud storage.

Details

The function performs the following steps:

Downloads the latest metadata RDS file (Airtable assets) from GCS.
Extracts the taxa table and calls expand_taxonomic_info().
Restricts species to the resolved FAO area(s) via filter_by_fao_area(), always keeping species with no area assignment.
Joins species-level data from the species, ecology, and estimate tables, the family, order and class, the IUCN and CITES codes from stocks, the median length at first maturity from maturity and the optimum length from the asymptotic length in popgrowth, both restated to total length with the popll fits where a study used another length.
Deduplicates by taking the first non-NA value per group.
Cleans column names with janitor::clean_names().
Uploads the result via upload_parquet_to_cloud() using the metadata.fishbase.taxa_enriched.file_prefix configuration key.

Both the assets snapshot it reads and the enriched table it writes resolve through resolve_storage_opts(conf, "coasts") — the shared hub bucket, which is where ingest_pds_trips() and the other readers of these objects look. Within the coasts package itself the hub and country buckets are the same, so this is a no-op; in a downstream package that defines storage.google.options_coasts it directs both ends at the hub rather than scattering per-country copies.

This function emits traits and nutrients only. For length-weight and length-length coefficients see get_taxa_morphometrics().

The nutrients are the seven rfishbase::estimate() models: calcium, iron, omega-3, protein, selenium, vitamin A and zinc, per 100 g of raw portion, in the units FishBase and SeaLifeBase publish them — calcium, iron and zinc in mg, selenium and vitamin A in μg, omega-3 and protein in g. They are passed through unconverted, and no substitute is supplied for species the models cannot estimate — most invertebrates, which is where a country publishing nutrition figures will need a food-composition table of its own. Timor-Leste carries both of those steps locally for exactly that reason: unit normalisation and an FAO food-composition override for six invertebrate codes. Neither is upstreamed here, because both would silently change published figures for every country already reading this table.

Examples

if (FALSE) { # \dontrun{
# Indian Ocean, Western + Eastern (the default)
coasts::enrich_taxa()

# Western Central Pacific
coasts::enrich_taxa(fao_areas = 71)

# Pinned to a fixed FishBase release
coasts::enrich_taxa(version = "25.04")
} # }