atlas_species: Collect the set of species observed within the specified...
In galah: Biodiversity Data from the GBIF Node Network

atlas_species

R Documentation

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 = "ala4r@ala.org.au")

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

galah documentation built on Nov. 20, 2023, 9:07 a.m.