Creating a more fluent conversation between data, model and users through interactive Jupyter Notebooks

Reproducibility and re-usability of research requires giving access to data and numerical code but, equally importantly, helping others to understand how inputs, models and outputs are linked together. Jupyter Notebooks is a programming environment that dramatically facilitates this task, by enabling to create stronger and more transparent links between data, model and results. Within a single document where all data, code, comments and results are brought together, Jupyter Notebooks provide an interactive computing environment in which users can read, run or modify the code, and visualise the resulting outputs. In this presentation, we will explain the philosophy that we have applied for the development of interactive Jupyter Notebooks for two Python toolboxes, iRONS (a package of functions for reservoir modelling and optimisation) and SAFE (a package of functions for global sensitivity analysis). The purposes of the Jupyter Notebooks are two: some Notebooks target current users by demonstrating the key functionalities of the toolbox (‘how’ to use it), effectively replacing the technical documentation of the software; other Notebooks target potential users by demonstrating the general value of the methodologies implemented in the toolbox (‘why’ use it). In all cases, the Notebooks integrate the following features: 1) the code is written in a math-like style to make it readable to a wide variety of users, 2) they integrate interactive results visualization to facilitate the conversation between the data, the model and the user, even when the user does not have the time or expertise to read the code, 3) they can be run on the cloud by using online computational environments, such as Binder, so that they are accessible by a web browser without requiring the installation of Python. We will discuss the feedback received from users and our preliminary results of measuring the effectiveness of the Notebooks in transferring knowledge of the different modelling tasks.