Look up information

Martin Westgate & Dax Kellie

2024-11-19

galah supports two functions to look up information: show_all() and search_all(). The first argument to both functions is a type of information that you wish to look up; for example to see what fields are available to filter a query by, use:

show_all(fields)
## # A tibble: 695 × 3
##    id                  description               type  
##    <chr>               <chr>                     <chr> 
##  1 _nest_parent_       <NA>                      fields
##  2 _nest_path_         <NA>                      fields
##  3 _root_              <NA>                      fields
##  4 abcdTypeStatus      <NA>                      fields
##  5 acceptedNameUsage   Accepted name             fields
##  6 acceptedNameUsageID Accepted name             fields
##  7 accessRights        Access rights             fields
##  8 annotationsDoi      <NA>                      fields
##  9 annotationsUid      Referenced by publication fields
## 10 assertionUserId     Assertions by user        fields
## # ℹ 685 more rows

And to search for a specific field:

search_all(fields, "australian states")
## # A tibble: 2 × 3
##   id     description                            type  
##   <chr>  <chr>                                  <chr> 
## 1 cl2013 ASGS Australian States and Territories fields
## 2 cl22   Australian States and Territories      fields

Here is a list of information types that can be used with show_all() and search_all():

Information type Description Sub-functions
Configuration
atlases Show what living atlases are available show_all_atlases(), search_atlases()
apis Show what APIs & functions are available for each atlas show_all_apis(), search_apis()
reasons Show what values are acceptable as ‘download reasons’ for a specified atlas show_all_reasons(), search_reasons()
Taxonomy
taxa Search for one or more taxonomic names search_taxa()
identifiers Take a universal identifier and return taxonomic information search_identifiers()
ranks Show valid taxonomic ranks (e.g. Kingdom, Class, Order, etc.) show_all_ranks(), search_ranks())
Filters
fields Show fields that are stored in an atlas show_all_fields(), search_fields()
assertions Show results of data quality checks run by each atlas show_all_assertions(), search_assertions()
Group filters
profiles Show what data quality profiles are available show_all_profiles(), search_profiles()
lists Show what species lists are available show_lists(), search_lists()
Data providers
providers Show which institutions have provided data show_all_providers(), search_providers()
collections Show the specific collections within those institutions show_all_collections(), search_collections()
datasets Shows all the data groupings within those collections show_all_datasets(), search_datasets()

show_all_ subfunctions

While show_all is useful for a variety of cases, you can still call the underlying subfunctions if you prefer. Functions with the prefix show_all_ do exactly that; they show all the possible values of the category specified.

show_all_atlases()
## # A tibble: 10 × 4
##    region         institution                                                             acronym url                    
##    <chr>          <chr>                                                                   <chr>   <chr>                  
##  1 Australia      Atlas of Living Australia                                               ALA     https://www.ala.org.au 
##  2 Austria        Biodiversitäts-Atlas Österreich                                         BAO     https://biodiversityat…
##  3 Brazil         Sistemas de Informações sobre a Biodiversidade Brasileira               SiBBr   https://sibbr.gov.br   
##  4 France         Portail français d'accès aux données d'observation sur les espèces      OpenObs https://openobs.mnhn.fr
##  5 Global         Global Biodiversity Information Facility                                GBIF    https://gbif.org       
##  6 Guatemala      Sistema Nacional de Información sobre Diversidad Biológica de Guatemala SNIBgt  https://snib.conap.gob…
##  7 Portugal       GBIF Portugal                                                           GBIF.pt https://www.gbif.pt    
##  8 Spain          GBIF Spain                                                              GBIF.es https://gbif.es        
##  9 Sweden         Swedish Biodiversity Data Infrastructure                                SBDI    https://biodiversityda…
## 10 United Kingdom National Biodiversity Network                                           NBN     https://nbn.org.uk
show_all_reasons()
## # A tibble: 13 × 2
##       id name                            
##    <int> <chr>                           
##  1     1 biosecurity management/planning 
##  2    11 citizen science                 
##  3     5 collection management           
##  4     0 conservation management/planning
##  5     7 ecological research             
##  6     3 education                       
##  7     2 environmental assessment        
##  8    12 restoration/remediation         
##  9     4 scientific research             
## 10     8 systematic research/taxonomy    
## 11    13 species modelling               
## 12     6 other                           
## 13    10 testing

search_ subfunctions

You can also call subfunctions that use the search_ prefix to lookup information. search_ subfunctions differ from show_all_ in that they require a query to work, and they useful to search for detailed information that can’t be summarised across the whole atlas.

search_taxa() is an especially useful function in galah. It let’s you search for a single taxon or multiple taxa by name.

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        https://biodiversity.org.au/afd/taxa/682e1228… class exactMatch Animal… Chord… Rept… noIss…
search_taxa("reptilia", "aves", "mammalia", "pisces")
## # 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        https://biodiversity.org.au/afd/taxa/682e1228… class exactMatch Animal… Chord… Rept… noIss…

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.

search_identifiers("urn:lsid:biodiversity.org.au:afd.taxon:682e1228-5b3c-45ff-833b-550efd40c399")
## # A tibble: 1 × 15
##   search_term     success scientific_name taxon_concept_id rank  rank_id   lft   rgt match_type kingdom kingdom_id phylum
##   <chr>           <lgl>   <chr>           <chr>            <chr>   <int> <int> <int> <chr>      <chr>   <chr>      <chr> 
## 1 urn:lsid:biodi… TRUE    REPTILIA        https://biodive… class    3000 33626 36658 taxonIdMa… Animal… https://b… Chord…
## # ℹ 3 more variables: phylum_id <chr>, class <chr>, class_id <chr>

show_values() & search_values()

Once a desired field is found, you can use show_values() to understand the information contained within that field. For example, we can show the values contained in the field basisOfRecord.

search_all(fields, "basisOfRecord") |> show_values()
## ! Search returned 2 matched fields.
## • Showing values for 'basisOfRecord'.
## # A tibble: 9 × 1
##   basisOfRecord      
##   <chr>              
## 1 HUMAN_OBSERVATION  
## 2 PRESERVED_SPECIMEN 
## 3 MACHINE_OBSERVATION
## 4 OCCURRENCE         
## 5 OBSERVATION        
## 6 MATERIAL_SAMPLE    
## 7 LIVING_SPECIMEN    
## 8 MATERIAL_CITATION  
## 9 FOSSIL_SPECIMEN

Use this information to pass meaningful queries to galah_filter().

galah_call() |> 
  galah_filter(basisOfRecord == "LIVING_SPECIMEN") |> 
  atlas_counts()
## # A tibble: 1 × 1
##    count
##    <int>
## 1 126135

This works for other types of query, such as data profiles:

search_all(profiles, "ALA") |> 
  show_values() |> 
  head()
## • Showing values for 'ALA'.
## # A tibble: 6 × 5
##      id enabled description                                                                           filter displayOrder
##   <int> <lgl>   <chr>                                                                                 <chr>         <int>
## 1    94 TRUE    "Exclude all records where spatial validity is \"false\""                             "-spa…            1
## 2    96 TRUE    "Exclude all records with an assertion that the scientific name provided does not ma… "-ass…            1
## 3    97 TRUE    "Exclude all records with an assertion that the scientific name provided is not stru… "-ass…            2
## 4    98 TRUE    "Exclude all records with an assertion that the name and classification supplied can… "-ass…            3
## 5    99 TRUE    "Exclude all records with an assertion that kingdom provided doesn't match a known k… "-ass…            4
## 6   100 TRUE    "Exclude all records with an assertion that the scientific name provided in the reco… "-ass…            5