get_datasets {neotoma2}

get_datasets

Description

The get_datasets() function is a wrapper for the Neotoma datasets API endpoint. The function takes parameters defined by the user and returns dataset information supplied by the Neotoma Paleoecological Database. The user may define all or none of the possible fields.

Usage

get_datasets(x = NA, ...)

Arguments

x

A single datasetid, or a vector of unique dataset ids.

...

accepted arguments, see details for more information.

Details

A dataset is an element nested within neotoma2 site objects. The get_datasets() call returns a list of individual site objects with collunits (collection units) that contain valid, matching dataset elements. So, get_sites() returns only site metadata. get_datasets() returns site metadata, plus metadata about the individual datasets present at that site. The get_datasets() function searches for each site within Neotoma that matches the query parameters, and returns them as a sites object, a list of site objects, plus returns all the additional metadata for the datasets at that site. The get_datasets() command wraps the Neotoma API (api.neotomadb.org) call for datasets. The call itself uses a SQL query which accepts any one of the following parameters:

• siteid The unique site ID (integer) in Neotoma. Can be passed as a vector of site IDs.

• sitename The site name, or approximate match using the % wildcard.

• database The constituent database for the record. See get_table("constituentdatabases")

• datasettype Neotoma contains data for a number of dataset types. This returns a subset of data types. For a complete list of available dataset types, run neotoma2::get_table('datasettypes')

• altmin The minimum altitude range for site elevation (in meters).

• altmax The maximum altitude range for site elevation (in meters).

• datasetid The unique dataset ID (integer) in Neotoma. Can be passed as a vector of dataset IDs.

• doi The dataset DOI for a dataset contained within a site. Can be passed as a vector of DOIs.

• gpid The geopolitical name or identifier containing a site. Can be passed as a vector of names.

• keywords Keywords for samples within a set of sites. For example "modern" indicates a sample within the record uses the keyword "modern".

• contacts Contact names or IDs associated with a site.

• ageyoung A minimum spanning age for the record, in years before radiocarbon present (1950).

• ageold A maximum spanning age for the record, in years before radiocarbon present (1950).

• ageof An age which must be contained within the range of sample ages for a site.

• taxa The names of taxa which must be present within samples in a record.

• all_data The API only downloads the first 25 records of the query. For the complete records, use all_data=TRUE

Value

The function returns either a single item of class "try-error" describing the reason for failure (either misdefined parameters or an error from the Neotoma API), or list of site objects, each containing one or more collunit objects, with fully populated datasets elements.

Author(s)

Socorro Dominguez [e-mail]

Examples

# To find all datasets with a min altitude of 12 and a max altitude of 25:
sites_12to25 <- get_datasets(altmin=12, altmax=25)
# To find all datasets in Brazil
brazil <- '{"type": "Polygon",
"coordinates": [[
 [-73.125, -9.102096738726443],
 [-56.953125,-33.137551192346145],
 [-36.5625,-7.710991655433217],
 [-68.203125,13.923403897723347],
 [-73.125,-9.102096738726443]]]}'
brazil_datasets <- get_datasets(loc = brazil[1], limit=2)
# To obtain the dataset metadata:
datasets(brazil_datasets)
# There is insufficient metadata at this point to obtain information
# about taxa present at the site. We must use get_downloads() to
# obtain the full set of sample information:
# This fails: taxa(brazil_datasets)