Taxonomic filtering

search_taxa()

search_taxa() enables users to look up taxonomic names before downloading data, which allows for disambiguating homonyms and checking that the search term matches the taxon name in the ALA . search_taxa() returns the scientific name, authorship, rank, and full classification for the taxon matched to the provided search term.

search_taxa("Petroica boodang") |> gt::gt()

# Muscicapa chrysoptera is a synonym for the Flame Robin, Petroica phoenicea
# Guniibuu is the Yuwaalaraay Indigenous name for the Red-Capped Robin, Petroica goodenovii
search_taxa("Muscicapa chrysoptera", "Guniibuu") |> gt::gt()

search_taxa("Morganella") |> gt::gt()

## Warning: Search returned multiple taxa due to a homonym issue.
## ℹ Please provide another rank in your search to clarify taxa.
## ℹ Use a `tibble` to clarify taxa, see `?search_taxa`.
## ✖ Homonym issue with "Morganella".

search_taxa(tibble(kingdom = "Fungi", genus = "Morganella")) |> gt::gt()

identify()

identify() is similar to search_taxa(), except that it can be used within a piped workflow to retrieve counts, species, or records e.g.

galah_call() |>
  identify("Petroica boodang") |>
  count() |>
  collect()

## # A tibble: 1 × 1
##    count
##    <int>
## 1 132981

galah_call(type = "species") |>
  identify("Muscicapa chrysoptera", "Guniibuu") |>
  collect() |> 
  gt::gt()

galah_call() |>
  identify(tibble(kingdom = "Fungi", genus = "Morganella")) |>
  collect() |>
  head() |> 
  gt::gt()

## Retrying in 1 seconds.

filter()

filter() subsets records by searching for exact matches to an expression, and may also be used for taxonomic filtering e.g.

galah_call() |>
  filter(species == "Petroica boodang") |>
  count() |>
  collect()

## # A tibble: 1 × 1
##    count
##    <int>
## 1 132981

Alternatively, we could use filter() after first checking taxonomy with search_taxa(), in place of identify():

robins <- search_taxa("Muscicapa chrysoptera", "Guniibuu") 

galah_call() |>
  filter(taxonConceptID == robins$taxon_concept_id) |>
  count() |>
  collect()

## # A tibble: 1 × 1
##   count
##   <int>
## 1 88434

It is also possible to specify several species at once using filter():

aus_petroica <- c("Petroica boodang", "Petroica goodenovii", 
                  "Petroica phoenicea", "Petroica rosea",
                  "Petroica rodinogaster", "Petroica multicolor")

galah_call() |>
  filter(species %in% aus_petroica) |>
  group_by(species, vernacularName) |>
  count() |> 
  collect() |>
  gt::gt()

This can be useful in searching for paraphyletic or polyphyletic groups, which cannot be done using identify(). For example, to get counts of non-chordates:

galah_call() |>
  filter(kingdom == "Animalia", phylum != "Chordata") |>
  group_by(phylum) |>
  count() |>
  collect() |>
  head() |> 
  gt::gt()

filter(), identify(), and taxonomic ranks

Deciding between using filter() and identify() in a query comes down to how a record has been classified, and whether or not you have the correct unique name and classification of the taxa of interest.

The ALA has fields for the primary taxonomic ranks (kingdom, phylum, class, order, family, genus, species) and some secondary ranks (e.g. subfamily, subgenus), all of which may be used with galah_filter() and galah_identify(). Additionally, there is a field named scientificName, which refers to the lowest taxonomic rank to which a record has been identified e.g.

galah_call() |>
  identify(tibble(genus = "Pitta")) |>
  group_by(scientificName, taxonRank) |>
  count() |>
  collect() |>
  filter(!is.na(scientificName)) |>
  gt::gt()

If, for instance, you have the correct species or subspecies name, then searching for matches against the species and subspecies fields, respectively, will provide more precise results. This is because the field scientificName may include subgenera. If you’ve used search_taxa() to get the ALA-matched name of a taxon and only want records identified to a particular level of classification, searching for matches against scientificName is recommended.

Paraphyletic or polyphyletic groups may contain taxa identified to different taxonomic levels. In this case, it is simpler to use search_taxa() and identify() rather than filter(). In the example below, search_taxa() matches terms to one genus, three species, and two subspecies. This can then be used in a piped workflow with identify().

tas_endemic <- c("Sarcophilus", # Tasmanian Devil
                 "Bettongia gaimardi", # Tasmanian Bettong
                 "Melanodryas vittata", # Dusky Robin
                 "Platycercus caledonicus",# Green Rosella
                 "Aquila audax fleayi", # Tasmanian Wedge-Tailed Eagle
                 "Tyto novaehollandiae castanops") # Tasmanian Masked Owl

search_taxa(tas_endemic) |> gt::gt()

galah_call() |>
  identify(tas_endemic) |>
  group_by(scientificName) |>
  count() |>
  collect() |>
  arrange(scientificName) |>
  gt::gt()