Computational Notebooks allow for code, data, graphics, and narrative to be combined into a single document with a linear flow. Notebooks are commonly used in research work for tasks such as data review and clean up, exploratory analysis and visualization, creation of interactive mini-apps or widgets and for preparing figures for a final manuscript. In each case, notebooks allow additional rich documentation and explanation to be added around code cells and their outputs making for a document that stands up better than source code alone.
Preparing a Notebook based research paper builds on this practice but requires additional effort in order to create a good quality narrative without overwhelming the reader with irrelevant code (See tutorial on single notebook based papers for tips on how to structure code). A publication Notebook properly incorporates cross references, citations and reference lists and other elements that you would expect in a journal quality research paper. It also incorporates and enables supplementary sections and materials to ensure that the whole submission is independently reproducible on another computer (See Reproducible Environments), enabling editors, reviewers and readers to run your notebooks.
To best support the authoring process, submissions can be prepared using the Jupyter Notebook format with the two prominent open source notebook authoring toolchains; MyST Markdown with JupyterLab and Quarto.
Advantages of Notebook based in Research PublicationsΒΆ
Notebook based papers open up interesting new opportunities for researchers and authors, as a computational environment is always available alongside the manuscript, the purpose of the computational aspects of the paper can be considered. While full reproducibility of a paper may not be possible, steps to better communicate results and support understanding for readers can be made.
Some motivations for using notebooks in your publication are:
- Demonstrate Reproducibility
- where a reader can execute notebooks against your data or some subset of it, potentially varying some parameters
- Enabling Effective Reuse
- providing a much better effective starting point for researchers to understand and build on your work
- Exploratory Figures
- augmenting static figures with interactive widgets, that allow readers to explore your data or results sets
Additionally, the submission system behind the Notebooks Now! project allows you to encode all your metadata once in your repository and automates the bulk of the submission process for you, making submissions easier and faster.