Build Length-Weight and Length-Length Tables for a Set of Taxa

Single entry point for the morphometric half of the taxa pipeline: expands a taxa table against the FishBase / SeaLifeBase backbone, restricts it to the configured FAO major fishing area(s), and returns both the length-weight and the length-length coefficient tables from that one expansion.

Usage

get_taxa_morphometrics(
  data,
  fao_areas = NULL,
  filter_by_area = TRUE,
  length_types = c("TL", "FL"),
  strip_parentheticals = FALSE,
  version = NULL,
  conf = NULL
)

Arguments

data

A data frame with alpha3_code and scientific_name columns, as accepted by expand_taxonomic_info().

fao_areas

Numeric vector of FAO major fishing area codes to restrict species to. If NULL (default) the value is resolved from conf via resolve_fao_areas(), which falls back to c(51, 57). Pass filter_by_area = FALSE to apply no restriction at all.

filter_by_area

Logical. If FALSE, species are not restricted by FAO area and fao_areas is ignored. Default TRUE. See Details for the coverage trade-off, which is substantial.

length_types

Character vector of length measurement codes for the length-length table. See get_length_length_coeffs().

strip_parentheticals

Logical, passed to expand_taxonomic_info(). Default FALSE.

version

FishBase / SeaLifeBase release to read. If NULL (default) it is resolved once, from the metadata.fishbase.db_version configuration key, and the same release is used for every read this call makes. Falls back to "latest". See resolve_db_version().

conf

Optional configuration list. If NULL (default) and the area or the release is being resolved from configuration, read_config() is called.

Value

A named list of three tibbles:

• expanded: the species expansion actually used.

• length_weight: see get_length_weight_coeffs().

• length_length: see get_length_length_coeffs().

Details

Because both coefficient tables are derived from a single expansion, the two are guaranteed to be keyed consistently and can be joined on species_found and server without re-resolving names.

No Type or EsQ filtering is applied to length_weight — see get_length_weight_coeffs() for why.

The release is resolved once, at the top, and threaded through all five table reads, so a single call cannot mix two snapshots of FishBase.

Whether to filter by FAO area

Restricting to an area is right for distributional traits, and it is what enrich_taxa() does. For length-weight coefficients it is a coverage decision rather than a correctness one: a and b describe body form, which does not stop applying at an FAO boundary, and FishBase's area assignments are incomplete. Measured over Timor-Leste's 57 taxa:

	area 71	unrestricted
species expanded	2,469	5,150
species with a/b	764	1,283
length-weight rows	2,970	5,225
taxon codes with length-length	38	39

Filtering here costs 40% of the species that have usable coefficients. Set filter_by_area = FALSE when maximum coefficient coverage matters more than regional specificity, which is generally the case when the coefficients feed a weight estimate aggregated across a whole taxon code.

See also

expand_taxonomic_info(), enrich_taxa()

Examples

if (FALSE) { # \dontrun{
taxa <- data.frame(
  alpha3_code = c("EMP", "SNA"),
  scientific_name = c("Lethrinidae", "Lutjanus spp")
)

# Indian Ocean, Western + Eastern (the configured default)
m <- get_taxa_morphometrics(taxa)

# Western Central Pacific, e.g. Timor-Leste
m <- get_taxa_morphometrics(taxa, fao_areas = 71)

# Maximum coefficient coverage, no area restriction
m <- get_taxa_morphometrics(taxa, filter_by_area = FALSE)

# Pinned to a fixed FishBase release
m <- get_taxa_morphometrics(taxa, version = "25.04")
} # }