galah (version 1.5.4)

atlas_species: Return species lists

Description

While there are reasons why users may need to check every record meeting their search criteria (i.e. using atlas_occurrences()), a common use case is to simply identify which species occur in a specified region, time period, or taxonomic group. This function returns a data.frame with one row per species, and columns giving associated taxonomic information.

Usage

atlas_species(
  request = NULL,
  identify = NULL,
  filter = NULL,
  geolocate = NULL,
  data_profile = NULL,
  refresh_cache = FALSE
)

Value

An object of class tbl_df and data.frame (aka a tibble), returning matching species The data.frame object has attributes listing of the user-supplied arguments of the data_request

(i.e., identify, filter, geolocate, columns)

Arguments

request

optional data_request object: generated by a call to galah_call().

identify

data.frame: generated by a call to galah_identify().

filter

data.frame: generated by a call to galah_filter()

geolocate

string: generated by a call to galah_geolocate()

data_profile

string: generated by a call to galah_apply_profile()

refresh_cache

logical: if set to TRUE and galah_config(caching = TRUE) then files cached from a previous query will be replaced by the current query

Details

The primary use case of this function is to extract species-level information given a set of criteria defined by search_taxa(), galah_filter() or galah_geolocate(). If the purpose is simply to get taxonomic information that is not restricted by filtering, then search_taxa() is more efficient. Similarly, if counts are required that include filter but without returning taxonomic detail, then atlas_counts() is more efficient (see examples).

Examples

if (FALSE) {
# First register a valid email address
galah_config(email = "[e-mail]")

# Get a list of species within genus "Heleioporus"
# (every row is a species with associated taxonomic data)
galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_species()

# Get a list of species within family "Peramelidae"
galah_call() |>
  galah_identify("peramelidae") |>
  atlas_species()

# It's good idea to find how many species there are before downloading
galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_counts(type = "species")
}