Look up information

Martin Westgate & Dax Kellie

2022-01-24

show_all_ functions

Functions with the prefix show_all_ return a tibble doing exactly that - showing all the possible values of the category specified. These functions include:

show_all_ functions require no arguments. Simply call the function and it will return all accepted values as a tibble:

show_all_atlases()
## # A tibble: 6 × 3
##   atlas     taxonomy_source taxonomy_info                                                    
##   <chr>     <chr>           <chr>                                                            
## 1 Australia ALA             https://bie.ala.org.au/                                          
## 2 Austria   GBIF            https://www.gbif.org/dataset/d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
## 3 Guatemala GBIF            https://www.gbif.org/dataset/d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
## 4 Spain     GBIF            https://www.gbif.org/dataset/d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
## 5 Sweden    GBIF            https://www.gbif.org/dataset/d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
## 6 UK        NBN             https://www.nhm.ac.uk/our-science/data/uk-species.html
show_all_reasons()
## # A tibble: 13 × 2
##       id name                            
##    <int> <chr>                           
##  1     0 conservation management/planning
##  2     1 biosecurity management/planning 
##  3     2 environmental assessment        
##  4     3 education                       
##  5     4 scientific research             
##  6     5 collection management           
##  7     6 other                           
##  8     7 ecological research             
##  9     8 systematic research/taxonomy    
## 10    10 testing                         
## 11    11 citizen science                 
## 12    12 restoration/remediation         
## 13    13 species modelling

Of these functions, the one that has by far the largest output is show_all_fields. Given how important fields are to the proper use of galah, it might be more useful to search for a specific field. This need for a more detailed search is when search_ functions come in handy.

search_ functions

The second subset of lookup functions use the search_ prefix, and differ from show_all_ in that they require a query to work. They are used to search for detailed information that can’t be summarised across the whole atlas, and include:

Search for a single taxon or multiple taxa by name with search_taxa.

search_taxa("reptilia")
## # A tibble: 1 × 9
##   search_term scientific_name taxon_concept_id                                    rank  match_type kingdom  phylum   class  issues
##   <chr>       <chr>           <chr>                                               <chr> <chr>      <chr>    <chr>    <chr>  <chr> 
## 1 reptilia    REPTILIA        urn:lsid:biodiversity.org.au:afd.taxon:682e1228-5b… class exactMatch Animalia Chordata Repti… noIss…
search_taxa("reptilia", "aves", "mammalia", "pisces")
## # A tibble: 4 × 10
##   search_term scientific_name taxon_concept_id                   rank      match_type kingdom  phylum class issues vernacular_name
##   <chr>       <chr>           <chr>                              <chr>     <chr>      <chr>    <chr>  <chr> <chr>  <chr>          
## 1 reptilia    REPTILIA        urn:lsid:biodiversity.org.au:afd.… class     exactMatch Animalia Chord… Rept… noIss… <NA>           
## 2 aves        AVES            urn:lsid:biodiversity.org.au:afd.… class     exactMatch Animalia Chord… Aves  noIss… Birds          
## 3 mammalia    MAMMALIA        urn:lsid:biodiversity.org.au:afd.… class     exactMatch Animalia Chord… Mamm… noIss… Mammals        
## 4 pisces      PISCES          urn:lsid:biodiversity.org.au:afd.… species … exactMatch Animalia Chord… <NA>  noIss… fishes

Alternatively, search_identifiers is the partner function to search_taxa. If we already know a taxonomic identifier, we can search for which taxa the identifier belongs to with search_identifiers:

search_identifiers("urn:lsid:biodiversity.org.au:afd.taxon:682e1228-5b3c-45ff-833b-550efd40c399")
## # A tibble: 1 × 8
##   scientific_name taxon_concept_id                                              rank  match_type   kingdom  phylum  class   issues
##   <chr>           <chr>                                                         <chr> <chr>        <chr>    <chr>   <chr>   <chr> 
## 1 REPTILIA        urn:lsid:biodiversity.org.au:afd.taxon:682e1228-5b3c-45ff-83… class taxonIdMatch Animalia Chorda… Reptil… noIss…

Sifting through the output of show_all_fields to find a specific field can be inefficient. Instead, we might wish to use search_fields to look for specific fields that match a search. As with search_taxa, search_fields requires a query to work.

search_fields("date") |> head()
## # A tibble: 6 × 4
##   id                description        type   link 
##   <chr>             <chr>              <chr>  <chr>
## 1 dateIdentified    Date Identified    fields <NA> 
## 2 datePrecision     Date precision     fields <NA> 
## 3 eventDate         Event Date         fields <NA> 
## 4 eventDateEnd      <NA>               fields <NA> 
## 5 firstLoadedDate   Date first indexed fields <NA> 
## 6 georeferencedDate Georeferenced Date fields <NA>

Once a desired field is found, use search_field_values to find values to pass to galah_filter

search_field_values("basisOfRecord")
## # A tibble: 8 × 2
##   field         category           
##   <chr>         <chr>              
## 1 basisOfRecord HUMAN_OBSERVATION  
## 2 basisOfRecord PRESERVED_SPECIMEN 
## 3 basisOfRecord OBSERVATION        
## 4 basisOfRecord MACHINE_OBSERVATION
## 5 basisOfRecord MATERIAL_SAMPLE    
## 6 basisOfRecord UNKNOWN            
## 7 basisOfRecord LIVING_SPECIMEN    
## 8 basisOfRecord FOSSIL_SPECIMEN
galah_call() |> galah_filter(basisOfRecord == "LIVING_SPECIMEN") |> atlas_counts()
## # A tibble: 1 × 1
##    count
##    <int>
## 1 216371

search_profile_attributes gives more information on criteria used to remove records in data quality profiles, for example:

search_profile_attributes("ALA") |> head()
## # A tibble: 6 × 2
##   description                                                                                        filter                       
##   <chr>                                                                                              <chr>                        
## 1 "Exclude all records where spatial validity is \"false\""                                          "-spatiallyValid:\"false\""  
## 2 "Exclude all records with an assertion that the scientific name provided does not match any of th… "-assertions:TAXON_MATCH_NON…
## 3 "Exclude all records with an assertion that the scientific name provided is not structured as a v… "-assertions:INVALID_SCIENTI…
## 4 "Exclude all records with an assertion that the name and classification supplied can't be used to… "-assertions:TAXON_HOMONYM"  
## 5 "Exclude all records with an assertion that kingdom provided doesn't match a known kingdom e.g. A… "-assertions:UNKNOWN_KINGDOM"
## 6 "Exclude all records with an assertion that the scientific name provided in the record does not m… "-assertions:TAXON_SCOPE_MIS…