Dev

.Rbuildignore

@@ -17,4 +17,6 @@
 ^data-raw/
 ^data-raw$
 ^cheatsheet/
-^cheatsheet$
+^cheatsheet$
+^\.positai$
+^\.claude$

.gitignore

@@ -14,4 +14,5 @@ docs/*
 docs
 SECRETS.txt
 .secure-credentials
-/TEST-SENSITIVE-DATA
+/TEST-SENSITIVE-DATA
+.positai

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: galah
 Type: Package
 Title: Biodiversity Data from the GBIF Node Network
-Version: 2.2.0
+Version: 2.3.0
 Authors@R: 
     c(person(given = "Martin",
              family = "Westgate",

NAMESPACE

@@ -33,6 +33,7 @@ S3method(compute,prequery)
 S3method(compute,query)
 S3method(compute,query_set)
 S3method(count,data_request)
+S3method(describe,data_request)
 S3method(distinct,data_request)
 S3method(filter,data_request)
 S3method(filter,files_request)
@@ -80,6 +81,7 @@ export(collect_media)
 export(compound)
 export(compute)
 export(count)
+export(describe)
 export(distinct)
 export(filter)
 export(galah_apply_profile)
@@ -94,6 +96,9 @@ export(galah_polygon)
 export(galah_radius)
 export(galah_select)
 export(geolocate)
+export(geolocate_bbox)
+export(geolocate_polygon)
+export(geolocate_radius)
 export(glimpse)
 export(group_by)
 export(identify)

NEWS.md

@@ -1,3 +1,27 @@
+# galah 2.3.0
+
+### New functions and options
+* New function `describe()` to check what fields are available (#291).
+* `authenticate()` gains arguments to allow in-pipe email- or JWT-based authentication. Support added for JWT-based authentication on VBP (#296).
+* `request_data()` and friends gain a `from` argument, allowing in-pipe atlas specification (#297).
+* New names for spatial functions: `geolocate_polygon()`, `geolocate_bbox()` and `geolocate_radius()`.
+* Now possible to call `select()` on GBIF occurrence queries, though they are applied post-hoc.
+
+### Bug fixes & performance improvements
+* `isAuthoritative` and `isThreatened` returned by default by `search_all()` (#293).
+* Calling functions using `pkg::fun()` syntax work without first calling `library(galah)` (#294, #298).
+* `query_API()` now uses `cli::cli_progress_step()`, `httr2::req_retry()` and `httr::req_perform_parallel()` for improved performance. Timeout is now 60 seconds, rather than 20.
+* Misc bug fixes for `atlas_occurrences()`, `glimpse()` and `show_values()` for GBIF (#299).
+* Upgraded to v2 of specieslist API for ALA (#300).
+* `galah` now auto-populates the `q` parameter for living atlas API calls for server-side performance reasons (#301).
+* Added check that object has correct Coordinate Reference System when using `geolocate()` (#302)
+* Improved query parsing for more complex text strings (#303)
+
+### Lifecycle
+* `galah_` prefix functions for piping formally superseded by their `dplyr` alternatives.
+* Using `filter`, `select` etc as arguments to the `atlas_` family formally superseded in favor of piping.
+* `all_fields` argument in `show_values()` used to return all columns in a specified list superseded to supplying all columns by default.
+
 # galah 2.2.0
 
 ### Improved organisational support
@@ -12,7 +36,7 @@
 * `dplyr::glimpse()` can be used to see what the resulting query will look like.
 * New functions `capture()` and `compound()` as prequels to `collapse()` (#278).
 
-## Changes to metadata functions
+### Changes to metadata functions
 * All metadata requests now accept `select()`.
 * Metadata types that support `unnest()` now also support `filter()`, even when `unnest()` is not supplied.
 * All `show_all()` and `search_all()` functions gain an `all_fields` argument.
@@ -27,7 +51,7 @@
 * Move to `{cli}` for `print()` calls, not `cat()`.
 * Reduce usage of `@importFrom` in favour of `pkg::fun()` syntax, as per R style guide.
 * `basisOfRecord` now included as default field (i.e. with `select(group = "basic")`). (#281)
-* `query` objects now have a `request` slot showing the request that generated them .
+* `query` objects now have a `request` slot showing the request that generated them.
 
 
 # galah 2.1.2

R/galah_apply_profile.R → R/apply_profile.R

@@ -39,24 +39,6 @@ apply_profile <- function(.data, ...){
                         apply_profile = result)
 }
 
-#' @rdname apply_profile
-#' @export
-galah_apply_profile <- function(...){
-  dots <- rlang::enquos(..., .ignore_empty = "all") |>
-    detect_request_object()
-  switch(class(dots[[1]])[1],
-         "data_request" = {
-           result <- parse_quosures_basic(dots[-1]) |>
-             parse_profile()
-           update_request_object(dots[[1]],
-                                 apply_profile = result)
-         },
-         {
-           parse_quosures_basic(dots) |>
-             parse_profile()
-         })
-}
-
 #' Internal parsing of `profile` args
 #' @noRd
 #' @keywords Internal

R/atlas_counts.R

@@ -1,6 +1,6 @@
 #' @rdname atlas_
 #' @order 2
-#' @param group_by `tibble`: generated by a call to [galah_group_by()].
+#' @param group_by `r lifecycle::badge("superseded")` `tibble`: generated by a call to [galah_group_by()].
 #' @param limit `numeric`: maximum number of categories to return, defaulting to 100.
 #' If limit is NULL, all results are returned. For some categories this will
 #' take a while.

R/atlas_distributions.R

@@ -4,9 +4,9 @@
 #' @param request optional `data_request` object: generated by a call to
 #' [galah_call()].
 #' @param identify `data.frame`: generated by a call to
-#' [galah_identify()].
+#' identify().
 #' @param filter `data.frame`: generated by a call to
-#' [galah_filter()]
+#' filter()
 #' @return An object of classes `sf`, `tbl`, `tbl_df` and `data.frame` 
 #' (aka a Simple feature collection) of distribution maps, with one column per
 #' map, and spatial data stored in the `geometry` column.

R/atlas_media.R

@@ -12,27 +12,27 @@ atlas_media <- function(request = NULL,
                         apply_profile = NULL,
                         all_fields = FALSE
                         ) {
-
-  # check media is available
-  media_supported()
-
   # capture supplied arguments
   args <- as.list(environment())
   # convert to `data_request` object
   .query <- check_atlas_inputs(args)
   .query$type <- "occurrences" # default, but in case supplied otherwise
 
+  # check media is available
+  media_supported(atlas = .query$atlas)
+
   # ensure a filter is present (somewhat redundant with `collapse`)
   if(is.null(.query$filter)){
     cli::cli_abort("You must specify a valid `filter()` to use `atlas_media()`")
   }
 
+  # work out which fields are most available for this atlas
+  present_fields <- image_fields(atlas = .query$atlas)
+
   # ensure media columns are present in `select`
   if(is.null(.query$select)){
     .query <- .query |>
       dplyr::select(group = c("basic", "media"))
-    present_fields <- image_fields()
-    present_fields <- present_fields[present_fields != "multimedia"] # check these fields for Spain
     query_collapse <- collapse(.query)
     # if `select` is present, ensure that at least one 'media' field is requested
   }else{
@@ -45,42 +45,49 @@ atlas_media <- function(request = NULL,
       strsplit(split = ",") |>
       purrr::pluck(!!!list(1))
 
-    # `multimedia` should be in `select`, but not `filter`
-    image_select <- image_fields()
-    image_select <- image_select[image_select != "multimedia"] 
-
     # abort if no fields are given to `select`
-    if(!any(selected_fields %in% image_select)){
+    if(!any(selected_fields %in% present_fields)){
       selected_text <- glue::glue_collapse(selected_fields, sep = ", ")
       c("No media fields requested by `select()`", 
         i = "try `galah_select({selected_text}, group = 'media')` instead") |>
         cli::cli_abort()
     }else{
-      present_fields <- selected_fields[selected_fields %in% image_select]
+      present_fields <- selected_fields[selected_fields %in% present_fields]
       query_collapse <- x
     }
   } # end `select` checks
 
   # add media content to filters
   if(length(present_fields) > 0){
     # do region-specific filter parsing
-    media_fq <- image_filters(present_fields)
+    media_fq <- image_filters(present_fields, atlas = .query$atlas)
     # add back to source object
     if(length(media_fq) > 1){
       media_fq <- glue::glue("({glue::glue_collapse(media_fq, ' OR ')})") 
     }
     url <- httr2::url_parse(query_collapse$url)
-    url$query$fq <- glue::glue("{url$query$fq}AND{media_fq}")
+    # NOTE: since v 2.3.0, we need to adapt to whether there are `q` or `fq filters`
+    if(is.null(url$query$q)){
+      url$query$fq <- media_fq
+    }else{
+      if(is.null(url$query$fq)){
+        url$query$fq <- media_fq  
+      }else{
+        url$query$fq <- glue::glue("{url$query$fq}AND{media_fq}")
+      }
+    }
     query_collapse$url <- httr2::url_build(url)
   }
 
   # get occurrences, expand to one row per media entry
   occ <- query_collapse |> 
     collect(wait = TRUE) |>
-    build_media_id(media_fields = present_fields)
+    build_media_id(media_fields = present_fields[present_fields != "multimedia"])
+  # NOTE: `multimedia` field contains a description of which field has IDs
+  # _not_ IDs themselves; hence removal in above processing stage
 
   # collect media metadata
-  media_query <- request_metadata() |>
+  media_query <- request_metadata(from = .query$atlas) |>
     filter(media == dplyr::pull(occ, "media_id"))
   if(isTRUE(all_fields)){
     media_query <- media_query |>

R/atlas_occurrences.R

@@ -11,7 +11,7 @@
 #' 
 #'   * They have the ability to accept `filter`, `select` etc as arguments,
 #'     rather than within a pipe; but **only** when using the `galah_` forms of 
-#'     those functions (e.g. [galah_filter()]).
+#'     those functions (see [superseded_functions]).
 #'   * `atlas_` functions do not require you to specify the `method` or `type` 
 #'     arguments to [galah_call()], as they are more specific in what data are 
 #'     being requested.
@@ -20,11 +20,11 @@
 #' @order 1
 #' @param request optional `data_request` object: generated by a call to
 #' [galah_call()].
-#' @param identify `tibble`: generated by a call to [galah_identify()].
-#' @param filter `tibble`: generated by a call to [galah_filter()]
-#' @param geolocate `string`: generated by a call to [galah_geolocate()]
-#' @param apply_profile `string`: generated by a call to [galah_apply_profile()]
-#' @param select `tibble`: generated by a call to [galah_select()] 
+#' @param identify `r lifecycle::badge("superseded")` `tibble`: generated by a call to [galah_identify()].
+#' @param filter `r lifecycle::badge("superseded")` `tibble`: generated by a call to [galah_filter()]
+#' @param geolocate `r lifecycle::badge("superseded")` `string`: generated by a call to [galah_geolocate()]
+#' @param apply_profile `r lifecycle::badge("superseded")` `string`: generated by a call to [galah_apply_profile()]
+#' @param select `r lifecycle::badge("superseded")` `tibble`: generated by a call to [galah_select()] 
 #' @param mint_doi `logical`: by default no DOI will be generated. Set to
 #' `TRUE` if you intend to use the data in a publication or similar.
 #' @param doi `string`: (Optional) DOI to download. If provided overrides

R/atlas_species.R

@@ -32,7 +32,7 @@ atlas_species <- function(request = NULL,
 check_distinct_for_atlas_species <- function(.query){
   if(is.null(.query$distinct)){
     .query |>
-      distinct(species_facets(), .keep_all = TRUE)
+      distinct(species_facets(.query), .keep_all = TRUE)
   }else{
     .query$distinct$keep_all <- TRUE
     .query

R/atlas_taxonomy.R

@@ -20,7 +20,7 @@ atlas_taxonomy <- function(request = NULL,
   .query$type <- "taxonomy" # default, but in case supplied otherwise
   check_identify(.query)
   check_down_to(.query)
-  constrain_ids <- check_constraints(args = args, 
+  constrain_ids <- check_constraints(.query,
                                      call = as.list(sys.call()))
 
   # extract required information from `identify` 
@@ -58,11 +58,11 @@ atlas_taxonomy <- function(request = NULL,
 #' Internal function to check whether constraints have been passed
 #' @noRd
 #' @keywords Internal
-check_constraints <- function(args, call){
+check_constraints <- function(.query, call){
   if(any(names(call) == "constrain_ids")){ # i.e. if user specifies an argument
     call$constrain_ids
   }else{ # if NULL only occurs because no argument is set
-    if(potions::pour("atlas", "region") == "Australia"){
+    if(.query$atlas == "Australia"){
       "biodiversity.org.au"
     }
   }