edit readme 📝

README.md

@@ -1,6 +1,6 @@
 <img src="man/figures/rmangal.png" width="130" align="right"/>
 
-# rmangal :package:
+# rmangal :package: - an R Client for the Mangal database
 
 [![Travis-CI Build Status](https://travis-ci.org/mangal-wg/rmangal.svg?branch=master)](https://travis-ci.org/mangal-wg/rmangal)
 [![Build status](https://ci.appveyor.com/api/projects/status/mibs2ni969xiqgrd?svg=true)](https://ci.appveyor.com/project/KevCaz/rmangal)
@@ -9,26 +9,109 @@
 [![CRAN status](https://www.r-pkg.org/badges/version/rmangal)](http://www.r-pkg.org/badges/version/rmangal)
 
 
-A R package to interact with the ecological interactions database Mangal
+## Context
 
-- API documentation: https://mangal.io/doc/api
-- Data explorer: https://mangal.io/#/network
-- Package documentation: https://mangal.io/doc/r
+Interactions among species is at the heart of ecology. Despite their importance,
+studying ecological interactions remains difficult due to the lack of standard
+information and the disparity of formats in which ecological interactions are
+stored. Historically, ecologists have used matrices to store interactions, which
+tend to easily decontextualize interactions from fieldwork when metadata is
+missing. To overcome these limitations, [Mangal](https://mangal.io/#/) -- a
+global ecological interactions database -- serializes ecological interaction
+matrices into nodes (e.g. taxon, individuals or population) and edges. Hence the
+base unit in Mangal is a published ecological network and thus distinct from
+other initiatives such as [Globi](https://www.globalbioticinteractions.org/)
+(see [rglobi](https://github.com/ropensci/rglobi) for an R Client to) that store
+pairwise interactions.
+
+For every network, Mangal store a vast array of metadata: from the details
+of the orginal publication to taxonomic information. Regarding the latter, Mangal store unique taxonomic identifiers such as Encyclopedia
+of Life (EOL), Catalogue of Life (COL), Global Biodiversity Information Facility
+(GBIF) and Integrated Taxonomic Information System (ITIS)
+
+**rmangal** is an R client to the Mangal database. As such, it provides various functions to query the data base and retrieve networks that are stored as
+`mgNetwork` or `mgNetworksCollection`. It also provides methods to convert `mgNetwork` to other object in order to use powerful package to work with networks: [`igraph`](https://igraph.org/r/), [`tidygraph`](https://github.com/thomasp85/tidygraph), and [`ggraph`](https://github.com/thomasp85/ggraph).
 
 
-## Installation
 
 
-So far, the development version can be installed via the [remotes](https://cran.r-project.org/web/packages/remotes/index.html) :package:
+## Installation
+
+So far, only the development version is available and can be installed via the [remotes](https://cran.r-project.org/web/packages/remotes/index.html) :package:
 
 ```r
-devtools::install_github("mangal-wg/rmangal")
-library("rmangal")
+R> devtools::install_github("mangal-wg/rmangal")
+R> library("rmangal")
 ```
 
+
 ## How to use rmangal
 
-See the vignettes ["Get started with rmangal"](https://mangal-wg.github.io/rmangal/articles/rmangal.html).
+In order to query the data base, there are [five `search_*()` functions](), for instance `search_datasets()`:
+
+```r
+R> mgs <- search_datasets("lagoon")
+Found 2 datasets
+```
+
+Once this first step achieved networks found can be retrieved with the `get_collection()` function:
+
+```r
+R> mgn <- get_collection(mgs)
+```
+
+which returns an object `mgNetwork` if there is one network returned, otherwise
+an object `mgNetworkCollection` is returned, which basically is a list of
+`mgNetwork` objects:
+
+
+```r
+R> class(mgn)
+[1] "mgNetworksCollection"
+R> mgn
+A collection of 3 networks
+
+* Network # from data set #
+* Description: Dietary matrix of the Huizache–Caimanero lagoon
+* Includes 189 edges and 26 nodes
+* Current taxonomic IDs coverage for nodes of this network:
+  --> ITIS: 81%, BOLD: 81%, EOL: 85%, COL: 81%, GBIF: 0%, NCBI: 85%
+* Published in ref # DOI:10.1016/s0272-7714(02)00410-9
+
+* Network # from data set #
+* Description: Food web of the Brackish lagoon
+* Includes 27 edges and 11 nodes
+* Current taxonomic IDs coverage for nodes of this network:
+  --> ITIS: 45%, BOLD: 45%, EOL: 45%, COL: 45%, GBIF: 18%, NCBI: 45%
+* Published in ref # DOI:NA
+
+* Network # from data set #
+* Description: Food web of the Costal lagoon
+* Includes 34 edges and 13 nodes
+* Current taxonomic IDs coverage for nodes of this network:
+  --> ITIS: 54%, BOLD: 54%, EOL: 54%, COL: 54%, GBIF: 15%, NCBI: 54%
+* Published in ref # DOI:NA
+```
+
+[`igraph`](https://igraph.org/r/) and
+[`tidygraph`](https://github.com/thomasp85/tidygraph) offer powerful features to
+analyse networks and **rmangal** provides functions to convert `mgNetwork` to
+`igraph` and `tbl_graph` so that the user can easily benefit from those
+features.
+
+```r
+R> ig <- as.igraph(mgn[[1]])
+R> class(ig)
+[1] "igraph"
+R> library(tidygraph)
+R> tg <- as_tbl_graph(mgn[[1]])
+R> class(tg)
+[1] "tbl_graph" "igraph"
+```
+
+:book: Note that the vignette ["Get started with
+rmangal"](https://mangal-wg.github.io/rmangal/articles/rmangal.html) will guide
+the reader through several examples and provide further details about **rmangal** features.
 
 
 

vignettes/rmangal.Rmd

@@ -20,7 +20,6 @@ knitr::opts_chunk$set(
   collapse = TRUE,
   comment = "#>"
 )
-# library(sf)
 ```
 
 
@@ -242,12 +241,13 @@ networks in California:
 
 
 ```{R}
+library(sf)
 library(mapview)
 library(USAboundaries)
 area <- us_states(state = "california")
-in_CA <- search_networks(area)  
+in_CA <- search_networks(area)
 
-mapview(in_CA, legend = FALSE) + mapview(sf::st_cast(area,"MULTILINESTRING"), color = "red", legend = FALSE)  
+mapview(in_CA, legend = FALSE) + mapview(sf::st_cast(area,"MULTILINESTRING"), color = "red", legend = FALSE)
 ```
 
 
@@ -275,7 +275,7 @@ sr_ficus <- search_taxonomy("Ficus")
 
 
 This function allows to search for a specific taxonomic entity using it's validated
-name or unique identifiers, i.e. EOL, TSN, GBIF, COL, BOLD and NCBI IDs. 
+name or unique identifiers, i.e. EOL, TSN, GBIF, COL, BOLD and NCBI IDs.
 Taxon names of the `taxonomy` table were validated with
 TNRS (see <http://tnrs.iplantcollaborative.org/> and/or GNR (see <https://resolver.globalnames.org/>). The taxon names in this table
 might not be the taxon name documented in the original publication.
@@ -368,7 +368,7 @@ tsn_acer <- search_taxonomy("Acer")$taxonomy.tsn
 classification(tsn_acer, db = "itis")
 ```
 
-## Network analysis with `igraph` 
+## Network analysis with `igraph`
 
 
 Once the data are retrieved and a `mgNetwork` or a `mgNetworkCollection` objects
@@ -403,10 +403,10 @@ from all the tools included in `tidygraph`:
 ```{R}
 library(tidygraph)
 # NB the line below would not work with a mgNetworksCollection (use lapply)
-tg_lagoons <-  as_tbl_graph(mg_lagoons[[1]]) %>% 
+tg_lagoons <-  as_tbl_graph(mg_lagoons[[1]]) %>%
   mutate(centrality_dg = centrality_degree(mode = 'in'))
 tg_lagoons %E>% as_tibble
-tg_lagoons %N>% as_tibble %>% 
+tg_lagoons %N>% as_tibble %>%
   select(original_name, taxonomy.tsn, centrality_dg)
 ```
 
@@ -416,10 +416,10 @@ offers various functions (theme, geoms, etc.) to efficiently visualize networks:
 
 ```{R}
 library(ggraph)
-ggraph(tg_lagoons, layout = "stress") + 
+ggraph(tg_lagoons, layout = "stress") +
   geom_edge_parallel(end_cap = circle(.5), start_cap = circle(.5),
-        arrow = arrow(length = unit(1, 'mm'), type = 'closed')) + 
-  geom_node_point(aes(colour = taxonomy.rank), size = 8) + 
+        arrow = arrow(length = unit(1, 'mm'), type = 'closed')) +
+  geom_node_point(aes(colour = taxonomy.rank), size = 8) +
   theme_graph(background = "grey40", foreground = NA, text_colour = 'white')
 ```