jsonOccFormulation: Create a JSON Query for GBIF's Occurrence API

In joechip90/PaGAn: Paleo-Geography Analysis Package

Create a JSON Query for GBIF's Occurrence API

Description

A function to create a JSON query for the occurrence download API of GBIF.

Usage

jsonOccFormulation(
  ...,
  user = NULL,
  email = NULL,
  sendNotification = TRUE,
  geodistance.values = NULL
)

Arguments

...	A set of queries to combine to create for GBIF's occurrence download API (see details below).
user	A character string containing a valid username associated with a GBIF account. If NULL then Sys.getenv('GBIF_USER') and getOptions('gbif_user') are searched for a value instead.
email	A character string containing a valid email associated with a GBIF account. If NULL then Sys.getenv('GBIF_EMAIL') and getOptions('gbif_email') are searched for a value instead.
sendNotification	A scalar logical that, if TRUE, adds a portion to the query that requests that an email be sent to the account specified in email when the download is ready.
geodistance.values	Argument is only used when using a 'geodistance' query (see details below).

Details

Queries to be converted to JSON are specified using named parameters. Any named parameter that shares a name with one of the parameters listed in GBIF's occurrence search API will be interpreted as a filter on the relevant records. For example, having an argument entitled COUNTRY with value "NO" will result a query that will only download records that have an ISO-3166-1 country code of NO (that is all record registered in Norway). If the vector provided for this argument has a length greater than one, then all records that match any of the composite values will be returned. These query types correspond to the 'equals' and 'in' predicates described in the occurrence download API document respectively. Other predicates can be specified by adding a suffix to the named argument. For example:

key.min

Will set a query that will only return records that have a value for the key that are greater than or equal to the value provided in the argument. For example, supplying YEAR.min = 1960 as an argument will result in a query that only returns records that have been collected from the year 1960 onward. There is also the suffix .xmin that can be used to create a query that will retrieve records only if they have a relevant value for key that are greater than the value provided in the argument.

key.max

Will set a query that will only return records that have a value for the key that are less than or equal to the value provided in the argument. For example, supplying YEAR.max = 1990 as an argument will result in a query that only returns records that have been collected in the year 1990 or earlier onward. There is also the suffix .xmax that can be used to create a query that will retrieve records only if they have a relevant value for key that are less than the value provided in the argument.

key.range

Will set a query that will only return records that have a value for the key that are greater than or equal to the minimum value and less than or equal to the maximum value provided in the vector of values provided for this argument. For example, supplying ELEVATION.range = c(400, 600) as an argument will result in a query that only returns records that have been collected at an elevation of between 400 and 600 metres above sea level.

key.like

Will set a query that will only return records that have a value for the key that match a pattern set in the value given for the argument. Details on how the string provided for the pattern matching is interpreted in the specification for the 'like' predicate in the occurrence download API document.

key.notnull

If the value of this argument is TRUE then it will result in a query that will only include records that have a non-empty value for key. Similarly a value of FALSE will result in a query that will only include records that have an empty value for key.

key.not

This presence of this suffix represents the logical negation for all components of the suffix that comes before it. For example, supplying DATASET_KEY.not = "4fa7b334-ce0d-4e88-aaae-2e0c138d049e" will result in a query that includes records from all datasets except that with the provided dataset key. Similarly, supplying ELEVATION.range.not = c(400, 600) as an argument will result in a query that retrieves all records that do not fall within the elevational band that lies between 400 and 600 metres above sea level.

This function will accept arguments that are named either using the uppercase notation used in the examples provided here or using the camel case notation used in the pred function.

By default the arguments HAS_GEOSPATIAL_ISSUE = FALSE, HAS_COORDINATE = TRUE, OCCURRENCE_STATUS = "PRESENT", and BASIS_OF_RECORD.not = c("FOSSIL_SPECIMEN", "LIVING_SPECIMEN") are added to the list of arguments provided by the user. These are commonly applied defaults and are added to avoid accidental requests for erroneous records. If the user does not want these default to be applied then they can override this by providing NULL as the relevant argument. For example, supplying OCCURRENCE_STATUS = NULL will result in a query that requests records that represent both presences and absences.

If an argument with the name 'geometry' appears in the list of query arguments with a value represented by an object of class sfc (or that inherits from it), then a query will be produced that only includes records that fall within the polygon specified in the object. Similarly, if an argument with the name 'geodistance' appears in the list of query arguments with a value with class that inherits from sfc than a query will be produced that only included records that fall within a distance (specified by the geodistance.values argument) of the coordinates (as resulting from the st_coordinates function) that make up the relevant spatial feature.

If any arguments are passed to the function with names that match those in taxonLookup and/or name_lookup functions, then a call will be made to taxonLookup using those arguments. The resulting data frame will be added as a "taxonFrame" attribute to the output. The keys associated with the finest taxonomic resolution in the taxonomic lookup query will then be used as keys to refine the occurrence record search. For example, providing the arguments species = "Aeshna grandis" and order = "Odonata", will result in a data frame returned in the "taxonFrame" attribute of the output that will include the column "speciesKey" representing the keys in GBIF's taxonomic database that are possible entries for the species Aeshna grandis in the order Odonata. These keys values will be used in a query as though they were passed to the function using the argument notation SPECIES_KEY = vectorOfSpeciesKeys and therefore ensuring that only records corresponding to this species are requested.

Value

A jsonlite object containing a query to use in GBIF's occurrence download API. This object may have the "taxonFrame" attribute defined if a call to taxonLookup was made. If so, this attribute will be set to the data frame resulting from the taxonomic query.

Author(s)

Joseph D. Chipperfield, [e-mail]

See Also

name_lookup, taxonLookup, gbifOccDownload, st_sfc, st_coordinates

joechip90/PaGAn documentation built on April 17, 2025, 4:05 p.m.