How igf-psd/bozio_wasmer_simulations works
Project type and purpose
• This is a Python simulation library (bozio_wasmer_simulations) designed to quantify employer‐contribution reforms from the “Bozio-Wasmer” report.
• It includes empirical and theoretical simulators, data loaders, parameter files, scripts for batch runs, Jupyter notebooks for analysis, and MkDocs‐based documentation.
File structure
• Top‐level folders:
• bozio_wasmer_simulations/ ← Core Python package
– datasets/ ← Data‐loading modules (base classes & XLS loaders)
– description/ ← DescriptionBuilder abstractions
– simulation/ ← Two subpackages: empirical/ & theoretical/
– utils/ ← Shared utilities (passage, misc helpers)
• data/ ← Raw XLS files (ZRR, ZRD, distributions)
• parameters/ ← JSON files for default simulation parameters
• scripts/ ← simulate.py entry point (reads config.yaml)
• notebooks/ ← Example analysis notebooks
• outputs/ & logs/ ← Results and logging outputs
• docs/ ← MkDocs source (API and conceptual docs)
• config.yaml ← Scenario definitions for scripts
• pyproject.toml, requirements.txt, mkdocs.yml
Extract insights from README
• Two simulation modes: empirical (budget & employment effects) and theoretical (wage‐increase incentives, PPV impact).
• Typical usage: instantiate a simulator class (e.g., CaptationMarginaleSimulator), call simulate_reform(...) with parameters and receive a DataFrame.
• Scripts orchestrate multiple reforms defined in config.yaml.
• Documentation generated via MkDocs.
Main components & relationships (
a. Data Inputs
• Raw data folder (Excel files)
• parameters/*.json
• config.yaml
b. Core Package (“bozio_wasmer_simulations”)
1. datasets loaders ← read raw data + parameters
2. description builder ← assemble metadata & scenario descriptions
3. simulation engines
• empirical simulator pipeline: preprocessing → weighting → reform application
• theoretical simulator pipeline: marginal capture rates (ppv, taux…)
4. utils ← shared functions (data passage, general helpers)
c. Orchestration & I/O
• scripts/simulate.py ← reads config.yaml, instantiates simulators, writes outputs to outputs/ & logs/
• notebooks ← consume core package APIs for ad‐hoc analysis
d. Documentation
• docs/ (MkDocs) ← auto‐generated API docs & conceptual pages
Data Inputs → Dataset Loaders → Description Builder → Simulation Engines → Outputs/Logs
Scripts orchestrate the pipeline; Notebooks and user code call the same API.
Architectural patterns & principles
• Modular package with clear separation: data‐ingestion, description, simulation logic, utilities.
• Single Responsibility: each subpackage addresses one concern.
• Plugin‐style extensibility: new simulation types can be added under simulation/.
• Configuration‐driven runs: script driven by config.yaml to run multiple scenarios in batch.