:newpaper_roll:

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
 

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
+         <int>     <int>    <int>         <int>     <int> <chr>   <int>
+     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 <chr>, Spawningarea <chr>, Jan <dbl>,
+    #   Feb <dbl>, Mar <dbl>, Apr <dbl>, May <dbl>, Jun <dbl>, Jul <dbl>,
+    #   Aug <dbl>, Sep <dbl>, Oct <dbl>, Nov <dbl>, Dec <dbl>, GSI <int>,
+    #   PercentFemales <int>, TempLow <dbl>, TempHigh <dbl>, SexRatiomid <dbl>,
+    #   SexRmodRef <int>, FecundityMin <int>, WeightMin <dbl>,
+    #   LengthFecunMin <dbl>, LengthTypeFecMin <chr>, FecundityRef <int>, …
+
+## 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
+      <chr>                  <chr>                       <chr>       <int>
+    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