#' Observed Fish Functional Traits from FishLife
#'
#' @description
#' A processed species-level dataset containing 17 quantitative fish
#' functional traits extracted from the observed-data component of
#' \code{FishBase_and_Morphometrics} in FishLife. The dataset contains
#' one taxonomic record for each of 26,622 fish species.
#'
#' @format A data frame with 26,622 rows and 20 variables:
#' \describe{
#'   \item{species}{
#'     Character. Full binomial species name.
#'   }
#'   \item{genus}{
#'     Character. Genus name.
#'   }
#'   \item{family}{
#'     Character. Taxonomic family.
#'   }
#'   \item{age_max}{
#'     Numeric. Maximum reported age, years.
#'   }
#'   \item{trophic_level}{
#'     Numeric. Trophic level, dimensionless.
#'   }
#'   \item{aspect_ratio}{
#'     Numeric. Caudal-fin aspect ratio, calculated as squared
#'     caudal-fin height divided by caudal-fin surface area,
#'     dimensionless.
#'   }
#'   \item{fecundity}{
#'     Numeric. Absolute fecundity, expressed as the number of eggs
#'     or offspring produced per female per year or per spawning batch,
#'     depending on the source record.
#'   }
#'   \item{growth_coefficient}{
#'     Numeric. von Bertalanffy growth coefficient K, year^-1.
#'   }
#'   \item{temperature}{
#'     Numeric. Mean environmental temperature associated with the
#'     sampled population or stock, degrees Celsius.
#'   }
#'   \item{length_max}{
#'     Numeric. Maximum recorded body length, cm.
#'   }
#'   \item{length_infinity}{
#'     Numeric. von Bertalanffy asymptotic body length, cm.
#'   }
#'   \item{length_maturity}{
#'     Numeric. Body length at sexual maturity, generally corresponding
#'     to the length at which 50 percent of individuals are mature, cm.
#'   }
#'   \item{age_maturity}{
#'     Numeric. Age at sexual maturity, generally corresponding to the
#'     age at which 50 percent of individuals are mature, years.
#'   }
#'   \item{natural_mortality}{
#'     Numeric. Instantaneous natural mortality rate M, year^-1.
#'   }
#'   \item{weight_infinity}{
#'     Numeric. von Bertalanffy asymptotic body mass, g.
#'   }
#'   \item{max_body_depth}{
#'     Numeric. Size-standardized maximum body depth, dimensionless.
#'   }
#'   \item{max_body_width}{
#'     Numeric. Size-standardized maximum body width, dimensionless.
#'   }
#'   \item{lower_jaw_length}{
#'     Numeric. Size-standardized lower-jaw length, dimensionless.
#'   }
#'   \item{min_caudal_pedoncule_depth}{
#'     Numeric. Size-standardized minimum caudal-peduncle depth,
#'     dimensionless. The variable name retains the spelling used in
#'     the source dataset.
#'   }
#'   \item{offspring_size}{
#'     Numeric. Offspring size, measured as egg diameter, egg-case
#'     length, or newborn body length depending on taxon, mm.
#'   }
#' }
#'
#' @details
#' This dataset was derived from the \code{Y_ij} component of
#' \code{FishBase_and_Morphometrics} in FishLife version 3.0.1.
#' \code{Y_ij} contains observed trait records in transformed space
#' and is distinct from the model-predicted and imputed trait values
#' available elsewhere in the FishLife object.
#'
#' Variables stored on the natural-log scale were back-transformed
#' using \code{exp()}. The source data contained 41,546
#' observation-level records representing 26,622 unique species.
#' When multiple finite observations were available for the same
#' species and trait, they were summarized using the median.
#' No model-based imputation was applied.
#'
#' Of the 26,622 species, 16,237 have at least one observed value
#' among the 17 selected traits, whereas 10,385 contain taxonomic
#' information but no observed value for any of these traits.
#' Only 46 species have complete observations for all 17 traits.
#' Users should therefore examine trait coverage and select
#' biologically appropriate trait subsets before multivariate
#' analyses.
#'
#' The four specimen-based morphometric traits
#' (\code{max_body_depth}, \code{max_body_width},
#' \code{lower_jaw_length}, and
#' \code{min_caudal_pedoncule_depth}) describe relative body shape.
#' In the source analysis, each linear measurement was standardized
#' by the geometric mean of specimen length, width, and height.
#' These variables are therefore dimensionless.
#'
#' Maximum body length is generally reported as total length, although
#' some source records use standard length, fork length, disc width,
#' or another reported measure of body size.
#'
#' Fecundity is not consistently standardized to annual reproductive
#' output. Depending on the source record, values may represent annual
#' production for single-spawning species or production per spawning
#' batch for species that reproduce multiple times within a year.
#'
#' Offspring size represents egg diameter for most fishes, egg-case
#' length for skates and rays, or body length of a newborn pup for
#' sharks, expressed in millimetres.
#'
#' @source
#' FishLife version 3.0.1:
#' \doi{10.5281/zenodo.7590994}
#'
#' @references
#' Thorson, J. T., Maureaud, A. A., Frelat, R., Merigot, B.,
#' Bigman, J. S., Friedman, S. T., Palomares, M. L. D.,
#' Pinsky, M. L., Price, S. A., and Wainwright, P. (2023).
#' Identifying direct and indirect associations among traits by
#' merging phylogenetic comparative methods and structural equation
#' models. \emph{Methods in Ecology and Evolution}, 14,
#' 1259--1275.
#' \doi{10.1111/2041-210X.14076}
#'
#' @examples
#' data(FishLife)
#'
#' dim(FishLife)
#' head(FishLife[, c(
#'   "species",
#'   "length_max",
#'   "offspring_size"
#' )])
#'
"FishLife"
