Summary and Setup

Welcome to our mini-tutorial!

We will do a sequence of hands-on tasks on a toy research project to demonstrate a selection of Software Tools for Reproducible Research. The essential tools are Make, Python, Git, and LaTeX. Here is a longer list of tools we recommend.

We used software from the carpentries (without their endorsement) to build this tutorial, and we derived this tutorial from their make-novice lesson. Our emphasis on Make reflects that. The collection of tools is connected to a literature about software practices. In that literature, we particularly recommend Best Practices for Scientific Computing.

Quick Start

Without reading further, you can see some of the tools in action with these shell commands

BASH

$ git clone https://gitlab.com/fraserphysics/zipf work_dir
$ cd work_dir
$ git checkout 06-documentation
$ make

If that is successful, the last line of output will be

OUTPUT

Latexmk: All targets (build/report.pdf) are up-to-date

and you can view the result in build/report.pdf.

If it didn’t work, go to the setup page.

Prerequisite

Prerequisites

We will assume that you are somewhat familiar with the following tools (in order of familiarity)

bash: It’s probably OK if you use a different shell, but you should be comfortable with command line tools.
A text editor of your choice: Software Carpentry insists that instructors use Nano to avoid frightening the learners. We will use Emacs or Vim so that we can cover more material.
Python: Most of the code we will discuss is written in Python. If you are not comfortable with Python, you should not sign up for this mini-tutorial.
git: We use git to keep code up to date for each learner as we progress from one section to the next throughout the mini-tutorial. While we will provide you with the necessary git commands, it will make more sense to you if you have used the tool before.
LaTeX: We use LaTeX to format results. As with git, it will make more sense to you if you have used the tool before.

A Real Project

While we use a toy project in this tutorial to introduce a collection of tools, Andy Fraser has used the same tools to build the second edition of “Hidden Markov Models and Dynamical Systems” which SIAM will publish in 2027. Here you can read a brief description of that project.

Setup

For this tutorial you will use some files that represent a toy research project. Some of those files are data and some are code. You should fetch those project files using the git commands that we specify below.

You will also need some software in an environment on your computer. We assume that your computer provides a UNIX-like environment. How you install the software will depend on your operating system and your environment.

Please clone the git repository and install the required software before coming to the tutorial.

Project Files via Git

You need to clone a git repository to follow this tutorial. We’ve made a separate branch in the repository for each episode so that as we progress from one episode to the next you can save your work on the old branch and check-out the next branch to get files that are identical to the ones the instructor is using. Here are the steps:

Open a Bash (or other shell) window.
(Optional) Navigate to a convenient directory.
Use the following commands to fetch the project and list the branches:

BASH

$ git clone https://gitlab.com/fraserphysics/zipf work_dir
$ cd work_dir
$ git branch -a

The result of the last command should be something like

OUTPUT

* 06-documentation
  remotes/origin/01-command-line
  remotes/origin/02-first-makefile
  remotes/origin/03-no-hands
  remotes/origin/04-testing
  remotes/origin/05-standards
  remotes/origin/06-documentation
  remotes/origin/HEAD -> origin/06-documentation

Minimum Software

You will need to have the following software installed on your computer to follow the first episodes of this tutorial:

Make (at least version 4.3): We use Gnu Make to specify the whole sequence of operations from raw data to a pdf document. While other versions of make may work well enough, we occasionally use features that only the Gnu version of make provides. In particular, we use the ability to specify more than one target in a single rule that Gnu Make provides in versions 4.3 and later.
Python: We use Python for calculations, and we segregate all plotting into scripts that use Matplotlib.
Git: We will use git branches to keep episodes using various tools separate.
LaTeX: The tutorial uses LaTeX for formatting.
Bash: Even if you use another shell at the command line, bash should be available because our makefiles invoke it.
Sed: Sed is a command line stream editor that we use to extract documentation from makefiles in response to “make help”.
AWK: We use awk for extracting specific columns from data files.

The following commands exercise this minimal set of software tools:

BASH

$ git checkout 04-testing
$ make help

should yield

OUTPUT

 help                 : Holy mackerel!  What is this?

and

$ make

should yield several screens of output ending with

Latexmk: All targets (build/report.pdf) are up-to-date

More Software

The later episodes use the following additional tools:

yapf: We use (Yet Another Python Formatter) to coerce code to follow Google’s Python style.
mypy: Mypy is a static type checker for Python.
pylint: Analyzes and scores python code against a user defined style guide, pylintrc.
sphinx: We use Sphinx to format documentation. We use the autodoc extension that imports the modules we are documenting. It pulls in documentation from docstrings in a semi-automatic way.
pytest: We use pytest to write small, readable tests.
coverage: We use coverage to find out what lines of code get run by the set of unit tests.
pdb: pdb is Python’s built-in interactive source code debugger.

You can verify that these tools are installed with the following commands

BASH

$ yapf --version
$ mypy --version
$ pylint --version
$ sphinx-build --version
$ pytest --version
$ python -m pdb --help