Build a reproducible thesis template: writing, code, data, and build.
- User
Build a reproducible thesis template: writing, code, data, and build.
Assistant
The user wants a "reproducible thesis template" that covers four main aspects:
- Writing: The actual text of the thesis (likely LaTeX or Markdown).
- Code: The scripts used for analysis/visualization.
- Data: The raw and processed data.
- Build: The system that knits everything together into a final PDF/document.
The goal is to create a template structure and configuration that ensures anyone (or the user themselves, years later) can run a single command and regenerate the entire thesis exactly as it was.
Core Technologies:
- Writing: LaTeX is the standard for thesis work due to its typographic quality and citation management. Markdown (via Pandoc) is a modern alternative, but LaTeX offers more robust control for complex academic documents (like the University of Oxford/Harvard thesis templates). I should stick to LaTeX for the main document but maybe mention Quarto/Pandoc as an alternative. Actually, a Makefile or Snakemake or Python script can handle the build.
- Code: Python (Jupyter/Scripts) or R. A template should probably be language-agnostic but provide examples. Let's use Python as a safe default but structure it so it's easy to swap.
- Data: Needs a clear folder structure. Raw vs. Processed.
- Build: This is the crucial part.
- Old school: A
Makefile. Very standard, very robust. - New school: Docker/Singularity. This ensures the environment (libraries, OS) is reproducible, not just the code. This is essential for "true" reproducibility.
- Python specific:
pyproject.toml/requirements.txt.
- Old school: A
- Version Control: Git is non-negotiable.
Proposed Structure:
-
Root Directory:
thesis.tex(Main file)Makefile(The build engine)README.md(Instructions).gitignoreDockerfile(For environment reproducibility)
-
Subdirectories:
src/orchapters/: The LaTeX files for content.code/: Python/R scripts.data/:raw/: Immutable original data.processed/: Output from scripts.
output/orfigures/: Generated plots.bib/: Bibliography.
Detailed Implementation Steps:
-
The "Build" System (Makefile):
- Needs to run the code (e.g.,
python code/analysis.py). - The code reads
data/raw, outputsdata/processedandfigures/. - Then the Makefile runs
latexmkto compile the PDF, including the generated figures. - This creates a dependency chain:
Raw Data->Code->Figures/Proc Data->LaTeX->PDF.
- Needs to run the code (e.g.,
-
The Environment (Docker):
- A
Dockerfileis necessary to lock down TexLive version and Python packages. Without this, "reproducible" is a lie 3 years later.
- A
-
The LaTeX Template:
- Keep it simple but standard.
reportorbookclass. Include standard packages (inputenc, biblatex, graphicx).
- Keep it simple but standard.
-
The Code Template:
- A simple Python script that demonstrates reading CSV, doing a math operation, and saving a plot.
Drafting the Content:
- Intro: Explain the philosophy (Data -> Code -> Figure -> Text -> PDF).
- File Tree: Visual representation.
- Step 1: Directory Structure: Create folders.
- Step 2: The Environment (Docker): Provide a Dockerfile. This is the "hardcore" part but necessary for the prompt.
- Step 3: The Build Script (Makefile): The logic.
- Step 4: The Code (Python): An example analysis.
- Step 5: The Writing (LaTeX): The skeleton.
- Step 6: Instructions: How to run it.
Refinement:
- Is Docker too complex for a starter template? Maybe. But "reproducible" implies it works 5 years from now. Docker is the answer. I will provide the Docker route as the primary solution but mention that it works locally without Docker if the user has the dependencies installed.
- LaTeX vs. Quarto: Quarto is gaining ground. However, traditional PhDs often require strict LaTeX formatting provided by universities. I will stick to LaTeX because it's the "lingua franca" of academic theses, but I'll make the Makefile flexible enough to theoretically swap for Pandoc if desired.
- Crucial detail: Git LFS. Data files are often big. I should mention
.gitignorefor data or Git LFS.
Let's assemble the response. I'll provide a complete, copy-pasteable project structure.
-
Project Name:
my-thesis -
Files:
MakefileDockerfilerequirements.txtthesis.texcode/analysis.pydata/raw/data.csv(dummy)bib/references.bib
-
Makefile logic:
- Target
all: runs code, then builds pdf. - Target
code: runs python. - Target
pdf: runs latexmk. - Target
clean: removes auxiliary files.
- Target
This looks solid. It covers all four requested aspects.
One final check on LaTeX: Use
\inputmintedor similar for code inclusion? Or just standard\lstlisting? Standard is safer. I will ensure the LaTeX document actually includes the generated figure to prove the pipeline works.Let's write it out. To build a truly reproducible thesis, you need an architecture that treats code, data, and text as interconnected components. If the data changes, the figures update; if the code changes, the output updates.
Here is a complete, executable file structure and configuration for a Reproducible Thesis Template.
This solution uses:
- LaTeX for typesetting (the gold standard for academia).
- Python for analysis and visualization.
- Make to orchestrate the build (the "glue" that forces code to run before PDF compilation).
- Docker (Optional but recommended) to ensure the environment (Python libraries, LaTeX distribution) is identical 5 years from now.
1. The Directory Structure
Create a folder named
thesis_templateand arrange it like this:thesis_template/ ├── Makefile # The build system orchestrator ├── Dockerfile # Environment specification (OS + Libs) ├── requirements.txt # Python dependencies ├── output/ # Generated content (Gitignored) │ ├── figures/ │ └── tables/ ├── data/ │ ├── raw/ # Immutable original data │ └── processed/ # Cleaned data generated by scripts ├── code/ │ ├── config.py # Shared settings (paths, colors) │ ├── 01_process.py # Script to clean data │ └── 02_analyze.py # Script to generate figures ├── chapters/ │ ├── introduction.tex │ └── results.tex # Inputs the generated figures ├── bib/ │ └── references.bib └── main.tex # The root LaTeX file
2. The Environment (
Dockerfile&requirements.txt)This ensures your thesis compiles exactly the same way on your supervisor's machine as it does on yours.
Dockerfile# Use a lightweight TeX distribution + Python image FROM python:3.11-slim # Install LaTeX and Make RUN apt-get update && apt-get install -y \ texlive-latex-recommended \ texlive-latex-extra \ texlive-fonts-recommended \ latexmk \ make \ && rm -rf /var/lib/apt/lists/* # Set working directory WORKDIR /thesis # Install Python dependencies COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txtrequirements.txtpandas matplotlib numpy seaborn
3. The Build System (
Makefile)This is the engine of reproducibility. Instead of compiling LaTeX directly, you run
make. It ensures your Python scripts run before the PDF is built.Makefile.PHONY: all clean figures data thesis # Default target: Build everything all: thesis # 1. Process Data (Code -> Data) data: code/01_process.py python code/01_process.py # 2. Generate Figures (Data + Code -> Figures) # Depends on 'data' step being finished figures: data code/02_analyze.py python code/02_analyze.py # 3. Build Thesis (Figures + LaTeX -> PDF) # Depends on 'figures' step being finished thesis: figures latexmk -pdf -interaction=nonstopmode main.tex # Cleanup auxiliary files clean: latexmk -c rm -rf output/figures/*.pdf rm -rf output/tables/*.tex # Nuclear option: clean everything scrub: clean rm -f main.pdf
4. The Code Layer (
code/)We separate configuration from logic to keep things clean.
code/config.pyimport os # Define paths relative to project root # This makes the script runnable from any directory ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) PATHS = { 'raw_data': os.path.join(ROOT, 'data', 'raw'), 'proc_data': os.path.join(ROOT, 'data', 'processed'), 'output': os.path.join(ROOT, 'output'), 'figures': os.path.join(ROOT, 'output', 'figures') } # Ensure output directories exist for p in PATHS.values(): os.makedirs(p, exist_ok=True)code/01_process.pyimport pandas as pd import config # 1. Load raw data (Dummy data for demonstration) print("Processing data...") raw = pd.DataFrame({ 'x': range(1, 11), 'y': [i**2 + (i*0.5) for i in range(1, 11)] }) # 2. Save processed data raw.to_csv(f"{config.PATHS['proc_data']}/clean_data.csv", index=False) print("Data processed.")code/02_analyze.pyimport pandas as pd import matplotlib.pyplot as plt import config print("Generating figures...") # 1. Load processed data df = pd.read_csv(f"{config.PATHS['proc_data']}/clean_data.csv") # 2. Plot fig, ax = plt.subplots(figsize=(4, 3)) ax.plot(df['x'], df['y'], marker='o', linestyle='-', color='navy') ax.set_xlabel('Independent Variable') ax.set_ylabel('Dependent Variable') ax.set_title('Reproducible Plot') ax.grid(True, alpha=0.3) # 3. Save to output/figures plt.tight_layout() plt.savefig(f"{config.PATHS['figures']}/result_plot.pdf") print("Figures saved.")
5. The Writing Layer (
main.tex&chapters/)In LaTeX, we point to the output files generated by Python. We use
\input{}to keep the main file clean.main.tex\documentclass[12pt]{report} \usepackage{graphicx} \usepackage{lipsum} % For dummy text \usepackage[backend=biber, style=authoryear]{biblatex} \addbibresource{bib/references.bib} % Define paths for graphics (so we don't have to type 'output/figures/' every time) \graphicspath{{output/figures/}} \title{A Reproducible Thesis Template} \author{Graduate Student} \begin{document} \maketitle \input{chapters/introduction} \input{chapters/results} \printbibliography \end{document}chapters/results.tex\chapter{Results} Here is a plot generated automatically by the Python script. Note that if the data in \texttt{data/raw} changes, this figure updates automatically when you run \texttt{make}. \begin{figure}[h] \centering % We reference the file generated by code/02_analyze.py \includegraphics[width=0.8\textwidth]{result_plot.pdf} \caption{The relationship between X and Y.} \label{fig:results} \end{figure} As seen in Figure \ref{fig:results}, the trend is quadratic.
6. How to Run It
You have two options: using Docker (fully reproducible) or running locally (easier setup).
Option A: The "Hardened" Way (Docker)
This guarantees the build works in 2030.
- Build the container:
docker build -t my-thesis . - Run the build:
# Mount current directory to /thesis and run make docker run -v $(pwd):/thesis my-thesis make
Option B: The Local Way
Requires you to have
pdflatexandpythoninstalled locally.- Install Python libs:
pip install -r requirements.txt - Build the thesis:
make
Summary of Workflow
- You write your analysis logic in
code/. - You write your text in
chapters/. - You run
make.makedetects dependencies.- It runs Python scripts.
- Python saves figures to
output/. makeruns LaTeX.- LaTeX grabs the fresh figures from
output/. - A PDF is born.
If you change a number in your raw data, simply run
makeagain, and the PDF will update with the new graph automatically.