User Guide

The Euromod Conector is a Python library providing tools for running simulations and interacting with the tax-benefit microsimulation model EUROMOD.

Installation

The Euromod Connector can be installed from PyPi using pip:

$ pip install euromod

Requirements

In order to run the model, we require two components: 1) the model (coded policy rules), and 2) the input microdata with the variables that respect the EUROMOD naming conventions. For more information, please, read the sections “Model” and “Input microdata” on the Download Euromod web page.

Running and navigating the model

The euromod package is object oriented and evolves around using the Model class that loads a representation of the EUROMOD model. This can be imported as follows:

from euromod import Model

Create an object of the Model class by passing the path to the EUROMOD project:

mod=Model(r"C:\EUROMOD_RELEASES_I6.0+")
mod

------------------------------
Model
------------------------------
	 countries: 28 elements
	 extensions: 11 elements
	 model_path: 'C:\\EUROMOD_RELEASES_I6.0+'

Note that every object that is related to the EUROMOD project comes with an informative description. Here we can see that the model has 3 relevant attributes to the user:

  • countries

  • extensions

  • model_path

The countries and extensions attributes contain elements of the respective objects. If we take a look at countries:

mod.countries

0: AT 
1: BE 
2: BG 
3: CY 
4: CZ 
5: DE 
6: DK 
7: EE 
8: EL 
9: ES 
10: FI
11: FR
12: HR
13: HU
14: IE
15: IT
16: LT
17: LU
18: LV
19: MT
20: NL
21: PL
22: PT
23: RO
24: SE
25: SI
26: SK
27: SL

The countries attirbute is a container storing the Country objects nesting the country-specific tax-benefit policies and systems. We see indeed that the euromod model contains 28 countries.

Note

The elements in an attribute of type Container can be accessed by indexing the attribute with the element position.

In a similar fashion we can look what kind of extensions are stored in the model.

Tip

The countries container can be indexed by both the number of the element and the country shortcode.

Let us take a look at Sweden:

mod.countries["SE"]

------------------------------
Country
------------------------------
	 datasets: 27 elements
	 extensions: 12 elements
	 local_extensions: COVID
	 name: 'SE'
	 policies: 26 elements
	 systems: 18 elements

Here we see again an informative representation of the Country object, which contains several attributes that can be accessed. In order to simulate a system we run a specific System object. We can obtain the systems for Sweden as follows:

mod.countries["SE"].systems

0: SE_2006 
1: SE_2007 
2: SE_2008 
3: SE_2009 
4: SE_2010 
5: SE_2011 
6: SE_2012 
7: SE_2013 
8: SE_2014 
9: SE_2015 
10: SE_2016
11: SE_2017
12: SE_2018
13: SE_2019
14: SE_2020
15: SE_2021
16: SE_2022
17: SE_2023

Tip

The systems container can be indexed by both the number of the element and the system name.

Running a simulation

In order to run the tax system we need a dataset that fits the requirement to use.

See also

See Other important euromod objects on what datasets are configured and how.

If you know already which dataset to use you can simply load the data and run the model as follows:

import pandas as pd
data=pd.read_csv(r"C:\EUROMOD_RELEASES_I6.0+\Input\SE_2021_b1.txt",sep="\t")
out_baseline = mod.countries["SE"].systems["SE_2021"].run(data,"SE_2021_b1")
out_baseline

Simulation for system SE_2021 with dataset SE_2021_b1 finished.

------------------------------
Simulation
------------------------------
	 constantsToOverwrite: {}
	 errors: []
	 output_filenames: ['se_2021_std.txt']
	 outputs: Pandas DataFrame of 240 variables and 21671 observations.

Note that the run function here takes the mandatory argument dataset_id, which in our case is SE_2021_b1. This is necessary such that EUROMOD can apply the dataset specific logic with respect to setting default values and uprating. This returned us a Simulation object with multiple attributes. The one of interest here is outputs, which contains the outputdataset(s) returned by the microsimulation model:

out_baseline.outputs[0]
idhh idperson idmother ... tu_bho_se_IsDependentChild tu_bho_se_IsLoneParent tu_bho_se_IsPartner
0 200.0 20001.0 0.0 ... 0.0 0.0 0.0
1 300.0 30001.0 0.0 ... 0.0 0.0 0.0
2 300.0 30002.0 0.0 ... 0.0 0.0 1.0
3 500.0 50001.0 0.0 ... 0.0 0.0 0.0
4 500.0 50002.0 0.0 ... 0.0 0.0 1.0
... ... ... ... ... ... ... ...
21666 1936500.0 193650002.0 0.0 ... 0.0 0.0 1.0
21667 1936800.0 193680001.0 0.0 ... 0.0 0.0 1.0
21668 1936800.0 193680002.0 0.0 ... 0.0 0.0 0.0
21669 1936800.0 193680003.0 193680002.0 ... 1.0 0.0 0.0
21670 1936800.0 193680004.0 193680002.0 ... 1.0 0.0 0.0

21671 rows × 240 columns