rmangal blogpost

content/authors/kevin-cazelles/_index.md

@@ -2,4 +2,6 @@
 name: Kevin Cazelles
 twitter: KCazelles
 link: https://kevcaz.github.io/
+github: KevCaz
+orcid: 0000-0001-6619-9874
 ---

content/authors/steve-vissault/_index.md

@@ -0,0 +1,7 @@
+---
+name: Steve Vissault
+link: http://steveviss.github.io/
+github: SteveViss
+twitter: SVissault
+orcid: 0000-0002-0866-4376
+---

content/blog/2019-10-21-rmangal.md

@@ -0,0 +1,177 @@
+---
+slug: rmangal
+title: 'rmangal: making ecological networks easily accessible'
+date: 2019-10-21
+authors:
+  - Kevin Cazelles
+  - Steve Vissault
+categories: blog
+topicid: 
+tags:
+  - Software Peer Review
+  - R
+  - packages
+  - open-data
+  - data
+  - data-access
+  - ecology
+  - ecological networks
+  - API
+  - API client
+  - Mangal
+  - rmangal
+---
+
+
+In early September, the version 2.0.0 of [rmangal][rmangal] was approved by
+rOpenSci, four weeks later it made it to CRAN. Following-up on our experience we
+detail below the reasons why we wrote rmangal, why we submitted our package to
+rOpenSci and how the peer review improved our package.
+
+
+
+### Mangal, a database for ecological networks
+
+Ecological networks are defined as a set of species populations (the nodes of
+the network) connected through ecological interactions (the edges). Interactions
+are ecological processes in which one species affects another. Although
+predation is probably the most known and documented interaction, other less
+noticeable associations are just as essential to ecosystem functioning. For
+instance, a mammal that unintentionally disperses viable seeds attached to its
+fur might help plants to thrive. All of these interactions occur simultaneously,
+shaping ecosystem functioning and making them as complex as they are
+fascinating.
+
+Recording and properly storing these interactions help ecologists to better
+understand ecosystems. That is why they are currently compiling datasets to
+explore how species associations vary over environmental gradients and how
+species lost might affect ecosystem functioning. This fundamental research
+question should help us understanding how ecological networks will respond to
+global change. To this end, the Mangal project <https://mangal.io/#/>
+standardizes ecological networks and eases their access. Every dataset contains
+a collection of networks described in a specific reference (a scientific
+publication, a book, etc.). For every network included in the database, Mangal
+includes all the species names and several taxonomic identifiers
+([gbif](https://www.gbif.org/), [eol](https://eol.org/),
+[tsn](https://www.itis.gov/) etc.) as well as all interactions and their types.
+Currently, Mangal includes 172 datasets, which represents over 1300 ecological
+networks distributed worldwide.
+
+
+
+### An R client to make ecological networks easily accessible
+
+In 2016, the first paper describing the project was published[^original_ref]. In
+2018, a substantial effort was made in order to improve the data structure and
+gather new networks from existing publications. In 2019, the web API was
+rewritten, a new website launched and hundreds of new interactions were added. 
+
+[{{< figure src="/img/blog-images/2019-10-22-rmangal/mangal_explorer.png" width="100%" >}}](https://mangal.io/#/network)
+
+Because of all these modifications, the first version of rmangal was obsolete
+and a new version needed. It is worth explaining here why the R client is an
+important component of the Mangal project. Even though Mangal has a documented
+[RESTful API](https://mangal.io/doc/api/), this web technology is not commonly
+used by ecologists. On the contrary, providing a R client ensures that the
+scientific community that documents these interactions in the field can access
+them, as easily as possible. The same argument holds true for the [Julia
+client](https://mangal.io/doc/jl/) that [Timothée Poisot](https://poisotlab.io/)
+wrote because [Julia](https://julialang.org/) is increasingly popular among
+theoreticians, that can test ecological theory with such datasets.
+
+We had two main objectives for [rmangal 2.0.0][rmangal]. First, the rmangal
+package had to allow users to search for all entries in the database in a very
+flexible way. From a technical point this means that we had to write functions
+to query all the endpoints of the [new web API][API]. The second goal was to
+make the package as user friendly as possible. To do so, we used explicit and
+consistent names for functions and arguments. We then designed a simple workflow, and
+documented how to use other field related packages (such as [igraph][igraph]) to
+visualize and analyze networks (see below). You can find further details in the vignette ["get
+started with rmangal"](https://docs.ropensci.org/rmangal/articles/rmangal.html).
+
+
+```r
+# Loading dependancies
+library(rmangal)
+library(magrittr)
+library(ggraph)
+library(tidygraph)
+
+# Retrieving all ecological networks documented in Haven, 1992
+havens_1992 <- search_references(doi="10.1126/science.257.5073.1107") 
+                  %>% get_collection()
+
+# Coerce and visualize the first network object return by mangal with ggraph 
+ggraph(as_tbl_graph(havens_1992[[1]])) +
+     geom_edge_link(aes(colour = factor(type))) +
+     geom_node_point() +
+     theme_graph(background = "white")
+```
+
+{{< figure src="/img/blog-images/2019-10-22-rmangal/vis_net1.png" width="80%" >}}
+
+
+
+### A successful peer review process
+
+<!-- version to prerelease -->
+After some hard work behind the screen and once we deemed our two objectives
+achieved, we decided to submit the rmangal package to rOpenSci for peer review. We
+did so because we needed feedback, we needed qualified people to critically
+assess whether our two main objectives were achieved. Given the strong expertise
+of rOpenSci in software review, and given that our package was in-scope,
+submitting rmangal to rOpenSci was an obvious choice.
+
+We [had very valuable
+feedback](https://github.com/ropensci/software-review/issues/332) from [Anna
+Willoughby][arw36] and [Thomas Lin Pedersen][thomasp85]. They carefully assessed
+our work and pointed out areas where improvement was required. One good example
+of how their review made our package better concerns the dependencies. We
+originally listed [sf][sf] in `Imports` as we used it to filter networks based
+on geographic coordinates. But the reviewers pointed out that this was not an
+essential part of the package and that [sf][sf] has several dependencies. This  made us realize that for one extra feature, we were substantially
+increasing the number of indirect dependencies. Following the reviewers'
+suggestions, we moved [sf][sf] to `Suggests` and added a message to warn users
+that to use the [spatial filtering
+feature](https://docs.ropensci.org/rmangal/articles/rmangal.html#geolocalize-mangal-networks-with-sf)
+requires sf to be installed. Similarly, based on another good comment, we
+added a function to convert Mangal networks into [tidygraph][tidygraph] objects
+and we documented how to plot Mangal networks with [ggraph][ggraph] (and so we
+added those packages in `Suggests`). Such improvements were very helpful to
+properly connect rmangal to the existing R packages. The plethora of R packages
+is one of its major strengths, and connecting a package properly to others makes
+the entire ecosystem even stronger.
+
+<!-- Future -->
+We are now looking for user experience feedback, not only for rmangal
+([vignette](https://docs.ropensci.org/rmangal/articles/rmangal.html)) but also
+for the web API ([documentation](https://mangal.io/doc/api/)) and the [mangal.io
+website](https://mangal.io). We welcome suggestions and contributions,
+especially for the documentation by opening new issues on GitHub
+([mangal-api](https://github.com/mangal-wg/mangal-api/issues),
+[mangal-app](https://github.com/mangal-wg/mangal-app/issues),
+[rmangal](https://github.com/ropensci/rmangal/issues)). In the future, we
+envision that rmangal will integrate functions to format ecological networks for
+ecologists willing to add their datasets to Mangal. This will likely be the next
+major release of rmangal.
+
+### Acknowledgments
+
+We are thankful to all [contributors to
+rmangal](https://ropensci.github.io/rmangal/authors.html) and to all ecologists
+that have spent countless hours in collecting data. We would like to thank [Anna
+Willoughby][arw36] and [Thomas Lin Pedersen][thomasp85] for thorough reviews as
+well as [Noam Ross](https://github.com/noamross) for handling the review
+process.
+
+[^original_ref]: Poisot, T. et al. mangal - making ecological network analysis simple. Ecography 39, 384–390 (2016). https://doi.org/10.1111/ecog.00976
+
+
+[arw36]: https://github.com/arw36
+[thomasp85]: https://github.com/thomasp85
+[igraph]: https://igraph.org/r/
+[tidygraph]: https://tidygraph.data-imaginist.com/
+[ggraph]:https://ggraph.data-imaginist.com/
+[rmangal]: https://ropensci.github.io/rmangal/
+[API]: https://mangal.io/doc/api/
+[sf]: https://cran.r-project.org/web/packages/sf/index.html

readme.md

@@ -18,8 +18,8 @@ See [editorial suggestions](#blog-post-editorial-suggestions). Before that, tech
 
 1. [Fork the repo](https://happygitwithr.com/fork-and-clone.html)
 2. Create a new file in `/content/blog/YEAR-MONTH-DAY-slug.md`, either directly or after developing it in a separate project. i.e. working on an R Markdown file in a separate RStudio project and then moving the images and Markdown output to your fork of the website
-    * [Markdown template](2019-06-04-post-template.md), 
-    * R Markdown template: either [to be copy-pasted](https://github.com/ropenscilabs/rodev/blob/master/inst/rmarkdown/templates/ropensci-blog-post/skeleton/skeleton.Rmd) or install [`rodev`](https://docs.ropensci.org/rodev/) via `remotes::install_github("ropenscilrodev")` after which in RStudio you can click on `File > New File > R Markdown... > From Template > rOpenSci Blog Post `to create the file.
+    * [Markdown template](2019-06-04-post-template.md),
+    * R Markdown template: either [to be copy-pasted](https://github.com/ropenscilabs/rodev/blob/master/inst/rmarkdown/templates/ropensci-blog-post/skeleton/skeleton.Rmd) or install [`rodev`](https://docs.ropensci.org/rodev/) via `remotes::install_github("ropensci/rodev")` after which in RStudio you can click on `File > New File > R Markdown... > From Template > rOpenSci Blog Post `to create the file.
 
 3. Your post must include YAML in this format:
 
@@ -55,7 +55,7 @@ tags:
 {{< figure src="/img/blog-images/<DATE-SLUG>/name-of-image.png" alt="write an alternative text describing the information contained in the image" width="500" >}}
 ```
 
-6. Once you've drafted your blog post, you can [preview locally using Hugo](#installing-hugo-for-local-preview) or skip to the next step to preview on the pull request. 
+6. Once you've drafted your blog post, you can [preview locally using Hugo](#installing-hugo-for-local-preview) or skip to the next step to preview on the pull request.
 
 7. Send a pull request from your fork at least one week prior to the post date to allow time for review. Netlify will start building the new version of the site within seconds and you can preview you changes to make sure everything looks as intended. Otherwise push additional fixes till things look right.  
 
@@ -73,8 +73,8 @@ tags:
 - If you would like a specific image from your post to be featured in tweets that include a link to your post, add to YAML `twitterImg: img/blog-images/<DATE-SLUG>/name-of-image.png`. Omit the leading `/`
 - Use ### or #### to format headings in your post; larger sizes don't look good. Note long headings with #### don't wrap well.
 - Spell 'rOpenSci', not 'ROpenSci'
-- For references, put `[^1]` after the text you want to cite in body of the post, and put `[^1]: citation details` at the end of the post. They will link to each other. Example in this post [markdown](https://raw.githubusercontent.com/ropensci/roweb2/master/content/blog/2019-04-18-ropensci-mee.md) -> [rendered](https://ropensci.org/blog/2019/04/18/wild-standards/). 
-- Check to see if you're listed on [our authors page](https://ropensci.org/authors/). If you are listed, consider updating the links to your online presence in the author's index file. If not, create an [author's index file for yourself](#author-file). 
+- For references, put `[^1]` after the text you want to cite in body of the post, and put `[^1]: citation details` at the end of the post. They will link to each other. Example in this post [markdown](https://raw.githubusercontent.com/ropensci/roweb2/master/content/blog/2019-04-18-ropensci-mee.md) -> [rendered](https://ropensci.org/blog/2019/04/18/wild-standards/).
+- Check to see if you're listed on [our authors page](https://ropensci.org/authors/). If you are listed, consider updating the links to your online presence in the author's index file. If not, create an [author's index file for yourself](#author-file).
 
 ##### Instructions for posts about peer-reviewed packages
 
@@ -94,7 +94,7 @@ For a post about your experience as a reviewer you can browse other posts with t
 
 If you don't already have one, create `_index.md` in `roweb2/content/authors/firstname-lastname/` with information about your online presence. Keep accents in your name. If you're not sure of how to slugify/urlize your name, look at other people's folder names for examples.
 
-[Template for an author file](author-name.md), Example 
+[Template for an author file](author-name.md), Example
 
 ```yaml
 ---
@@ -112,15 +112,15 @@ Example when rendered: [Kelly O'Briant's author page](https://ropensci.org/autho
 
 At minimum, provide your name and at least one link or Twitter/GitHub/GitLab username. The `link` field is meant for your preferred online presence URL, to be filled only if you have one that's not your GitHub, GitLab or Twitter account. The `twitter`, `github`, `gitlab`, `keybase` and `orcid` fields are for your Twitter/GitHub/GitLab/Keybase/ORCID usernames/IDs (without "@").
 
-Then when a reader clicks on your by-line in your blog post, tech note, or a community call you have presented in, they can see how to find you online, as well as seeing a list of all of those you have contributed. 
+Then when a reader clicks on your by-line in your blog post, tech note, or a community call you have presented in, they can see how to find you online, as well as seeing a list of all of those you have contributed.
 
 ### Installation requirements
 
 There are no requirements to simply add a post/fix and push to GitHub for a render preview on a pull request. However, if you wish to preview the site locally, you must install Hugo.
 
 #### Installing Hugo for local preview
 
-The version of Hugo used by the server is defined in [netlify.toml](netlify.toml). 
+The version of Hugo used by the server is defined in [netlify.toml](netlify.toml).
 
 To install Hugo locally, refer to [Hugo docs](https://gohugo.io/getting-started/installing/) or run `blogdown::install_hugo()`.