Package 'emodnet.wcs'

Individual coverage level metadata

Description

Get coverage metadata from a ⁠<WCSCoverageSummary>⁠ object.

Usage

emdn_get_bbox(summary)

emdn_get_WGS84bbox(summary)

emdn_get_band_nil_values(summary, band = NULL)

emdn_get_band_descriptions(summary)

emdn_get_band_uom(summary)

emdn_get_band_constraints(summary)

emdn_get_grid_size(summary)

emdn_get_resolution(summary)

emdn_get_coverage_function(summary)

emdn_get_temporal_extent(summary)

emdn_get_vertical_extent(summary)

emdn_get_dimensions_info(
  summary,
  format = c("character", "list", "tibble"),
  include_coeffs = FALSE
)

emdn_get_dimensions_names(summary)

emdn_get_dimensions_n(summary)

emdn_get_dimension_types(summary)

Arguments

summary	a ⁠<WCSCoverageSummary>⁠ object.
band	Character vector of bands. By default all bands.
format	character string. Coverage dimension info output format. One of "character" (default), "list" or "tibble".
include_coeffs	whether to include a vector of temporal or vertical dimension coefficients (if applicable) in the coverage dimension info "list" output format. Defaults to FALSE. Ignored for other formats.

Value

• emdn_get_bbox: an object of class bbox of length 4 expressing the boundaries coverage extent/envelope. See sf::st_bbox() for more details.

• emdn_get_WGS84bbox: an object of class bbox of length 4 expressing the boundaries coverage extent/envelope. See sf::st_bbox() for more details.

• emdn_get_band_nil_values a numeric scalar of the value representing nil values in a coverage.

• emdn_get_band_descriptions a character vector of band descriptions.

• emdn_get_band_uom a character vector of band units of measurement.

• emdn_get_band_constraints a list of numeric vectors of length 2 indicating the min and max values of the data contained in each bands of the coverage.

• emdn_get_grid_size a numeric vector of length 2 giving the spatial size in grid cells (pixels) of the coverage grid (ncol x nrow)

• emdn_get_resolution a numeric vector of length 2 giving the spatial resolution of grid cells (size in the x dimension, size in the y dimension) of a coverage. The attached attribute uom gives the units of measurement of each dimension.

• emdn_get_coverage_function a list with elements:

  • sequence_rule, character string, the function describing the sequence rule, i.e. the relationship between the axes of data and coordinate system axes.

  • starting_point a numeric vector of length 2, the location of the origin of the data in the coordinate system.

  • axis_order a character vector of length 2 specifying the axis order and direction of mapping of values onto the grid, beginning at the starting point. For example, "+2 +1" indicates the value range is ordered from the bottom left to the top right of the grid envelope - lowest to highest in the x-axis direction first (+2), then lowest to highest in the y-axis direction (+1) from the starting_point.

• emdn_get_temporal_extent if the coverage has a temporal dimension, a numeric vector of length 2 giving the min and max values of the dimension. Otherwise, NA.

• emdn_get_vertical_extent if the coverage has a vertical dimension, a numeric vector of length 2 giving the min and max values of the dimension. Otherwise, NA.

• emdn_get_dimensions_info output depends on format argument:

  • character: (default) a concatenated character string of dimension information

  • list: a list of dimension information

  • tibble: a tibble of dimension information

Functions

• emdn_get_bbox(): Get the announced bounding box (geographic extent) of a coverage. Coordinates are given in the same Coordinate Reference System as the coverage. The bounding box is approximate and may overestimate coverage.

• emdn_get_WGS84bbox(): Get the announced bounding box (geographic extent) of a coverage in World Geodetic System 1984 (WGS84) Coordinate Reference System (or EPSG:4326). The bounding box is approximate and may overestimate coverage.

• emdn_get_band_nil_values(): Get the value representing nil values in a coverage.

• emdn_get_band_descriptions(): Get the band descriptions of a coverage.

• emdn_get_band_uom(): Get the units of measurement of the data contained in the bands values of a coverage.

• emdn_get_band_constraints(): Get the range of values of the data allowed in the bands of the coverage, for requests.

• emdn_get_grid_size(): Get the grid size of a coverage.

• emdn_get_resolution(): Get the resolution of a coverage.

• emdn_get_coverage_function(): Get the grid function of a coverage.

• emdn_get_temporal_extent(): Get the temporal extent of a coverage.

• emdn_get_vertical_extent(): Get the vertical (elevation) extent of a coverage.

• emdn_get_dimensions_info(): Get information on dimensions of a coverage in various formats. Information includes dimension label, type, unit and range (in tibble format).

• emdn_get_dimensions_names(): Get coverage dimension names (labels) and units.

• emdn_get_dimensions_n(): Get number of coverage dimensions.

• emdn_get_dimension_types(): Get dimensions types of a coverage.

Examples

wcs <- emdn_init_wcs_client(service = "biology")
summary <- emdn_get_coverage_summaries(wcs, "Emodnetbio__ratio_large_to_small_19582016_L1_err")[[1]]
# get bbox
emdn_get_bbox(summary)
# get WGS84 bbox
emdn_get_WGS84bbox(summary)
# get the nil value of a coverage
emdn_get_band_nil_values(summary)
# get coverage band descriptions
emdn_get_band_descriptions(summary)
# get band units of measurement
emdn_get_band_uom(summary)
# get range of band values
emdn_get_band_constraints(summary)
# get coverage grid size
emdn_get_grid_size(summary)
# get coverage resolution
emdn_get_resolution(summary)
# get coverage grid function
emdn_get_coverage_function(summary)
# get the extent of the temporal dimension
emdn_get_temporal_extent(summary)
# get the extent of the vertical dimension
emdn_get_vertical_extent(summary)
# get information about coverage dimensions in various formats
emdn_get_dimensions_info(summary)
emdn_get_dimensions_info(summary, format = "list")
emdn_get_dimensions_info(summary, format = "tibble")
# get dimension names
emdn_get_dimensions_names(summary)
# get number of dimensions
emdn_get_dimensions_n(summary)
# get dimensions types
emdn_get_dimension_types(summary)

---

Download data (coverage)

Description

Get a coverage from an EMODnet WCS Service

Usage

emdn_get_coverage(
  wcs = NULL,
  service = NULL,
  coverage_id,
  service_version = c("2.0.1", "2.1.0", "2.0.0", "1.1.1", "1.1.0"),
  logger = c("NONE", "INFO", "DEBUG"),
  bbox = NULL,
  crs = "EPSG:4326",
  time = NULL,
  elevation = NULL,
  format = NULL,
  rangesubset = NULL,
  filename = NULL,
  nil_values_as_na = FALSE
)

Arguments

wcs	A WCSClient R6 object, created with function emdn_init_wcs_client.
service	the EMODnet OGC WCS service name. For available services, see emdn_wcs().
coverage_id	character string. Coverage ID. Inspect your wcs object for available coverages.
service_version	the WCS service version. Defaults to "2.0.1".
logger	character string. Level of logger: 'NONE' for no logger, 'INFO' to get ows4R logs, 'DEBUG' for all internal logs (such as as Curl details)
bbox	a named numeric vector of length 4, with names xmin, ymin, xmax and ymax, specifying the bounding box (extent) of the raster to be returned. Can also be an object that can be coerced to a bbox object with sf::st_bbox().
crs	the CRS of the supplied bounding box (EPSG prefixed code, or URI/URN). Defaults to "EPSG:4326". It will be ignored when the CRS is already defined for argument bbox.
time	for coverages that include a temporal dimension, a vector of temporal coefficients specifying the time points for which coverage data should be returned. If NULL (default), the last time point is returned. To get a list of all available temporal coefficients, see emdn_get_coverage_dim_coefs. For a single time point, a SpatRaster is returned. For more than one time points, SpatRaster stack is returned.
elevation	for coverages that include a vertical dimension, a vector of vertical coefficients specifying the elevation for which coverage data should be returned. If NULL (default), the last elevation is returned. To get a list of all available vertical coefficients, see emdn_get_coverage_dim_coefs. For a single elevation, a SpatRaster is returned. For more than one elevation, SpatRaster stack is returned.
format	the format of the file the coverage should be written out to.
rangesubset	character vector of band descriptions to subset. Can work better if you use a bounding box (https://github.com/eblondel/ows4R/issues/147).
filename	the file name to write to.
nil_values_as_na	logical. Should raster nil values be converted to NA?

Value

an object of class terra::SpatRaster. The function also writes the coverage to a local file.

Examples

wcs <- emdn_init_wcs_client(service = "biology")
coverage_id <- "Emodnetbio__cal_fin_19582016_L1_err"
# Subset using a bounding box
emdn_get_coverage(wcs,
  coverage_id = coverage_id,
  bbox = c(
    xmin = 0, ymin = 40,
    xmax = 5, ymax = 45
  )
)
# Subset using a bounding box and specific timepoints
emdn_get_coverage(wcs,
  coverage_id = coverage_id,
  bbox = c(
    xmin = 0, ymin = 40,
    xmax = 5, ymax = 45
  ),
  time = c(
    "1958-02-16T01:00:00",
    "1958-05-16T01:00:00"
  )
)
# Subset using a bounding box and a specific band
north_sea_bbox <- c(xmin = -4, ymin = 50, xmax = 10, ymax = 62)
emdn_get_coverage(wcs,
  coverage_id = coverage_id,
  bbox = north_sea_bbox,
  rangesubset = "Relative abundance"
)

---

Service and coverage level metadata

Description

Get metadata objects from a WCSClient object. ⁠<WCSCoverageSummary>⁠ in particular can be used to extract further metadata about individual coverages.

Usage

emdn_get_coverage_summaries(wcs, coverage_ids)

emdn_get_coverage_summaries_all(wcs)

emdn_get_coverage_ids(wcs)

emdn_has_dimension(wcs, coverage_ids, type = c("temporal", "vertical"))

emdn_get_coverage_dim_coefs(
  wcs,
  coverage_ids,
  type = c("temporal", "vertical")
)

Arguments

wcs	A WCSClient R6 object, created with function emdn_init_wcs_client.
coverage_ids	character vector of coverage IDs.
type	a coverage dimension type. One of "temporal" or "vertical".

Value

• emdn_get_coverage_summaries: returns a list of objects of class ⁠<WCSCoverageSummary>⁠ for each coverage_id provided.

• emdn_get_coverage_summaries_all: returns a list of objects of class ⁠<WCSCoverageSummary>⁠ for each coverage avalable through the service.

• emdn_get_coverage_ids returns a character vector of coverage ids.

• emdn_get_coverage_dim_coefs returns a list containing a vector of coefficients for each coverage requested.

a list containing a vector of coefficients for each coverage requested.

Functions

• emdn_get_coverage_summaries(): Get summaries for specific coverages.

• emdn_get_coverage_summaries_all(): Get summaries for all available coverages from a service.

• emdn_get_coverage_ids(): Get coverage IDs for all available coverages from a service.

• emdn_has_dimension(): check whether a coverage has a temporal or vertical dimension.

• emdn_get_coverage_dim_coefs(): Get temporal or vertical coefficients for a coverage.

Examples

wcs <- emdn_init_wcs_client(service = "biology")
cov_ids <- emdn_get_coverage_ids(wcs)
cov_ids
emdn_has_dimension(wcs,
  cov_ids,
  type = "temporal"
)
emdn_has_dimension(wcs,
  cov_ids,
  type = "vertical"
)
emdn_get_coverage_summaries(wcs, cov_ids[1:2])
emdn_get_coverage_summaries_all(wcs)
emdn_get_coverage_dim_coefs(wcs,
  cov_ids[1:2],
  type = "temporal"
)

---

Metadata about data available from the different services: data (coverage) from a data source (service), metadata on coverage from a service.

Description

Get EMODnet WCS service and available coverage information.

Usage

emdn_get_wcs_info(
  wcs = NULL,
  service = NULL,
  service_version = c("2.0.1", "2.1.0", "2.0.0", "1.1.1", "1.1.0"),
  logger = c("NONE", "INFO", "DEBUG")
)

emdn_get_wcs_info_all(logger = c("NONE", "INFO", "DEBUG"))

emdn_get_coverage_info(
  wcs = NULL,
  service = NULL,
  coverage_ids,
  service_version = c("2.0.1", "2.1.0", "2.0.0", "1.1.1", "1.1.0"),
  logger = c("NONE", "INFO", "DEBUG")
)

Arguments

wcs	A WCSClient R6 object, created with function emdn_init_wcs_client.
service	the EMODnet OGC WCS service name. For available services, see emdn_wcs().
service_version	the WCS service version. Defaults to "2.0.1".
logger	character string. Level of logger: 'NONE' for no logger, 'INFO' to get ows4R logs, 'DEBUG' for all internal logs (such as as Curl details)
coverage_ids	character vector of coverage IDs.

Details

To minimize the number of requests sent to webservices, these functions use memoise to cache results inside the active R session. To clear the cache, re-start R or run memoise::forget(emdn_get_wcs_info)/memoise::forget(emdn_get_coverage_info)

Value

emdn_get_wcs_info & emdn_get_wcs_info return a list of service level metadata, including a tibble containing coverage level metadata for each coverage available from the service. emdn_get_coverage_info returns a list containing a tibble of more detailed metadata for each coverage specified.

emdn_get_wcs_info / emdn_get_wcs_info_all

emdn_get_wcs_info and emdn_get_wcs_info_all return a list with the following metadata:

• data_source: the EMODnet source of data.

• service_name: the EMODnet WCS service name.

• service_url: the EMODnet WCS service URL.

• service_title: the EMODnet WCS service title.

• service_abstract: the EMODnet WCS service abstract.

• service_access_constraits: any access constraints associated with the EMODnet WCS service.

• service_fees: any access fees associated with the EMODnet WCS service.

• service_type: the EMODnet WCS service type.

• coverage_details: a tibble of details of each coverage available through EMODnet WCS service:

  • coverage_id: the coverage ID.

  • dim_n: the number of coverage dimensions

  • dim_names: the coverage dimension names, units (in brackets) and types.

  • extent: the coverage extent (xmin, ymin, xmax and ymax).

  • crs: the coverage CRS (Coordinate Reference System).

  • wgs84_bbox: the coverage extent (xmin, ymin, xmax and ymax) in WGS84 (EPSG:4326) CRS coordinates.

  • temporal_extent: the coverage temporal extent (min - max), NA if coverage contains no temporal dimension.

  • vertical_extent: the coverage vertical extent (min - max), NA if coverage contains no vertical dimension.

  • subtype: the coverage subtype.

emdn_get_coverage_info

emdn_get_coverage_info returns a tibble with a row for each coverage specified and columns with the following details:

• data_source: the EMODnet source of data.

• service_name: the EMODnet WCS service name.

• service_url: the EMODnet WCS service URL.

• coverage_ids: the coverage ID.

• band_description: the description of the data contained each band of the coverage.

• band_uom: the unit of measurement of the data contained each band of the coverage. If all bands share the same unit of measurement, the single shared uom is shown.

• constraint: the range of values of the data contained in each band of the coverage. If all bands share the same constraint, the single shared constraint range is shown.

• nil_value: the nil values of the data contained each band of the coverage. If all bands share the same nil value, the single shared nil value is shown.

• grid_size: the spatial size of the coverage grid (ncol x nrow).

• resolution: the spatial resolution (pixel size) of the coverage grid in the CRS units of measurement (size in the x dimension x size in the y dimension).

• dim_n: the number of coverage dimensions

• dim_names: the coverage dimension names, units (in brackets) and types.

• extent: the coverage extent (xmin, ymin, xmax and ymax).

• crs: the coverage CRS (Coordinate Reference System).

• wgs84_bbox: the coverage extent (xmin, ymin, xmax and ymax) in WGS84 (EPSG:4326) CRS coordinates.

• temporal_extent: the coverage temporal extent (min - max), NA if coverage contains no temporal dimension.

• vertical_extent: the coverage vertical extent (min - max), NA if coverage contains no vertical dimension.

• subtype: the coverage subtype.

• fn_seq_rule: the function describing the sequence rule which specifies the relationship between the axes of data and coordinate system axes.

• fn_start_point: the location of the origin of the data in the coordinate system.

• fn_axis_order: the axis order and direction of mapping of values onto the grid, beginning at the starting point. For example, "+2 +1" indicates the value range is ordered from the bottom left to the top right of the grid envelope - lowest to highest in the x-axis direction first (+2), then lowest to highest in the y-axis direction (+1) from the starting_point.

For additional details on WCS metadata, see the GDAL wiki section on WCS Basics and GDAL

Functions

• emdn_get_wcs_info(): Get info on all coverages from am EMODnet WCS service.

• emdn_get_wcs_info_all(): Get metadata on all services and all available coverages from each service.

• emdn_get_coverage_info(): Get metadata for specific coverages. Requires a WCSClient R6 object as input.

Examples

# Get information from a wcs object.
wcs <- emdn_init_wcs_client(service = "seabed_habitats")
emdn_get_wcs_info(wcs)
# Get detailed info for specific coverages from wcs object
coverage_ids <- c(
  "emodnet_open_maplibrary__mediseh_cora",
  "emodnet_open_maplibrary__mediseh_posidonia"
)
emdn_get_coverage_info(
  wcs = wcs,
  coverage_ids = coverage_ids
)

---

Connect to a data source (service)

Description

Initialise an EMODnet WCS client

Usage

emdn_init_wcs_client(
  service,
  service_version = c("2.0.1", "2.1.0", "2.0.0", "1.1.1", "1.1.0"),
  logger = c("NONE", "INFO", "DEBUG")
)

Arguments

service	the EMODnet OGC WCS service name. For available services, see emdn_wcs().
service_version	the WCS service version. Defaults to "2.0.1".
logger	character string. Level of logger: 'NONE' for no logger, 'INFO' to get ows4R logs, 'DEBUG' for all internal logs (such as as Curl details)

Value

An ows4R::WCSClient R6 object with methods for interfacing an OGC Web Coverage Service.

See Also

WCSClient in package ows4R.

Examples

(wcs <- emdn_init_wcs_client(service = "bathymetry"))

---

Which data sources (services) are available?

Description

Available EMODnet Web Coverage Services

Usage

emdn_wcs()

Value

Tibble of available EMODnet Web Coverage Services

Examples

emdn_wcs()

---