Reproducible Research

This repository contains the code for the fictional paper “Migraines and Math Degrees: A Spurious Love Story”, as well as the paper itself and all necessary files to generate a PDF version of the paper in a reproducible manner.

To build the paper, we use the Nix package manager to ensure that the environment in which the paper is built is consistent across different systems. The tools and packages required in the build process are fetched automatically by the Nix package manager from the Nixpkgs repository, which is the official package repository for Nix. In particular, these tools include LaTeX for typesetting the paper and Python, along with several Python packages, for processing the data and generating plots.

Nix also aids in achieving bit-for-bit reproducibility of the generated PDF file, meaning that the same source code and data produces exactly the same PDF file every time it is built. This is particularly important for scientific papers, where reproducibility is a key aspect of the research process.

Building the paper requires some data files, which are fetched from the internet during the build process. The data includes Google Trends data for specific search terms, as well as data from the National Center for Education Statistics (NCES). Both data sources have been made available separately in a GitHub Gist. This data can be fetched either automatically by Nix during the build process or manually using git-annex, which is a tool for managing large files in Git repositories.

A pre-built version of this paper is available here.

To get started with reproducing the paper, you can follow the instructions below.

Requirements

• Git
  • Last tested using version 2.49.0
• Nix, the package manager
  • Last tested using version 2.25.3

Platform requirements

Building the paper has been tested on the following platforms:

• Linux: Ubuntu 22.04 LTS, NixOS 25.05
• macOS: macOS 13.6.3 (Ventura)
• Windows: Windows 11 with WSL (Windows Subsystem for Linux) and Ubuntu 22.04 LTS

If you are using macOS or Linux, you are already set up to run the commands in this guide, as Nix is natively supported on these platforms. Simply open a terminal and continue with the instructions for installing Git and Nix below.

If you are using Windows, you will need to install WSL (Windows Subsystem for Linux) and set up a Linux distribution (e.g., Ubuntu) to run the commands in this guide. This is because Nix is not natively supported on Windows as Nix relies on a Unix-like environment.

Setting up WSL with Ubuntu on Windows

You must be running Windows 11 version 2004 and higher (Build 19041 and higher) or Windows 11 to use the following instructions to install WSL and set up a Linux distribution.

1. Open a Windows Terminal or PowerShell as an administrator by searching for Windows Terminal or PowerShell in the Start menu, right-clicking on it, and selecting Run as administrator.
2. Enter the wsl --install -d Ubuntu-22.04 command to install WSL (if it isn't already installed) and set up the Ubuntu Linux distribution.
3. If WSL isn't already installed, this command will also enable the required Windows features and download the necessary components to run WSL. In that case, it will prompt you to restart your computer to complete the installation. After the restart, open Ubuntu from the Start menu to complete the setup.
4. After the installation is complete and Ubuntu has been launched, WSL will prompt you to enter a username and password for your new Linux user account. Choose a username and password that you will remember, as you will use these to log in to your WSL environment. Note that this account is not related to your Windows user account.
5. Once the setup is complete, you can use the Linux shell to run commands.

These commands were taken from the WSL installation guide. Please refer to that guide for more information or if you encounter any issues.

In the following sections of this guide, please follow the instructions for Linux if you are using WSL, as the commands are the same for both WSL and a native Linux installation.

Installing Git

Please head to the Git downloads page and select your platform. Follow the instructions provided there to install Git.

Tip

If you are using WSL, you can install Git by running the following command in your Linux shell: sudo apt install git. You may need to enter your Linux user password to allow the installation to proceed.

Installing Nix

Nix can be installed using the following command:

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install)

This will download and run the Nix installation script, which will guide you through the installation process. You may need to enter your password to allow the installation to proceed. For more information on installing Nix, see the Nix installation guide.

Enabling Nix flakes

Building the paper also requires you to have Nix flakes enabled. To do this, you need to add the following line to your Nix configuration file (at /etc/nix/nix.conf or ~/.config/nix/nix.conf):

experimental-features = nix-command flakes

This can be done automatically by running the following two commands in your terminal:

# Create the `/etc/nix` directory
sudo mkdir -p /etc/nix

# Create the `nix.conf` file and add the necessary line to it
echo 'experimental-features = nix-command flakes' | sudo tee -a /etc/nix/nix.conf

You're all set! You can now proceed to build the paper using Nix as described below. 🎉

Building the paper

There are two main ways to build the paper:

1. Using data fetched from the internet using Nix.
2. Using data fetched from the internet using git-annex.

1. Using Nix

Simply run the following command:

nix build github:thunze/rr/1.1#paper

You can find the built paper in result/migraines-math-degrees.pdf.

Tip

If you are using WSL and you want to view the generated PDF file, you can install either a Linux PDF viewer like Evince to view it or wslu to view it using your default Windows PDF viewer.

• To install either of these packages, first run sudo apt-get update to update your local package index, then install Evince via sudo apt install evince or wslu via sudo apt install wslu.
• If you installed Evince, you can then open the PDF file by navigating to the result directory and running evince migraines-math-degrees.pdf.
• If you installed wslu, you can open the directory containing the PDF file in Windows Explorer by running wslview . in the result directory. You can then double-click the migraines-math-degrees.pdf file to open it in your default Windows PDF viewer.

2. Using git-annex

First clone the repository and navigate to the cloned directory:

git clone --branch 1.1 https://github.com/thunze/rr.git
# Or using SSH:
# git clone --branch 1.1 [email protected]:thunze/rr.git
cd rr

Activate the provided Nix shell to get access to git-annex:

nix develop

Then, run the following commands to fetch the data using git-annex and prepare it for the build:

git annex get
cp -Lr data/*.* data/resolved

Finally, build the paper:

nix build .#paperAnnex

You can find the built paper in result/migraines-math-degrees.pdf.

Verifying the build

This paper aims to be bit-for-bit reproducible, meaning that the same source code and data should produce the same output every time it is built.

To verify this, you can check the output of the build (currently, the PDF file) against known good hashes in result.SUMS by running:

• nix run github:thunze/rr/1.1#verifyResult if you used method 1 (pure Nix build).
• nix run .#verifyResultAnnex if you used method 2 (Nix build with data fetched via git-annex).

If the verification passes, you should see output similar to the following:

hashdeep: Audit passed
          Files matched: 1
Files partially matched: 0
            Files moved: 0
        New files found: 0
  Known files not found: 0

Rationale for using Nix

Nix is used in this project to ensure that the build environment is reproducible and consistent across different systems. It allows us to specify exact versions of dependencies and tools, which helps avoid issues related to differing software versions or configurations. Nixpkgs also applies specific patches to the TeX Live distribution it provides to ensure that built PDFs are reproducible, which aids in achieving bit-for-bit reproducibility.

License

This project is licensed as follows:

• All source code files in this repository are licensed under the The Unlicense (SPDX identifier: Unlicense). See the LICENSE file for the full license text.
• The generated paper is licensed under the CC0 1.0 Universal license (SPDX identifier: CC0-1.0). See the LICENSE-paper file for the full license text.
• The licensing of the Google Trends data is described in the Google Terms of Service.
• The NCES data is placed in the public domain by the U.S. Department of Education, as described in 17 U.S. Code § 105.