galah_call: Start building a query

In AtlasOfLivingAustralia/galah: Biodiversity Data from the GBIF Node Network

Start building a query

Description

To download data from the selected atlas, one must construct a query. This query tells the atlas API what data to download and return, as well as how it should be filtered. Using galah_call() allows you to build a piped query to download data, in the same way that you would wrangle data with dplyr and the tidyverse.

Usage

galah_call(method = c("data", "metadata", "files"), type, ...)

request_data(
  type = c("occurrences", "occurrences-count", "occurrences-doi", "species",
    "species-count"),
  ...
)

request_metadata(
  type = c("fields", "apis", "assertions", "atlases", "collections", "datasets",
    "licences", "lists", "media", "profiles", "providers", "ranks", "reasons", "taxa",
    "identifiers")
)

request_files(type = "media")

Arguments

method	string: what request function should be called. Should be one of "data" (default), "metadata" or "files"
type	string: what form of data should be returned? Acceptable values are specified by the corresponding request function
...	Zero or more arguments passed to collapse() to alter a query. Currently only mint.doi (for occurrences) and thumbnail (for media downloads) are supported. Both are logical.

Details

In practice, galah_call() is a wrapper to a group of underlying request_ functions, selected using the method argument. Each of these functions can begin a piped query and end with collapse(), compute() or collect(), or optionally one of the atlas_ family of functions. For more details see the object-oriented programming vignette: vignette("object_oriented_programming", package = "galah")

Accepted values of the type argument are set by the underlying request_ functions. While all accepted types can be set directly, some are affected by later functions. The most common example is that adding count() to a pipe updates type, converting type = "occurrences" to type = "occurrences-count" (and ditto for type = "species").

The underlying request_ functions are useful because they allow galah to separate different types of requests to perform better. For example, filter.data_request translates filters in R to solr, whereas filter.metadata_request searches using a search term.

Value

Each sub-function returns a different object class: request_data() returns data_request. request_metadata returns metadata_request, request_files() returns files_request. These objects are list-like and contain the following slots:

• filter: edit by piping filter() or galah_filter().

• select: edit by piping select or galah_select().

• group_by: edit by piping group_by() or galah_group_by().

• identify: edit by piping identify() or galah_identify().

• geolocate: edit by piping st_crop(), galah_geolocate(), galah_polygon() or galah_bbox().

• limit: edit by piping slice_head().

• doi: edit by piping filter(doi == "my-doi-here").

See Also

collapse.data_request(), compute.data_request(), collect.data_request()

Examples

## Not run:  
# Begin your query with `galah_call()`, then pipe using `%>%` or `|>`

# Get number of records of *Aves* from 2001 to 2004 by year
galah_call() |>
  identify("Aves") |>
  filter(year > 2000 & year < 2005) |>
  group_by(year) |>
  atlas_counts()
  
# Get information for all species in *Cacatuidae* family
galah_call() |>
  identify("Cacatuidae") |>
  atlas_species()
  
# Download records of genus *Eolophus* from 2001 to 2004
galah_config(email = "[e-mail]")

galah_call() |>
  identify("Eolophus") |>
  filter(year > 2000 & year < 2005) |>
  atlas_occurrences() # synonymous with `collect()`


# galah_call() is a wrapper to various `request_` functions.
# These can be called directly for greater specificity.

# Get number of records of *Aves* from 2001 to 2004 by year
request_data() |>
  identify("Aves") |>
  filter(year > 2000 & year < 2005) |>
  group_by(year) |>
  count() |>
  collect()

# Get information for all species in *Cacatuidae* family
request_data(type = "species") |>
  identify("Cacatuidae") |>
  collect()
  
# Get metadata information about supported atlases in galah
request_metadata(type = "atlases") |>
  collect()


## End(Not run)

AtlasOfLivingAustralia/galah documentation built on Feb. 8, 2025, 9:25 a.m.