A guide to collaborative development with R for reproducible PROPRE reporting

Processus development collaborative
Tags : development, Rmarkdown, rstudio, tips
Date :

With our “PROPRE” Project Guide, get a publishing committee and a development team to collaborate on creating your automated reports using the “PROPRE” methodology. Follow our suggestions for organization, tools and R development practices, for a controlled and benevolent DevOps practice.

It is possible to collaborate around git in a team composed of developers and non developers. In this guide “Organisation d’un projet collaboratif de publication PROPRE”, we explain how.

Although the guide is only available in French, the concept of ‘PROPRE’ and the list of chapters as presented below may be of interest to other teams who wants to collaborate around a common development project.

What is a “PROPRE” collaborative project?

A “PROPRE” collaborative project is a project that follows the “PROPRE Publications Process” and is led by a multi-disciplinary team.
Following DREAL Pays de la Loire’s response to a call for projects from the Commissariat Général au Développement Durable (CGDD) at the end of 2015 on the theme of strategic knowledge of territories, a data service center was formed in 2018.
The “DREAL datalab” must provide easy access to the raw, aggregated and analyzed data produced and disseminate them.
In order to promote the success of the projects, modern development methods and the use of free and open-source tools have been tested.
The production of data and the analysis of these data now require their presentation in a reproducible framework for at least three reasons: confidence in the information, its freshness and the saving of time in producing new information.
Thus, the need arose to define a PROcessus to set up collaborative Projects of REproducible and therefore disseminable Publications. The acronym “PROPRE” was born (PROPRE means CLEAN in French).
The implementation of this process could only be done in a single team.
A multi-disciplinary team of agents from different DREALs was formed to test the process against the needs and constraints of each on a common collaborative project.

Details of the genesis and concepts of the process can be found in the digital book: It’s “PROPRE”!, written in French too.

What is in this R development guide?

This book, written in French, is intended for the various people involved in an “PROPRE” development process. We will distinguish three categories of content:

  • [01 – coordination] : How to set up such a project, what are the roles to be distributed, what are the necessary means and tools, … ?
  • [02 – editing] : How to define your needs, how to present the content of the documents, how to collaborate with the development team, … ?
  • [03 – development] : How to launch the project technically, which tools to use, which development method with R, which are the best practices, … ?

Project steps in chronological order

Setting up the project

The DevOps development cycle

Each request from the editorial board will be listed in one or more tickets.
Generally speaking, for a production with R, the validation concerns (1) the general appearance of the production (excluding relevant content), (2) the content (not formatted), and (3) the content integrated in the production medium.
In the context of a “PROPRE” publication, validation is about the content creation support tools.

The development product is always a R package, documented, tested and versioned.
The intended end product is a reproducible publication created from this package.
The implementation steps should have separated the publication into different chapters, independent if possible.
The publication will be built in several steps, repeated for each chapter.

  1. UI first: Creation and validation of the appearance of the future product (bookdown, without content) and the way it is built by the users (How the publication creation menu appears).
  2. Rmd then :
    • [dev]: Creation of the thumbnails of the package. Rather dedicated to the documentation of the development, they present the direct use of the created functions. The compiled thumbnails will be presented on a web site for validation of the content and data processing by the editorial committee [Ed].
    • [edition] : Creation of the content of the texts of the publication. Titles and paragraphs are validated in the editorial committee. In theory, there should be no discussion on the structure of the chapter at this stage.
  3. User documentation. This is an extension of the Rmd then part, which should explain to users of the product how to use it. This includes
  4. Integration of the content into the product. In this phase, there should be no more discussion about appearance, content or substance. The R codes are fixed. It is mainly a matter of checking that everything goes well in the final product.

The 1., 2. and 3. can be done independently, in parallel.
The 4. is done at the end. It can be the end of the validation of a particular chapter. But not of a paragraph.

The guides required for the good realization of the development cycles are the following:

User tests and deliveries

At the end of a cycle, the content is fixed, the development of new functionalities is fixed.
We enter a validation phase.
The development and publishing teams test the proper functioning of the tools

Learn more about PROPRE

Slide shows presenting the “PROPRE” process:

About the author

Sébastien Rochette

Sébastien Rochette

Modélisateur, formateur R, joueur de cartographies

Leave a Reply

Also read