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 example endpoints worth pointing it at:

• USGS waterdata OGC API

• Western Water Datahub (a pygeoapi deployment)

A typical session looks like:

1. Build a client with edr_client().

2. Discover what's on offer with edr_collections(), edr_parameters(), optional edr_parameter_groups(), 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 range value and axis-coordinate combination. Handles the Point and PointSeries domain types used by station-based EDR providers, and falls back to a general N-dimensional unrolling for Grid-like domains.

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 wrapping the returned CoverageJSON, or a parsed list for other JSON. The result contains data inside the requested polygon.

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,
  headers = NULL,
  verbose = FALSE
)

Arguments

Value

An object of class edr_client containing the service URL and reusable HTTP request settings.

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 = NULL,
  width_units = "km",
  height_units = "m",
  datetime = NULL,
  parameter_name = NULL,
  z = NULL,
  crs = NULL,
  format = c("covjson", "json"),
  ...
)

Arguments

Value

An edr_response wrapping the returned CoverageJSON, or a parsed list for other JSON. The result contains data inside the requested corridor around the path.

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 wrapping the returned CoverageJSON, or a parsed list for other JSON. The result contains data inside the requested bounding box.

One-shot fetch + plot + map for a collection

Description

Convenience wrapper that finds stations via edr_locations(), fetches time series with one bulk request via edr_cube() or edr_area() when the collection supports it, and hands the lot to edr_map() for rendering. Optionally writes the map to a selfcontained HTML file.

Usage

edr_explore(
  client,
  collection_id,
  bbox = NULL,
  coords = NULL,
  datetime = NULL,
  parameter_name = NULL,
  limit = NULL,
  record_limit = NULL,
  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. For polygon coords, locations are first restricted to the polygon.

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.

When polygon coords are supplied but the collection only advertises locations, method = "auto" falls back to bbox-filtered location discovery, filters those locations to the polygon, and fetches each matching location. If the collection advertises area, the area query is attempted first; an unavailable endpoint (HTTP 404, 405, or 501) triggers the same locations fallback. Explicit method = "area" instead requires the collection's ⁠/area⁠ endpoint.

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

When the server returns GeoJSON, an sf object if the sf package is installed, otherwise an edr_response wrapping the raw GeoJSON. For other JSON responses, a parsed list. The result describes the matching collection items from edr_items() or the requested feature from edr_item().

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 wrapping the returned CoverageJSON or GeoJSON, a tibble for CSV, or a parsed list for other JSON. The result contains data associated with the requested location.

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. The result describes the collection locations matching the supplied filters.

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 cross-collection parameter groups

Description

Some EDR deployments advertise a top-level parameterGroups block on ⁠/collections⁠. A group maps one environmental concept to the parameter identifiers used by multiple collections, which is useful when building comparable cross-provider queries.

Usage

edr_parameter_groups(client)

Arguments

Details

This is an optional deployment extension rather than a required EDR capability. Servers without parameterGroups return an empty tibble.

Value

A tibble with name, description, and list-column members.

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 visualizing the selected parameter and view.

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 wrapping the returned CoverageJSON, or a parsed list for other JSON. The result contains data at the requested point.

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 wrapping the returned CoverageJSON, or a parsed list for other JSON. The result contains data within the requested radius of the point.

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

The parsed response body: usually a list, tibble, or edr_response representing the requested EDR resource. Returns an httr2_response when parse = FALSE or format = "raw".

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 wrapping the returned CoverageJSON, or a parsed list for other JSON. The result contains data sampled along the requested path.

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 containing the GeoJSON feature properties and geometries. Requires the sf package. If sf is not installed, returns a tibble of feature properties without geometry and warns.