Improve documentation #12

.Rbuildignore

@@ -1,3 +1,4 @@
 ^eurobis\.Rproj$
 ^\.Rproj\.user$
 ^data-raw$
+^README\.Rmd$

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: eurobis
-Title: EurOBIS data download package
+Title: Download data from EurOBIS using the LifeWatch/EMODnet-Biology Web Feature Services
 Version: 0.0.0.9000
 Authors@R: c(person("Salvador", "Fernandez", email = "[email protected]", role = c("cre", "ctb")),
              person("Daphnis", "De Pooter", role = "aut"),
@@ -33,7 +33,8 @@ Imports:
     tibble
 Suggests:
     testthat (>= 3.0.0),
-    mapview
+    mapview,
+    dplyr
 Remotes: 
     eblondel/ows4R
 RoxygenNote: 7.1.1

NAMESPACE

@@ -3,8 +3,15 @@
 export("%>%")
 export(eurobis_download_toolbox)
 export(eurobis_list_datasets)
+export(eurobis_list_regions)
 export(eurobis_map_draw)
-export(eurobis_map_regions)
+export(eurobis_map_regions_ecoregions)
+export(eurobis_map_regions_eez)
+export(eurobis_map_regions_eez_iho)
+export(eurobis_map_regions_iho)
+export(eurobis_map_regions_reportingareas)
 export(eurobis_name2id)
-export(eurobis_occurrences)
+export(eurobis_occurrences_basic)
+export(eurobis_occurrences_full)
+export(eurobis_occurrences_full_and_parameters)
 importFrom(magrittr,"%>%")

R/data.R

@@ -0,0 +1,13 @@
+#' Species traits and classifications important to society
+#'
+#' You can query on the values shown here
+#'
+#' @format A data frame with 32 rows and 4 variables:
+#' \describe{
+#'   \item{category}{traits or important to society}
+#'   \item{group}{subclategory}
+#'   \item{selection}{value of functional group or classification important to society}
+#'   \item{selectid}{ignore - used internally to retrieve data from EurOBIS using WFS}
+#'   ...
+#' }
+"species_traits"

R/eurobis_occurrences.R

@@ -28,7 +28,6 @@
 #' @param ... Any parameters to pass to  \code{ows4R} get feature request (e.g. cql_filter or parallel)
 #'
 #' @return a tibble or sf object with eurobis data
-#' @export
 #'
 #' @details 
 #' Set \code{options(verbose = TRUE)} to display more information
@@ -116,16 +115,19 @@ eurobis_occurrences <- function(type,
 }
 
 #' @rdname eurobis_occurrences
+#' @export
 eurobis_occurrences_basic <- function(...){
   eurobis_occurrences(type = "basic", ...)
 }
 
 #' @rdname eurobis_occurrences
+#' @export
 eurobis_occurrences_full <- function(...){
   eurobis_occurrences(type = "full", ...)
 }
 
 #' @rdname eurobis_occurrences
+#' @export
 eurobis_occurrences_full_and_parameters <- function(...){
   eurobis_occurrences(type = "full_and_parameters", ...)
 }

R/helper.R

@@ -56,7 +56,8 @@ eurobis_list_datasets <- function(){
 #' List Marine Regions 
 #'
 #' @return a tibble with the Marine Regions names and unique identifier MRGID. See details section.
-#'
+#' @export
+#' 
 #' @details 
 #' The Marine Regions Gazetteer is the geographical backbone of EurOBIS.
 #' 

R/map.R

@@ -3,7 +3,6 @@
 #' @param layer The region or place type to be displayed. See details.
 #'
 #' @return A leaflet map with the regions that retrieves info by clicking
-#' @export
 #'
 #' @details 
 #' To select a specific layer you have to provide the code for the layer. These are:
@@ -71,26 +70,31 @@ eurobis_map_regions <- function(layer = 'eez'){
 }
 
 #' @rdname eurobis_map_regions
+#' @export
 eurobis_map_regions_ecoregions <- function(){
   eurobis_map_regions('ecoregions')
 }
 
 #' @rdname eurobis_map_regions
+#' @export
 eurobis_map_regions_eez <- function(){
   eurobis_map_regions('eez')
 }
 
 #' @rdname eurobis_map_regions
+#' @export
 eurobis_map_regions_iho <- function(){
   eurobis_map_regions('iho')
 }
 
 #' @rdname eurobis_map_regions
+#' @export
 eurobis_map_regions_eez_iho <- function(){
   eurobis_map_regions('eez_iho')
 }
 
 #' @rdname eurobis_map_regions
+#' @export
 eurobis_map_regions_reportingareas <- function(){
   eurobis_map_regions('reportingareas')
 }

R/viewparams.R

@@ -253,7 +253,7 @@ build_filter_traits <- function(functional_groups = NULL, cites = NULL, habitats
   # Check values passed to traits
   for(i in 1:length(traits)){
       trait_name <- names(traits[i])
-      accepted <- subset(species_traits$selection, species_traits$group == trait_name)
+      accepted <- subset(eurobis::species_traits$selection, eurobis::species_traits$group == trait_name)
       not_accepted <- subset(traits[[i]], !(tolower(traits[[i]]) %in% tolower(accepted)))
 
       if(length(not_accepted) != 0){
@@ -263,7 +263,7 @@ build_filter_traits <- function(functional_groups = NULL, cites = NULL, habitats
 
   # Perform
   traits <- tolower(unlist(traits))
-  selectid <- subset(species_traits$selectid, tolower(species_traits$selection) %in% traits)
+  selectid <- subset(eurobis::species_traits$selectid, tolower(eurobis::species_traits$selection) %in% traits)
   selectid <- paste0("'", selectid, "'")
   selectid <- paste0(selectid, collapse = "\\,")
 
@@ -276,27 +276,3 @@ build_filter_traits <- function(functional_groups = NULL, cites = NULL, habitats
   return(query)
 
 }
-
-
-
-
-# ## Other filter that won't be created as it will bring further confusion
-# ## We can get these by asking the user to parse an WFS request url from the EMODnet-Biology Download Toolbox
-# ## and choosing only the viewParams query
-# ## We can also give the option of passing cql_filters with vendor params
-# 
-# ## season NOPE
-# # +AND+((observationdate+BETWEEN+'2000-01-01'+AND+'2022-01-31'+AND+seasonID+IN+(2\\,3)))
-# 
-# ## Taxon rank - NOPE
-# # +AND+taxonrank+>=+180
-# 
-# ## Time precision - NOPE
-# # +AND+time_precision+>=+10
-# 
-# ## Coordinate precision - NOPE
-# # +AND+(false+OR+coordinateprecision_category+=+0+OR+coordinateprecision_category+=+1)
-# 
-# ## Certain measurement types
-# # +AND+measurement_type_group_ids+&&+ARRAY[19\\,46]
-# 

README.Rmd

@@ -0,0 +1,154 @@
+---
+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(verbose = FALSE)
+```
+
+# Download data from EurOBIS using the LifeWatch/EMODnet-Biology Web Feature Services
+
+<!-- badges: start -->
+[![Funding](https://img.shields.io/static/v1?label=powered+by&message=lifewatch.be&labelColor=1a4e8a&color=f15922)](http://lifewatch.be)
+[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+<!-- badges: end -->
+
+
+The `eurobis` R package allows you to download data from EurOBIS. 
+
+You can query on:
+
+- **Dataset**: provide the Integrated Marine Information System ([IMIS](https://www.vliz.be/en/integrated-marine-information-system)) unique identifier for datasets [DasID](https://www.vliz.be/imis?page=webservices).
+- **Taxon**: use a scientific name (e.g. the sea turtle _Caretta caretta_) or a [WoRMS AphiaID](https://www.marinespecies.org/about.php#what_is_aphia) (e.g. [137205](https://www.marinespecies.org/aphia.php?p=taxdetails&id=137205))
+- **Traits**: get all occurrences that are benthos. Or zooplankton. Or both. Powered by [WoRMS](https://www.marinespecies.org/).
+- **Time**: just give start and end dates.
+- **Geographically**: it allows to query on more than 300 records from the [Marine Regions Gazetteer](https://marineregions.org/gazetteer.php) by giving the [MRGID](https://marineregions.org/mrgid.php). Or just pass the area of your interest as a polygon written in as [Well Known Text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)
+- Other important classifications as [IUCN Red List](https://www.iucnredlist.org/en), [MSDF Indicators](https://msfd.eu/knowseas/guidelines/3-INDICATORS-Guideline.pdf) or [Habitats Directive](https://ec.europa.eu/environment/nature/conservation/species/habitats_dir_en.htm) and [CITES](https://cites.org/eng/app/index.php) Annexes.
+
+Or create your own selection using the [EMODnet Biology toolbox](http://www.emodnet-biology.eu/toolbox). Just copy the webservice URL and paste in R.
+
+## Installation
+
+You can install the development version from GitHub with `devtools`:
+
+```{r install, eval=FALSE}
+devtools::install_github("lifewatch/eurobis")
+```
+
+## Get occurrences
+
+Use the `eurobis_occurrences()` family of functions to query data. 
+
+A basic example is:
+
+```{r occurrences_get}
+library(eurobis)
+
+# Get one single dataset
+dataset <- eurobis_occurrences_basic(dasid = 8045)
+dplyr::glimpse(dataset)
+```
+
+To see the list of datasets, use:
+
+```{r datasets}
+eurobis_list_datasets()
+```
+
+For detailed information run:
+
+```{r occurrences, eval=FALSE}
+help(eurobis_occurrences)
+```
+
+## Query by traits
+Use the `functional_group` argument:
+
+```{r func_groups}
+# Get one single dataset
+dataset <- eurobis_occurrences_basic(dasid = 8045, functional_groups = "angiosperms")
+dplyr::glimpse(dataset)
+```
+
+See the full list of queriable traits in the exported dataset `species_traits`:
+
+```{r traits}
+tibble::as_tibble(species_traits)
+```
+
+
+## Query by location
+
+You can also filter by location, either using the Marine Regions Gazetteer Identifier (MRGID) or passing any polygon as Well Known Text.
+
+```{r mrgid, eval = FALSE}
+eurobis_occurrences_basic(mrgid = 5688, geometry = "POLYGON ((-9.099426 40.33016, -9.099426 40.9788, -8.366089 40.9788, -8.366089 40.33016, -9.099426 40.33016))")
+```
+
+To help drawing the area of your interest, you can use `eurobis_map_draw()`. You can draw here a polygon interactively:
+
+```{r draw, eval = FALSE}
+selected_area <- eurobis_map_draw()
+#> POLYGON ((-9.099426 40.33016, -9.099426 40.9788, -8.366089 40.9788, -8.366089 40.33016, -9.099426 40.33016))
+
+eurobis_occurrences_full(geometry = selected_area)
+```
+
+To help choosing the MRGID from Marine Regions, see the list of queriable regions with:
+
+```{r map1}
+eurobis_list_regions()
+```
+
+Or select the MRGIDs of you interest with the family of functions `eurobis_map_regions_*`: these will open a leaflet map including the layers, read via Web Map Services (WMS).
+
+```{r map2, eval = FALSE}
+# MEOW Ecoregions
+eurobis_map_regions_ecoregions()
+
+# Exclusive Economic Zones (EEZ)
+eurobis_map_regions_eez()
+
+# International Hydrographic Office areas (IHO)
+eurobis_map_regions_iho()
+
+# Marine Regions intersection of EEZ and IHO. Named as Marine Region in eurobis_list_regions()
+eurobis_map_regions_eez_iho()
+
+# EMODnet-Biology Reporting Areas
+eurobis_map_regions_reportingareas()
+```
+
+See the manual with:
+
+```{r map3, eval = FALSE}
+help(eurobis_map_regions)
+```
+
+Note that passing both an MRGID and a geometry does not restrict to the selected area within the MRGID record, but adds both data fetched from the selected data and the MRGID record.
+
+## Why an EurOBIS R package? Didn't exist an OBIS package already?
+Yes, you could also use the [OBIS R package](https://github.com/iobis/robis) `robis`. The main advantage of the `eurobis` R package is the functionality to query on species traits.
+
+## Disclaimer
+
+If data are extracted from the EMODnet Biology for secondary analysis resulting in a publication, the appropriate source should be cited.
+
+The downloaded data should be cited as: EMODnet Biology (yyyy) Fulll Occurrence Data and parameters downloaded from the EMODnet Biology Project (www.emodnet-biology.eu). Available online at www.emodnet-biology.eu/toolbox, consulted on yyyy-mm-dd.
+
+Regarding the citation of the individual datasets, the following guidelines should be taken into account:
+
+- If any individual data source of EurOBIS constitutes a significant proportion of the downloaded and used records (e.g. more than 10% of the data is derived from a single source), the individual data source should also be cited.
+- If any individual data source of EurOBIS constitutes a substantial proportion of the downloaded and used records (e.g. more than 25% of the data is derived from a single source or the data is essential to arrive at the conclusion of the analysis), the manager or custodian of this data set should be contacted.
+- In any case, it may be useful to contact the data custodian directly. The data custodian might have additional data available that may strengthen the analysis or he/she might be able to provide additional helpful information that may not be apparent from the provided metadata.
+- The data may not be redistributed without the permission of the appropriate data owners. If data are extracted from the EMODnet Data Portal for redistribution, please contact us at [email protected].
+
+[![LifeWatch.be](https://raw.githubusercontent.com/lifewatch/eurobis/master/fig/LifeWatch_banner_test.PNG)](http://www.lifewatch.be/)