Abstract

Quarto is a open-source technical publishing system for Jupyter notebooks, which can be extended with templates. This article introduces a template for generating IEEE-formatted articles. The template handles the key elements of a scientific article: references, equations, figures, tables, code, cross references.

Introduction

In the “Doc-as-code” paradigm, technical writers uses software development tools to edit, collaborate on, and publish technical documentation. In addition to its home ground in documenting software projects, it is particularly well suited for engineers and scientists, writing data-rich articles. Similarly to a software project, such an article relies on significant computer code. Hence, managing the code and the corresponding article within the same environment boosts productivity, and favor deeper collaboration, because the code embodies the approach. By contrast, just collaborating on the manuscript and the results, without the code explaining how we got there, obfuscates critical elements of the approach.

When the article takes the form of a computation notebook (as opposed to a static manuscript), an additional level of integration is achieved. The article can directly invoke the code in order to rerun some analysis and update the plots on the fly. This boosts reproducibility further. Provided that the code and the supporting materials (data and software dependencies) are shared, anyone can reproduce the computational part of the article.

As noted by [1], the main purpose of a reproducible workflow is not to deal with outright fraud. Instead, it is to enable better scholarship. This is because reproducibility instills trust, a prerequisite for collaboration. In the same reference, it was also noted that some works don’t need to be reproduced, and that there is a there is a continuum between reproducibility and reuse of results. Similarly, we don’t advocate for an inappropriate blanket requirement that every single plot or table should be reproducible from scratch.

Still, there are many cases, where it is desirable. Data-rich analysis, for example, involves complicated math and bug-prone code. New data, new assumption, new findings might emerge possibly challenging or strengthening the previous conclusion. Having a reproducible analysis pipeline to re-run the analysis on demand is considered a good practice. If the article is a computation notebook, the updated results can be readily incorporated in an updated article. As noted in [2], striving for reproducibility imposes a discipline that leads to better work.

Jupyter notebook as article

A Jupyter notebook is well suited to serve as full-blown scholarly article—especially when the article relies on data analysis. It enables tight connection between the narrative story and the code powering the analysis. The complete article is then treated as code. This “article-as-code” paradigm is already popular in various domains of science and engineering.

As an example, ref. [3] is a chemistry paper, and provides a complete companion notebook freely available on Google Colab. The notebook fully reproduces the final paper, while also incorporating the code and the explanation.

Ref. [4] provides ten rules for writing and sharing computational analyses in Jupyter notebooks. The paper was published in a biology journal, but the rules are more generally applicable. Here is a condensed version of the ten rules

Tell a story, explaining the process not just the results.
Use coding best practices: modularize the code, make dependencies explicit, use version control, share data, build an analysis pipeline.
Design your notebooks for three purposes: to be read, run, and explored.

Beyond formal scholarly articles, engineering design and analysis reports also benefit from the computational notebook format. Engineering design typically rely on equations, quick inline calculations, pseudocode for algorithm description, and plots to explore the trade-offs. All these elements are first-class citizens in the notebook. In addition, significant code might be needed to configure support tool (e.g. CAD, FEM simulations), and this code is often critical to reproduce the design.

During the engineering analysis phase, large dataset from simulations or experiments, prototypes are manipulated and summarized in table and plots. The notebook is ideally suited to serve as an automatic analysis pipeline.

This concept is being stretched in chip design. See for example this “Code-a-chip” grant to travel to the largest semiconductor chip design conference and present an innovative notebook-driven design.

IEEE Quarto template

Quarto is a publishing system for Jupyter notebook. It is specially designed to produce polished scholarly articles. We explored its capabilities in a previous article [5].

In particular, it provides built-in templates for 7 journals and publishers (Association of Computing Machinery, American Chemical Society, Elsevier Journals …). It also provides an extension mechanism to add new templates from Latex classes.

There is no built-in template for IEEE journals. IEEE published nearly a third of the world’s technical literature in electrical engineering, computer science, and electronics.

We introduce here the ieeetran template, which was developed by the author. It produces polished PDF articles from a Jupyter notebook formatted according to the IEEE class IEEEtran. The template supports the IEEE specifics, namely the 2-column format and the figure* and table* environment spanning the two columns.

The development of the actual template consists of populating a template article in Latex invoking the existing class. While the template development requires Latex knowledge, this is transparent to the writer.

Example

Install the template by unzipping the content of the repository in the document directory. To use the template, run the following single command invoking Quarto with the output format ieeetran-pdf.

quarto render article.qmd --to ieeetran-pdf

Figure 1 illustrates the workflow and the example input and output documents.

Figure 1: Conversion from Jupyter notebook to fully formatted IEEE paper with a single command. Image by author.

Conclusion

In conclusion, we developed a Quarto extension to convert seamlessly Jupyter notebook to polished IEEE paper in PDF format. Still, we recommend that the HTML output (use the argument --to ieeetran-html) is used during the article drafting. The drafting can also take place fully in the usual notebook editor, with the assurance that the final formatting is just one command away. The writer does not need any Latex commands. A limitation is that the template does not support yet the conference format.

Quarto is lowering the barrier to adoption of the “doc-as-code” paradigm. With the template extension mechanism, a template based on a pre-existing Latex class can be readily developed. Formatting a paper becomes a routine operation, saving valuable time to focus on the article content.

Watermark

Code

%load_ext watermark
%watermark -n -u -v -g -iv

Last updated: Tue May 02 2023

Python implementation: CPython
Python version       : 3.9.12
IPython version      : 8.4.0

Git hash: 2cf6d41e5b1430ef5752aeec2fe91e39d3a895bf

forallpeople: 2.6.3
pint_pandas : 0.2
seaborn     : 0.11.2
pandas      : 1.4.4
logging     : 0.5.1.2
numpy       : 1.23.5
pyprojroot  : 0.2.0
matplotlib  : 3.5.3
sys         : 3.9.12 (main, Apr  5 2022, 06:56:58) 
[GCC 7.5.0]
hvplot      : 0.8.1
holoviews   : 1.15.0

References

[1]

J. Baillieul et al., “Report on the first IEEE workshop on the future of research curation and research reproducibility.” 2016 [Online]. Available: https://www.ieee.org/content/dam/ieee-org/ieee/web/org/ieee_reproducibility_workshop_report_final.pdf

[2]

L. A. Barba, “Defining the role of open source software in research reproducibility,” Computer, vol. 55, no. 8, pp. 40–48, Aug. 2022 [Online]. Available: http://dx.doi.org/10.1109/MC.2022.3177133

[3]

M. Ziatdinov, C. Nelson, R. Vasudevan, D. Chen, and S. Kalinin, “Building ferroelectric from the bottom up: The machine learning analysis of the Atomic-Scale ferroelectric distortions,” ChemRxiv, Apr. 2019 [Online]. Available: https://chemrxiv.org/engage/chemrxiv/article-details/60c74146567dfe2305ec3d40

[4]

A. Rule et al., “Ten simple rules for writing and sharing computational analyses in jupyter notebooks,” PLoS Comput. Biol., vol. 15, no. 7, p. e1007007, Jul. 2019 [Online]. Available: http://dx.doi.org/10.1371/journal.pcbi.1007007

[5]

G. Close, “Signal chain analysis in python: A case study for hardware engineers.” Feb. 2021 [Online]. Available: https://towardsdatascience.com/signal-chain-analysis-in-python-84513fcf7db2

Reuse

https://creativecommons.org/licenses/by/4.0/

Citation

BibTeX citation:

@online{close2022,
  author = {Close, Gaël},
  title = {Formatting a {Jupyter} {Notebook} for {IEEE} {Transactions}
    {Journals}},
  date = {2022-10-02},
  url = {https://gael-close.github.io/posts/2209-formatting-ieeetran/2209-formatting-ieeetran.html},
  langid = {en},
  abstract = {Quarto is a open-source technical publishing system for
    Jupyter notebooks, which can be extended with templates. This
    article introduces a template for generating IEEE-formatted
    articles. The template handles the key elements of a scientific
    article: references, equations, figures, tables, code, cross
    references.}
}

For attribution, please cite this work as:

G. Close, “Formatting a Jupyter Notebook for IEEE Transactions Journals,” Oct. 02, 2022. [Online]. Available: https://gael-close.github.io/posts/2209-formatting-ieeetran/2209-formatting-ieeetran.html