| Title: | ICES Vocabularies Database Web Services |
|---|---|
| Description: | R interface to access the Vocabularies REST API of the ICES (International Council for the Exploration of the Sea) Vocabularies database <https://vocab.ices.dk/services/>. |
| Authors: | Colin Millar [aut, cre], Arni Magnusson [aut] |
| Maintainer: | Colin Millar <[email protected]> |
| License: | GPL-3 |
| Version: | 1.3.0 |
| Built: | 2025-01-31 19:17:10 UTC |
| Source: | https://github.com/ices-tools-prod/icesVocab |
R interface to access the web services of the ICES Vocabularies database of reference codes.
Get full tables:
getCodeTypeList |
all code code types |
getCodeList |
codes of a given type |
getCodeDetail |
details for a given code |
Look up specific codes:
findAphia |
species code |
Colin Millar and Arni Magnusson.
ICES Vocabularies database: http://vocab.ices.dk.
ICES Vocabularies web services: http://vocab.ices.dk/services/POX.aspx.
Useful links:
Report bugs at https://github.com/ices-tools-prod/icesVocab/issues
Look up Aphia code for a given species.
findAphia(species, latin = FALSE, regex = FALSE, full = FALSE)findAphia(species, latin = FALSE, regex = FALSE, full = FALSE)
species |
the species name, either in English (default) or Latin. |
latin |
whether the species name is in Latin. |
regex |
whether to match the species name as a regular expression. |
full |
whether to return a data frame with all species columns. |
Species name matches are case-insensitive.
A vector of Aphia codes (default) or a data frame if full is TRUE.
Arni Magnusson.
getCodeList can be used to get all Aphia codes; see example on
that help page.
icesVocab-package gives an overview of the package.
## Not run: findAphia("cod") findAphia("Gadus morhua", latin = TRUE) # Multiple matches findAphia(c("cod", "haddock", "saithe")) # Regular expressions findAphia("ray", regex = TRUE, full = TRUE) findAphia("Sebastes", latin = TRUE, regex = TRUE, full = TRUE) ## End(Not run)## Not run: findAphia("cod") findAphia("Gadus morhua", latin = TRUE) # Multiple matches findAphia(c("cod", "haddock", "saithe")) # Regular expressions findAphia("ray", regex = TRUE, full = TRUE) findAphia("Sebastes", latin = TRUE, regex = TRUE, full = TRUE) ## End(Not run)
Look up a key for a given code and code type.
findCode(code_type, code, regex = TRUE, full = FALSE)findCode(code_type, code, regex = TRUE, full = FALSE)
code_type |
a search string for a code type, e.g. SpecWorms, or simply worms. |
code |
a search string for a code, e.g. a species name, cod, or ship name, Clupea. |
regex |
whether to match as a regular expression. |
full |
whether to return a data frame. |
Matches are case-insensitive.
A vector of keys (default) or a data frame if full is TRUE.
getCodeList can be used to get all code types; see example on
that help page.
icesVocab-package gives an overview of the package.
## Not run: findCode("aphia", "cod") # Multiple matches findCode("aphia", c("cod", "haddock", "saithe"), full = TRUE) findCodeType("ship", full = TRUE) findCode("ship", "clupea", full = TRUE) ## End(Not run)## Not run: findCode("aphia", "cod") # Multiple matches findCode("aphia", c("cod", "haddock", "saithe"), full = TRUE) findCodeType("ship", full = TRUE) findCode("ship", "clupea", full = TRUE) ## End(Not run)
Find a lookup key corresponding to a code type.
findCodeType(code, date = NULL, regex = TRUE, full = FALSE)findCodeType(code, date = NULL, regex = TRUE, full = FALSE)
code |
a code name, e.g. Gear Type, or DATRAS to find all DATRAS related codes. |
date |
restrict output to code types modified after a given date in yyyy-mm-dd format, e.g. "2010-12-01" |
regex |
whether to match the stock name as a regular expression. |
full |
whether to return a data frame with all stock list columns. |
A vector of keys (default) or a data frame if full is TRUE.
getCodeTypeList gets a list of code types.
icesVocab-package gives an overview of the package.
## Not run: findCodeType("worms") findCodeType("DATRAS", full = TRUE) findCodeType("DATRAS", full = TRUE, date = "2010-01-01") ## End(Not run)## Not run: findCodeType("worms") findCodeType("DATRAS", full = TRUE) findCodeType("DATRAS", full = TRUE, date = "2010-01-01") ## End(Not run)
Get details for a given code.
getCodeDetail(code_type, code)getCodeDetail(code_type, code)
code_type |
the code type, e.g. SpecWoRMS. |
code |
the code, e.g. 101170. |
A data frame.
getCodeTypeList and getCodeList get code types
and codes of a given type.
icesVocab-package gives an overview of the package.
## Not run: # Species code 101170 - Myxine glutinosa getCodeDetail("SpecWoRMS", 101170) # find details of Haddock using the aphia ID findCode("species", "haddock", full = TRUE) getCodeDetail("SpecWoRMS", 126437) # get info for had-34 getCodeDetail("ICES_StockCode", "had-34") ## End(Not run)## Not run: # Species code 101170 - Myxine glutinosa getCodeDetail("SpecWoRMS", 101170) # find details of Haddock using the aphia ID findCode("species", "haddock", full = TRUE) getCodeDetail("SpecWoRMS", 126437) # get info for had-34 getCodeDetail("ICES_StockCode", "had-34") ## End(Not run)
Get codes of a given code type.
getCodeList(code_type, code = NULL, date = NULL)getCodeList(code_type, code = NULL, date = NULL)
code_type |
the code type, e.g. SpecWoRMS. |
code |
optional code to restrict output to. |
date |
restrict output to codes modified after a given date in yyyy-mm-dd format, e.g. "2010-12-01". |
A data frame.
getCodeTypeList and getCodeDetail get code types
and code details.
findCodeType and findAphia provide support for searching the code type and code lists.
icesVocab-package gives an overview of the package.
## Not run: # Aphia Species codes findCodeType("aphia", full = TRUE) codes <- getCodeList("SpecWoRMS") head(codes) findCode("ship", "clupea", full = TRUE) getCodeList("ICES_Area") getCodeList("ICES_Area", code = "27.4.a") ## End(Not run)## Not run: # Aphia Species codes findCodeType("aphia", full = TRUE) codes <- getCodeList("SpecWoRMS") head(codes) findCode("ship", "clupea", full = TRUE) getCodeList("ICES_Area") getCodeList("ICES_Area", code = "27.4.a") ## End(Not run)
Get all code types. Mainly useful as a reminder of what code types are available.
getCodeTypeList(code_type = NULL, date = NULL)getCodeTypeList(code_type = NULL, date = NULL)
code_type |
optional parameter to restrict output to a specific code type. |
date |
restrict output to code types modified after a given date in yyyy-mm-dd format, e.g. "2010-12-01" |
A data frame.
getCodeList and getCodeDetail get codes of a
given type and code details.
findCodeType searches for a code types based on a search string.
icesVocab-package gives an overview of the package.
## Not run: # Find code type for World Register of Marine Species (WoRMS) types <- getCodeTypeList() types[grep("worms", tolower(types$Description)),] # The code type "SpecWoRMS" can be used when calling getCodeTypeList() getCodeTypeList(code_type = "SpecWoRMS") # or using the guid getCodeTypeList(code_type = "f107b677-97ff-4cd9-b4ab-637bb6706066") findCodeType("worms", full = TRUE) ## End(Not run)## Not run: # Find code type for World Register of Marine Species (WoRMS) types <- getCodeTypeList() types[grep("worms", tolower(types$Description)),] # The code type "SpecWoRMS" can be used when calling getCodeTypeList() getCodeTypeList(code_type = "SpecWoRMS") # or using the guid getCodeTypeList(code_type = "f107b677-97ff-4cd9-b4ab-637bb6706066") findCodeType("worms", full = TRUE) ## End(Not run)
Get details for a given code.
getCodeTypeRelation(code_type, linked_code_type, rename = TRUE)getCodeTypeRelation(code_type, linked_code_type, rename = TRUE)
code_type |
an ICES Vocabulary code type. |
linked_code_type |
another ICES Vocabulary code type. |
rename |
logical, if TRUE (default) the columns of the output is renamed to the code type and linked code type |
A data frame.
getCodeTypeList and getCodeList get code types
and codes of a given type.
icesVocab-package gives an overview of the package.
## Not run: x <- getCodeTypeRelation("Pargroup", "PARAM") # get all stocks in subarea 4a # note you would need to cross check with icesSD for # currently active stocks lookup <- getCodeTypeRelation("ICES_Area", "ICES_StockCode") lookup[lookup$ICES_Area == "27.4.a", ] # get relation between stock code and area, unformatted output lookup_raw <- getCodeTypeRelation("ICES_StockCode", "ICES_Area", rename = FALSE) head(lookup_raw) ## End(Not run)## Not run: x <- getCodeTypeRelation("Pargroup", "PARAM") # get all stocks in subarea 4a # note you would need to cross check with icesSD for # currently active stocks lookup <- getCodeTypeRelation("ICES_Area", "ICES_StockCode") lookup[lookup$ICES_Area == "27.4.a", ] # get relation between stock code and area, unformatted output lookup_raw <- getCodeTypeRelation("ICES_StockCode", "ICES_Area", rename = FALSE) head(lookup_raw) ## End(Not run)
Find parent or child linkages between the codes of two code types.
linkCodes(code_type, linked_code_type, codes = NULL, ...)linkCodes(code_type, linked_code_type, codes = NULL, ...)
code_type |
an ICES Vocabulary code type. |
linked_code_type |
another ICES Vocabulary code type. |
codes |
a vector of codes to restrict the output to. |
... |
for back compatibility. |
A data frame.
Colin Millar.
icesVocab-package gives an overview of the package.
## Not run: x <- linkCodes("Pargroup", "PARAM") # note it is much faster to use: # getCodeTypeRelation("Pargroup", "PARAM") # when getting a full lookup table. # get all areas for cod.27.1-2 linkCodes("ICES_StockCode", "ICES_Area", codes = c("cod.27.1-2")) # get areas for cod.27.21, cod.27.24-32 and cod.27.46a7d20 linkCodes("ICES_StockCode", "ICES_Area", codes = c("cod.27.21", "cod.27.24-32", "cod.27.46a7d20")) ## End(Not run)## Not run: x <- linkCodes("Pargroup", "PARAM") # note it is much faster to use: # getCodeTypeRelation("Pargroup", "PARAM") # when getting a full lookup table. # get all areas for cod.27.1-2 linkCodes("ICES_StockCode", "ICES_Area", codes = c("cod.27.1-2")) # get areas for cod.27.21, cod.27.24-32 and cod.27.46a7d20 linkCodes("ICES_StockCode", "ICES_Area", codes = c("cod.27.21", "cod.27.24-32", "cod.27.46a7d20")) ## End(Not run)
utility to build a url with optional query arguments
vocab_api(service, ...)vocab_api(service, ...)
service |
the name of the service |
... |
name arguments will be added as queries |
a complete url as a character string
vocab_api("hi", bye = 21) vocab_api("CodeType")vocab_api("hi", bye = 21) vocab_api("CodeType")
Get a url, optionally using an ICES authentication token
vocab_get( url, retry = TRUE, quiet = !getOption("icesVocab.messages"), verbose = FALSE, content = TRUE ) vocab_get_cached( url, retry = TRUE, quiet = !getOption("icesVocab.messages"), verbose = FALSE, content = TRUE )vocab_get( url, retry = TRUE, quiet = !getOption("icesVocab.messages"), verbose = FALSE, content = TRUE ) vocab_get_cached( url, retry = TRUE, quiet = !getOption("icesVocab.messages"), verbose = FALSE, content = TRUE )
url |
the url to get. |
retry |
should the get request be retried if first attempt fails? default TRUE. |
quiet |
should all messages be suppressed, default FALSE. |
verbose |
should verbose output form the http request be returned? default FALSE. |
content |
should content be returned, or the full http response? default TRUE, i.e. content is returned by default. |
content or an http response.
vocab_get_cached(): cached version of vocab_get
vocab_api builds a SAG web service url.
icesVocab-package gives an overview of the package.
## Not run: vocab_get(vocab_api("StockList", year = 2022)) ## End(Not run)## Not run: vocab_get(vocab_api("StockList", year = 2022)) ## End(Not run)