Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarity in `quick_start_guide #221

Closed
andrew-1234 opened this issue Dec 5, 2023 · 2 comments
Closed

Clarity in `quick_start_guide #221

andrew-1234 opened this issue Dec 5, 2023 · 2 comments
Labels
documentation Improvements or additions to documentation

Comments

@andrew-1234
Copy link

andrew-1234 commented Dec 5, 2023

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)()
@andrew-1234 andrew-1234 added bug Something isn't working documentation Improvements or additions to documentation and removed bug Something isn't working labels Dec 5, 2023
@daxkellie
Copy link
Contributor

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
Copy link
Author

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.

daxkellie added a commit that referenced this issue Dec 14, 2023
* Minor text edits to taxonomic + temporal advanced vignettes
* Add `search_all(fields)` example in quick start vignette
* Update Rmd.orig files, rerender vignettes
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants