Daniel Wolffram, Johannes Bracher

• code/ — Python project (primary codebase)
  • src/ — reusable Python modules
  • *.ipynb — Jupyter notebooks for tuning, training, evaluation, and plotting
  • pyproject.toml, uv.lock — Python environment
• r/ — R project (separate renv environment)
  • hhh4/, tscount/, persistence/ — model-specific scripts
  • nowcasting/ — nowcast computation
  • illustrations/ — visualizations
  • renv.lock, .Rprofile — R environment
• data/ — input datasets
• figures/ — generated plots
• forecasts/ — generated forecasts
• nowcasts/ — generated nowcasts
• results/ — generated results
  • scores/ — evaluation metrics
  • tuning/ — hyperparameter tuning results

Python code lives in code/. R code lives in r/, with its own environment. Shared inputs and outputs (data/, forecasts/, nowcasts/, figures/, results/) live at the repo root and are accessible from both Python and R.

The project uses uv to manage the Python environment.
Install uv on your system as follows:

• Linux / macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows:

irm https://astral.sh/uv/install.ps1 | iex

(In case of problems, please refer to the official installation guide.)

Once uv is installed, set up the environment from the repository root:

uv sync

This will create a local .venv/ and install all dependencies specified in pyproject.toml and uv.lock. It will also automatically install the required Python version if it is not already available on your system.

To run the notebooks with this environment, you must first register it as a Jupyter kernel:

uv run -m ipykernel install --user --name=replication-sari

For interactive use, you can start JupyterLab inside the managed environment:

uv run jupyter lab

This provides a browser-based interface, useful if you don't have a preferred IDE installed. After launching, select the kernel replication-sari when opening notebooks.

To ensure reproducibility, please use R 4.5.1. Dependencies are managed with renv. From the r/ folder, restore the environment with:

R -e "install.packages('renv'); renv::restore()"

This will restore all R package dependencies as specified in renv.lock. 
⚠️ Unlike uv, renv does not install R itself — you must install R 4.5.1 manually.

Note: The repository includes .Rprofile files (at both the root and in r/) that automatically activate the correct renv environment and anchor the here package to the repository root. This ensures that paths like here("data", ...) always work consistently, whether you open the whole repo or just the R subproject.

The repository contains a helper script run_pipeline.py that orchestrates the execution of all notebooks and R scripts in a defined order. This ensures reproducibility of results and allows running the full pipeline or just selected parts of it.
(If preferred, you can also open and run the individual notebooks or R scripts manually.)

The pipeline runs through the following stages:

The pipeline can be executed with different options from the repository root.
(We use uv run instead of python to ensure the script is executed inside the correct environment managed by uv.)

• Run the entire pipeline

  uv run run_pipeline.py

• Run a single stage

  uv run run_pipeline.py --stage evaluation

• Run a contiguous range of stages

  uv run run_pipeline.py --start forecasts --end scores

• Run everything except selected stages

  uv run run_pipeline.py --skip tuning

⚠️ Note: The tuning stage can take a very long time (several days). If you do not want to run it, use --skip tuning

When running the pipeline, make sure that the Rscript command points to the correct R version (4.5.1).
On some systems, the default Rscript may refer to an older version of R.

You can check this with:

Rscript --version