atlas_species {galah}

Collect the set of species observed within the specified filters

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
)

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

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

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)

Examples

## Not run: 
# 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()
  
# Or alternatively
request_data(type = "species") |>
  identify("peramelidae") |>
  collect()

# It's good idea to find how many species there are before downloading
galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_counts(type = "species")
# Or alternatively
request_data(type = "species") |>
  identify("Heleioporus") |>
  count() |>
  collect()

## End(Not run)