# Look up information

#### Martin Westgate & Dax Kellie

#### 2023-01-18

# `show_all()` & `search_all()`

As of galah 1.5.0, there are two simplified functions to look up information: `show_all()` and `search_all()`.

These are individual functions that are able to return all types of information in one place, rather than using specific sub-functions to look up information.

For example, to show all available Living Atlases supported:

    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

To search for a specific available Living Atlas:

    search_all(atlases, "Spain")

    ## # A tibble: 1 × 4
    ##   region institution acronym url
    ##   <chr>  <chr>       <chr>   <chr>
    ## 1 Spain  GBIF Spain  GBIF.es https://www.gbif.es

To show all fields:

    show_all(fields)

    ## # A tibble: 573 × 4
    ##    id                    description                                                                                        type   link
    ##    <chr>                 <chr>                                                                                              <chr>  <chr>
    ##  1 abcdTypeStatus        ABCD field in use by herbaria                                                                      fields <NA>
    ##  2 acceptedNameUsage     http://rs.tdwg.org/dwc/terms/acceptedNameUsage                                                     fields <NA>
    ##  3 acceptedNameUsageID   http://rs.tdwg.org/dwc/terms/acceptedNameUsageID                                                   fields <NA>
    ##  4 accessRights          <NA>                                                                                               fields <NA>
    ##  5 assertionUserId       User ID of the person who has made an assertion about this record                                  fields <NA>
    ##  6 assertions            A list of all assertions (user and system supplied) for a record resulting from data quality tests fields <NA>
    ##  7 associatedMedia       http://rs.tdwg.org/dwc/terms/associatedMedia                                                       fields <NA>
    ##  8 associatedOccurrences http://rs.tdwg.org/dwc/terms/associatedOccurrences                                                 fields <NA>
    ##  9 associatedOrganisms   http://rs.tdwg.org/dwc/terms/associatedOrganisms                                                   fields <NA>
    ## 10 associatedReferences  http://rs.tdwg.org/dwc/terms/associatedReferences                                                  fields <NA>
    ## # … with 563 more rows

And to search for a specific field:

    search_all(fields, "australian states")

    ## # A tibble: 2 × 4
    ##   id     description                                                                                                         type   link
    ##   <chr>  <chr>                                                                                                               <chr>  <chr>
    ## 1 cl2013 ASGS Australian States and Territories Australian Statistical Geography Standard  Australian States and Territories layers http:/…
    ## 2 cl22   Australian States and Territories Australian States and Territories                                                 layers http:/…

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. These 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_fields`
- `show_all_atlases`
- `show_all_ranks`
- `show_all_profiles`
- `show_all_reasons`
- `show_all_cached_files`

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

    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

# `search_` subfunctions

The second subset of lookup subfunctions 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_taxa`
- `search_identifiers`
- `search_fields`
- `show_values`

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…¹ 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-550ef… class exactM… Animal… Chord… Rept… noIss…
    ## # … with abbreviated variable name ¹​match_type

    search_taxa("reptilia", "aves", "mammalia", "pisces")

    ## # A tibble: 4 × 10
    ##   search_term scientific_name taxon_concept_id                                            rank  match…¹ kingdom phylum class issues verna…²
    ##   <chr>       <chr>           <chr>                                                       <chr> <chr>   <chr>   <chr>  <chr> <chr>  <chr>
    ## 1 reptilia    REPTILIA        https://biodiversity.org.au/afd/taxa/682e1228-5b3c-45ff-83… class exactM… Animal… Chord… Rept… noIss… <NA>
    ## 2 aves        AVES            https://biodiversity.org.au/afd/taxa/65625205-db74-4a87-b5… class exactM… Animal… Chord… Aves  noIss… Birds
    ## 3 mammalia    MAMMALIA        https://biodiversity.org.au/afd/taxa/e9e7db31-04df-41fb-bd… class exactM… Animal… Chord… Mamm… noIss… Mammals
    ## 4 pisces      PISCES          https://biodiversity.org.au/afd/taxa/e22efeb4-2cb5-4250-8d… <NA>  exactM… Animal… Chord… <NA>  noIss… Fishes
    ## # … with abbreviated variable names ¹​match_type, ²​vernacular_name

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        https://biodiversity.org.au/afd/taxa/682e1228-5b3c-45ff-833b-550efd40c399 class taxonIdMatch Animalia Chord… Rept… 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 month         "Month of observation, specimen collection date. http://rs.tdwg.org/dwc/terms/month"                            fiel… <NA>
    ## 2 eventDate     "The ISO formatted date of observation, specimen collection date. http://rs.tdwg.org/dwc/terms/eventDate"       fiel… <NA>
    ## 3 cl10903       "Tenure of Australia's forests (2013) v2.0 Tenure of Australia's forests (2013) v2.0 is a continental dataset … laye… http…
    ## 4 cl10955       "National Indicative Aggregated Fire Extent Dataset 2019-2020 - v20200324 The National Indicative Aggregated F… laye… http…
    ## 5 lastLoadDate   <NA>                                                                                                           fiel… <NA>
    ## 6 datePrecision "The precision of the date information for the record. Values include Day, Month, Year, Year range, Month rang… fiel… <NA>

# `show_values()` & `search_values()`

Once a desired field is found, you can use `show_values` to understand the information contained within that field, e.g.

    search_all(fields, "basis") |> show_values()

    ## ! Search returned 2 matched fields.
    ## • Showing values for 'basisOfRecord'.

    ## # A tibble: 9 × 2
    ##   field         category
    ##   <chr>         <chr>
    ## 1 basisOfRecord HUMAN_OBSERVATION
    ## 2 basisOfRecord PRESERVED_SPECIMEN
    ## 3 basisOfRecord OBSERVATION
    ## 4 basisOfRecord OCCURRENCE
    ## 5 basisOfRecord MACHINE_OBSERVATION
    ## 6 basisOfRecord MATERIAL_SAMPLE
    ## 7 basisOfRecord LIVING_SPECIMEN
    ## 8 basisOfRecord MATERIAL_CITATION
    ## 9 basisOfRecord FOSSIL_SPECIMEN

This provides the information you need to pass meaningful queries to `galah_filter`.

    galah_call() |>
      galah_filter(basisOfRecord == "LIVING_SPECIMEN") |>
      atlas_counts()

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

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

    search_all(profiles, "ALA") |>
      show_values() |>
      head()

    ## ! Search returned 2 matched profiles.
    ## • Showing values for 'ALA'.

    ## # A tibble: 6 × 2
    ##   description                                                                                                                        filter
    ##   <chr>                                                                                                                              <chr>
    ## 1 "Exclude all records where spatial validity is \"false\""                                                                          "-spa…
    ## 2 "Exclude all records with an assertion that the scientific name provided does not match any of the names lists used by the ALA.  … "-ass…
    ## 3 "Exclude all records with an assertion that the scientific name provided is not structured as a valid scientific name. Also catch… "-ass…
    ## 4 "Exclude all records with an assertion that the name and classification supplied can't be used to choose between 2 homonyms"       "-ass…
    ## 5 "Exclude all records with an assertion that kingdom provided doesn't match a known kingdom e.g. Animalia, Plantae"                 "-ass…
    ## 6 "Exclude all records with an assertion that the scientific name provided in the record does not match the expected taxonomic scop… "-ass…

Or collections:

    search_all(collections, "herbarium") |>
      show_values() |>
      head()

    ## ! Search returned 21 matched collections.
    ## • Showing values for 'co214'.

    ## # A tibble: 1 × 17
    ##   name            acronym uid   phone  email pubDe…¹ latit…² longi…³ websi…⁴ alaPu…⁵ dateC…⁶ lastU…⁷ userL…⁸ active numRe…⁹ numRe…˟ geogr…˟
    ##   <chr>           <chr>   <chr> <chr>  <chr> <chr>     <dbl>   <dbl> <chr>   <chr>   <chr>   <chr>   <chr>   <chr>    <int>   <int> <chr>
    ## 1 Allan Herbarium CHR     co214 +64 3… Herb… "The A…   -43.6    172. http:/… https:… 2015-0… 2021-1… not av… Activ…  660000  236000 Worldw…
    ## # … with abbreviated variable names ¹​pubDescription, ²​latitude, ³​longitude, ⁴​websiteUrl, ⁵​alaPublicUrl, ⁶​dateCreated, ⁷​lastUpdated,
    ## #   ⁸​userLastModified, ⁹​numRecords, ˟​numRecordsDigitised, ˟​geographicDescription