Quick Start¶

Prerequisites¶

Python 3.11+
Git
uv
make (optional but recommended — see Installing Make below)

Installation¶

Bash

git clone https://github.com/setupelz/fair-shares.git
cd fair-shares
uv sync

Verify:

Bash

uv run pytest tests/unit

Anaconda / Conda¶

If you use Anaconda or Miniconda, skip the uv prerequisite. Use conda to create the environment and pip to install:

Bash

conda create -n fair-shares python=3.11
conda activate fair-shares
pip install -e .

Verify:

Bash

pytest tests/unit

Sync notebooks (replaces make sync-ipynb, which requires uv):

Bash

jupytext --sync notebooks/*.py
jupytext --set-formats ipynb,py:percent notebooks/*.py

Then launch JupyterLab:

Bash

jupyter lab

Note

make targets that call uv (e.g. make sync-ipynb, make test) will not work in a conda environment. Use the equivalent commands shown above instead.

Notebook Format¶

This project uses jupytext to store notebooks as plain Python files (.py) in the py:percent format. This means:

.py files are the source format — version-controlled, clean diffs, easy to edit in any IDE
.ipynb files are generated from the .py files — used for interactive execution in JupyterLab

After cloning (or pulling new changes), sync the .ipynb files:

Bash

make sync-ipynb

Without make

Bash

uv run jupytext --sync notebooks/*.py
uv run jupytext --set-formats ipynb,py:percent notebooks/*.py

Tip

You don't need .ipynb files — you can run the .py files directly with uv run python notebooks/301_custom_fair_share_allocation.py. The .ipynb format is only needed if you want the interactive JupyterLab experience.

Running Notebooks¶

Bash

uv run jupyter lab

Workflow	Notebook
country-fair-shares	`notebooks/301_custom_fair_share_allocation.ipynb`
iamc-regional-fair-shares	`notebooks/401_custom_iamc_allocation.ipynb`

See User Guide for detailed workflow documentation.

Installing Make¶

make is a standard build tool used to run project commands conveniently. It is optional — every make target has an equivalent uv command shown in the Makefile.

macOSLinux (Debian/Ubuntu)Linux (Fedora/RHEL)Windows

Already installed with Xcode Command Line Tools:

Bash

xcode-select --install

Bash

sudo apt install make

Bash

sudo dnf install make

Install via Chocolatey:

PowerShell

choco install make

Or via winget:

PowerShell

winget install GnuWin32.Make