Skip to contents

Look up taxon information

Source: R/search_taxa.R
search_taxa.Rd

Look up taxonomic names before downloading data from the ALA, using atlas_occurrences(), atlas_species() or atlas_counts(). Taxon information returned by search_taxa() may be passed to galah_identify() to provide the identify argument of atlas_ functions. search_taxa() allows users to disambiguate homonyms (i.e. where the same name refers to taxa in different clades) prior to downloading data.

Usage

search_taxa(...)

Arguments

...

: A string of one or more scientific names, separated by commas, or a data frame specifying taxonomic levels. Note that searches are not case-sensitive.

Value

An object of class tbl_df, data.frame (aka a tibble) and ala_id

containing taxonomic information.

Details

Users can also specify taxonomic levels in a search using a data frame (tibble). Taxa may be specified using either the specificEpithet argument to designate the second element of a Latin binomial, or the scientificName argument to specify the scientific name (which may include the subspecific epithet if required).

See also

search_identifiers() for how to get names if taxonomic identifiers are already known. galah_identify(), galah_select(), galah_filter(), and galah_geolocate() for ways to restrict the information returned by atlas_occurrences() and related functions. atlas_taxonomy() to look up taxonomic trees.

Examples

# Search using a single string. 
# Note that `search_taxa()` isn't case sensitive
search_taxa("Reptilia")
#> # A tibble: 1 × 9
#>   search_term scientific_name taxon_…¹ rank  match…² kingdom phylum class issues
#>   <chr>       <chr>           <chr>    <chr> <chr>   <chr>   <chr>  <chr> <chr> 
#> 1 Reptilia    REPTILIA        https:/… class exactM… Animal… Chord… Rept… noIss…
#> # … with abbreviated variable names ¹​taxon_concept_id, ²​match_type

# Search using multiple strings. 
# `search_taxa()` will return one row per taxon
search_taxa("reptilia", "mammalia")
#> # A tibble: 2 × 10
#>   search_term scient…¹ taxon…² rank  match…³ kingdom phylum class issues verna…⁴
#>   <chr>       <chr>    <chr>   <chr> <chr>   <chr>   <chr>  <chr> <chr>  <chr>  
#> 1 reptilia    REPTILIA https:… class exactM… Animal… Chord… Rept… noIss… NA     
#> 2 mammalia    MAMMALIA https:… class exactM… Animal… Chord… Mamm… noIss… Mammals
#> # … with abbreviated variable names ¹​scientific_name, ²​taxon_concept_id,
#> #   ³​match_type, ⁴​vernacular_name

# Specify taxonomic levels in a tibble using "specificEpiphet"
search_taxa(tibble::tibble(
  class = "aves", 
  family = "pardalotidae", 
  genus = "pardalotus", 
  specificEpithet = "punctatus"))
#> # A tibble: 1 × 15
#>   search_term   scien…¹ scien…² taxon…³ rank  match…⁴ kingdom phylum class order
#>   <chr>         <chr>   <chr>   <chr>   <chr> <chr>   <chr>   <chr>  <chr> <chr>
#> 1 aves_pardalo… Pardal… (Shaw,… https:… spec… exactM… Animal… Chord… Aves  Pass…
#> # … with 5 more variables: family <chr>, genus <chr>, species <chr>,
#> #   vernacular_name <chr>, issues <chr>, and abbreviated variable names
#> #   ¹​scientific_name, ²​scientific_name_authorship, ³​taxon_concept_id,
#> #   ⁴​match_type

# Specify taxonomic levels in a tibble using "scientificName"                    
search_taxa(tibble::tibble(
  family = c("pardalotidae", "maluridae"), 
  scientificName = c("Pardalotus striatus striatus", "malurus cyaneus")))
#> # A tibble: 2 × 15
#>   search_term   scien…¹ scien…² taxon…³ rank  match…⁴ kingdom phylum class order
#>   <chr>         <chr>   <chr>   <chr>   <chr> <chr>   <chr>   <chr>  <chr> <chr>
#> 1 pardalotidae… Pardal… (Gmeli… https:… subs… exactM… Animal… Chord… Aves  Pass…
#> 2 maluridae_ma… Maluru… (Ellis… https:… spec… exactM… Animal… Chord… Aves  Pass…
#> # … with 5 more variables: family <chr>, genus <chr>, species <chr>,
#> #   issues <chr>, vernacular_name <chr>, and abbreviated variable names
#> #   ¹​scientific_name, ²​scientific_name_authorship, ³​taxon_concept_id,
#> #   ⁴​match_type

# `galah_identify()` uses `search_taxa()` to narrow data queries
taxa <- search_taxa("reptilia", "mammalia")
galah_call() |>
  galah_identify(taxa) |>
  atlas_counts()
#> # A tibble: 1 × 1
#>     count
#>     <int>
#> 1 5231166