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")
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'.
Value
Each sub-function returns a different object class: request_data()
returns data_request
. request_metadata
returns metadata_request
,
request_files()
returns files_request
.
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
(acceptsgalah_filter()
orfilter()
)select
(acceptsgalah_select()
orselect
)group_by
(acceptsgalah_group_by()
orgroup_by()
)identify
(acceptsgalah_identify()
oridentify()
)geolocate
(acceptsgalah_geolocate()
,galah_polygon()
galah_bbox()
orst_crop()
)limit
(acceptsslice_head()
)doi
(accepts a sting listing a valid DOI, specific tocollect()
whentype = "doi"
)
Unrecognised names are ignored by collect()
and related functions.
Examples
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()
}