AtlasOfLivingAustralia / galah-R

Query living atlases from R
https://galah.ala.org.au
40 stars 2 forks source link

Clarity in `quick_start_guide #221

Closed andrew-1234 closed 9 months ago

andrew-1234 commented 10 months ago

The cl22 part is confusing in the code example, because the term is undefined in the guide and it was also difficult to find out what this means. I think it could be changed to a recognisable field.

result <- [galah_call](https://galah.ala.org.au/R/reference/galah_call.html)() |>
  [galah_identify](https://galah.ala.org.au/R/reference/galah_identify.html)("Litoria") |>
  [galah_filter](https://galah.ala.org.au/R/reference/galah_filter.html)(year >= 2020, cl22 == "Tasmania") |>
  [galah_select](https://galah.ala.org.au/R/reference/galah_select.html)(basisOfRecord, group = "basic") |>
  [atlas_occurrences](https://galah.ala.org.au/R/reference/atlas_occurrences.html)()

result |> [head](https://rdrr.io/r/utils/head.html)()
daxkellie commented 10 months ago

This is a good pick up, thanks Andrew. In my opinion, beginners shouldn't need to refer to the more detailed documentation to get started (I imagine all that documentation might be daunting to new-ish R users especially).

In other articles, we usually go through how one might find that ID with search_all(fields). Looks like this one seemed to slip past us though! Something like:

Find fields and field IDs for filtering queries

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

See values within a field, which you can use to narrow your query

search_all(fields, "cl22") |> show_values()
#> • Showing values for 'cl22'.
#> # A tibble: 11 × 1
#>    cl22                        
#>    <chr>                       
#>  1 New South Wales             
#>  2 Victoria                    
#>  3 Queensland                  
#>  4 South Australia             
#>  5 Western Australia           
#>  6 Northern Territory          
#>  7 Tasmania                    
#>  8 Australian Capital Territory
#>  9 Unknown1                    
#> 10 Coral Sea Islands           
#> 11 Ashmore and Cartier Islands

Would that be sufficient? Or do you prefer links to function documentation? (we could honestly do both without too much hassle)

andrew-1234 commented 10 months ago

Find fields and field IDs for filtering queries

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

I like this ^^ I think just adding this would be sufficient. Its concise, but it tells me how to do a thing I didn't know how to do (searching fields like that, cool) and also what cl22 means, context for the later filter call.