Specimen operations

This client connects to all Specimen-related endpoints of the NBA. Each endpoint is available as a class method (see section 'Methods' below). Optionally, a custom URL pointing to a NBA server and a user Agent can be specified by the user (see section 'Fields' below).

# client <- SpecimenClient$new()

Format

R6 class

Fields

basePath

Stores url path of the request, defaults to http://api.biodiversitydata.nl/v2

userAgent

Set the user agent of the request, defaults to nbaR/0.1.0

Methods

count

Get the number of specimens matching a given condition; Conditions given as query parameters or a querySpec JSON. Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• queryParams : named list or vector with query parameters

• ... : additional parameters passed to httr::GET

Returns: integer

count_distinct_values

Count the distinct number of values that exist for a given field; See also endpoint /getDistinctValues. Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• field : Name of field in the specimen object

• queryParams : named list or vector with query parameters

• ... : additional parameters passed to httr::GET

Returns: integer

count_distinct_values_per_group

Count the distinct number of field values that exist per the given field to group by; See also endpoint /getDistinctValuesPerGroup. Parameters:

• group : Name of field in the specimen object you want to group by

• field : Name of field in the specimen object

• ... : additional parameters passed to httr::GET

Returns: list

download_query

Dynamic download service: Query for specimens and return result as a stream ...; Query with query parameters or querySpec JSON. .... Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• queryParams : named list or vector with query parameters

• ... : additional parameters passed to httr::GET

Returns: Specimen

dwca_get_data_set

Download dataset as Darwin Core Archive File; Available datasets can be queried with /specimen/dwca/getDataSetNames. Response saved to <datasetname>-<yyyymmdd>.dwca.zip. Parameters:

• dataset : name of dataset

• filename : location to save data, defaults to format(Sys.time(), "download-%Y-%m-%dT%H:%m.zip")

• ... : additional parameters passed to httr::GET

Returns:

dwca_get_data_set_names

Retrieve the names of all available datasets; Individual datasets can then be downloaded with /dwca/getDataSet/dataset. Parameters:

• ... : additional parameters passed to httr::GET

Returns: character

dwca_query

Dynamic download service: Query for specimens and return result as Darwin Core Archive File; Query with query parameters or querySpec JSON. Response saved to nba-specimens.dwca.zip. Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• queryParams : named list or vector with query parameters

• filename : location to save data, defaults to format(Sys.time(), "download-%Y-%m-%dT%H:%m.zip")

• ... : additional parameters passed to httr::GET

Returns:

exists

Returns whether or not a unitID for a specimen exists; Returns either true or false. Parameters:

• unit_id : the unitID of the specimen to query

• ... : additional parameters passed to httr::GET

Returns: logical

find

Find a specimen by id; If found, returns a single specimen. Parameters:

• id : id of specimen

• ... : additional parameters passed to httr::GET

Returns: Specimen

find_by_ids

Find specimens by ids; Given multiple ids, returns a list of specimen. Parameters:

• ids : ids of multiple specimen, separated by comma

• ... : additional parameters passed to httr::GET

Returns: Specimen

find_by_unit_id

Find a specimen by unitID; Get a specimen by its unitID. Returns a list of specimens since unitIDs are not strictly unique. Parameters:

• unit_id : the unitID of the specimen to query

• ... : additional parameters passed to httr::GET

Returns: Specimen

get_distinct_values

Get all different values that exist for a field; A list of all fields for specimen documents can be retrieved with /metadata/getFieldInfo. Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• field : Name of field in specimen object

• queryParams : named list or vector with query parameters

• ... : additional parameters passed to httr::GET

Returns: list

get_distinct_values_per_group

Get all distinct values (and their document count) for the field given divided per distinct value of the field to group by; See also endpoint /getDistinctValues. Parameters:

• group : Name of field in the specimen object you want to group by

• field : Name of field in the specimen object

• ... : additional parameters passed to httr::GET

Returns: list

get_field_info

Returns extended information for each field of a specimen document; Info consists of whether the fields is indexed, the ElasticSearch datatype and a list of allowed operators. Parameters:

• ... : additional parameters passed to httr::GET

Returns: list

get_ids_in_collection

Retrieve all ids within a 'special collection' of specimens; Available collections can be queried with /getNamedCollections. Parameters:

• name : name of dataset

• ... : additional parameters passed to httr::GET

Returns: character

get_named_collections

Retrieve the names of all 'special collections' of specimens; See also here: http://bioportal.naturalis.nl/collecties. Parameters:

• ... : additional parameters passed to httr::GET

Returns: character

get_paths

Returns the full path of all fields within a document; See also metadata/getFieldInfo for all allowed operators per field. Parameters:

• ... : additional parameters passed to httr::GET

Returns: character

get_setting

Get the value of an NBA setting; All settings can be queried with /metadata/getSettings. Parameters:

• name : name of setting

• ... : additional parameters passed to httr::GET

Returns: list

get_settings

List all publicly available configuration settings for the NBA; The value of a specific setting can be queried with metadata/getSetting/name. Parameters:

• ... : additional parameters passed to httr::GET

Returns: list

group_by_scientific_name

Aggregates Taxon and Specimen documents according to their scientific names; Returns a list with ScientificNameGroups, which contain Taxon and Specimen documents that share a scientific name. Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• queryParams : named list or vector with query parameters

• ... : additional parameters passed to httr::GET

Returns: QueryResult

is_operator_allowed

Checks if a given operator is allowed for a given field; See also metadata/getFieldInfo. Parameters:

• field : specimen document field

• operator : operator

• ... : additional parameters passed to httr::GET

Returns: logical

query

Query for specimens; Search for specimens (GET) using query parameters or a querySpec JSON. Parameters:

• query_spec : Object of type QuerySpec or its JSON representation

• queryParams : named list or vector with query parameters

• ... : additional parameters passed to httr::GET

Returns: QueryResult