Match taxa to WoRMS aphia_id and update database

Match taxa in the provided field fld of the data frame df to the unique WoRMS identifier (aphia_id) and return df with prepended aphia_id column. Update database tables taxa_wm with full WoRMS taxonomic records and metadata on uniquely matching taxa in database table taxa also using fields tbl_str and fld_str.

wm_add_aphia_id(
  df,
  fld,
  tbl_str = deparse(substitute(df)),
  fld_str = deparse(substitute(fld))
)

Arguments

df

data frame

fld

unquoted field name containing taxonomic field, eg taxa

tbl_str

the source table to be written into the database referenced in taxa.tbl

fld_str

the source field to be written into the database referenced in taxa.fld

Value

the original data frame df with aphia_id column prepended

Details

Perform the match with the following order of precedence:

1. Existing match for in the database taxa table

2. Exact match in WoRMS REST API with wm_rest() having operation="AphiaRecordsByMatchNames"

3. Fuzzy match in WoRMS REST API with wm_rest() having operation="AphiaRecordsByNames"

With all possible matches made, proceed to:

1. Prepend the input data frame df with the matched column aphia_id.

2. Populate taxa table in database with rows containing:

   • tbl: tbl_str

   • fld: fld_str

   • taxa: unique values of fld

   • aphia_id: matching WoRMS identifier, possibly NA if no match found

3. Fetch full WoRMS records for any new taxa.aphia_ids using wm_rest() with operation="AphiaRecordsByAphiaIDs", and append to taxa_wm table.

Examples

if (FALSE) {
tmp_test <- tibble::tribble(
        ~common,                  ~scientific,
  "Minke whale",  "Balaenoptera acutorostrata",
   "Blue whale",  "Balaenoptera musculus")
wm_add_aphia_id(df_test, scientific, tbl_str = "tmp_test")
}