Skip to content

Commit

Permalink
docs: more clarifications
Browse files Browse the repository at this point in the history
  • Loading branch information
@maelle
maelle committed Nov 5, 2024
1 parent 76403c3 commit 23b683a
Show file tree
Hide file tree
Showing 3 changed files with 115 additions and 36 deletions.
3 changes: 2 additions & 1 deletion R/emodnet_wfs.R
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
.emodnet_wfs <- function() {
utils::read.csv(
data <- utils::read.csv(
system.file("services.csv", package = "emodnet.wfs"),
stringsAsFactors = FALSE
)
tibble::as_tibble(data)
}
#' Available EMODnet Web Feature Services
#'
Expand Down
11 changes: 6 additions & 5 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,7 @@ In the documentation we assume a basic familiarity with spatial data: knowing ab

All available data sources, called services, are contained in the [tibble](https://tibble.tidyverse.org/) returned by `emodnet_wfs()`.


```{r, echo=FALSE}
```{r, echo=TRUE}
library(emodnet.wfs)
services <- emodnet_wfs()
class(services)
Expand All @@ -83,7 +82,7 @@ wfs_bio

## List contents of a data source: Get layer information from a service client

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

```{r}
emodnet_get_wfs_info(service = "biology")
Expand Down Expand Up @@ -115,8 +114,10 @@ emodnet_get_all_wfs_info()

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 `reduce_layers = TRUE` stack all the layers in one single tibble.
Default is `FALSE` and returns a list of sf objects, one per layer.
The argument `reduce_layers = 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)
Expand Down
137 changes: 107 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,35 +46,62 @@ client created successfully”, set the `"emodnet.wfs.quiet"` option to
options("emodnet.wfs.quiet" = TRUE)
```

## Available services

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

#> [1] "data.frame"
#> [1] "service_name" "service_url"
#> [1] "bathymetry"
#> [2] "biology"
#> [3] "biology_occurrence_data"
#> [4] "chemistry_cdi_data_discovery_and_access_service"
#> [5] "chemistry_cdi_distribution_observations_per_category_and_region"
#> [6] "chemistry_contaminants"
#> [7] "chemistry_marine_litter"
#> [8] "geology_coastal_behavior"
#> [9] "geology_events_and_probabilities"
#> [10] "geology_marine_minerals"
#> [11] "geology_sea_floor_bedrock"
#> [12] "geology_seabed_substrate_maps"
#> [13] "geology_submerged_landscapes"
#> [14] "human_activities"
#> [15] "physics"
#> [16] "seabed_habitats_general_datasets_and_products"
#> [17] "seabed_habitats_individual_habitat_map_and_model_datasets"
## 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
library(emodnet.wfs)
services <- emodnet_wfs()
class(services)
#> [1] "tbl_df" "tbl" "data.frame"
names(services)
#> [1] "service_name" "service_url"
services$service_name
#> [1] "bathymetry"
#> [2] "biology"
#> [3] "biology_occurrence_data"
#> [4] "chemistry_cdi_data_discovery_and_access_service"
#> [5] "chemistry_cdi_distribution_observations_per_category_and_region"
#> [6] "chemistry_contaminants"
#> [7] "chemistry_marine_litter"
#> [8] "geology_coastal_behavior"
#> [9] "geology_events_and_probabilities"
#> [10] "geology_marine_minerals"
#> [11] "geology_sea_floor_bedrock"
#> [12] "geology_seabed_substrate_maps"
#> [13] "geology_submerged_landscapes"
#> [14] "human_activities"
#> [15] "physics"
#> [16] "seabed_habitats_general_datasets_and_products"
#> [17] "seabed_habitats_individual_habitat_map_and_model_datasets"
```

To explore available services you can use `View()` or your usual way to
explore `data.frames`.

## Create Service Client
## Connect to a data source: Create a service client

Specify the service using the `service` argument.

Expand All @@ -93,9 +120,10 @@ wfs_bio
#> ....|-- capabilities <WFSCapabilities>
```

## Get WFS Layer info
## List contents of a data source: Get layer information from a service client

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

``` r
emodnet_get_wfs_info(service = "biology")
Expand Down Expand Up @@ -164,14 +192,27 @@ the server
emodnet_get_all_wfs_info()
```

## Get WFS layers
## 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.
named element for each layer requested. The argument
`reduce_layers = 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)
#> Called from: emodnet_get_layers(wfs = wfs_bio, layers = layers)
#> debug: if (reduce_layers) {
#> tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> }
#> debug: standardise_crs(out, crs)
#> $mediseh_zostera_m_pnt
#> Simple feature collection with 54 features and 3 fields
#> Geometry type: POINT
Expand Down Expand Up @@ -211,10 +252,18 @@ emodnet_get_layers(wfs = wfs_bio, layers = layers)
#> 10 mediseh_posidonia_nodata.84 0 2.817453 MULTICURVE (LINESTRING (15....
```

You can change the output `crs` through the argument `crs`.
You can change the output `crs` (“projection”) through the argument
`crs`.

``` r
emodnet_get_layers(wfs = wfs_bio, layers = layers, crs = 3857)
#> Called from: emodnet_get_layers(wfs = wfs_bio, layers = layers, crs = 3857)
#> debug: if (reduce_layers) {
#> tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> }
#> debug: standardise_crs(out, crs)
#> ℹ crs transformed to 3857.
#> ℹ crs transformed to 3857.
#> $mediseh_zostera_m_pnt
Expand Down Expand Up @@ -266,6 +315,14 @@ emodnet_get_layers(
#> ✔ WFS client created successfully
#> ℹ Service: "https://geo.vliz.be/geoserver/Emodnetbio/wfs"
#> ℹ Version: "2.0.0"
#> Called from: emodnet_get_layers(service = "biology", layers = c("mediseh_zostera_m_pnt",
#> "mediseh_posidonia_nodata"))
#> debug: if (reduce_layers) {
#> tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> }
#> debug: standardise_crs(out, crs)
#> $mediseh_zostera_m_pnt
#> Simple feature collection with 54 features and 3 fields
#> Geometry type: POINT
Expand Down Expand Up @@ -317,6 +374,15 @@ emodnet_get_layers(
layers = layers,
reduce_layers = TRUE
)
#> Called from: emodnet_get_layers(wfs = wfs_bio, layers = layers, reduce_layers = TRUE)
#> debug: if (reduce_layers) {
#> tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> }
#> debug: tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> Error in `value[[3L]]()`:
#> ! Cannot reduce layers.
#> ℹ Try again with `reduce_layers = FALSE`
Expand All @@ -334,6 +400,17 @@ emodnet_get_layers(
#> ✔ WFS client created successfully
#> ℹ Service: "https://geo.vliz.be/geoserver/Emodnetbio/wfs"
#> ℹ Version: "2.0.0"
#> Called from: emodnet_get_layers(service = "biology", layers = c("mediseh_posidonia_nodata"),
#> reduce_layers = TRUE)
#> debug: if (reduce_layers) {
#> tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> }
#> debug: tryCatch(out <- purrr::reduce(out, rbind), error = function(e) {
#> cli::cli_abort(c("Cannot reduce layers.", i = "Try again with {.code reduce_layers = FALSE}"))
#> })
#> debug: standardise_crs(out, crs)
#> Simple feature collection with 465 features and 3 fields
#> Geometry type: MULTICURVE
#> Dimension: XY
Expand Down

0 comments on commit 23b683a

Please sign in to comment.