Package 'CopernicusMarine'

How to cite a Copernicus marine product

Description

Get details for properly citing a Copernicus product.

Usage

cms_cite_product(product)

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

Value

Returns a vector of character strings. The first element is always the product title, id and doi. Remaining elements are other associated references. Note that the remaining references are returned as listed at Copernicus. Note that the citing formatting does not appear to be standardised.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_product_details(), cms_product_metadata(), cms_product_services(), cms_products_list()

Examples

cms_cite_product("SST_MED_PHY_SUBSKIN_L4_NRT_010_036")

---

List and get STAC files for a Copernicus marine product

Description

Full marine data sets can be downloaded using the SpatioTemporal Asset Catalogs (STAC). Use these functions to list download locations and get the files.

Usage

cms_download_stac(
  file_tibble,
  destination,
  show_progress = TRUE,
  overwrite = FALSE
)

cms_list_stac_files(product, layer)

cms_stac_properties(product, layer)

Arguments

file_tibble	A dplyr::tibble() with in each row the files to be downloaded. Should be created with cms_list_stac_files().
destination	A character string representing the path location where the downloaded files should be stored.
show_progress	A logical value. When TRUE (default) the download progress will be shown. This can be useful for large files.
overwrite	A logical value. When FALSE (default), files at the destination won't be overwritten when the exist. Instead an error will be thrown if this is the case. When set to TRUE, existing files will be overwritten.
product	An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.
layer	The name of a desired layer within a product (type character). Can be obtained with cms_product_details.

Value

In case of cms_stac_properties a dplyr::tibble() is returned with some product properties, It is used as precursor for cms_list_stac_files. In case of cms_list_stac_files a dplyr::tibble() is returned containing available URLs (for the specified product and layer) and some meta information is returned. In case of cms_download_stac an invisible logical value is returned, indicating whether all requested files are successfully stored at the destination path. A list of responses (of class httr2::response()) for all requested download links is included as attribute to the result.

Author(s)

Pepijn de Vries

Examples

## Not run: 
## List some STAC properties for a specific product and layer
cms_stac_properties(
  product       = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
  layer         = "cmems_mod_glo_phy-cur_anfc_0.083deg_P1D-m"
)

## Get the available files for a specific product and layer:
file_tibble <-
  cms_list_stac_files("GLOBAL_ANALYSISFORECAST_PHY_001_024",
                      "cmems_mod_glo_phy-cur_anfc_0.083deg_P1D-m")

dest <- tempdir()

## download the first file from the file_tibble to 'dest'
cms_download_stac(file_tibble[1,, drop = FALSE], dest)

## End(Not run)

---

Subset and download a specific marine product from Copernicus

Description

Subset and download a specific marine product from Copernicus. You need to register an account at https://data.marine.copernicus.eu before you can use this function.

Usage

cms_download_subset(
  username = getOption("CopernicusMarine_uid", ""),
  password = getOption("CopernicusMarine_pwd", ""),
  destination,
  product,
  layer,
  variable,
  region,
  timerange,
  verticalrange,
  overwrite = FALSE
)

Arguments

username	Your Copernicus marine user name. Can be provided as options(CopernicusMarine_uid = "my_user_name"), or as argument here.
password	Your Copernicus marine password. Can be provided as options(CopernicusMarine_pwd = "my_password"), or as argument here.
destination	File or path where the requested file will be downloaded to.
product	An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.
layer	The name of a desired layer within a product (type character). Can be obtained with cms_product_details.
variable	The name of a desired variable in a specific layer of a product (type character). Can be obtained with cms_product_details.
region	Specification of the bounding box as a vector of numerics WGS84 lat and lon coordinates. Should be in the order of: xmin, ymin, xmax, ymax.
timerange	A vector with two elements (lower and upper value) for a requested time range. The vector should be coercible to POSIXct.
verticalrange	A vector with two elements (minimum and maximum) numerical values for the depth of the vertical layers (if any). Note that values below the sea surface needs to be specified as negative values.
overwrite	A logical value. When FALSE (default), files at the destination won't be overwritten when the exist. Instead an error will be thrown if this is the case. When set to TRUE, existing files will be overwritten.

Value

Returns a logical value invisibly indicating whether the requested file was successfully stored at the destination.

Author(s)

Pepijn de Vries

Examples

## Not run: 
destination <- tempfile("copernicus", fileext = ".nc")

## Assuming that Copernicus account details are provided as `options`
cms_download_subset(
  destination   = destination,
  product       = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
  layer         = "cmems_mod_glo_phy-cur_anfc_0.083deg_P1D-m",
  variable      = "sea_water_velocity",
  region        = c(-1, 50, 10, 55),
  timerange     = c("2021-01-01 UTC", "2021-01-02 UTC"),
  verticalrange = c(0, -2)
)

mydata <- stars::read_stars(destination)

plot(mydata["vo"])

## End(Not run)

---

Contact Copernicus Marine login page

Description

Contact Copernicus Marine login page and check if login is successful.

Usage

cms_login(
  username = getOption("CopernicusMarine_uid", ""),
  password = getOption("CopernicusMarine_pwd", "")
)

Arguments

username	Your Copernicus marine user name. Can be provided as options(CopernicusMarine_uid = "my_user_name"), or as argument here.
password	Your Copernicus marine password. Can be provided as options(CopernicusMarine_pwd = "my_password"), or as argument here.

Details

This function will return a logical value indicating if the login is successful. It can be used to test your account details.

Value

Returns a logical value indicating if the login is successful. The response from the login page is returned as an attribute named response.

Author(s)

Pepijn de Vries

Examples

## Not run: 
## This will return FALSE if you have not set your account details with 'options'.
## If you have specified your account details and there are no other problems,
## it will return TRUE.
cms_login()

## End(Not run)

---

Obtain details for a specific Copernicus marine product

Description

Obtain details for a specific Copernicus marine product. This can be narrowed down to specific layers and/or variables within the product.

Usage

cms_product_details(
  product,
  layer,
  variable,
  variant = c("", "detailed-v2", "detailed-v3")
)

Arguments

product	An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.
layer	The name of a desired layer within a product (type character). Can be obtained with cms_product_details.
variable	The name of a desired variable in a specific layer of a product (type character). Can be obtained with cms_product_details.
variant	A character string indicating the type of details that should be returned. Should be one of "" (default), "detailed-v2", or "detailed-v3".

Value

Returns a named list with properties of the requested product.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_metadata(), cms_product_services(), cms_products_list()

Examples

cms_product_details("GLOBAL_ANALYSISFORECAST_PHY_001_024")

cms_product_details(
  product  = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
  layer    = "cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m",
  variable = "thetao"
)

---

Obtain meta data for a specific Copernicus marine product

Description

Collect meta information, such as vocabularies used, for specific Copernicus marine products

Usage

cms_product_metadata(product, type = c("list", "xml"))

Arguments

product	An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.
type	A character string indicating how the data should be returned. Should be one of "list" or "xml".

Value

Returns a named list (when type = "list") with info about the requested product. Returns the same info as xml_document (see xml2::xml_new_document()) when type = "xml". Returns NULL when contacting Copernicus fails.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_details(), cms_product_services(), cms_products_list()

Examples

cms_product_metadata("GLOBAL_ANALYSISFORECAST_PHY_001_024")

---

Obtain available services for a specific Copernicus marine product

Description

Obtain an overview of services provided by Copernicus for a specific marine product.

Usage

cms_product_services(product)

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

Value

Returns a tibble with a list of available services for a Copernicus marine product.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_details(), cms_product_metadata(), cms_products_list()

Examples

cms_product_services("GLOBAL_ANALYSISFORECAST_PHY_001_024")

---

List products available from data.marine.copernicus.eu

Description

Collect a list of products and some brief descriptions for marine products available from Copernicus

Usage

cms_products_list(..., info_type = c("list", "meta"))

Arguments

...	Allows you to pass (search) query parameters to apply to the list. When omitted, the full list of products is returned.
info_type	One of "list" (default) or "meta". "list" returns the actual list whereas "meta" returns meta information for the executed query (e.g. number of hits).

Value

Returns a tibble of products available from https://data.marine.copernicus.eu or a named list when info_type = "meta". Returns NULL in case on-line services are unavailable.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_details(), cms_product_metadata(), cms_product_services()

Examples

cms_products_list()

## Query a specific product:
cms_products_list(freeText = "GLOBAL_ANALYSISFORECAST_PHY_001_024")

---

Obtain a WMTS entry for specific Copernicus marine products and add to a leaflet map

Description

Functions for retrieving Web Map Tile Services information for specific products, layers and variables and add them to a leaflet map.

Usage

cms_wmts_details(product, layer, variable)

addCmsWMTSTiles(
  map,
  product,
  layer,
  variable,
  tilematrixset = "EPSG:3857",
  options = leaflet::WMSTileOptions(format = "image/png", transparent = TRUE),
  ...
)

cms_wmts_get_capabilities(product, layer, variable, type = c("list", "xml"))

Arguments

product	An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.
layer	The name of a desired layer within a product (type character). Can be obtained with cms_product_details.
variable	The name of a desired variable in a specific layer of a product (type character). Can be obtained with cms_product_details.
map	A map widget object created from leaflet::leaflet()
tilematrixset	A character string representing the tilematrixset to be used. In many cases "EPSG:3857" (Pseudo-Mercator) or "EPSG:4326" (World Geodetic System 1984) are available, but should be checked with cms_wmts_details.
options	Passed on to leaflet::addWMSTiles().
...	Passed on to leaflet::addWMSTiles().
type	A character string indicating whether the capabilities should be returned as "list" (default) or "xml" (xml2::xml_new_document()).

Value

cms_wmts_details returns a tibble with detains on the WMTS service. cms_wmts_getcapabilities returns either a list or xml_document depending on the value of type. AddCmsWMTSTiles returns a leaflet map updated with the requested tiles.

Author(s)

Pepijn de Vries

Examples

wmts_details <-
  cms_wmts_details(
    product  = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
    layer    = "cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m",
    variable = "thetao"
  )

cms_wmts_get_capabilities("GLOBAL_ANALYSISFORECAST_PHY_001_024")

if (interactive() && nrow(wmts_details) > 0) {
  leaflet::leaflet() |>
    leaflet::setView(lng = 3, lat = 54, zoom = 4) |>
    leaflet::addProviderTiles("Esri.WorldImagery") |>
    addCmsWMTSTiles(
      product  = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
      layer    = "cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m",
      variable = "thetao")
}

---