Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pepijn-devries/CopernicusMarine

Subset and download marine data from EU Copernicus Marine Service Information. Import data on the oceans physical and biogeochemical state from Copernicus into R without the need of external software.
https://github.com/pepijn-devries/CopernicusMarine

Last synced: 3 months ago
JSON representation

Subset and download marine data from EU Copernicus Marine Service Information. Import data on the oceans physical and biogeochemical state from Copernicus into R without the need of external software.

Awesome Lists containing this project

README 

        
---

output: github_document

---



```{r, echo = FALSE, message = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-"

)

library(CopernicusMarine)

```



> `{CopernicusMarine}` Easily access information from 

[![version](https://www.r-pkg.org/badges/version/CopernicusMarine)](https://CRAN.R-project.org/package=CopernicusMarine)

![cranlogs](https://cranlogs.r-pkg.org/badges/CopernicusMarine)



## Overview



CopernicusMarine logo



[Copernicus Marine Service Information](https://marine.copernicus.eu/about) is a programme subsidised by the

European Commission. Its mission is to provide free authoritative information on the oceans physical and

biogeochemical state. The `{CopernicusMarine}` R package is developed apart from this programme and facilitates

retrieval of information from . With the package you can:



 * List available marine data for Copernicus and provide meta-information.

 * Download and use the data directly in R.



## Why use `{CopernicusMarine}`



Copernicus Marine offers access to their data services through a

[Python application interface](https://pypi.org/project/copernicus-marine-client/).

For R users this requires complex installation procedures and is difficult to maintain in

a stable R package. The `{CopernicusMarine}` R package has

a much simpler installation procedure (see below) and does not depend on

third party software, other than packages available from [CRAN](https://cran.r-project.org/).



## Installation



> Get CRAN version

```{r eval=FALSE}

install.packages("CopernicusMarine")

```

> Get development version on github

```{r eval=FALSE}

devtools::install_github('pepijn-devries/CopernicusMarine')

```



## Usage



The package provides an interface between R and the Copernicus Marine services. Note that for some of these

services you need an account and have to comply with

[specific terms](https://marine.copernicus.eu/user-corner/service-commitments-and-licence). The usage section

briefly shows three different ways of obtaining data from Copernicus:



 * [Downloading a subset](#sec-subset)

 * [Downloading a full dataset](#sec-full)

 * [Using the WMTS server](#sec-wtms)



Please check the manual for complete documentation of the package.



Downloading a subset



The code below assumes that you have registered your account details using `options(CopernicusMarine_uid = "my_user_name")` and

`options(CopernicusMarine_pwd = "my_password")`. If you are comfortable that it is secure enough, you can also store these

options in your `.Rprofile` such that they will be loaded each session. Otherwise, you can also provide your account details

as arguments to the functions.



The example below demonstrates how to subset a specific layer for a specific product. The subset is constrained by

the `region`, `timerange` and `verticalrange` arguments. The subset is downloaded to the temporary

file specified with `destination` and can be read using the [`{stars}`](https://r-spatial.github.io/stars/) package.



```{r download-subset, eval=TRUE}

destination <- tempfile("copernicus", fileext = ".nc")



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", "2021-01-02"),

  verticalrange = c(0, -2)

)



mydata <- stars::read_stars(destination)



plot(mydata["vo"], col = hcl.colors(100), axes = TRUE)

```



Downloading a complete Copernicus marine product



If you don't want to subset the data and want the complete set, you can use the

SpatioTemporal Asset Catalogs (STAC), if these are available for your product.

First you can list STAC files available for a specific product (and layer):



```{r, eval=TRUE}

stac_files <-

  cms_list_stac_files(

    "GLOBAL_ANALYSISFORECAST_PHY_001_024",

    "cmems_mod_glo_phy-cur_anfc_0.083deg_P1D-m")

stac_files

```



Downloading the first file can be done with

`cms_download_stac(stac_files[1,,drop = FALSE], tempdir())`, where the

file would be stored in a temporary directory. By default the progress is printed as files can be very large and

may take some time to download.



Copernicus Web Map Tile Services (WMTS)



Web Map Tile Services (WMTS) allow to quickly plot pre-rendered images onto a map. This may not be useful when

you need the data for analyses but is handy for quick visualisations, inspection or presentation of data.

In R it is very easy to add WMTS layers to an interactive map using [leaflet](https://rstudio.github.io/leaflet/)

widgets. This is demonstrated with the example below (note that in the documentation the map is only shown

statically and is not interactive).



```{r leaflet, eval=TRUE}

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"

  )

```



### Citing the data you use



A Copernicus account comes with several terms of use. One of these is that you

[properly cite](https://help.marine.copernicus.eu/en/articles/4444611-how-to-cite-copernicus-marine-products-and-services)

the data you use in publications. In fact, we also have credit the data used in this documentation, which can be easily

done with the following code:



```{r, eval=TRUE}

cms_cite_product("GLOBAL_ANALYSISFORECAST_PHY_001_024")

```



A note to CopernicusMarine ≤0.1.3 users



Older versions of the `CopernicusMarine` package implemented functions that interface with

services that are deprecated by Copernicus Marine. Namely, the MOTU server (for subsetting

and downloading), the FTP server (for downloading full sets) and the WMS server for

adding tiles to maps.



These services are phased out, and in the latest release of this package, functions that interact

with them are deprecated. They can still be used for as long as these services are provided by

Copernicus Marine. When these services are terminated, the functions will become defunct.



Please switch to the implementation of the new services at your earliest convenience. Specifically,

this means that you need to use:



  * `cms_download_subset` instead of ~~`copernicus_download_motu`~~;

  * `cms_download_stac` instead of ~~`copernicus_download_ftp`~~;

  * `addCmsWMTSTiles` instead of ~~`addCopernicusWMSTiles`~~.



The design of the new functions is very similar to that of

the old ones, so switching should be relatively easy.



## Resources



```{r, eval=TRUE, echo=FALSE}

cop_det <- cms_product_details("GLOBAL_ANALYSISFORECAST_PHY_001_024")

```



 * [E.U. Copernicus Marine Service Information](https://data.marine.copernicus.eu)

 * `r sprintf("[%s - %s (%s); DOI:%s](https://doi.org/%s)", cop_det$title, cop_det$id, cop_det$creationDate, cop_det$doi, cop_det$doi)`