The most common form of data stored by living atlases are observations of
individual life forms, known as 'occurrences'. This function allows the
user to search for occurrence records that match their specific criteria,
and return them as a data.frame
for analysis. Optionally,
the user can also request a DOI for a given download to facilitate citation
and re-use of specific data resources.
Usage
atlas_occurrences(
request = NULL,
identify = NULL,
filter = NULL,
geolocate = NULL,
data_profile = NULL,
select = NULL,
mint_doi = FALSE,
doi = NULL,
refresh_cache = FALSE
)
Arguments
- request
optional
data_request
object: generated by a call togalah_call()
.- identify
data.frame
: generated by a call togalah_identify()
.- filter
data.frame
: generated by a call togalah_filter()
- geolocate
string
: generated by a call togalah_geolocate()
- data_profile
string
: generated by a call togalah_apply_profile()
- select
data.frame
: generated by a call togalah_select()
- mint_doi
logical
: by default no DOI will be generated. Set toTRUE
if you intend to use the data in a publication or similar- doi
Use
collect_occurrences
instead.string
: this argument enables retrieval of occurrence records previously downloaded from the ALA, using the DOI generated by the data.- refresh_cache
logical
: if set toTRUE
andgalah_config(caching = TRUE)
then files cached from a previous query will be replaced by the current query
Value
An object of class tbl_df
and data.frame
(aka a tibble) of
occurrences, containing columns as specified by galah_select()
.
The data.frame
object has the following attributes:
a listing of the user-supplied arguments of the
data_request
(i.e., identify, filter, geolocate, select)a
doi
of the data downloadthe
search_url
of the query to ALA API
Details
Note that unless care is taken, some queries can be particularly large.
While most cases this will simply take a long time to process, if the number
of requested records is >50 million the call will not return any data. Users
can test whether this threshold will be reached by first calling
atlas_counts()
using the same arguments that they intend to pass to
atlas_occurrences
(). It may also be beneficial when requesting a large
number of records to show a progress bar by setting verbose = TRUE
in
galah_config()
.
Examples
if (FALSE) {
# Download occurrence records for a specific taxon
galah_config(email = "your_email_here")
galah_call() |>
galah_identify("Reptilia") |>
atlas_occurrences()
# Download occurrence records in a year range
galah_call() |>
galah_identify("Litoria") |>
galah_filter(year >= 2010 & year <= 2020) |>
atlas_occurrences()
# Download occurrences records in a WKT-specified area
polygon <- "POLYGON((146.24960 -34.05930,
146.37045 -34.05930,
146.37045 -34.152549,
146.24960 -34.15254,
146.24960 -34.05930))"
galah_call() |>
galah_identify("Reptilia") |>
galah_filter(year >= 2010, year <= 2020) |>
galah_geolocate(polygon) |>
atlas_occurrences()
}