Skip to contents

One-shot fetch + plot + map for a collection

Source: R/explore.R
edr_explore.Rd

Convenience wrapper that plans a supported query, fetches data with one bulk request via edr_cube() or edr_area() when possible, and hands the result to edr_map() or edr_plot(). Station locations are requested only when the result needs a station map or a per-location fallback. Optionally writes a map to a self-contained HTML file.

Usage

edr_explore(
  client,
  collection_id,
  bbox = NULL,
  coords = NULL,
  datetime = NULL,
  parameter_name = NULL,
  limit = NULL,
  record_limit = NULL,
  max_requests = 100L,
  file = NULL,
  popup = "plot+csv",
  method = c("auto", "cube", "area", "position", "per-location"),
  output = c("auto", "map", "plot", "data"),
  plot_view = c("auto", "time", "profile", "grid"),
  quiet = FALSE,
  ...,
  instance_id = NULL,
  initial = list()
)

Arguments

client

An edr_client.

collection_id

Collection identifier.

bbox

Optional numeric length-4 bbox. Used both to filter the locations index (if the server honours it) and as the bbox for the cube fetch in method = "auto". If omitted with method = "cube", derived from the bounding box of the returned locations sf.

coords

Point coords for position, or polygon coords for area. Forwarded to edr_position() / edr_area().

datetime

ISO-8601 interval forwarded to the data fetch.

parameter_name

Character vector of parameter ids; forwarded to the data fetch. Use edr_parameters() to discover valid ids.

limit

Optional cap on the number of stations to map.

record_limit

Optional per-station record cap, passed through to edr_location() in the per-location path. Useful for servers (e.g. USGS waterdata) that cap responses at ~10 records by default. Ignored on the cube and area paths.

max_requests

Maximum number of per-location data requests permitted in one call. Defaults to 100. Set to Inf only when an intentionally unbounded batch is acceptable. Ignored by bulk methods.

file

If non-NULL, write the map to this HTML path via edr_save_html() and return file invisibly. Otherwise return the leaflet map.

popup

Popup mode (forwarded to edr_map()).

method

One of "auto" (default), "cube", "area", "position", or "per-location". See above.

output

One of "auto" (default), "map", "plot", or "data". "auto" returns a station map for station time-series results and an interactive coverage map for gridded/profile results.

plot_view

Plot view passed to edr_plot() when returning a plot. Defaults to "auto".

quiet

If FALSE (default), print a cli progress bar when falling back to per-location fetches.

...

Forwarded to edr_map() when returning a map.

instance_id

Optional collection instance identifier. When supplied, capability planning and every locations/data request use that instance. This keyword-only argument leaves existing positional calls unchanged.

initial

Named list of initial coverage-map selections, including friendly custom-coordinate names such as list(realisations = "control"). Keyword-only and used only when the result is a grid/profile coverage map.

Value

A leaflet htmlwidget, a ggplot, a tidy tibble/list when output = "data", or invisible(file) when a map is saved.

Details

The default method = "auto" picks the cheapest route the collection advertises in its data_queries:

  • cube – one HTTP call returning a CoverageCollection across the whole bbox. Fast. Used when the collection supports cube and a bbox is supplied.

  • area – like cube but uses a polygon. Used when coords is supplied and the collection supports area.

  • position – one HTTP call at a point. Useful for vertical profiles returned by position queries.

  • per-location – the fallback: one HTTP call per station via edr_location(). Slower (N+1), used when neither spatial bulk query is supported or the matching spatial input was not supplied.

Force a specific path by setting method. coords is required for area and position; if method = "cube" and bbox is omitted, the bbox is derived from the returned locations.

Examples

if (FALSE) { # \dontrun{
cl <- edr_client("https://api.wwdh.internetofwater.app")

# One /cube call across a bbox -- fast.
edr_explore(
  cl, "rise-edr",
  bbox           = c(-116, 35.5, -114, 36.5),
  datetime       = "2023-01-01/2023-03-31",
  parameter_name = "3",
  file           = tempfile(fileext = ".html")
)
} # }