README.Rmd

---
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 -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![R-CMD-check](https://github.com/EMODnet/emodnet.wfs/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/EMODnet/emodnet.wfs/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/EMODnet/emodnet.wfs/branch/main/graph/badge.svg)](https://app.codecov.io/gh/EMODnet/emodnet.wfs/tree/main)
[![DOI](https://zenodo.org/badge/DOI/10.14284/679.svg)](https://doi.org/10.14284/679)
[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/653_status.svg)](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 though 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. 
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)
```

## Available services

All available services are contained in the tibble returned by `emodnet_wfs()`.


```{r, echo=FALSE}
library(emodnet.wfs)
services <- emodnet_wfs()
class(services)
names(services)
services$service_name
```

To explore available services you can use:

```r
View(emodnet_wfs())
```

## Create Service Client

Specify the service using the `service` argument. 

```{r}
wfs_bio <- emodnet_init_wfs_client(service = "biology")

wfs_bio
```

## Get WFS Layer info

You can get metadata about the layers available from a service. 

```{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 WFS 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.

```{r}
emodnet_get_layers(wfs = wfs_bio, layers = layers)
```

You can change the output `crs` 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 `reduce_layers`.  
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,
  reduce_layers = TRUE
)
```

Using `reduce_layers = 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"),
  reduce_layers = 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).

## Other web services

There are three ways to access EMODnet data at the moment, that complement each other.

### EMODnet ERDDAP server

Some EMODnet data are also published in an [ERDDAP server](https://erddap.emodnet.eu). You can access these data in R using the [rerddap R package](https://docs.ropensci.org/rerddap/):


```{r rerddap}
# install.packages("rerrdap")
library(rerddap)

erddap_url <- "https://erddap.emodnet.eu/erddap/"

rerddap::ed_datasets(url = erddap_url)

rerddap::ed_search(query = "vessel density", url = erddap_url)

human_activities_data_info <- rerddap::info(datasetid = "humanactivities_9f8a_3389_f08a", url = erddap_url)
human_activities_data_info

year_2020_gridded_data <- griddap(datasetx = human_activities_data_info, time = c("2020-03-18", "2020-03-19"))
head(year_2020_gridded_data$data)
```


### EMODnetWCS: Access EMODnet Web Coverage Service data

This package emodnet.wfs uses [Web Feature Services](https://www.ogc.org/publications/standard/wfs/), hence it is limited to getting vector data. EMODnet also hosts raster data that can be accessed via [Web Coverage Services (WCS)](https://www.ogc.org/publications/standard/wcs/). The R package [EMODnetWCS](https://github.com/EMODnet/EMODnetWCS) makes these data available in R.

## 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.