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.

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")

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").

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.

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() |>
  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 = "your-email@email.com")

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()

}