-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
160 lines (124 loc) · 7.05 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
---
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 <https://data.marine.copernicus.eu>
<!-- badges: start -->
[](https://github.com/pepijn-devries/CopernicusMarine/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=CopernicusMarine)
<!--[](https://cran.r-project.org/web/checks/check_results_CopernicusMarine.html)-->
[](https://pepijn-devries.r-universe.dev/CopernicusMarine)
<!-- badges: end -->
## Overview
<a href="https://github.com/pepijn-devries/CopernicusMarine/"><img src="man/figures/logo.png" alt="CopernicusMarine logo" align="right" /></a>
[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 <https://data.marine.copernicus.eu>. 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/copernicusmarine/).
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.
<h3 id="sec-subset">Downloading a subset</h3>
Unfortunately, downloading subsets is not operational in R due to some
[technical issues](https://github.com/pepijn-devries/CopernicusMarine/issues/42).
It seems that it might take some time to get this fixed. In the meantime,
you could have a look at this
[work-around](https://github.com/pepijn-devries/CopernicusMarine/issues/42#issuecomment-2079745370).
<!-- 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) -->
<!-- ``` -->
<h3 id="sec-full">Downloading a complete Copernicus marine product</h3>
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.
<h3 id="sec-wmts">Copernicus Web Map Tile Services (WMTS)</h3>
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")
```
## 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)`