Package ritis. May 23, 2018

Transcription

1 Package ritis May 23, 2018 Title Integrated Taxonomic Information System Client An interface to the Integrated Taxonomic Information System ('ITIS') (< Includes functions to work with the 'ITIS' REST 'API' methods (< as well as the 'Solr' web service (< Version License MIT + file LICENSE URL BugReports VignetteBuilder knitr Imports solrium (>= 1.0.0), crul (>= 0.4.0), jsonlite (>= 1.5), data.table (>= 1.9.6), tibble (>= 1.3.4) Suggests roxygen2 (>= 6.0.1), knitr, testthat, webmockr, vcr RoxygenNote NeedsCompilation no Author Scott Chamberlain [aut, cre] (< Maintainer Scott Chamberlain <myrmecocystus@gmail.com> Repository CRAN Date/Publication :06:51 R topics documented: ritis-package accepted_names any_match_count comment_detail common_names core_metadata coverage credibility

2 2 R topics documented: currency date_data description experts full_record geographic_divisions geographic_values global_species_completeness hierarchy itis_facet itis_group itis_highlight itis_search jurisdiction kingdoms last_change_date lsid other_sources parent_ publications rank_name rank_names record review_year scientific_name search_anymatch search_any_match_paged search_common search_scientific solr synonym_names taxon_authorship terms lsid _by_vernacular_language unacceptability_reason usage vernacular_languages Index 37

3 ritis-package 3 ritis-package Interface to Integrated Taxonomic Information (ITIS) Interface to Integrated Taxonomic Information (ITIS) ritis package API All functions that start with itis_ work with the ITIS Solr API described at gov/solr_documentation.html, which uses the package solrium, and these functions have you use the solrium function interfaces, so you can pass on parameters to the solrium functions - so the solrium docs are important here. All other functions work with the ITIS REST API described at html. For these methods, they can grab data in either JSON or XML format. JSON is the default. We parse the JSON to R native format, either data.frame, character string, or list. You can get JSON as a character string back, or XML as a character string, and then parse yourself with jsonlite or xml2 Author(s) Scott Chamberlain <myrmecocystus@gmail.com> accepted_names Get accepted names from Get accepted names from accepted_names(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default:

4 4 any_match_count Zero row data.frame if the name is accepted, otherwise a data.frame with information on the currently accepted name # TSN accepted - good name accepted_names( = ) # TSN not accepted - input TSN is old name accepted_names( = ) # json accepted_names( = , = TRUE) any_match_count Get any match count. Get any match count. any_match_count(x, = "json", =,...) x text or taxonomic serial number (TSN) (character or numeric) (logical) Return JSON or XML as character string. Required. Default: An integer containing the number of matches the search will return. any_match_count(x = ) any_match_count(x = "dolphin") any_match_count(x = "dolphin", = "xml")

5 comment_detail 5 comment_detail Get comment detail from TSN Get comment detail from TSN comment_detail(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: A data.frame with results. comment_detail(=180543) comment_detail(=180543, = "xml") common_names Get common names from Get common names from common_names(, = "json", =,...)

6 6 core_metadata (logical) Return JSON or XML as character string. Required. Default: a data.frame common_names(=183833) common_names(=183833, = "xml") core_metadata Get core metadata from Get core metadata from core_metadata(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default:

7 coverage 7 # coverage and currrency data core_metadata(=28727) core_metadata(=28727, = "xml") # no coverage or currrency data core_metadata(183671) core_metadata(183671, = "xml") coverage Get coverge from Get coverge from coverage(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: # coverage data coverage(=28727) # no coverage data coverage(526852) coverage(526852, = "xml")

8 8 credibility credibility Get credibility rating from Get credibility rating from credibility_rating(, = "json", =,...) credibility_ratings( = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: Details methods: credibility_rating: Get credibility rating for a credibility_ratings: Get possible credibility ratings a data.frame credibility_rating( = ) credibility_rating(526852, = "xml") credibility_rating(526852, = TRUE) credibility_ratings() credibility_ratings( = "xml") credibility_ratings( = TRUE)

9 currency 9 currency Get currency from Get currency from currency(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a data.frame # currency data currency(=28727) currency(=28727, = "xml") # no currency dat currency(526852) currency(526852, = TRUE) date_data Get date data from Get date data from date_data(, = "json", =,...)

10 10 description (logical) Return JSON or XML as character string. Required. Default: date_data( = ) date_data(180543, = "xml") date_data(180543, = "json", = TRUE) description Get description of the ITIS service Get description of the ITIS service description( = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a string, the ITIS web service description description() description( = "xml")

11 experts 11 experts Get expert information for the TSN. Get expert information for the TSN. experts(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: experts( = ) experts(180544, = "xml") experts(180544, = TRUE) full_record Get full record from TSN or lsid Get full record from TSN or lsid full_record( = NULL, lsid = NULL, = "json", =,...) lsid lsid for a taxonomic group (character) (logical) Return JSON or XML as character string. Required. Default:

12 12 geographic_divisions # from full_record( = 50423) full_record( = ) full_record( = ) full_record( = , = "xml") full_record( = , = TRUE) # from lsid full_record(lsid = "urn:lsid:itis.gov:itis_:180543") full_record(lsid = "urn:lsid:itis.gov:itis_:180543") geographic_divisions Get geographic divisions from Get geographic divisions from geographic_divisions(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: geographic_divisions( = ) geographic_divisions( = , = "xml") geographic_divisions( = , = "json", = TRUE)

13 geographic_values 13 geographic_values Get all possible geographic values Get all possible geographic values geographic_values( = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: character vector of geographic names geographic_values() geographic_values( = "xml") geographic_values( = "json", = TRUE) global_species_completeness Get global species completeness from Get global species completeness from global_species_completeness(, = "json", =,...)

14 14 hierarchy (logical) Return JSON or XML as character string. Required. Default: global_species_completeness( = ) global_species_completeness(180541, = "xml") global_species_completeness(180541, = "json", = TRUE) hierarchy Get hierarchy down from Get hierarchy down from hierarchy_down(, = "json", =,...) hierarchy_up(, = "json", =,...) hierarchy_full(, = "json", =,...) Details (logical) Return JSON or XML as character string. Required. Default: Hierarchy methods: hierarchy_down: Get hierarchy down from hierarchy_up: Get hierarchy up from hierarchy_full: Get full hierarchy from

15 itis_facet 15 ## Full down (class Mammalia) hierarchy_down(=179913) ## Full up (genus Agoseris) hierarchy_up(=36485) ## Full hierarchy ### genus Liatris hierarchy_full(=37906) ### get data back hierarchy_full(=37906, = TRUE) ### genus Baetis, get xml back hierarchy_full(100800, = "xml") itis_facet ITIS Solr facet ITIS Solr facet itis_facet(..., proxy = NULL, callopts = list())... passed on to the params parameter of the solrium::solr_facet() function proxy callopts List of arguments for a proxy connection, including one or more of: url, port, username, password, and auth. See crul::proxy() for help, which is used to construct the proxy connection. Curl options passed on to crul::httpclient itis_facet(q = "rank:species", rows = 0, facet.field = "kingdom")$facet_fields x <- itis_facet(q = "hierarchysofar:*$aves$* AND rank:species AND usage:valid", facet.pivot = "namewind,vernacular", facet.limit = -1, facet.mincount = 1, rows = 0) head(x$facet_pivot$ namewind,vernacular )

16 16 itis_highlight itis_group ITIS Solr group search ITIS Solr group search itis_group(..., proxy = NULL, callopts = list())... passed on to the params parameter of the solrium::solr_group() function proxy List of arguments for a proxy connection, including one or more of: url, port, username, password, and auth. See crul::proxy() for help, which is used to construct the proxy connection. callopts Curl options passed on to crul::httpclient x <- itis_group(q = "namewoind:/[a-za-z0-9]*[%20]{1,1}[a-za-z0-9]*/", group.field = 'rank', group.limit = 3) head(x) itis_highlight ITIS Solr highlight ITIS Solr highlight itis_highlight(..., proxy = NULL, callopts = list())... passed on to the params parameter of the solrium::solr_highlight() function proxy List of arguments for a proxy connection, including one or more of: url, port, username, password, and auth. See crul::proxy() for help, which is used to construct the proxy connection. callopts Curl options passed on to crul::httpclient

17 itis_search 17 itis_highlight(q = "rank:species", hl.fl = 'rank', rows=10) itis_search ITIS Solr search ITIS Solr search itis_search(..., proxy = NULL, callopts = list())... passed on to the params parameter of the solrium::solr_search() function proxy List of arguments for a proxy connection, including one or more of: url, port, username, password, and auth. See crul::proxy() for help, which is used to construct the proxy connection. callopts Curl options passed on to crul::httpclient itis_search(q = ":182662") itis_search(q = "namewoind:liquidamber\\%20styraciflua~0.4") # matches only monomials itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{0,0}*/") # matches only binomials itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{1,1}[a-za-z0-9]*/") # matches only trinomials itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{1,1}[a-za-z0-9]*[%20]{1,1}[a-za-z0-9]*/") # matches binomials or trinomials itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{1,1}[a-za-z0-9]*[%20]{0,1}[a-za-z0-9]*/") itis_search(q = "namewoind:poa\\%20annua") itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{0,0}*/", rows = 2) itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{0,0}*/", rows = 200) itis_search(q = "namewoind:/[a-za-z0-9]*[%20]{0,0}*/", fl = c('namewind', ''))

18 18 jurisdiction jurisdiction Get jurisdictional origin from Get jurisdictional origin from jurisdictional_origin(, = "json", =,...) jurisdiction_origin_values( = "json", =,...) jurisdiction_values( = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: Details Jurisdiction methods: jurisdictional_origin: Get jurisdictional origin from jurisdiction_origin_values: Get jurisdiction origin values jurisdiction_values: Get all possible jurisdiction values jurisdictional_origin: data.frame jurisdiction_origin_values: data.frame jurisdiction_values: character vector jurisdictional_origin(=180543) jurisdictional_origin(=180543, = "xml") jurisdiction_origin_values() jurisdiction_values()

19 kingdoms 19 kingdoms Get kingdom names from Get kingdom names from kingdom_name(, = "json", =,...) kingdom_names( = "json", =,...) Details (logical) Return JSON or XML as character string. Required. Default: kingdom_name: Get kingdom name for a TSN kingdom_names: Get all possible kingdom names kingdom_name(202385) kingdom_name(202385, = "xml") kingdom_names() last_change_date Provides the date the ITIS database was last updated Provides the date the ITIS database was last updated last_change_date( = "json", =,...)

20 20 lsid2 (logical) Return JSON or XML as character string. Required. Default: character value with a date last_change_date() last_change_date( = "xml") lsid2 Gets the TSN corresponding to the LSID, or an empty result if there is no match. Gets the TSN corresponding to the LSID, or an empty result if there is no match. lsid2(lsid, = "json", =,...) lsid (character) lsid for a taxonomic group. Required. (logical) Return JSON or XML as character string. Required. Default: lsid2(lsid="urn:lsid:itis.gov:itis_:28726") lsid2(lsid="urn:lsid:itis.gov:itis_:28726", = "xml") lsid2("urn:lsid:itis.gov:itis_:0") lsid2("urn:lsid:itis.gov:itis_:0", = "xml")

21 other_sources 21 other_sources Returns a list of the other sources used for the TSN. Returns a list of the other sources used for the TSN. other_sources(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: other_sources(=182662) other_sources(=182662, = "xml") parent_ Returns the parent TSN for the entered TSN. Returns the parent TSN for the entered TSN. parent_(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default:

22 22 publications a data.frame parent_( = ) parent_( = , = TRUE) parent_( = , = "xml") publications Returns a list of the pulications used for the TSN. Returns a list of the pulications used for the TSN. publications(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a data.frame publications( = 70340) publications( = 70340, = "xml") publications( = 70340, verbose = TRUE)

23 rank_name 23 rank_name Returns the kingdom and rank information for the TSN. Returns the kingdom and rank information for the TSN. rank_name(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a data.frame, with rank name and other info rank_name( = ) rank_names Provides a list of all the unique rank names contained in the database and their kingdom and rank ID values. Provides a list of all the unique rank names contained in the database and their kingdom and rank ID values. rank_names( = "json", =,...)

24 24 record (logical) Return JSON or XML as character string. Required. Default: a data.frame, with columns: kingdomname rankid rankname rank_names() record Gets a record from an LSID Gets a record from an LSID record(lsid, = "json", =,...) lsid Details lsid for a taxonomic group (character). Required. (logical) Return JSON or XML as character string. Required. Default: Gets the partial ITIS record for the TSN in the LSID, found by comparing the TSN in the search key to the TSN field. Returns an empty result set if there is no match or the TSN is invalid.

25 review_year 25 a data.frame record(lsid = "urn:lsid:itis.gov:itis_:180543") review_year Returns the review year for the TSN. Returns the review year for the TSN. review_year(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a data.frame review_year( = )

26 26 search_anymatch scientific_name Returns the scientific name for the TSN. Also returns the component parts (names and indicators) of the scientific name. Returns the scientific name for the TSN. Also returns the component parts (names and indicators) of the scientific name. scientific_name(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a data.frame scientific_name( = ) search_anymatch Search for any match Search for any match search_anymatch(x, = "json", =,...)

27 search_any_match_paged 27 x text or taxonomic serial number (TSN) (character or numeric) (logical) Return JSON or XML as character string. Required. Default: a data.frame See Also search_any_match_paged search_anymatch(x = ) search_anymatch(x = "dolphin") search_any_match_paged Search for any matched page Search for any matched page search_any_match_paged(x, pagesize = NULL, pagenum = NULL, ascend = NULL, = "json", =,...) x pagesize pagenum ascend text or taxonomic serial number (TSN) (character or numeric) An integer containing the page size (numeric) An integer containing the page number (numeric) A boolean containing true for ascending sort order or false for descending (logical) (logical) Return JSON or XML as character string. Required. Default:

28 28 search_common See Also a data.frame a data.frame search_anymatch search_any_match_paged(x=202385, pagesize=100, pagenum=1, ascend=) search_any_match_paged(x="zy", pagesize=100, pagenum=1, ascend=) search_common Search for by common name Search for by common name search_common(x, from = "all", = "json", =,...) x from Details text or taxonomic serial number (TSN) (character or numeric) (character) One of "all", "begin", or "end". See Details. (logical) Return JSON or XML as character string. Required. Default: The from parameter: all - Search against the searchbycommonname API route, which searches entire name string begin - Search against the searchbycommonnamebeginswith API route, which searches for a match at the beginning of a name string end - Search against the searchbycommonnameendswith API route, which searches for a match at the end of a name string

29 search_scientific 29 a data.frame See Also search_scientific() search_common("american bullfrog") search_common("ferret-badger") search_common("polar bear") # comparison: all, begin, end search_common("inch") search_common("inch", from = "begin") search_common("inch", from = "end") # end search_common("snake", from = "end") search_scientific Search by scientific name Search by scientific name search_scientific(x, = "json", =,...) x text or taxonomic serial number (TSN) (character or numeric) (logical) Return JSON or XML as character string. Required. Default: a data.frame

30 30 synonym_names See Also search_common search_scientific("tardigrada") search_scientific("quercus douglasii") solr ITIS Solr Methods ITIS provides access to their data via their Solr service described at documentation.html. This is a powerful interace to ITIS data as you have access to a very flexible query interface. Functions itis_search() - Search itis_group() - Group itis_highlight() - Highlight itis_facet() - Facet synonym_names Returns a list of the synonyms (if any) for the TSN. Returns a list of the synonyms (if any) for the TSN. synonym_names(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default:

31 taxon_authorship 31 a data.frame synonym_names(=183671) # not accepted synonym_names(=526852) # accepted taxon_authorship Returns the author information for the TSN. Returns the author information for the TSN. taxon_authorship(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a data.frame taxon_authorship( = )

32 32 terms terms Get ITIS terms, i.e., s, authors, common names, and scientific names. Get ITIS terms, i.e., s, authors, common names, and scientific names. terms(query, what = "both", = "json", =,...) query what One or more common or scientific names, or partial names One of both (search common and scientific names), common (search just common names), or scientific (search just scientific names) (logical) Return JSON or XML as character string. Required. Default: # Get terms searching both common and scientific names terms(query='bear') # Get terms searching just common names terms(query='tarweed', "common") # Get terms searching just scientific names terms(query='poa annua', "scientific") # many at once terms(query=c('poa annua', 'Pinus contorta'), "scientific")

33 2lsid 33 2lsid Gets the unique LSID for the TSN, or an empty result if there is no match. Gets the unique LSID for the TSN, or an empty result if there is no match. 2lsid(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: a character string, an LSID, or NULL if nothing found 2lsid( = ) 2lsid( = ) 2lsid(155166, = TRUE) 2lsid(155166, = "xml") _by_vernacular_language Get by vernacular language Get by vernacular language _by_vernacular_language(language, = "json", =,...)

34 34 unacceptability_reason language A string containing the language. This is a language string, not the international language code (character) (logical) Return JSON or XML as character string. Required. Default: a data.frame _by_vernacular_language(language = "french") unacceptability_reason Returns the unacceptability reason, if any, for the TSN. Returns the unacceptability reason, if any, for the TSN. unacceptability_reason(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: unacceptability_reason( = )

35 usage 35 usage Returns the usage information for the TSN. Returns the usage information for the TSN. usage(, = "json", =,...) (logical) Return JSON or XML as character string. Required. Default: usage( = ) usage( = , = TRUE) usage( = , = "xml") vernacular_languages Provides a list of the unique languages used in the vernacular table. Provides a list of the unique languages used in the vernacular table. vernacular_languages( = "json", =,...) (logical) Return JSON or XML as character string. Required. Default:

36 36 vernacular_languages a character vector of verncular names vernacular_languages()

37 Index accepted_names, 3 any_match_count, 4 comment_detail, 5 common_names, 5 core_metadata, 6 coverage, 7 credibility, 8 credibility_rating (credibility), 8 credibility_ratings (credibility), 8 crul::httpclient, 3 35 crul::proxy(), currency, 9 date_data, 9 description, 10 experts, 11 full_record, 11 geographic_divisions, 12 geographic_values, 13 global_species_completeness, 13 hierarchy, 14 hierarchy_down (hierarchy), 14 hierarchy_full (hierarchy), 14 hierarchy_up (hierarchy), 14 itis_facet, 15 itis_facet(), 30 itis_group, 16 itis_group(), 30 itis_highlight, 16 itis_highlight(), 30 itis_search, 17 itis_search(), 30 jurisdiction, 18 jurisdiction_origin_values (jurisdiction), 18 jurisdiction_values (jurisdiction), 18 jurisdictional_origin (jurisdiction), 18 kingdom_name (kingdoms), 19 kingdom_names (kingdoms), 19 kingdoms, 19 last_change_date, 19 lsid2, 20 other_sources, 21 parent_, 21 publications, 22 rank_name, 23 rank_names, 23 record, 24 review_year, 25 ritis (ritis-package), 3 ritis-package, 3 scientific_name, 26 search_any_match_paged, 27, 27 search_anymatch, 26, 28 search_common, 28, 30 search_scientific, 29 search_scientific(), 29 solr, 30 solrium::solr_facet(), 15 solrium::solr_group(), 16 solrium::solr_highlight(), 16 solrium::solr_search(), 17 synonym_names, 30 taxon_authorship, 31 terms, 32 2lsid, 33 _by_vernacular_language, 33 37

38 38 INDEX unacceptability_reason, 34 usage, 35 vernacular_languages, 35