-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME.Rmd
230 lines (152 loc) · 10.5 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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
options(timeout = 2000)
```
# emodnet.wfs: Access EMODnet Web Feature Service data through R
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://github.com/EMODnet/emodnet.wfs/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/EMODnet/emodnet.wfs/tree/main)
[](https://doi.org/10.14284/679)
[](https://github.com/ropensci/software-review/issues/653)
<!-- badges: end -->
The goal of emodnet.wfs is to allow interrogation of and access to [EMODnet's, European Marine Observation and Data Network, geographic vector data](https://emodnet.ec.europa.eu/en/emodnet-web-service-documentation#inline-nav-3) in R through the [EMODnet Web Feature Services](https://emodnet.ec.europa.eu/en/data-0).
[Web Feature services (WFS)](https://www.ogc.org/publications/standard/wfs/) represent a change in the way geographic information is created, modified and exchanged on the Internet and offer direct fine-grained access to geographic information at the feature and feature property level.
Features are representation of geographic entities, such as a coastlines, marine protected areas, offshore platforms, or fishing areas. In WFS, features have geometry (spatial information) and attributes (descriptive data).
emodnet.wfs aims at offering an user-friendly interface to this rich data.
## Installation and setup
You can install the development version of emodnet.wfs from GitHub with:
``` r
# install.packages("pak")
pak::pak("EMODnet/emodnet.wfs")
```
If you want to avoid reading messages from emodnet.wfs such as "WFS client created successfully",
set the `"emodnet.wfs.quiet"` option to `TRUE`.
```r
options("emodnet.wfs.quiet" = TRUE)
```
The use of the EMODnet Web Feature Services is not subjet to rate limiting at the moment.
## Pre-requisites
The emodnet.wfs is designed to be compatible with the modern R geospatial stack, in particular output geospatial objects are [`sf`](https://r-spatial.github.io/sf/) objects, that is to say, a tibble with a geometry list-column.
For users not familiar yet with geospatial data in R, we recommend the following resources:
- [Spatial Data Science With Applications in R](https://r-spatial.org/book/) by Edzer Pebesma and Roger Bivand.
- [Geocomputation with R](https://r.geocompx.org/) by Robin Lovelace, Jakub Nowosad and Jannes Muenchow.
In the documentation we assume a basic familiarity with spatial data: knowing about coordinates and about projections / [coordinate reference systems (CRS)](https://r.geocompx.org/spatial-class#crs-intro).
## Available data sources (services)
All available data sources, called services, are contained in the [tibble](https://tibble.tidyverse.org/) returned by `emodnet_wfs()`.
```{r, echo=TRUE}
library(emodnet.wfs)
services <- emodnet_wfs()
class(services)
names(services)
services[, c("emodnet_thematic_lot", "service_name")]
```
EMODnet data covers several disciplines organized in 7 thematic lots: bathymetry, biology, chemistry, geology, human activities, physics, seabed habitats. Some thematic lots organize their data in more than one data source or service.
To explore available services you can use `View()` or your usual way to explore `data.frames`.
## Initialise a WFS Service Client
A WFS service client is responsible for sending requests to a WFS server and processing the responses to retrieve, display, or analyze geospatial features. As such, initialising a client is the first step to interacting with an EMODnet Web Feature Services.
Specify the service using the `service` argument.
```{r}
wfs_bio <- emodnet_init_wfs_client(service = "biology")
wfs_bio
```
## List contents of a WFS: Get layer information from a service client
In the context of a Web Feature Service (WFS), a layer refers to a logical grouping of geographic features that share the same schema (i.e., the same feature type, geometry, and attributes). Layers are the units of data that clients can query, retrieve, and manipulate through a WFS.
You can access information (metadata) about each layer available from an EMODnet WFS with `emodnet_get_wfs_info()`
```{r}
emodnet_get_wfs_info(service = "biology")
```
or you can pass a wfs client object.
```{r}
emodnet_get_wfs_info(wfs_bio)
```
You can also get info for specific layers from wfs object:
```{r}
layers <- c("mediseh_zostera_m_pnt", "mediseh_posidonia_nodata")
emodnet_get_layer_info(wfs = wfs_bio, layers = layers)
```
Finally, you can get details on all available services and layers from the server
```{r eval=FALSE}
emodnet_get_all_wfs_info()
```
## Get data from a data source: get layers
You can extract layers directly from a `wfs` object using layer names.
All layers are downloaded as `sf` objects and output as a list with a named element for each layer requested.
The argument `simplify = TRUE` stack all the layers in one single tibble, if possible (for instance if all column names are the same, otherwise it fails).
By default, `emodnet_get_layers()` returns a list of sf objects, one per layer.
```{r}
emodnet_get_layers(wfs = wfs_bio, layers = layers)
```
You can change the output Coordinate Reference System (CRS), which defines how geographic data is mapped to the Earth's surface, through the argument `crs`.
```{r}
emodnet_get_layers(wfs = wfs_bio, layers = layers, crs = 3857)
```
You can also extract layers using a WFS service name.
```{r}
emodnet_get_layers(
service = "biology",
layers = c("mediseh_zostera_m_pnt", "mediseh_posidonia_nodata")
)
```
Layers can also be returned to a single `sf` object through argument `simplify`.
If `TRUE` the function will try to reduce all layers into a single `sf`.
If attempting to reduce fails, it will error:
```{r, error=TRUE}
emodnet_get_layers(
wfs = wfs_bio,
layers = layers,
simplify = TRUE
)
```
Using `simplify = TRUE` is also useful for returning an `sf` object rather than a list in single layer request.
```{r}
emodnet_get_layers(
service = "biology",
layers = c("mediseh_posidonia_nodata"),
simplify = TRUE
)
```
## Help needed?
If you get an unexpected error,
- Look up the [EMODnet monitor](https://monitor.emodnet.eu/resources?lang=en&resource_type=OGC:WFS);
- Open an issue in this [repository](https://github.com/EMODnet/emodnet.wfs/issues).
## Unlock the Full Potential of the EMODnet Web Services: Access Raster and Gridded datasets.
EMODnet hosts a wealth of marine and maritime data distributed through three complementary web services: WFS, WCS, and ERDDAP. Web services allow users to retrieve data programmatically from remote servers, eliminating the need for manual downloads. This is particularly useful for handling large datasets or conducting dynamic analyses. These services are tailored to different data types and research needs, but together, they ensure seamless access to all EMODnet vector, raster, and gridded datasets. Vector data, such as shipwrecks or boundaries, are accessible through `emodnet.wfs` via Web Feature Services (WFS). Complementary, raster and gridded datasets are available through Web Coverage Services (WCS) and ERDDAP respectively.
### Access EMODnet raster data through Web Coverage Services with `EMODnetWCS` in R
EMODnet raster datasets, such as habitat maps or bathymetry, are available through [Web Coverage Services (WCS)](https://en.wikipedia.org/wiki/Web_Coverage_Service). These data are continuous, gridded, and often used for spatial visualization or environmental modeling. The EMODnetWCS R package provides tools to retrieve and process these raser datasets, in a similar fashion as `emodnet.wfs`. Extensive documentation is available at the [EMODnetWCS website](https://emodnet.github.io/EMODnetWCS/).
### Access EMODnet gridded and tabular datasets through the ERDDAP Server and `rerddap` in R
Both WFS and WCS EMODnet services are based on a federated system: each EMODnet thematic lot manages their servers and data, ensuring that their data are exposed both via WFS and WCS. The twin R packages `emodnet.wfs` and `EMODnetWCS` simplify the access to all the entry points by collecting them in single places, which are the packages themselves.
In contrast, the [EMODnet ERDDAP Server](https://erddap.emodnet.eu) is centrally managed by the EMODnet Central Portal, offering a single access point to all gridded and tabular datasets. ERDDAP simplifies access to datasets such as digital terrain models, vessel density or environmental data. It is particularly suited for large-scale, multidimensional data analysis. In R, the `rerddap` package allows users to query and subset ERDDAP data programmatically, enabling efficient analysis and integration into workflows. For example, researchers can retrieve datasets on vessel density.
```{r rerddap}
# install.packages("rerrdap")
library(rerddap)
# This is the url where the EMODnet ERDDAP server is located
erddap_url <- "https://erddap.emodnet.eu/erddap/"
# Inspect all available datasets
ed_datasets(url = erddap_url)
# Find datasets with the key words "vessel density"
ed_search(query = "vessel density", url = erddap_url)
# Inspect more info about the vessel density dataset, using its identifier
human_activities_data_info <- info(datasetid = "humanactivities_9f8a_3389_f08a", url = erddap_url)
human_activities_data_info
# Retrieve the vessel density at a particular time period
year_2020_gridded_data <- griddap(datasetx = human_activities_data_info, time = c("2020-03-18", "2020-03-19"))
head(year_2020_gridded_data$data)
```
More functionalities are available through `rerddap`. Feel free to explore the [rerddap website](https://docs.ropensci.org/rerddap/) to find out what else can you do with the EMODnet datasets in ERDDAP.
## Citation
To cite emodnet.wfs, please use the output from `citation(package = "emodnet.wfs")`.
```{r}
citation(package = "emodnet.wfs")
```
## Acknowledgements
This package was started by the Sheffield University during the EMODnet Biology WP4 data products workshop in June 2020.