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,
  refresh_cache = FALSE
)

Arguments

request

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

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

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

First, look up a genus of interest in the ALA with search_taxa()

search_taxa("Heleioporus")
#> # A tibble: 1 x 13
#>   search_term scientific_name scientific_name_~ taxon_concept_id   rank  match_type kingdom phylum class order family genus
#>   <chr>       <chr>           <chr>             <chr>              <chr> <chr>      <chr>   <chr>  <chr> <chr> <chr>  <chr>
#> 1 Heleioporus Heleioporus     Gray, 1841        urn:lsid:biodiver~ genus exactMatch Animal~ Chord~ Amph~ Anura Limno~ Hele~
#> # ... with 1 more variable: issues <chr>

It's a good idea to find how many species there are for the taxon you are interested in - in our case, genus Heleioporus - with atlas_counts()

galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_counts(type = "species")
#> # A tibble: 1 x 1
#>   count
#>   <int>
#> 1     6

Now get taxonomic information on all species within this genus with atlas_species()

# (every row is a species with associated taxonomic data)
galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_species()
#> # A tibble: 6 x 10
#>   kingdom  phylum   class    order family          genus       species     author    species_guid           vernacular_name
#>   <chr>    <chr>    <chr>    <chr> <chr>           <chr>       <chr>       <chr>     <chr>                  <chr>          
#> 1 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Gray, 1~ urn:lsid:biodiversity~ Moaning Frog   
#> 2 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Shaw & ~ urn:lsid:biodiversity~ Giant Burrowin~
#> 3 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ Gray, 18~ urn:lsid:biodiversity~ Western Spotte~
#> 4 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Lee & M~ urn:lsid:biodiversity~ Sand Frog      
#> 5 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Lee & M~ urn:lsid:biodiversity~ Plains Frog    
#> 6 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ Lee, 1967 urn:lsid:biodiversity~ Western Marsh ~

You can also get taxonomic information on species by piping with %>% or |>. Just begin your query with galah_call()

galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_species()
#> # A tibble: 6 x 10
#>   kingdom  phylum   class    order family          genus       species     author    species_guid           vernacular_name
#>   <chr>    <chr>    <chr>    <chr> <chr>           <chr>       <chr>       <chr>     <chr>                  <chr>          
#> 1 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Gray, 1~ urn:lsid:biodiversity~ Moaning Frog   
#> 2 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Shaw & ~ urn:lsid:biodiversity~ Giant Burrowin~
#> 3 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ Gray, 18~ urn:lsid:biodiversity~ Western Spotte~
#> 4 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Lee & M~ urn:lsid:biodiversity~ Sand Frog      
#> 5 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ (Lee & M~ urn:lsid:biodiversity~ Plains Frog    
#> 6 Animalia Chordata Amphibia Anura Limnodynastidae Heleioporus Heleioporu~ Lee, 1967 urn:lsid:biodiversity~ Western Marsh ~

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