Skip to contents

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
)

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

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)

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

# 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()
#> # A tibble: 6 × 10
#>   kingdom  phylum   class    order family   genus species author speci…¹ verna…²
#>   <chr>    <chr>    <chr>    <chr> <chr>    <chr> <chr>   <chr>  <chr>   <chr>  
#> 1 Animalia Chordata Amphibia Anura Limnody… Hele… Heleio… (Gray… https:… Moanin…
#> 2 Animalia Chordata Amphibia Anura Limnody… Hele… Heleio… (Shaw… https:… Giant …
#> 3 Animalia Chordata Amphibia Anura Limnody… Hele… Heleio… Gray,… https:… Wester…
#> 4 Animalia Chordata Amphibia Anura Limnody… Hele… Heleio… (Lee … https:… Sand F…
#> 5 Animalia Chordata Amphibia Anura Limnody… Hele… Heleio… (Lee … https:… Plains…
#> 6 Animalia Chordata Amphibia Anura Limnody… Hele… Heleio… Lee, … https:… Wester…
#> # … with abbreviated variable names ¹​species_guid, ²​vernacular_name

# Get a list of species within family "Peramelidae"
galah_call() |>
  galah_identify("peramelidae") |>
  atlas_species()
#> # A tibble: 15 × 10
#>    kingdom  phylum   class    order  family genus species author speci…¹ verna…²
#>    <chr>    <chr>    <chr>    <chr>  <chr>  <chr> <chr>   <chr>  <chr>   <chr>  
#>  1 Animalia Chordata Mammalia Peram… Peram… Isoo… Isoodo… (Goul… https:… Northe…
#>  2 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Geoff… https:… NA     
#>  3 Animalia Chordata Mammalia Peram… Peram… Isoo… Isoodo… (Shaw… https:… Southe…
#>  4 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Gray,… https:… Easter…
#>  5 Animalia Chordata Mammalia Peram… Peram… Isoo… Isoodo… (Rams… https:… Golden…
#>  6 Animalia Chordata Mammalia Peram… Peram… Isoo… Isoodo… (J.E.… https:… Quenda 
#>  7 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Thoma… https:… NA     
#>  8 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Quoy … https:… Shark …
#>  9 Animalia Chordata Mammalia Peram… Peram… Echy… Echymi… (Pete… https:… Rufous…
#> 10 Animalia Chordata Mammalia Peram… Peram… Isoo… Isoodo… Thoma… https:… NA     
#> 11 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Spenc… https:… Desert…
#> 12 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Travo… https:… Butter…
#> 13 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Thoma… https:… South-…
#> 14 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Wagne… https:… Marl   
#> 15 Animalia Chordata Mammalia Peram… Peram… Pera… Perame… Gray,… https:… Liverp…
#> # … with abbreviated variable names ¹​species_guid, ²​vernacular_name

# It's good idea to find how many species there are before downloading
galah_call() |>
  galah_identify("Heleioporus") |>
  atlas_counts(type = "species")
#> # A tibble: 1 × 1
#>   count
#>   <int>
#> 1     6