normschores

Code for the NormsChores project: a structural household model of gender norms and the division of market work, chores and leisure, with simulated-minimum-distance estimation tools.

The Python package lives in src/normschores/:

Requirements

Windows only. The model is solved in C++ which is compiled on first use with Microsoft Visual Studio (2019/2022 Community is found automatically; for other editions set COMPILER_PATH in the notebooks, or pass ChormsClass(..., compiler_path="<VS>/VC/Auxiliary/Build/")). The compiled model_cpp.dll is written to the current working directory. Python 3.12 or newer.

Running the notebooks from the published package

Create a fresh virtual environment, install the package with the notebooks extra (adds ipykernel and papermill) and copy the model code and notebooks to a working folder with normschores-copy.

The notebooks import the model code from the folder above them (from Chorms import *, from estimate.moments import ..., import exhibits), not from the installed normschores. A copy is therefore self-contained: edits to its Chorms.py, estimate/, exhibits.py and cppfuncs/*.cpp are what its notebooks use. The notebooks write their results (saved/, output/figures/, output/tables/, model_cpp.dll) into the copy's notebooks/ folder.

With uv:

uv venv --python 3.12 .venv
.venv\Scripts\activate
uv pip install "normschores[notebooks]"
normschores-copy my_run      # copies the code and notebooks to .\my_run

or with plain pip:

py -3.12 -m venv .venv
.venv\Scripts\activate
pip install "normschores[notebooks]"
normschores-copy my_run

Then open the notebooks in my_run\notebooks with .venv\Scripts\python.exe as the kernel (in VS Code: Select Kernel → Python Environments; for a browser, also pip install jupyterlab) and run _ Run all notebooks.ipynb, or the notebooks one at a time in numbered order. normschores-copy refuses to write into a folder that is not empty unless --force is given.

The copy also contains requirements.txt (the exact versions of all dependencies the package was released with, incl. the notebook tools) and environment.yml. They can be used instead of pip install "normschores[notebooks]" to set up an environment for the copy that does not depend on the installed package, e.g. on another machine:

cd my_run
pip install -r requirements.txt        # or: conda env create -f environment.yml

After editing C++ files, set DO_COMPILE = True (and restart the kernel) so model_cpp.dll is rebuilt; otherwise an existing dll in the notebook folder is reused. Python edits are picked up by the notebooks' %autoreload, or after a kernel restart.

The model can also be used directly:

from normschores import ChormsClass

model = ChormsClass(name="baseline")
model.link_to_cpp()   # compiles cppfuncs/model_cpp.cpp shipped with the package

Development setup (repository)

In the repository the notebooks are edited and run in place in src/normschores/notebooks/. Their results (saved/, output/) are kept next to them but are not included in the built package. The paper reads the figures and tables from there (\codefigs/\codetabs in _main.tex).

Move to the code directory and run:

Option A — uv

uv sync

This creates .venv, installs normschores in editable mode (so changes in src/ are picked up directly) and the notebook tools (ipykernel, papermill) from the dev dependency group.

Activate the environment:

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

For Jupyter notebooks in VS Code, the kernel is located at .venv\Scripts\python.exe.

Option B — pip + venv

python -m venv .venv

# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r src/normschores/requirements.txt   # pinned dependencies
pip install -e . --no-deps                        # normschores itself, in editable mode

Option C — Anaconda / conda

conda env create -f src/normschores/environment.yml
conda activate normschores
pip install -e . --no-deps                        # normschores itself, in editable mode

Releasing

Builds use uv (uv build, with the uv_build backend). Publishing is done by the GitHub Actions workflow .github/workflows/publish.yml (in the repository root).

To publish a new version to PyPI:

uv version --bump patch      # or minor / major; updates pyproject.toml and uv.lock
git commit -am "Release v$(uv version --short)"
git tag "v$(uv version --short)"
git push && git push --tags

Pushing a v* tag runs the workflow, which builds the package and uploads it to PyPI with trusted publishing (no API token stored in GitHub).

One-time setup on PyPI: under Your projects → Publishing add a pending trusted publisher with owner ThomasHJorgensen, repository NormsChores, workflow publish.yml and environment pypi. Also create an environment named pypi in the GitHub repository settings.

Appendix: Maintaining dependency files

Updating requirements.txt

requirements.txt and environment.yml live inside the package (src/normschores/), so they are shipped with it and copied by normschores-copy. requirements.txt is generated by uv from pyproject.toml. After adding or upgrading packages in pyproject.toml, regenerate it with:

uv lock
uv export --no-hashes --no-emit-project -o src/normschores/requirements.txt

--no-emit-project leaves out the package itself (-e .), so the file also works in a copied folder, where the notebooks use the code next to them.