Author: Scott Chamberlain
Date: 2020-07-07

# Introduction to worrms

#### Scott Chamberlain

#### 2020-07-07

`worrms` is an R client for the World Register of Marine Species (https://www.marinespecies.org/)

See the taxize book (https://taxize.dev) for taxonomically focused work in this and similar packages.

## Install

Stable version from CRAN

    install.packages("worrms")

Development version from GitHub

    install.packages("remotes")
    remotes::install_github("ropensci/worrms")

    library("worrms")

## Get records

WoRMS ‘records’ are taxa, not specimen occurrences or something else.

by date

    wm_records_date('2016-12-23T05:59:45+00:00')
    #> # A tibble: 50 x 27
    #>    AphiaID url   scientificname authority status unacceptreason taxonRankID
    #>      <int> <chr> <chr>          <chr>     <chr>  <lgl>                <int>
    #>  1  894302 http… Paleopolymorp… Vasilenk… accep… NA                     220
    #>  2  894296 http… Parapachyphlo… Miklukho… accep… NA                     220
    #>  3  894298 http… Parapachyphlo… Miklukho… accep… NA                     220
    #>  4  894301 http… Ovulina radia… Seguenza… accep… NA                     220
    #>  5  894299 http… Parafissurina… Petri, 1… accep… NA                     220
    #>  6  894297 http… Parapachyphlo… Miklukho… accep… NA                     220
    #>  7  919684 http… Flintina serr… Cuvillie… accep… NA                     220
    #>  8  906465 http… Verneuilinoid… Bartenst… accep… NA                     220
    #>  9  903640 http… Quinqueloculi… Hussey, … accep… NA                     220
    #> 10  917580 http… Orbitolina ra… Sahni & … accep… NA                     220
    #> # … with 40 more rows, and 20 more variables: rank <chr>, valid_AphiaID <int>,
    #> #   valid_name <chr>, valid_authority <chr>, parentNameUsageID <int>,
    #> #   kingdom <chr>, phylum <chr>, class <chr>, order <chr>, family <chr>,
    #> #   genus <chr>, citation <chr>, lsid <chr>, isMarine <int>, isBrackish <lgl>,
    #> #   isFreshwater <lgl>, isTerrestrial <lgl>, isExtinct <int>, match_type <chr>,
    #> #   modified <chr>

by a taxonomic name

    wm_records_name(name = 'Leucophaeus scoresbii')
    #> # A tibble: 1 x 27
    #>   AphiaID url   scientificname authority status unacceptreason taxonRankID rank
    #>     <int> <chr> <chr>          <chr>     <chr>  <lgl>                <int> <chr>
    #> 1  344089 http… Leucophaeus s… Traill, … accep… NA                     220 Spec…
    #> # … with 19 more variables: valid_AphiaID <int>, valid_name <chr>,
    #> #   valid_authority <chr>, parentNameUsageID <int>, kingdom <chr>,
    #> #   phylum <chr>, class <chr>, order <chr>, family <chr>, genus <chr>,
    #> #   citation <chr>, lsid <chr>, isMarine <int>, isBrackish <lgl>,
    #> #   isFreshwater <lgl>, isTerrestrial <lgl>, isExtinct <lgl>, match_type <chr>,
    #> #   modified <chr>

by many names

    wm_records_names(name = c('Leucophaeus scoresbii', 'Coryphaena'))
    #> [[1]]
    #> # A tibble: 1 x 27
    #>   AphiaID url   scientificname authority status unacceptreason taxonRankID rank
    #>     <int> <chr> <chr>          <chr>     <chr>  <lgl>                <int> <chr>
    #> 1  344089 http… Leucophaeus s… Traill, … accep… NA                     220 Spec…
    #> # … with 19 more variables: valid_AphiaID <int>, valid_name <chr>,
    #> #   valid_authority <chr>, parentNameUsageID <int>, kingdom <chr>,
    #> #   phylum <chr>, class <chr>, order <chr>, family <chr>, genus <chr>,
    #> #   citation <chr>, lsid <chr>, isMarine <int>, isBrackish <lgl>,
    #> #   isFreshwater <lgl>, isTerrestrial <lgl>, isExtinct <lgl>, match_type <chr>,
    #> #   modified <chr>
    #>
    #> [[2]]
    #> # A tibble: 2 x 27
    #>   AphiaID url   scientificname authority status unacceptreason taxonRankID rank
    #>     <int> <chr> <chr>          <chr>     <chr>  <chr>                <int> <chr>
    #> 1  125960 http… Coryphaena     Linnaeus… accep… <NA>                   180 Genus
    #> 2  843430 <NA>  <NA>           <NA>      quara… synonym                 NA <NA>
    #> # … with 19 more variables: valid_AphiaID <int>, valid_name <chr>,
    #> #   valid_authority <chr>, parentNameUsageID <int>, kingdom <chr>,
    #> #   phylum <chr>, class <chr>, order <chr>, family <chr>, genus <chr>,
    #> #   citation <chr>, lsid <chr>, isMarine <int>, isBrackish <int>,
    #> #   isFreshwater <int>, isTerrestrial <int>, isExtinct <lgl>, match_type <chr>,
    #> #   modified <chr>

by common name

    wm_records_common(name = 'clam')
    #> # A tibble: 4 x 27
    #>   AphiaID url   scientificname authority status unacceptreason taxonRankID rank
    #>     <int> <chr> <chr>          <chr>     <chr>  <lgl>                <int> <chr>
    #> 1  141919 http… Mercenaria me… (Linnaeu… accep… NA                     220 Spec…
    #> 2  140431 http… Mya truncata   Linnaeus… accep… NA                     220 Spec…
    #> 3  141936 http… Venus verruco… Linnaeus… accep… NA                     220 Spec…
    #> 4  575771 http… Verpa penis    (Linnaeu… accep… NA                     220 Spec…
    #> # … with 19 more variables: valid_AphiaID <int>, valid_name <chr>,
    #> #   valid_authority <chr>, parentNameUsageID <int>, kingdom <chr>,
    #> #   phylum <chr>, class <chr>, order <chr>, family <chr>, genus <chr>,
    #> #   citation <chr>, lsid <chr>, isMarine <int>, isBrackish <lgl>,
    #> #   isFreshwater <lgl>, isTerrestrial <lgl>, isExtinct <lgl>, match_type <chr>,
    #> #   modified <chr>

using the TAXMATCH algorithm

    wm_records_taxamatch(name = 'Leucophaeus scoresbii')
    #> [[1]]
    #> # A tibble: 1 x 27
    #>   AphiaID url   scientificname authority status unacceptreason taxonRankID rank
    #>     <int> <chr> <chr>          <chr>     <chr>  <lgl>                <int> <chr>
    #> 1  344089 http… Leucophaeus s… Traill, … accep… NA                     220 Spec…
    #> # … with 19 more variables: valid_AphiaID <int>, valid_name <chr>,
    #> #   valid_authority <chr>, parentNameUsageID <int>, kingdom <chr>,
    #> #   phylum <chr>, class <chr>, order <chr>, family <chr>, genus <chr>,
    #> #   citation <chr>, lsid <chr>, isMarine <int>, isBrackish <lgl>,
    #> #   isFreshwater <lgl>, isTerrestrial <lgl>, isExtinct <lgl>, match_type <chr>,
    #> #   modified <chr>

## APHIA ID <–> name

    wm_name2id(name = "Rhincodon")
    #> [1] 105749

    wm_id2name(id = 105706)
    #> [1] "Rhincodontidae"

## Get AphiaID via an external ID

    wm_external(id = 1080)
    #> [1] 85257
    wm_external(id = 105706)
    #> [1] 159854

## Get vernacular names from an AphiaID

    wm_common_id(id = 156806)
    #> # A tibble: 2 x 3
    #>   vernacular          language_code language
    #>   <chr>               <chr>         <chr>
    #> 1 gilded wedgeclam    eng           English
    #> 2 Turton's wedge clam eng           English

## Children

Get direct taxonomic children for an AphiaID

    wm_classification(id = 105706)
    #> # A tibble: 11 x 3
    #>    AphiaID rank       scientificname
    #>      <int> <chr>      <chr>
    #>  1       2 Kingdom    Animalia
    #>  2    1821 Phylum     Chordata
    #>  3  146419 Subphylum  Vertebrata
    #>  4    1828 Superclass Gnathostomata
    #>  5   11676 Superclass Pisces
    #>  6   10193 Class      Elasmobranchii
    #>  7  368407 Subclass   Neoselachii
    #>  8  368408 Infraclass Selachii
    #>  9  368410 Superorder Galeomorphi
    #> 10   10208 Order      Orectolobiformes
    #> 11  105706 Family     Rhincodontidae

## Classification

Get classification for an AphiaID

    wm_classification(id = 105706)
    #> # A tibble: 11 x 3
    #>    AphiaID rank       scientificname
    #>      <int> <chr>      <chr>
    #>  1       2 Kingdom    Animalia
    #>  2    1821 Phylum     Chordata
    #>  3  146419 Subphylum  Vertebrata
    #>  4    1828 Superclass Gnathostomata
    #>  5   11676 Superclass Pisces
    #>  6   10193 Class      Elasmobranchii
    #>  7  368407 Subclass   Neoselachii
    #>  8  368408 Infraclass Selachii
    #>  9  368410 Superorder Galeomorphi
    #> 10   10208 Order      Orectolobiformes
    #> 11  105706 Family     Rhincodontidae

## Synonyms

Get synonyms for an AphiaID

    wm_synonyms(id = 105706)
    #> # A tibble: 1 x 27
    #>   AphiaID url   scientificname authority status unacceptreason taxonRankID rank
    #>     <int> <chr> <chr>          <chr>     <chr>  <chr>                <int> <chr>
    #> 1  148832 http… Rhiniodontidae Müller &… unacc… synonym                140 Fami…
    #> # … with 19 more variables: valid_AphiaID <int>, valid_name <chr>,
    #> #   valid_authority <chr>, parentNameUsageID <int>, kingdom <chr>,
    #> #   phylum <chr>, class <chr>, order <chr>, family <chr>, genus <lgl>,
    #> #   citation <chr>, lsid <chr>, isMarine <lgl>, isBrackish <lgl>,
    #> #   isFreshwater <lgl>, isTerrestrial <lgl>, isExtinct <lgl>, match_type <chr>,
    #> #   modified <chr>

## attributes (i.e., traits)

attribute definition by ID

    wm_attr_def(id = 1)
    #> # A tibble: 1 x 4
    #>   measurementTypeID measurementType        CategoryID children
    #>               <int> <chr>                       <int> <list>
    #> 1                 1 IUCN Red List Category          1 <df[,4] [2 × 4]>

attribute data by AphiaID

    wm_attr_data(id = 127160)
    #> # A tibble: 24 x 10
    #>    AphiaID measurementType… measurementType measurementValue source_id reference
    #>    <chr>              <int> <chr>           <chr>                <int> <chr>
    #>  1 127160                23 Species import… FAO-ASFIS: Spec…    197354 "FAO Fis…
    #>  2 127160                23 Species import… MSFD indicators     197546 "Daniel …
    #>  3 127160                23 Species import… MSFD indicators     197549 "ICES. 2…
    #>  4 127160                23 Species import… MSFD indicators     197615 "List of…
    #>  5 127160                23 Species import… MSFD indicators     197615 "List of…
    #>  6 127160                23 Species import… MSFD indicators     197615 "List of…
    #>  7 127160                23 Species import… MSFD indicators     197615 "List of…
    #>  8 127160                23 Species import… MSFD indicators     197616 "List of…
    #>  9 127160                23 Species import… MSFD indicators     197616 "List of…
    #> 10 127160                23 Species import… MSFD indicators     197549 "ICES. 2…
    #> # … with 14 more rows, and 4 more variables: qualitystatus <chr>,
    #> #   AphiaID_Inherited <int>, CategoryID <int>, children <list>

attributes grouped by a CategoryID

    wm_attr_category(id = 7)
    #> # A tibble: 6 x 4
    #>   measurementValueID measurementValue measurementValueCode children
    #>                <int> <chr>            <chr>                <list>
    #> 1                183 benthos          <NA>                 <df[,4] [8 × 4]>
    #> 2                184 plankton         <NA>                 <df[,4] [7 × 4]>
    #> 3                194 nekton           <NA>                 <df[,0] [0 × 0]>
    #> 4                323 neuston          <NA>                 <df[,0] [0 × 0]>
    #> 5                378 edaphofauna      <NA>                 <df[,4] [2 × 4]>
    #> 6                331 not applicable   N/A                  <df[,0] [0 × 0]>

AphiaIDs by attribute definition ID

    wm_attr_aphia(id = 4)
    #> # A tibble: 50 x 2
    #>    AphiaID Attributes
    #>      <int> <list>
    #>  1      11 <df[,10] [1 × 10]>
    #>  2      55 <df[,10] [2 × 10]>
    #>  3      57 <df[,10] [2 × 10]>
    #>  4      58 <df[,10] [2 × 10]>
    #>  5      59 <df[,10] [2 × 10]>
    #>  6      63 <df[,10] [2 × 10]>
    #>  7      64 <df[,10] [2 × 10]>
    #>  8      69 <df[,10] [2 × 10]>
    #>  9      90 <df[,10] [2 × 10]>
    #> 10      91 <df[,10] [2 × 10]>
    #> # … with 40 more rows