---
title: "Look up information"
author: "Martin Westgate & Dax Kellie"
date: '2024-04-09'
output:
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Look up information}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


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:


```r
show_all(fields)
```

```
## # A tibble: 646 × 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
## # ℹ 636 more rows
```

And to search for a specific field:


```r
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()`:

<table class="table lightable-paper" style='width: auto !important; margin-left: auto; margin-right: auto; font-family: "Arial Narrow", arial, helvetica, sans-serif; margin-left: auto; margin-right: auto;'>
 <thead>
  <tr>
   <th style="text-align:left;"> Information type </th>
   <th style="text-align:left;"> Description </th>
   <th style="text-align:left;"> Sub-functions </th>
  </tr>
 </thead>
<tbody>
  <tr grouplength="3"><td colspan="3" style="background-color: #fdebf2; color: #343a40;"><strong>Configuration</strong></td></tr>
<tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> atlases </td>
   <td style="text-align:left;"> Show what living atlases are available </td>
   <td style="text-align:left;font-family: monospace;"> show_all_atlases(), search_atlases() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> apis </td>
   <td style="text-align:left;"> Show what APIs &amp; functions are available for each atlas </td>
   <td style="text-align:left;font-family: monospace;"> show_all_apis(), search_apis() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> reasons </td>
   <td style="text-align:left;"> Show what values are acceptable as 'download reasons' for a specified atlas </td>
   <td style="text-align:left;font-family: monospace;"> show_all_reasons(), search_reasons() </td>
  </tr>
  <tr grouplength="3"><td colspan="3" style="background-color: #fdebf2; color: #343a40;"><strong>Taxonomy</strong></td></tr>
<tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> taxa </td>
   <td style="text-align:left;"> Search for one or more taxonomic names </td>
   <td style="text-align:left;font-family: monospace;"> search_taxa() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> identifiers </td>
   <td style="text-align:left;"> Take a universal identifier and return taxonomic information </td>
   <td style="text-align:left;font-family: monospace;"> search_identifiers() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> ranks </td>
   <td style="text-align:left;"> Show valid taxonomic ranks (e.g. Kingdom, Class, Order, etc.) </td>
   <td style="text-align:left;font-family: monospace;"> show_all_ranks(), search_ranks()) </td>
  </tr>
  <tr grouplength="2"><td colspan="3" style="background-color: #fdebf2; color: #343a40;"><strong>Filters</strong></td></tr>
<tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> fields </td>
   <td style="text-align:left;"> Show fields that are stored in an atlas </td>
   <td style="text-align:left;font-family: monospace;"> show_all_fields(), search_fields() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> assertions </td>
   <td style="text-align:left;"> Show results of data quality checks run by each atlas </td>
   <td style="text-align:left;font-family: monospace;"> show_all_assertions(), search_assertions() </td>
  </tr>
  <tr grouplength="2"><td colspan="3" style="background-color: #fdebf2; color: #343a40;"><strong>Group filters</strong></td></tr>
<tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> profiles </td>
   <td style="text-align:left;"> Show what data quality profiles are available </td>
   <td style="text-align:left;font-family: monospace;"> show_all_profiles(), search_profiles() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> lists </td>
   <td style="text-align:left;"> Show what species lists are available </td>
   <td style="text-align:left;font-family: monospace;"> show_lists(), search_lists() </td>
  </tr>
  <tr grouplength="3"><td colspan="3" style="background-color: #fdebf2; color: #343a40;"><strong>Data providers</strong></td></tr>
<tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> providers </td>
   <td style="text-align:left;"> Show which institutions have provided data </td>
   <td style="text-align:left;font-family: monospace;"> show_all_providers(), search_providers() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> collections </td>
   <td style="text-align:left;"> Show the specific collections within those institutions </td>
   <td style="text-align:left;font-family: monospace;"> show_all_collections(), search_collections() </td>
  </tr>
  <tr>
   <td style="text-align:left;font-family: monospace;padding-left: 2em;" indentlevel="1"> datasets </td>
   <td style="text-align:left;"> Shows all the data groupings within those collections </td>
   <td style="text-align:left;font-family: monospace;"> show_all_datasets(), search_datasets() </td>
  </tr>
</tbody>
</table>


# `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. 




```r
show_all_atlases()
```

```
## # A tibble: 11 × 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://biodiversityatlas.at
##  3 Brazil         Sistemas de Informações sobre a Biodiversidade Brasileira               SiBBr   https://sibbr.gov.br        
##  4 Estonia        eElurikkus                                                              <NA>    https://elurikkus.ee        
##  5 France         Portail français d'accès aux données d'observation sur les espèces      OpenObs https://openobs.mnhn.fr     
##  6 Global         Global Biodiversity Information Facility                                GBIF    https://gbif.org            
##  7 Guatemala      Sistema Nacional de Información sobre Diversidad Biológica de Guatemala SNIBgt  https://snib.conap.gob.gt   
##  8 Portugal       GBIF Portugal                                                           GBIF.pt https://www.gbif.pt         
##  9 Spain          GBIF Spain                                                              GBIF.es https://www.gbif.es         
## 10 Sweden         Swedish Biodiversity Data Infrastructure                                SBDI    https://biodiversitydata.se 
## 11 United Kingdom National Biodiversity Network                                           NBN     https://nbn.org.uk
```

```r
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.


```r
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-5b3c-45ff-833b-550efd40c399 class exactMatch Animalia Chordata Reptilia noIssue
```

```r
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-5b3c-45ff-833b-550efd40c399 class exactMatch Animalia Chordata Reptilia noIssue
```

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.


```r
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 phylum_id class class_id
##   <chr>                                     <lgl>   <chr>           <chr>            <chr>   <int> <int> <int> <chr>      <chr>   <chr>      <chr>  <chr>     <chr> <chr>   
## 1 urn:lsid:biodiversity.org.au:afd.taxon:6… TRUE    REPTILIA        https://biodive… class    3000 33626 36658 taxonIdMa… Animal… https://b… Chord… https://… Rept… https:/…
```

# `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`.


```r
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 OBSERVATION        
## 4 OCCURRENCE         
## 5 MACHINE_OBSERVATION
## 6 MATERIAL_SAMPLE    
## 7 LIVING_SPECIMEN    
## 8 MATERIAL_CITATION  
## 9 FOSSIL_SPECIMEN
```

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


```r
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:


```r
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 match any of the names lists used by the ALA.  For a … "-ass…            1
## 3    97 TRUE    "Exclude all records with an assertion that the scientific name provided is not structured as a valid scientific name. Also catches ran… "-ass…            2
## 4    98 TRUE    "Exclude all records with an assertion that the name and classification supplied can't be used to choose between 2 homonyms"             "-ass…            3
## 5    99 TRUE    "Exclude all records with an assertion that kingdom provided doesn't match a known kingdom e.g. Animalia, Plantae"                       "-ass…            4
## 6   100 TRUE    "Exclude all records with an assertion that the scientific name provided in the record does not match the expected taxonomic scope of t… "-ass…            5
```
