Skip to contents

Download predicate DSL (domain specific language)

Source: R/download_predicate_dsl.R
download_predicate_dsl.Rd

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)

  • gbifId (GBIF_ID)

References

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

See also

Other downloads: occ_download_cached(), occ_download_cancel(), occ_download_dataset_activity(), occ_download_datasets(), occ_download_get(), occ_download_import(), occ_download_list(), occ_download_meta(), occ_download_queue(), occ_download_wait(), occ_download()

Examples

pred("taxonKey", 3119195)
#> <<gbif download - predicate>>
#>   > type: equals, key: TAXON_KEY, value: 3119195
pred_gt("elevation", 5000)
#> <<gbif download - predicate>>
#>   > type: greaterThan, key: ELEVATION, value: 5000
pred_gte("elevation", 5000)
#> <<gbif download - predicate>>
#>   > type: greaterThanOrEquals, key: ELEVATION, value: 5000
pred_lt("elevation", 1000)
#> <<gbif download - predicate>>
#>   > type: lessThan, key: ELEVATION, value: 1000
pred_lte("elevation", 1000)
#> <<gbif download - predicate>>
#>   > type: lessThanOrEquals, key: ELEVATION, value: 1000
pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))")
#> <<gbif download - predicate>>
#>   > type: within, key: geometry, value: 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))
#> <<gbif download - predicate list>>
#>   type: and
#>   > type: within, key: geometry, value: POLYGON((-14 42, 9 38, -7 26, -14 42))
#>   > type: greaterThanOrEquals, key: ELEVATION, value: 5000
pred_or(pred_lte("year", 1989), pred("year", 2000))
#> <<gbif download - predicate list>>
#>   type: or
#>   > type: lessThanOrEquals, key: YEAR, value: 1989
#>   > type: equals, key: YEAR, value: 2000
pred_and(pred_lte("year", 1989), pred("year", 2000))
#> <<gbif download - predicate list>>
#>   type: and
#>   > type: lessThanOrEquals, key: YEAR, value: 1989
#>   > type: equals, key: YEAR, value: 2000
pred_in("taxonKey", c(2977832, 2977901, 2977966, 2977835))
#> <<gbif download - predicate>>
#>   > type: in, key: TAXON_KEY, value: 2977832,2977901,2977966,2977835
pred_in("basisOfRecord", c("MACHINE_OBSERVATION", "HUMAN_OBSERVATION"))
#> <<gbif download - predicate>>
#>   > type: in, key: BASIS_OF_RECORD, value: MACHINE_OBSERVATION,HUMAN_OBSERVATION
pred_not(pred("taxonKey", 729))
#> <<gbif download - predicate list>>
#>   type: not
#>   > type: equals, key: TAXON_KEY, value: 729
pred_like("catalogNumber", "PAPS5-560%")
#> <<gbif download - predicate>>
#>   > type: like, key: CATALOG_NUMBER, value: PAPS5-560%
pred_notnull("issue")
#> <<gbif download - predicate>>
#>   > type: isNotNull, parameter: ISSUE
pred("basisOfRecord", "LITERATURE")
#> <<gbif download - predicate>>
#>   > type: equals, key: BASIS_OF_RECORD, value: LITERATURE
pred("hasCoordinate", TRUE)
#> <<gbif download - predicate>>
#>   > type: equals, key: HAS_COORDINATE, value: true
pred("stateProvince", "California")
#> <<gbif download - predicate>>
#>   > type: equals, key: STATE_PROVINCE, value: California
pred("hasGeospatialIssue", FALSE)
#> <<gbif download - predicate>>
#>   > type: equals, key: HAS_GEOSPATIAL_ISSUE, value: false
pred_within("POLYGON((-14 42, 9 38, -7 26, -14 42))")
#> <<gbif download - predicate>>
#>   > type: within, key: geometry, value: POLYGON((-14 42, 9 38, -7 26, -14 42))
pred_or(pred("taxonKey", 2977832), pred("taxonKey", 2977901),
  pred("taxonKey", 2977966))
#> <<gbif download - predicate list>>
#>   type: or
#>   > type: equals, key: TAXON_KEY, value: 2977832
#>   > type: equals, key: TAXON_KEY, value: 2977901
#>   > type: equals, key: TAXON_KEY, value: 2977966
pred_in("taxonKey", c(2977832, 2977901, 2977966, 2977835))
#> <<gbif download - predicate>>
#>   > type: in, key: TAXON_KEY, value: 2977832,2977901,2977966,2977835