Getting Started

This page gets you from installation to your first simulation in a few minutes. It is deliberately short; for a thorough tour of the model and all run options, see the User Guide, and for task-oriented recipes see the Examples.

The euromod package is a thin, object-oriented Python layer over the EUROMOD tax-benefit microsimulation model. It lets you load a model, inspect its policies, run simulations on microdata, and read the results back as pandas DataFrames.

Installation

pip install euromod

Requirements

To run a simulation you need two things, both distributed by the JRC:

  1. A EUROMOD model — the coded policy rules (the folder containing XMLParam).

  2. Input microdata — variables that follow the EUROMOD naming conventions.

Every public EUROMOD release ships with freely distributable training datasets (<CC>_training_data.txt, e.g. AT_training_data.txt) in its Input folder. These docs use that training data so every example is reproducible without access to confidential microdata. See the Download EUROMOD page.

1. Load a model

First tell Python where your EUROMOD installation lives by editing MODEL_PATH below, then create a Model object.

import os
import pandas as pd
from euromod import Model

# --- Point these to your local EUROMOD installation -------------------------
# MODEL_PATH : a EUROMOD model/release folder (the one that contains 'XMLParam').
# DATA_DIR   : folder with the input microdata (.txt). In a public release this
#              is the model's own 'Input' folder, which ships with the freely
#              distributable *training* datasets used throughout these docs.
MODEL_PATH = r"C:\EUROMOD\EUROMOD_RELEASE"
DATA_DIR   = os.path.join(MODEL_PATH, "Input")

# keep DataFrame previews compact in the rendered docs
pd.set_option("display.max_rows", 8, "display.max_columns", 8)

Using EUROMOD as defined in C:\EUROMOD\Executable

mod = Model(MODEL_PATH)
mod

------------------------------
Model
------------------------------
	 countries: 28 elements
	 extensions: 17 elements
	 model_path: 'C:\\EUROMOD\\EUROMOD_RELEASE'

Notice that every EUROMOD object prints an informative summary of itself. The Model exposes its countries and extensions.

3. Run a simulation

Pick a system, load the matching training data, and call run(). The only mandatory arguments are the input data (a pandas.DataFrame) and the dataset_id, which tells EUROMOD which dataset-specific rules (uprating, default values) to apply.

data = pd.read_csv(os.path.join(DATA_DIR, "AT_training_data.txt"), sep="\t")
sim = mod.countries["AT"].systems["AT_2025"].run(data, "AT_training_data")
sim

Simulation for system AT_2025 with dataset AT_training_data finished.

------------------------------
Simulation
------------------------------
	 constantsToOverwrite: {}
	 errors: []
	 output_filenames: ['at_2025_std.txt']
	 outputs: Pandas DataFrame of 727 variables and 7482 observations.

run() returns a Simulation object. Its outputs attribute holds the result dataset(s) as pandas DataFrames.

sim.outputs[0]
idhh idperson idmother idfather ... tu_bch00_at_IsDependentChild tu_bcc_at_HeadID tu_bcc_at_IsDependentChild tu_bcc_at_IsPartner
0 1.0 101.0 0.0 0.0 ... 0.0 101.0 0.0 0.0
1 2.0 201.0 0.0 0.0 ... 0.0 201.0 0.0 0.0
2 3.0 301.0 0.0 0.0 ... 0.0 301.0 0.0 0.0
3 4.0 401.0 0.0 0.0 ... 0.0 401.0 0.0 0.0
... ... ... ... ... ... ... ... ... ...
7478 2397.0 239701.0 0.0 0.0 ... 0.0 239701.0 0.0 0.0
7479 2397.0 239702.0 239701.0 0.0 ... 1.0 239702.0 0.0 0.0
7480 2397.0 239703.0 239701.0 0.0 ... 1.0 239703.0 0.0 0.0
7481 2397.0 239704.0 239701.0 0.0 ... 1.0 239704.0 0.0 0.0

7482 rows × 727 columns

That’s it — you have simulated household incomes under the Austrian 2025 system.

Where to go next

  • User Guide — the object model, the policy spine, datasets and best matches, running options, and how to build counterfactual reforms (policy switches, constants, add-ons, extensions).

  • Examples — short, copy-pasteable recipes for the most common tasks.

  • API Reference — the full list of classes and methods.