galah_call: 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.

Since version 2.0, galah_call() is a wrapper to a group of underlying request_ functions. Each of these functions can begin a piped query and end with collapse(), compute() or collect().

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.

For more details see the object-oriented programming vignette: vignette("object_oriented_programming", package = "galah")

Usage

galah_call(method = c("data", "metadata", "files"), type, ...)
request_data(
  type = c("occurrences", "occurrences-count", "occurrences-doi", "species",
    "species-count"),
  ...
)
request_metadata(type)
request_files(type = "media")

Value

Each sub-function returns a different object class: request_data()

returns data_request. request_metadata returns metadata_request, request_files() returns files_request.

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 to alter a query. See 'details'.

Details

Each atlas has several types of data that can be chosen. Currently supported are "occurrences" (the default), "species" and "media" (the latter currently only for ALA). It is also possible to use type = "occurrences-count" and type = "species-count"; but in practice this is synonymous with galah_call() |> count(), and is therefore only practically useful for debugging (via collapse() and compute()).

Other named arguments are supported via .... In practice, functions with a galah_ prefix and S3 methods ported from dplyr assign information to the correct slots internally. Overwriting these with user-defined alternatives is possible, but not advised. Accepted arguments are:

filter (accepts galah_filter() or filter())
select (accepts galah_select() or select)
group_by (accepts galah_group_by() or group_by())
identify (accepts galah_identify() or identify())
geolocate (accepts galah_geolocate(), galah_polygon() galah_bbox() or st_crop())
limit (accepts slice_head())
doi (accepts a sting listing a valid DOI, specific to collect() when type = "doi")

Unrecognised names are ignored by collect() and related functions.

Examples

Run this code

if (FALSE) { 
# Begin your query with `galah_call()`, then pipe using `%>%` or `|>`

# Get number of records of *Aves* from 2001 to 2004 by year
galah_call() |>
  galah_identify("Aves") |>
  galah_filter(year > 2000 & year < 2005) |>
  galah_group_by(year) |>
  atlas_counts()
  
# Get information for all species in *Cacatuidae* family
galah_call() |>
  galah_identify("Cacatuidae") |>
  atlas_species()
  
# Download records of genus *Eolophus* from 2001 to 2004
galah_config(email = "your-email@email.com")

galah_call() |>
  galah_identify("Eolophus") |>
  galah_filter(year > 2000 & year < 2005) |>
  atlas_occurrences()


# ----------
# Since galah 2.0.0, a pipe can start with a `request_` function.
# This allows users to use `collapse()`, `compute()` and `collect()`.

# Get number of records of *Aves* from 2001 to 2004 by year
request_data(type = "occurrences-count") |>
  galah_identify("Aves") |>
  galah_filter(year > 2000 & year < 2005) |>
  galah_group_by(year) |>
  collect()

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

}