Fig 1.
File structure created by the set_kit functions.
All files relevant to a publication can be found in this nested structure. The computational notebook (proj_name.Rmd/jl) stays at the upper level, from where it has access, through relative paths, to input data that is analyzed, as well as scripts, if necessary. The outputs of such analyses can stay visible in the notebook or be saved in the figures and tables dedicated folders, also through relative paths, if they are to be included in the main text.
Fig 2.
Schematics of the organization of a research project (proj_name) around a computational notebook (proj_name.Rmd/jl, referring to an RMarkdown or Julia file).
The notebook contains narrative text supplementary to the manuscript’s main text, as well as text explaining the reasoning behind the computational work (included as code blocks) and its respective outputs (either kept on the notebook or saved as figures or tables). The notebook stays at upper level of a file structure (Fig 1), which provides easy access to all relevant folders for input (purple) and output (green) files through relative paths. The gray area shows subfolders that are nested inside folders (e.g., the figures and tables folders are inside the text folder). The notebook, along with all the files in the project’s folder, can be subjected to version control and be referenced in a lab notebook, thanks to the nested structure of the project. We recommend publishing it as your main supplementary material to the manuscript, along with a rendered version (.pdf or.html), any scripts, and not yet public data you use.
Fig 3.
Comparison between the Rnotebook file available for editing (A) and the rendered html version (B).
The function in set_kit.R creates an.Rmd file (A) with basic metadata (title and minimal formatting of the rendered file), a brief tutorial on the Markdown syntax, paths to the most relevant folders, and suggestions of use. In the.html version (B), one can see how text and code are converted and combined, as well as a couple of features available in Rnotebooks: a table of contents, just below the title (defined by the toc argument set to true in the YAML section of the Rnotebook file), and a code button, that hides the blocks of code by default, to facilitate reading (defined by the code_folding argument set to hide in the YAML section). The video accompanying this tutorial details how the document works (available in https://github.com/FellowsFreiesWissen/computational_notebooks).
Fig 4.
Comparison between the Pluto notebook file available for editing (A) and the rendered html version (B). The function in set_kit.jl creates a.jl file (A) with a brief tutorial on the Markdown syntax, paths to the most relevant folders, and suggestions of use. The Pluto notebook offers the following features: Cells of code can be hidden by clicking the “Show/hide code” button (A.1), the time for running the code is shown alongside the “Run” button (A.2), and the file type to be exported (.jl,.html, or.pdf) can be chosen by clicking the “Export” button (A.3)—no detailed formatting is possible, however. In the html version (B), a button (B.1) allows the reader to edit and run the code on Binder, a free cloud server for scientific notebooks. The video accompanying this tutorial details how the document works (available in https://github.com/FellowsFreiesWissen/computational_notebooks).