New README and doc updating

DESCRIPTION

@@ -53,6 +53,6 @@ Suggests:
     knitr,
     rmarkdown,
     spelling
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.3
 VignetteBuilder: knitr
 Language: en-US

R/checklist.R

@@ -1,4 +1,9 @@
-#' Create a checklist.
+#' Create a checklist
+#'
+#' @description
+#' This function returns all taxa observed for a given set of filters. Users can,
+#' for example, return all taxa from a particular Phylum or from a certain geographic region.
+#'
 #'
 #' @usage checklist(scientificname = NULL, taxonid = NULL, datasetid = NULL,
 #'   nodeid = NULL, instituteid = NULL, areaid = NULL, startdate = NULL, enddate = NULL,
@@ -23,7 +28,9 @@
 #' @param flags quality flags which need to be set.
 #' @param exclude quality flags to be excluded from the results.
 #' @param verbose logical. Optional parameter to enable verbose logging (default = \code{FALSE}).
-#' @return The checklist.
+#' @return A checklist (\code{tibble}), with the records that met the filter.
+#' @note
+#' When using a \code{geometry}, the function will fail if the geometry is too complex. One alternative is to use a bounding box or a simplified version of the geometry.
 #' @examples
 #' taxa <- checklist(scientificname = "Tellinidae")
 #' taxa <- checklist(geometry = "POLYGON ((2.3 51.8, 2.3 51.6, 2.6 51.6, 2.6 51.8, 2.3 51.8))")

R/occurrence.R

@@ -1,4 +1,10 @@
-#' Find occurrences.
+#' Find occurrence records
+#'
+#' @description
+#' Download occurrence records from OBIS. A set of filters can be used to delimit
+#' which data will be downloaded. Note that scientificname can be a species name or any other taxon name
+#' (e.g. a family name).
+#'
 #'
 #' @usage occurrence(scientificname = NULL, taxonid = NULL, datasetid = NULL,
 #'   nodeid = NULL, instituteid = NULL, areaid = NULL, startdate = NULL, enddate = NULL,
@@ -40,7 +46,11 @@
 #' @param fields fields to be included in the results.
 #' @param qcfields include lists of missing and invalid fields (default = \code{NULL}).
 #' @param verbose logical. Optional parameter to enable verbose logging (default = \code{FALSE}).
-#' @return The occurrence records.
+#' @return The occurrence records in a \code{tibble} format. The number of columns will vary according to the number of information associated with the records.
+#' For more information about the type of data available with OBIS occurrences, see the \href{https://manual.obis.org/}{OBIS manual.}
+#'
+#' @note
+#' When using a \code{geometry}, the function will fail if the geometry is too complex. One alternative is to use a bounding box or a simplified version of the geometry.
 #' @examples
 #' records <- occurrence(scientificname = "Abra sibogai")
 #' records <- occurrence(taxonid = 141438, startdate = as.Date("2007-10-10"))

README.md

@@ -1,14 +1,23 @@
-# robis <a href="https://github.com/iobis/robis"><img src="man/figures/logo.png" align="right" height="139" /></a>
+# robis: an R client for the OBIS API <a href="https://github.com/iobis/robis"><img src="man/figures/logo.png" align="right" height="139" /></a>
 
 [![CRAN robis](http://www.r-pkg.org/badges/version-last-release/robis)](https://cran.r-project.org/package=robis)
 [![Travis-CI Build Status](https://api.travis-ci.org/iobis/robis.svg?branch=master&kill_cache=1)](https://travis-ci.org/iobis/robis)
 [![Coverage Status](https://coveralls.io/repos/iobis/robis/badge.svg?branch=master&service=github&kill_cache=1)](https://coveralls.io/github/iobis/robis?branch=master)
 [![DOI](https://zenodo.org/badge/47509713.svg)](https://zenodo.org/badge/latestdoi/47509713)
 
-R client for the OBIS API
+__robis__ is an R package that allows accessing data from the Ocean Biodiversity Information System (OBIS) directly from R. OBIS is a global open-access data and information clearing-house on marine biodiversity for science, conservation and sustainable development.
+
+With __robis__ users can:
+
+- Download data from OBIS
+- Create a checklist of taxa that met a set of filters
+- Download [measurements and facts](https://manual.obis.org/data_format.html#extendedmeasurementorfact-extension-emof) associated with occurrences
+- Create maps from occurrences (including `leaflet` maps)
 
 ## Installation
 
+__robis__ is available from CRAN.
+
 ```R
 # CRAN
 install.packages("robis")
@@ -19,4 +28,44 @@ remotes::install_github("iobis/robis")
 
 ## Getting started
 
-See the [Getting started vignette](https://iobis.github.io/robis/articles/getting-started.html).
+The main functions of the __robis__ package are `occurrences` and `checklist`. You can easily download data for one species using:
+
+```R
+records <- occurrence(scientificname = "Abra sibogai")
+```
+
+Then you can plot the occurrences with:
+
+```R
+map_leaflet(records)
+```
+
+Or you can create a `ggplot` map using:
+
+```R
+map_ggplot(records)
+```
+
+![](man/figures/map.png)
+
+With the function `checklist` it's possible to obtain a checklist of all taxa in OBIS that met a certain filter. For example, here we obtain all species from the family "Tellinidae" 
+
+```R
+taxa <- checklist(scientificname = "Tellinidae")
+```
+
+See the [Getting started vignette](https://iobis.github.io/robis/articles/getting-started.html) for more details on how to download data according to filters and how to extract measurements or facts from occurrence data using the function `measurements`.
+
+## How to use OBIS data
+
+OBIS holds a large collection of biodiversity information, with more than 100 million presence records and almost 200 measurements and facts. This information is powering research in areas like taxonomy, phylogeny and ecology, and is being used as an important tool in conservation and management. You can learn more about OBIS with the [OBIS manual](https://manual.obis.org/). You can also explore some of our [use cases](https://obis.org/usecases/) or the many [publications](https://obis.org/library/) that applied OBIS data.
+
+## obistools package
+
+There is a companion package, __obistools__, available from GitHub: [github.com/iobis/obistools](https://github.com/iobis/obistools)
+
+__obistools__ provide several tools for cleaning data downloaded from OBIS, like:
+
+- Checking points on land
+- Checking depths
+- Checking dates