Directory Structure

The big picture¶

The following graph shows the contents of template_project root directory after executing pytask

Color legend:

• Blue — Source code written by the researcher

• Yellow — Build outputs generated by pytask

• Green — Project root and document container directories

• Orange — Intermediate outputs (generated files that serve as inputs to document compilation)

The separation of inputs and outputs (one of our guiding principles) is visible at a glance:

• Source code (blue) in src/ and tests/ is written by the researcher

• Computational outputs (yellow) are generated into bld/ by the analysis pipeline

• Document outputs (yellow) are generated into _build/ by the document compilation

• Intermediate outputs (orange) in documents/public/ and documents/tables/ are figures and tables generated by the analysis pipeline that serve as inputs to document compilation

The figures and tables live inside documents/ rather than bld/ because document tools (MyST and Slidev) expect assets to be near the source files. The public/ directory name is required by Slidev for static assets.

Viewing papers and presentations¶

The paper is built in both PDF and HTML formats. Use these commands to view outputs interactively with live reload:

pixi run view-paper   # View paper in browser (HTML with live reload)
pixi run view-pres    # View presentation in browser (Slidev with live reload)

For the project documentation (this site), use:

pixi run -e docs view-docs

The contents of src/template_project/ follow the steps of the analysis workflow, with subdirectories for data management, analysis, and final output generation.

All outputs from these steps are placed in the bld/ directory, organized by type:

• Data processing outputs go to bld/data/

• Model outputs go to bld/estimation_results/

• Prediction outputs go to bld/predictions/

• Final figures go to documents/public/

• Final tables go to documents/tables/

Document build outputs (HTML site and PDF exports) go to _build/ at the project root.

Documents directory structure¶

The documents/ directory contains the source files for papers and presentations:

• paper.md: The main paper written in MyST Markdown, compiled to PDF and HTML using Jupyter Book 2.0

• presentation.md: The presentation written in Slidev Markdown format

• refs.bib: Bibliography file in BibTeX format

• style.css: Custom CSS styling for the presentation

• public/: Generated figure files (PNG) referenced by both the paper and presentation. Slidev requires this directory name for static assets.

• tables/: Generated table files (Markdown) included in MyST documents via the {include} directive

The configuration file myst.yml lives in the project root (not inside documents/) because Jupyter Book 2.0 expects it at the working directory where jupyter book build is run. This file defines project metadata, bibliography settings, and PDF export options.

The tasks in src/template_project/final/task_final_template.py generate figures and tables into documents/public/ and documents/tables/ respectively. These are then included in the paper and presentation using MyST Markdown directives (e.g., {figure} and {include}).

Zooming in¶

Lets go one step deeper and consider the root/src directory in more detail:

It is imperative that you do all the task handling inside the task_xxx.py-scripts, using the pathlib library. This ensures that your project can be used on different machines and it minimises the potential for cross-platform errors.

For running Python source code from pytask, simply include pathlib.Paths to the dependencies and similar path(s) for the special keyword produces as the default arguments to your function.

For running scripts in other languages, pass all required files (inputs, log files, outputs) as arguments to the @pytask.mark.[x]-decorator. You can then read them in. Check the sections on different programming languages for examples.