Package {edr4r}

edr4r: A tidy R client for OGC API - Environmental Data Retrieval

Description

edr4r talks to any service that implements OGC API - Environmental Data Retrieval. It's general-purpose, but most of the testing and real-world use to date has been against in-situ monitoring networks – the kind of service that exposes stream gauges, weather stations, snow telemetry, or reservoir telemetry as EDR collections.

Details

Two operational endpoints worth pointing it at:

• USGS waterdata OGC API

• Western Water Datahub (a pygeoapi deployment)

The Met Office Labs EDR demonstrator is also useful for cross-server compatibility experiments. It is a technical demonstrator, not an operational service, so its availability and advertised data may change without notice.

A typical session looks like:

1. Build a client with edr_client().

2. Discover what's on offer with edr_collections() and edr_queryables().

3. Pull data with edr_locations() / edr_location(), edr_cube(), edr_area(), edr_position(), or the less common edr_radius() / edr_trajectory() / edr_corridor().

4. Flatten the response with covjson_to_tibble() (for CoverageJSON) or geojson_to_sf() (for GeoJSON).

For everything the high-level verbs don't cover, edr_request() is the raw escape hatch.

Author(s)

Maintainer: Kyle Onda konda@lincolninst.edu [copyright holder]

See Also

Useful links:

• https://github.com/ksonda/edr4r

• Report bugs at https://github.com/ksonda/edr4r/issues

Convert a CoverageJSON response to a tidy tibble

Description

Flattens a CoverageJSON Coverage or CoverageCollection into a long tibble with one row per (coverage, parameter, domain position). Handles primitive, regularly spaced, and composite tuple axes, including the axes used by Grid, PointSeries, MultiPointSeries, and Trajectory domains. Inline NdArray ranges are validated before they are flattened.

Usage

covjson_to_tibble(x, datetime_as_posix = TRUE)

Arguments

Value

A tibble with columns coverage_id, parameter, parameter_label, unit, datetime, x, y, z, and value. Columns that are absent from the source are filled with NA.

Area query (data inside a polygon)

Description

Calls GET /collections/{collection_id}/area with a WKT POLYGON in the coords parameter.

Usage

edr_area(
  client,
  collection_id,
  coords,
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response containing the server's CoverageJSON response. Convert it with covjson_to_tibble().

Create an EDR client

Description

Builds a reusable client object that captures the base URL of an OGC API - EDR service, a default user-agent, and HTTP options that are applied to every request.

Usage

edr_client(
  base_url,
  user_agent = NULL,
  timeout = 60,
  max_tries = 3,
  retry_on_failure = TRUE,
  headers = NULL,
  verbose = FALSE
)

Arguments

Value

An object of class edr_client.

Examples

usgs <- edr_client("https://api.waterdata.usgs.gov/ogcapi/beta")
usgs

Get a single collection's metadata

Description

Get a single collection's metadata

Usage

edr_collection(client, collection_id)

Arguments

Value

A list with the raw collection document.

List collections offered by the service

Description

List collections offered by the service

Usage

edr_collections(client)

Arguments

Value

A tibble with one row per collection. Always includes id, title, description, extent_bbox, crs, data_queries, and links columns.

Declared OGC API conformance classes

Description

Declared OGC API conformance classes

Usage

edr_conformance(client)

Arguments

Value

A character vector of conformance class URIs.

Corridor query (data along a path with a width)

Description

Calls GET /collections/{collection_id}/corridor.

Usage

edr_corridor(
  client,
  collection_id,
  coords,
  corridor_width,
  corridor_height,
  width_units = "km",
  height_units = "m",
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response containing the server's CoverageJSON response. Convert it with covjson_to_tibble().

Cube query (data inside a bounding box)

Description

Calls GET /collections/{collection_id}/cube with a bounding box.

Usage

edr_cube(
  client,
  collection_id,
  bbox,
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response containing the server's CoverageJSON response. Convert it with covjson_to_tibble().

One-shot fetch + plot + map for a collection

Description

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,
  ...
)

Arguments

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.

Value

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

Examples

## Not run: 
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")
)

## End(Not run)

Items (OGC API Features) helpers

Description

Many EDR servers expose an OGC API Features ⁠/items⁠ endpoint alongside the EDR queries. Behaviour varies: some deployments implement items as a full Features endpoint, others as a thin stub used only to register the collection as both EDR and Features. In the stub case, non-trivial data is usually obtained via the EDR queries (edr_locations(), edr_area(), edr_cube(), etc.).

Usage

edr_items(
  client,
  collection_id,
  bbox = NULL,
  datetime = NULL,
  limit = NULL,
  format = c("geojson", "json"),
  ...
)

edr_item(client, collection_id, item_id, format = c("geojson", "json"), ...)

Arguments

Value

An sf object when sf is installed and the server returns GeoJSON; otherwise an edr_response wrapping the GeoJSON document.

EDR service landing page

Description

Retrieves the service root document, which advertises links to the collections, conformance, and openapi endpoints.

Usage

edr_landing(client)

Arguments

Value

A list with the parsed landing document.

Get data for a single location

Description

Calls GET /collections/{collection_id}/locations/{location_id}. Typically returns CoverageJSON; pass the result to covjson_to_tibble() for a tidy data frame.

Usage

edr_location(
  client,
  collection_id,
  location_id,
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "geojson", "csv", "json"),
  ...
)

Arguments

Value

An edr_response containing CoverageJSON or GeoJSON, or a tibble for CSV responses. Use covjson_to_tibble() or geojson_to_sf() to convert structured JSON responses.

List locations in a collection

Description

Calls GET /collections/{collection_id}/locations. With no extra filters, EDR servers typically return a GeoJSON FeatureCollection of available locations.

Usage

edr_locations(
  client,
  collection_id,
  bbox = NULL,
  datetime = NULL,
  parameter_name = NULL,
  crs = NULL,
  limit = NULL,
  format = c("geojson", "json"),
  ...
)

Arguments

Value

When the server returns GeoJSON, an sf object if the sf package is installed, otherwise an edr_response wrapping the raw GeoJSON. When the server returns CoverageJSON, an edr_response.

Map EDR locations or coverage data

Description

Builds a leaflet::leaflet map of station features or gridded/profile CoverageJSON data. Station maps can show per-station popups with interactive time-series charts and CSV downloads. Coverage maps keep all supplied parameters, times, and vertical levels in the widget and expose in-map controls for choosing the active slice; grid cells open popups with a time-series chart for the clicked cell.

Usage

edr_map(
  locations,
  data = NULL,
  popup = c("plot+csv", "plot", "csv", "table", "all"),
  location_col = "coverage_id",
  id_col = NULL,
  label_col = NULL,
  parameter = NULL,
  plot_width = 7,
  plot_height = 3.5,
  plot_dpi = 72,
  tile_provider = "CartoDB.Positron",
  marker_radius = 6,
  matched_color = "#2C7FB8",
  unmatched_color = "#BBBBBB",
  show_unmatched = TRUE,
  legend = TRUE,
  max_match_distance = NULL,
  mode = c("auto", "stations", "grid", "profile"),
  controls = TRUE,
  initial = list(),
  grid_opacity = 0.75
)

Arguments

Details

data can be one of:

• NULL – just markers with the sf attribute table as a popup (when popup = "table" or popup = "all").

• A long tibble (the output of covjson_to_tibble()) with one column matching the locations' id column. Set ⁠location_col =⁠ to the column in data that holds the location id and ⁠id_col =⁠ to the column in locations.

• A named list of tibbles, keyed by feature id. This is what edr_explore() passes when it fetches one time series per station — and the right shape when each station has its own CovJSON response, because server-assigned coverage_ids like "1" won't naturally match the feature id.

Value

A leaflet htmlwidget. Pass it to edr_save_html() to write a selfcontained HTML file.

List the data parameters a collection serves

Description

Pulls the parameter_names block out of the collection document (GET /collections/{id}) and flattens it into a tidy tibble. These are the observed properties you can pass to ⁠parameter_name =⁠ on the query verbs (edr_location(), edr_cube(), etc.).

Usage

edr_parameters(client, collection_id)

Arguments

Details

EDR servers vary in how they key the parameter_names dictionary (numeric IDs, short codes, etc.). The id column in the returned tibble is the value to pass back as parameter_name; the name column is the human-readable label.

Value

A tibble with one row per parameter. Columns: id, name, description, unit_symbol, unit_label, observed_property.

Plot an EDR response as a ggplot

Description

Convenience wrapper around ggplot2::ggplot() for the long tibble returned by covjson_to_tibble(). Automatically chooses a sensible view for time series, vertical profiles, and x/y grids.

Usage

edr_plot(
  data,
  parameter = NULL,
  group = "coverage_id",
  facet = "parameter",
  scales = "free_y",
  geom = c("line", "point", "both"),
  facet_labels = TRUE,
  view = c("auto", "time", "profile", "grid")
)

Arguments

Value

A ggplot object.

Examples

## Not run: 
cl <- edr_client("https://api.wwdh.internetofwater.app")
resp <- edr_location(cl, "rise-edr",
                     location_id    = 3514,
                     datetime       = "2023-01-01/2023-06-30",
                     parameter_name = "3")
edr_plot(resp)

## End(Not run)

Position query (data at a point)

Description

Calls GET /collections/{collection_id}/position with a WKT POINT in the coords parameter.

Usage

edr_position(
  client,
  collection_id,
  coords,
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response containing the server's CoverageJSON response. Convert it with covjson_to_tibble().

Get the queryables (filter properties) for a collection

Description

Returns the OGC API queryables document for a collection – a JSON Schema describing the filter properties the server exposes (this is typically used by OGC API Features for CQL2 / property-based filtering). It is not the right place to look up the data parameters / observed properties an EDR collection serves; for that, use edr_parameters().

Usage

edr_queryables(client, collection_id)

Arguments

Value

A list with the parsed queryables document.

Radius query (data within a radius of a point)

Description

Calls GET /collections/{collection_id}/radius.

Usage

edr_radius(
  client,
  collection_id,
  coords,
  within,
  within_units = "km",
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response containing the server's CoverageJSON response. Convert it with covjson_to_tibble().

Perform a low-level EDR request

Description

Generally you should not need to call this directly: the high-level verbs (edr_locations(), edr_area(), etc.) build the path and query string for you. Use edr_request() when you need to hit a bespoke path or a non-standard parameter.

Usage

edr_request(
  client,
  path,
  query = list(),
  format = c("json", "geojson", "covjson", "csv", "html", "raw"),
  parse = TRUE
)

Arguments

Value

A parsed list, tibble, or edr_response wrapper; an httr2_response when parse = FALSE; or a typed empty result for HTTP 204 responses.

Save a map to a standalone HTML file

Description

Thin wrapper around htmlwidgets::saveWidget() for the leaflet map returned by edr_map() or edr_explore(). With selfcontained = TRUE (the default), popup chart data and CSV download links live inside the file – no sidecar directory.

Usage

edr_save_html(map, file, selfcontained = TRUE, ...)

Arguments

Value

Invisibly returns file.

Trajectory query (data along a path)

Description

Calls GET /collections/{collection_id}/trajectory.

Usage

edr_trajectory(
  client,
  collection_id,
  coords,
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response containing the server's CoverageJSON response. Convert it with covjson_to_tibble().

Convert a GeoJSON EDR response to an sf object

Description

Convert a GeoJSON EDR response to an sf object

Usage

geojson_to_sf(x)

Arguments

Value

An sf object. Requires the sf package. If sf is not installed, returns a tibble of feature properties (without geometry) and warns.