Template for a Reproducible Computational Paper

This repository contains the boilerplate elements for a computational paper built from Python notebook(s).

Such paper consists of

code and data
manuscript in the form of a computational Python notebook mixing code, computation results and narrative with a simple Markdown syntax
possibly other support notebooks as supplementary materials
a companion A0 poster
Runfile to build the paper from scratch with simple commands (e.g. run pdf to build the journal-fromatted PDF, or run poster)
Configuration options

Formatted paper and poster

The deliverables consist of the paper and poster in PDF and HTML format. They are published automatically at this Gihub page for convenience. This is achived by a GitHub action which uploads the deliverables folder.

Paper: PDF | HTML
Poster: PDF | HTML

Features

Directories organized similarly to Cookiecutter Data Science
Python best-practices: reusable code in a module in src/, unit tests in tests/ and standalone notebooks.
Proper git setup (git LFS, git ignore, ...)
Paper manuscript in Quarto markdown. Ability to mix code, illustrations and narrative story in a lean syntax. Support all elements of a formal paper. See "Technical Writing and Publishing Data-Rich Articles with Quarto"
Runfile automating all frequency commands (build, release, ...).
Commands to generate IEEE-formatted PDF, and HTML version for quick preview
Commands to generate a A0 poster (HTML and PDF) using the BetterPoster approach also from Quarto Markdown source.
Command to publish to Gdrive
Configures Gitlab to post the deliverables online in Gitlab pages.
tbump configuration for managing version tag.
Plain 1-column PDF format also available for supplementary notes

Quick start

These instructions are valid for Linux OS.

Installation (one-time only)

Install the pre-requisites

Quarto
a Latex installation
google-chrome. The poster PDF rendering relies on printing to PDF via google-chrome.
Poetry

Install the Python dependencies in a Virtual environment (one-time only)

poetry install --no-root

Activation (to be done in each session)

Load the virtual environment.

poetry shell;
export QUARTO_PYTHON=`poetry env info --executable`

Double check the configuration with quarto check

Alternative with https://direnv.net/: activate autmoatically when entering the working directory. Use the provided file .envrc

Operation

To build the paper HTML and the poster:

run html
run poster

References

Here are two articles generated from Quarto. The template here was derived from these.

G. Close, “Technical Writing and Publishing Data-Rich Articles with Quarto,” Sep. 22, 2022. [Online]. Available: https://gael-close.github.io/posts/2209-tech-writing/2209-tech-writing.html.
B. Brajon, E. Gasparin, and G. Close, “A benchmark of integrated magnetometers and magnetic gradiometers,” IEEE Access, vol. 11, pp. 115635–115643, 2023, https://doi.org/10.1109/ACCESS.2023.3325035.

The poster stylesheet is taken from https://github.com/hits-mbm-dev/paper-talin-loop/.

gael-close / template-paper