From 31558f992e79f3675ae9dc3828750de58576e6da Mon Sep 17 00:00:00 2001 From: Carl Boettiger Date: Fri, 16 Aug 2024 17:51:50 +0000 Subject: [PATCH] :newpaper_roll: --- README.Rmd | 36 +++++++++++++++++++++++ README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/README.Rmd b/README.Rmd index 55e6b33..1f90531 100644 --- a/README.Rmd +++ b/README.Rmd @@ -93,6 +93,42 @@ fb_tbl("species") %>% ``` +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 spawing tables and filtering to the grouper family, _Epinephelidae_: + +```{r message=FALSE} +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: + +```{r message=FALSE} +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()` + +```{r message=FALSE} +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 diff --git a/README.md b/README.md index fd15e6e..51b1651 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,90 @@ fb_tbl("species") %>% 1 Oreochromis niloticus Nile tilapia 60 2 Salmo trutta Sea trout 140 +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 spawing tables and +filtering to the grouper family, *Epinephelidae*: + +``` r +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) +``` + + # A tibble: 227 × 95 + autoctr StockCode SpecCode SpawningRefNo SourceRef C_Code E_CODE + + 1 18 18 12 5222 3092 528A NA + 2 19 18 12 26409 1784 388 145 + 3 20 20 14 26409 NA 192 NA + 4 9147 20 14 118249 118249 826E 8 + 5 22 21 15 5241 5241 630 NA + 6 23 21 15 5241 6484 388 NA + 7 24 21 15 5241 3095 060 NA + 8 24 21 15 5241 3095 060 NA + 9 24 21 15 5241 3095 060 NA + 10 24 21 15 5241 3095 060 NA + # ℹ 217 more rows + # ℹ 88 more variables: SpawningGround , Spawningarea , Jan , + # Feb , Mar , Apr , May , Jun , Jul , + # Aug , Sep , Oct , Nov , Dec , GSI , + # PercentFemales , TempLow , TempHigh , SexRatiomid , + # SexRmodRef , FecundityMin , WeightMin , + # LengthFecunMin , LengthTypeFecMin , FecundityRef , … + +## 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: + +``` r +validate_names("Abramites ternetzi") +``` + + [1] "Abramites hypselonotus" + +`rfishbase` can also provide tables of `synonyms()`, a table of +`common_names()` in multiple languages, and convert `common_to_sci()` or +`sci_to_common()` + +``` r +common_to_sci(c("Bicolor cleaner wrasse", "humphead parrotfish"), Language="English") +``` + + # A tibble: 5 × 4 + Species ComName Language SpecCode + + 1 Labroides bicolor Bicolor cleaner wrasse English 5650 + 2 Chlorurus cyanescens Blue humphead parrotfish English 7909 + 3 Bolbometopon muricatum Green humphead parrotfish English 5537 + 4 Bolbometopon muricatum Humphead parrotfish English 5537 + 5 Chlorurus oedema Uniform humphead parrotfish English 8394 + +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