Make it clearer how lists are used in `galah_filter()`

At the moment, it is opaque how to use lists in a galah query. Despite the lists IDs being held in the field dataResourceUid, you need to supply the list id to galah_filter() with the field species_list_uid.

library(galah)

# Search returns IDs under field `dataResourceUid`
search_all(lists, "New South Wales")
#> # A tibble: 2 × 19
#>   dataResourceUid listName         listType dateCreated lastUpdated lastUploaded
#>   <chr>           <chr>            <chr>    <chr>       <chr>       <chr>       
#> 1 dr650           New South Wales… CONSERV… 2015-04-04… 2023-06-07… 2023-06-07T…
#> 2 dr487           New South Wales… SENSITI… 2013-06-20… 2023-08-30… 2023-08-30T…
#> # ℹ 13 more variables: lastMatched <chr>, username <chr>, itemCount <int>,
#> #   isAuthoritative <lgl>, isInvasive <lgl>, isThreatened <lgl>, wkt <chr>,
#> #   region <chr>, category <chr>, generalisation <chr>, authority <chr>,
#> #   sdsType <chr>, looseSearch <lgl>

# To filter by list in a query, supply list id to field `species_list_uid`
galah_config(email = "your-email-here")

galah_call() |>
  filter(cl10923 == "YASS VALLEY COUNCIL",
         year == 2023,
         species_list_uid == dr650) |>
  atlas_species()
#> # A tibble: 17 × 10
#>    kingdom  phylum     class      order family genus species author species_guid
#>    <chr>    <chr>      <chr>      <chr> <chr>  <chr> <chr>   <chr>  <chr>       
#>  1 Animalia Chordata   Aves       Psit… Cacat… Call… Calloc… (Gran… https://bio…
#>  2 Animalia Chordata   Aves       Pass… Petro… Petr… Petroi… (Less… https://bio…
#>  3 Animalia Chordata   Aves       Pass… Estri… Stag… Stagon… (Shaw… https://bio…
#>  4 Animalia Chordata   Aves       Pass… Petro… Petr… Petroi… Gould… https://bio…
#>  5 Animalia Chordata   Aves       Pass… Neosi… Daph… Daphoe… (Lath… https://bio…
#>  6 Animalia Chordata   Aves       Acci… Accip… Hier… Hieraa… (Goul… https://bio…
#>  7 Animalia Chordata   Aves       Stri… Strig… Ninox Ninox … (Goul… https://bio…
#>  8 Plantae  Charophyta Equisetop… Aste… Aster… Ammo… Ammobi… Benth. https://id.…
#>  9 Animalia Chordata   Aves       Psit… Psitt… Poly… Polyte… (Desm… https://bio…
#> 10 Animalia Chordata   Aves       Pass… Pachy… Pach… Pachyc… Vigor… https://bio…
#> 11 Animalia Chordata   Aves       Pass… Melip… Epth… Epthia… (Jard… https://bio…
#> 12 Animalia Chordata   Amphibia   Anura Hylid… Lito… Litori… (Dumé… https://bio…
#> 13 Animalia Arthropoda Insecta    Lepi… Castn… Syne… Synemo… Walke… https://bio…
#> 14 Animalia Chordata   Aves       Acci… Accip… Hali… Haliae… (Gmel… https://bio…
#> 15 Animalia Chordata   Mammalia   Dipr… Phasc… Phas… Phasco… (Gold… https://bio…
#> 16 Plantae  Charophyta Equisetop… Aste… Aster… Leuc… Leucoc… (A.Cu… https://id.…
#> 17 Plantae  Charophyta Equisetop… Myrt… Myrta… Euca… Eucaly… Siebe… https://id.…
#> # ℹ 1 more variable: vernacular_name <chr>

^{Created on 2023-11-27 with reprex v2.0.2}

Is it possible to either supply a message when using search_all(lists) and show_all(lists) of how to supply this information to galah_filter()? For example:

Supply a list to `galah_filter()` by using field `species_list_uid`
e.g., `galah_filter(species_list_uid == dr650)`

Alternatively, would it be bad to replace the column name dataResourceUid to species_list_uid in search_all(lists)/show_all(lists) output?

Fixed as of v2.0.1 & commit d0f193123e190b6e00fadf3f26a420a328c41898, search_all(lists) now outputs species_list_uid as the list ID column name

library(galah)

# list IDs are now under `species_list_uid` column
search_all(lists, "New South Wales") |> select(1:3)
#> # A tibble: 2 × 3
#>   species_list_uid listName                               listType         
#>   <chr>            <chr>                                  <chr>            
#> 1 dr650            New South Wales : Conservation Status  CONSERVATION_LIST
#> 2 dr487            New South Wales Sensitive Species List SENSITIVE_LIST

# This matches the field name used by `filter()`
galah_config(email = "your-email-here")

galah_call() |>
  filter(cl10923 == "YASS VALLEY COUNCIL",
         year == 2023,
         species_list_uid == dr650) |> # `filter()` also uses `species_list_uid`
  atlas_species()
#> # A tibble: 21 × 10
#>    species_guid           species author kingdom phylum class order family genus
#>    <chr>                  <chr>   <chr>  <chr>   <chr>  <chr> <chr> <chr>  <chr>
#>  1 https://biodiversity.… Calloc… (Gran… Animal… Chord… Aves  Psit… Cacat… Call…
#>  2 https://biodiversity.… Petroi… (Less… Animal… Chord… Aves  Pass… Petro… Petr…
#>  3 https://biodiversity.… Stagon… (Shaw… Animal… Chord… Aves  Pass… Estri… Stag…
#>  4 https://biodiversity.… Petroi… Gould… Animal… Chord… Aves  Pass… Petro… Petr…
#>  5 https://biodiversity.… Daphoe… (Lath… Animal… Chord… Aves  Pass… Neosi… Daph…
#>  6 https://biodiversity.… Hieraa… (Goul… Animal… Chord… Aves  Acci… Accip… Hier…
#>  7 https://id.biodiversi… Ammobi… Benth. Plantae Charo… Equi… Aste… Aster… Ammo…
#>  8 https://biodiversity.… Ninox … (Goul… Animal… Chord… Aves  Stri… Strig… Ninox
#>  9 https://id.biodiversi… Eucaly… Siebe… Plantae Charo… Equi… Myrt… Myrta… Euca…
#> 10 https://biodiversity.… Polyte… (Desm… Animal… Chord… Aves  Psit… Psitt… Poly…
#> # ℹ 11 more rows
#> # ℹ 1 more variable: vernacular_name <chr>

^{Created on 2024-02-16 with reprex v2.0.2}

AtlasOfLivingAustralia / galah-R

Make it clearer how lists are used in `galah_filter()` #213