download_predicate_dsl: Download predicate DSL (domain specific language)
In rgbif: Interface to the Global Biodiversity Information Facility API

download_predicate_dsl

R Documentation

Download predicate DSL (domain specific language)

Description

Download predicate DSL (domain specific language)

Usage

pred(key, value)

pred_gt(key, value)

pred_gte(key, value)

pred_lt(key, value)

pred_lte(key, value)

pred_not(...)

pred_like(key, value)

pred_within(value)

pred_isnull(key)

pred_notnull(key)

pred_or(..., .list = list())

pred_and(..., .list = list())

pred_in(key, value)

pred_default()

Arguments

`key`	(character) the key for the predicate. See "Keys" below
`value`	(various) the value for the predicate
`..., .list`	For `pred_or()` or `pred_and()`, one or more objects of class `occ_predicate`, created by any `⁠pred*⁠` function

predicate methods and their equivalent types

⁠pred*⁠ functions are named for the 'type' of operation they do, following the terminology used by GBIF, see https://www.gbif.org/developer/occurrence#predicates

Function names are given, with the equivalent GBIF type value (e.g., pred_gt and greaterThan)

The following functions take one key and one value:

pred: equals
pred_lt: lessThan
pred_lte: lessThanOrEquals
pred_gt: greaterThan
pred_gte: greaterThanOrEquals
pred_like: like

The following function is only for geospatial queries, and only accepts a WKT string:

pred_within: within

The following function is only for stating the you don't want a key to be null, so only accepts one key:

pred_notnull: isNotNull

The following function is only for stating that you want a key to be null.

pred_isnull : isNull

The following two functions accept multiple individual predicates, separating them by either "and" or "or":

pred_and: and
pred_or: or

The not predicate accepts one predicate; that is, this negates whatever predicate is passed in, e.g., not the taxonKey of 12345:

pred_not: not

The following function is special in that it accepts a single key but many values; stating that you want to search for all the values:

pred_in: in

The following function will apply commonly used defaults.

pred_default

Using pred_default() is equivalent to running:

  pred_and(
   pred("HAS_GEOSPATIAL_ISSUE",FALSE),
   pred("HAS_COORDINATE",TRUE),
   pred("OCCURRENCE_STATUS","PRESENT"),
   pred_not(pred_in("BASIS_OF_RECORD",
    c("FOSSIL_SPECIMEN","LIVING_SPECIMEN")))
  )

What happens internally

Internally, the input to ⁠pred*⁠ functions turns into JSON to be sent to GBIF. For example ...

pred_in("taxonKey", c(2480946, 5229208)) gives:

{
   "type": "in",
   "key": "TAXON_KEY",
   "values": ["2480946", "5229208"]
 }

pred_gt("elevation", 5000) gives:

{
   "type": "greaterThan",
   "key": "ELEVATION",
   "value": "5000"
}

pred_or(pred("taxonKey", 2977832), pred("taxonKey", 2977901)) gives:

{
  "type": "or",
  "predicates": [
     {
       "type": "equals",
       "key": "TAXON_KEY",
       "value": "2977832"
     },
     {
       "type": "equals",
       "key": "TAXON_KEY",
       "value": "2977901"
     }
  ]
}

Keys

Acceptable arguments to the key parameter are (with the version of the key in parens that must be sent if you pass the query via the body parameter; see below for examples). You can also use the 'ALL_CAPS' version of a key if you prefer. Open an issue in the GitHub repository for this package if you know of a key that should be supported that is not yet.

taxonKey (TAXON_KEY)
acceptedTaxonKey (ACCEPTED_TAXON_KEY)
kingdomKey (KINGDOM_KEY)
phylumKey (PHYLUM_KEY)
classKey (CLASS_KEY)
orderKey (ORDER_KEY)
familyKey (FAMILY_KEY)
genusKey (GENUS_KEY)
subgenusKey (SUBGENUS_KEY)
speciesKey (SPECIES_KEY)
scientificName (SCIENTIFIC_NAME)
country (COUNTRY)
publishingCountry (PUBLISHING_COUNTRY)
hasCoordinate (HAS_COORDINATE)
hasGeospatialIssue (HAS_GEOSPATIAL_ISSUE)
typeStatus (TYPE_STATUS)
recordNumber (RECORD_NUMBER)
lastInterpreted (LAST_INTERPRETED)
modified (MODIFIED)
continent (CONTINENT)
geometry (GEOMETRY)
basisOfRecord (BASIS_OF_RECORD)
datasetKey (DATASET_KEY)
datasetID/datasetId (DATASET_ID)
eventDate (EVENT_DATE)
catalogNumber (CATALOG_NUMBER)
otherCatalogNumbers (OTHER_CATALOG_NUMBERS)
year (YEAR)
month (MONTH)
decimalLatitude (DECIMAL_LATITUDE)
decimalLongitude (DECIMAL_LONGITUDE)
elevation (ELEVATION)
depth (DEPTH)
institutionCode (INSTITUTION_CODE)
collectionCode (COLLECTION_CODE)
issue (ISSUE)
mediatype (MEDIA_TYPE)
recordedBy (RECORDED_BY)
recordedById/recordedByID (RECORDED_BY_ID)
establishmentMeans (ESTABLISHMENT_MEANS)
coordinateUncertaintyInMeters (COORDINATE_UNCERTAINTY_IN_METERS)
gadm (GADM_GID) (for the Database of Global Administrative Areas)
level0Gid (GADM_LEVEL_0_GID)
level1Gid (GADM_LEVEL_1_GID)
level2Gid (GADM_LEVEL_2_GID)
level3Gid (GADM_LEVEL_3_GID)
stateProvince (STATE_PROVINCE)
occurrenceStatus (OCCURRENCE_STATUS)
publishingOrg (PUBLISHING_ORG)
occurrenceId/occurrenceID (OCCURRENCE_ID)
eventId/eventID (EVENT_ID)
parentEventId/parentEventID (PARENT_EVENT_ID)
identifiedBy (IDENTIFIED_BY)
identifiedById/identifiedByID (IDENTIFIED_BY_ID)
license (LICENSE)
locality(LOCALITY)
pathway (PATHWAY)
preparations (PREPARATIONS)
networkKey (NETWORK_KEY)
organismId/organismID (ORGANISM_ID)
organismQuantity (ORGANISM_QUANTITY)
organismQuantityType (ORGANISM_QUANTITY_TYPE)
protocol (PROTOCOL)
relativeOrganismQuantity (RELATIVE_ORGANISM_QUANTITY)
repatriated (REPATRIATED)
sampleSizeUnit (SAMPLE_SIZE_UNIT)
sampleSizeValue (SAMPLE_SIZE_VALUE)
samplingProtocol (SAMPLING_PROTOCOL)
verbatimScientificName (VERBATIM_SCIENTIFIC_NAME)
taxonID/taxonId (TAXON_ID)
taxonomicStatus (TAXONOMIC_STATUS)
waterBody (WATER_BODY)
iucnRedListCategory (IUCN_RED_LIST_CATEGORY)
degreeOfEstablishment (DEGREE_OF_ESTABLISHMENT)
isInCluster (IS_IN_CLUSTER)
lifeStage (LIFE_STAGE)
distanceFromCentroidInMeters (DISTANCE_FROM_CENTROID_IN_METERS)

References

Download predicates docs: https://www.gbif.org/developer/occurrence#predicates

Examples

pred("taxonKey", 3119195)
pred_gt("elevation", 5000)
pred_gte("elevation", 5000)
pred_lt("elevation", 1000)
pred_lte("elevation", 1000)
pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))")
pred_and(pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))"),
  pred_gte("elevation", 5000))
pred_or(pred_lte("year", 1989), pred("year", 2000))
pred_and(pred_lte("year", 1989), pred("year", 2000))
pred_in("taxonKey", c(2977832, 2977901, 2977966, 2977835))
pred_in("basisOfRecord", c("MACHINE_OBSERVATION", "HUMAN_OBSERVATION"))
pred_not(pred("taxonKey", 729))
pred_like("catalogNumber", "PAPS5-560%")
pred_notnull("issue")
pred("basisOfRecord", "LITERATURE")
pred("hasCoordinate", TRUE)
pred("stateProvince", "California")
pred("hasGeospatialIssue", FALSE)
pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))")
pred_or(pred("taxonKey", 2977832), pred("taxonKey", 2977901),
  pred("taxonKey", 2977966))
pred_in("taxonKey", c(2977832, 2977901, 2977966, 2977835))

rgbif documentation built on Sept. 11, 2023, 9:06 a.m.