The New rfishbase

Building a species list

Almost all functions in rfishbase take a list (character vector) of species scientific names, for example:

fish <- c("Oreochromis niloticus", "Salmo trutta")

You can also read in a list of names from any existing data you are working with. When providing your own species list, you should always begin by validating the names. Taxonomy is a moving target, and this well help align the scientific names you are using with the names used by FishBase, and alert you to any potential issues:

fish <- validate_names(c("Oreochromis niloticus", "Salmo trutta"))

Another typical use case is in wanting to collect information about all species in a particular taxonomic group, such as a Genus, Family or Order. The function species_list recognizes six taxonomic levels, and can help you generate a list of names of all species in a given group:

fish <- species_list(Genus = "Labroides")
fish

[1] "Labroides dimidiatus"    "Labroides bicolor"      
[3] "Labroides pectoralis"    "Labroides phthirophagus"
[5] "Labroides rubrolabiatus"

rfishbase also recognizes common names. When a common name refers to multiple species, all matching species are returned:

trout <- common_to_sci("trout")
trout

# A tibble: 306 x 4
   Species                   ComName              Language SpecCode
   <chr>                     <chr>                <chr>       <dbl>
 1 Salmo obtusirostris       Adriatic trout       English      6210
 2 Schizothorax richardsonii Alawan snowtrout     English      8705
 3 Schizopyge niger          Alghad snowtrout     English     24454
 4 Salvelinus fontinalis     American brook trout English       246
 5 Salmo trutta              Amu-Darya trout      English       238
 6 Salmo kottelati           Antalya trout        English     67602
 7 Oncorhynchus apache       Apache Trout         English      2687
 8 Oncorhynchus apache       Apache trout         English      2687
 9 Plectropomus areolatus    Apricot trout        English      6082
10 Salmo trutta              Aral Sea Trout       English       238
# … with 296 more rows

Note that there is no need to validate names coming from common_to_sci or species_list, as these will always return valid names.

Getting data

With a species list in place, we are ready to query fishbase for data. Note that if you have a very long list of species, it is always a good idea to try out your intended functions with a subset of that list first to make sure everything is working.

The species() function returns a table containing much (but not all) of the information found on the summary or homepage for a species on fishbase.org. rfishbase functions always return tidy data tables: rows are observations (e.g. a species, individual samples from a species) and columns are variables (fields).

species(trout$Species)

# A tibble: 306 x 100
   SpecCode Species SpeciesRefNo Author FBname PicPreferredName
      <dbl> <chr>          <dbl> <chr>  <chr>  <chr>           
 1     6210 Salmo …        59043 (Heck… Adria… Saobt_u0.jpg    
 2     8705 Schizo…         4832 (Gray… Snowt… Scric_u1.jpg    
 3    24454 Schizo…         4832 (Heck… Algha… <NA>            
 4      246 Salvel…        86798 (Mitc… Brook… Safon_u4.jpg    
 5      238 Salmo …         4779 Linna… Sea t… Satru_u2.jpg    
 6    67602 Salmo …        99540 Turan… Antal… Sakot_m0.jpg    
 7     2687 Oncorh…         5723 (Mill… Apach… Onapa_u0.jpg    
 8     2687 Oncorh…         5723 (Mill… Apach… Onapa_u0.jpg    
 9     6082 Plectr…         5222 (R<fc… Squar… Plare_u4.jpg    
10      238 Salmo …         4779 Linna… Sea t… Satru_u2.jpg    
# … with 296 more rows, and 94 more variables: PicPreferredNameM <chr>,
#   PicPreferredNameF <chr>, PicPreferredNameJ <chr>, FamCode <dbl>,
#   Subfamily <chr>, GenCode <dbl>, SubGenCode <dbl>, BodyShapeI <chr>,
#   Source <chr>, AuthorRef <lgl>, Remark <chr>, TaxIssue <dbl>,
#   Fresh <dbl>, Brack <dbl>, Saltwater <dbl>, DemersPelag <chr>,
#   Amphibious <lgl>, AmphibiousRef <lgl>, AnaCat <chr>, MigratRef <dbl>,
#   DepthRangeShallow <dbl>, DepthRangeDeep <dbl>, DepthRangeRef <dbl>,
#   DepthRangeComShallow <dbl>, DepthRangeComDeep <dbl>,
#   DepthComRef <dbl>, LongevityWild <dbl>, LongevityWildRef <dbl>,
#   LongevityCaptive <dbl>, LongevityCapRef <dbl>, Vulnerability <dbl>,
#   Length <dbl>, LTypeMaxM <chr>, LengthFemale <dbl>, LTypeMaxF <chr>,
#   MaxLengthRef <dbl>, CommonLength <dbl>, LTypeComM <chr>,
#   CommonLengthF <dbl>, LTypeComF <chr>, CommonLengthRef <dbl>,
#   Weight <dbl>, WeightFemale <dbl>, MaxWeightRef <dbl>, Pic <chr>,
#   PictureFemale <chr>, LarvaPic <chr>, EggPic <chr>,
#   ImportanceRef <dbl>, Importance <chr>, PriceCateg <chr>,
#   PriceReliability <chr>, Remarks7 <chr>, LandingStatistics <chr>,
#   Landings <chr>, MainCatchingMethod <chr>, II <chr>, MSeines <dbl>,
#   MGillnets <dbl>, MCastnets <dbl>, MTraps <dbl>, MSpears <dbl>,
#   MTrawls <dbl>, MDredges <dbl>, MLiftnets <dbl>, MHooksLines <dbl>,
#   MOther <dbl>, UsedforAquaculture <chr>, LifeCycle <chr>,
#   AquacultureRef <dbl>, UsedasBait <chr>, BaitRef <dbl>, Aquarium <chr>,
#   AquariumFishII <chr>, AquariumRef <dbl>, GameFish <dbl>,
#   GameRef <dbl>, Dangerous <chr>, DangerousRef <dbl>,
#   Electrogenic <chr>, ElectroRef <dbl>, Complete <lgl>,
#   GoogleImage <dbl>, Comments <chr>, Profile <chr>, PD50 <dbl>,
#   Emblematic <dbl>, Entered <dbl>, DateEntered <dttm>, Modified <dbl>,
#   DateModified <dttm>, Expert <dbl>, DateChecked <dttm>, TS <lgl>

Most tables contain many fields. To avoid overly cluttering the screen, rfishbase displays tables as “tibbles” from the dplyr package. These act just like the familiar data.frames of base R except that they print to the screen in a more tidy fashion. Note that columns that cannot fit easily in the display are summarized below the table. This gives us an easy way to see what fields are available in a given table.

Most rfishbase functions will let the user subset these fields by listing them in the fields argument, for instance:

dat <- species(trout$Species, fields=c("Species", "PriceCateg", "Vulnerability"))
dat

# A tibble: 306 x 3
   Species                   PriceCateg Vulnerability
   <chr>                     <chr>              <dbl>
 1 Salmo obtusirostris       very high           47.0
 2 Schizothorax richardsonii unknown             34.8
 3 Schizopyge niger          unknown             46.8
 4 Salvelinus fontinalis     very high           43.4
 5 Salmo trutta              very high           60.0
 6 Salmo kottelati           <NA>                33.7
 7 Oncorhynchus apache       very high           53.8
 8 Oncorhynchus apache       very high           53.8
 9 Plectropomus areolatus    very high           30.3
10 Salmo trutta              very high           60.0
# … with 296 more rows

Alternatively, just subset the table using the standard column selection in base R ([[) or dplyr::select.

FishBase Docs: Discovering data

Unfortunately identifying what fields come from which tables is often a challenge. Each summary page on fishbase.org includes a list of additional tables with more information about species ecology, diet, occurrences, and many other things. rfishbase provides functions that correspond to most of these tables.

Because rfishbase accesses the back end database, it does not always line up with the web display. Frequently rfishbase functions will return more information than is available on the web versions of the these tables. Some information found on the summary homepage for a species is not available from the species summary function, but must be extracted from a different table. For instance, the species Resilience information is not one of the fields in the species summary table, despite appearing on the species homepage of fishbase.org. To discover which table this information is in, we can use the special rfishbase function list_fields, which will list all tables with a field matching the query string:

list_fields("Resilience")

# A tibble: 1 x 1
  table 
  <chr> 
1 stocks

This shows us that this information appears on the stocks table. We can then request this data from the stocks table:

stocks(trout$Species, fields=c("Species", "Resilience", "StockDefs"))

# A tibble: 408 x 3
   Species           Resilience StockDefs                                  
   <chr>             <chr>      <chr>                                      
 1 Salmo obtusirost… Medium     Europe:  Adriatic basin in Krka, Jardo, Vr…
 2 Schizothorax ric… Medium     Asia:  Himalayan region of India, Sikkim a…
 3 Schizopyge niger  Medium     Asia:  Kashmir Valley in India and Azad Ka…
 4 Salvelinus fonti… Medium     North America:  native to most of eastern …
 5 Salmo trutta      Medium     Europe and Asia:  Atlantic, North, White a…
 6 Salmo trutta      <NA>       <i>Salmo trutta aralensis</i>:  Asia:  end…
 7 Salmo trutta      Medium     <i>Salmo trutta fario</i>:  Northeast  Atl…
 8 Salmo trutta      Low        "<i>Salmo trutta lacustris</i>\t:  Europe:…
 9 Salmo trutta      <NA>       "<i>Salmo trutta oxianus</i>\t:  Asia:  Am…
10 Salmo trutta      <NA>       <i>Salmo trutta aralensis</i>:  Asia:  Ara…
# … with 398 more rows