collapse all

User Guide

The Euromod Conector is a Matlab toolbox providing tools for running simulations and interacting with the tax-benefit microsimulation model 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.

The euromod toolbox is object oriented and evolves around using the Model class that loads a representation of the EUROMOD model. Create an object of the Model class by passing the path to the EUROMOD project: 

mod = euromod("C:\EUROMOD_RELEASES_I6.0+");
mod     
1×1 Model with properties:
     
  extensions: [11×1 Extension]
   countries: [28×1 Country]
   modelpath: "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
  • modelpath

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

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

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

Note that the properties in a class array can be accessed by indexing the property with the element position, by the property name or by the ID.

Let us take have a look at Sweden: 

mod.countries("SE")  
1×1 Country with properties:
     
        datasets: [27×1 Dataset]
      extensions: [12×1 Extension]
local_extensions: COVID
            name: "SE"
          parent: [1×1 Model]
        policies: [26×1 Policy]
         systems: [18×1 System]

Here we see again an informative representation of the Country object, which contains several properties 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.SE.systems     
18×1 System array:
     
      1: SE_2006
      2: SE_2007
      3: SE_2008
      4: SE_2009
      5: SE_2010
      6: SE_2011
      7: SE_2012
      8: SE_2013
      9: SE_2014
     10: SE_2015
     11: SE_2016
     12: SE_2017
     13: SE_2018
     14: SE_2019
     15: SE_2020
     16: SE_2021
     17: SE_2022
     18: SE_2023

Running a simulation

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

See the section 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: 

data = readtable("SE_2021_b1.txt");
out_baseline=mod.("SE").("SE_2021").run(data,"SE_2021_b1");
out_baseline 
1×1 Simulation with properties:
     
           outputs: {[21671×240 table]}
          settings: [1×1 struct]
  output_filenames: "se_2021_std"
            errors: [0×1 string]
 
 output 1 : [21671x240 table]
    idhh   idperson   idmother   idfather   idpartner   idorighh   idorigperson   dag   dgn   dec
     200     20001          0        0            0        200         20001       45    1     0
     300     30001          0        0        30002        300         30001       26    1     0
     300     30002          0        0        30001        300         30002       26    0     0
     500     50001          0        0        50002        500         50001       37    1     0
     500     50002          0        0        50001        500         50002       33    0     0
     500     50003      50002    50001            0        500         50003        4    1     1
    ...

Note that the run function here takes the mandatory input 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. Run returns a Simulation class with multiple properties. The one of interest here is outputs, which contains the outputdataset(s) of type table returned by the microsimulation model: 

out_baseline(1:10,1:10)     
10×10 table array:

idhh    idperson    idmother    idfather    idpartner    idorighh    idorigperson    dag    dgn    dec
____    ________    ________    ________    _________    ________    ____________    ___    ___    ___

 200      20001          0           0             0        200          20001       45      1      0 
 300      30001          0           0         30002        300          30001       26      1      0 
 300      30002          0           0         30001        300          30002       26      0      0 
 500      50001          0           0         50002        500          50001       37      1      0 
 500      50002          0           0         50001        500          50002       33      0      0 
 500      50003      50002       50001             0        500          50003        4      1      1 
 600      60001          0           0             0        600          60001       44      1      0 
 700      70001          0           0             0        700          70001       28      0      6 
 900      90001          0           0             0        900          90001       77      1      0 
1300    1.3e+05          0           0       1.3e+05       1300        1.3e+05       54      0      0

Navigating the model

The Model object actually contains a full representation of the model that can be accessed using it’s properties. The implementation in Matlab mimicks the hierarchical structure of the EUROMOD User Interface. A full description of the available types can be found in the API reference.

The spine

The spine of EUROMOD is what represents the series of calculations with respect to taxes and benefits. The spine consists out of three hierarchically ordered elements:

  • Policy
  • Function
  • Parameter

The connector mimmicks this hierarchical implementation through an object-oriented representation. The three hierarchical elements are defined on the Country level and implemented on the System level.

Let us take a look at the policies, which are a property of the Country object: 

mod.countries("SE").policies 
26×1 Policy array:
    1: setdefault_se    |                            | DEF: SET DEFAULT
    2: uprate_se        |                            | DEF: UPRATING FACTORS
    3: ConstDef_se      |                            | DEF: CONSTANTS
    4: IlsDef_se        |                            | DEF: INCOME CONCEPTS (standardized)
    5: IlsUDBdef_se     |                            | DEF: INCOME CONCEPTS (UDB)
    6: ildef_se         |                            | DEF: INCOME CONCEPTS (non-standardized)
    7: random_se        |                            | DEF: Random assignment
    8: TransLMA_se      |                            | DEF: Modelling labour market transitions (DO NOT SWITCH ON; ONLY WORKS WITH THE LMA ADD-ON)
    9: tudef_se         |                            | DEF: ASSESSMENT UNITS
   10: yem_se           |  (with switch set for MWA) | DEF: minimum wage
   11: neg_se           |                            | DEF: recode negative self-employment income to zero
   12: yemcomp_se       |                            | BEN: wage compensation scheme COVID-19  (ONLY WORKING WITH LMA ADD-ON)
   13: bunct_se         |                            | BEN: unemployment benefit (contributory)
   14: bfapl_se         |  (with switch set for PBE) | BEN: Parental leave benefit 
   15: bpa_se           |  (with switch set for PBE) | BEN: Special leave days other parent (10 days)
   16: tscee_se         |                            | SIC: Employee Social Insurance contribution
   17: tscer_se         |                            | SIC: Employer Social Insurance contribution
   18: tscse_se         |                            | SIC: Self-employed Social Insurance contribution
   19: tin_se           |                            | TAX: Personal Income tax
   20: tinkt_se         |                            | TAX: Tax on Capital Income
   21: bch_se           |                            | BEN: Child benefit
   22: bho_se           |                            | BEN: Housing allowance
   23: bhope_se         |                            | BEN: Housing allowance for pensioners
   24: bsamt_se         |                            | BEN: Social Assistance (means-tested)
   25: output_std_se    |                            | DEF: STANDARD OUTPUT INDIVIDUAL LEVEL
   26: output_std_hh_se |                            | DEF: STANDARD OUTPUT HOUSEHOLD LEVEL

As one can see the policies property is a class array therefore its elements, which are of type Policy here, are accessible by indexing: 

mod.countries('SE').policies(13)    
1×1 Policy with properties:

   comment: "BEN: unemployment benefit (contributory)"
 functions: [16×1 Function]
   private: "no"
extensions: [0×1 Extension]
        ID: "01f1c7ff-3b6d-4191-bc71-bb86db5603d6"
      name: "bunct_se"
     order: "13"
    parent: [1×1 Country]
spineOrder: "13"

The implementation of a policy is accessible through the System class: 

mod.countries("SE").systems("SE_2021").policies 
26×1 PolicyInSystem array:
    1: setdefault_se    | on                            | DEF: SET DEFAULT
    2: uprate_se        | on                            | DEF: UPRATING FACTORS
    3: ConstDef_se      | on                            | DEF: CONSTANTS
    4: IlsDef_se        | on                            | DEF: INCOME CONCEPTS (standardized)
    5: IlsUDBdef_se     | on                            | DEF: INCOME CONCEPTS (UDB)
    6: ildef_se         | on                            | DEF: INCOME CONCEPTS (non-standardized)
    7: random_se        | on                            | DEF: Random assignment
    8: TransLMA_se      | off                           | DEF: Modelling labour market transitions (DO NOT SWITCH ON; ONLY WORKS WITH THE LMA ADD-ON)
    9: tudef_se         | on                            | DEF: ASSESSMENT UNITS
   10: yem_se           | off (with switch set for MWA) | DEF: minimum wage
   11: neg_se           | on                            | DEF: recode negative self-employment income to zero
   12: yemcomp_se       | on                            | BEN: wage compensation scheme COVID-19  (ONLY WORKING WITH LMA ADD-ON)
   13: bunct_se         | off                           | BEN: unemployment benefit (contributory)
   14: bfapl_se         | off (with switch set for PBE) | BEN: Parental leave benefit 
   15: bpa_se           | off (with switch set for PBE) | BEN: Special leave days other parent (10 days)
   16: tscee_se         | on                            | SIC: Employee Social Insurance contribution
   17: tscer_se         | on                            | SIC: Employer Social Insurance contribution
   18: tscse_se         | on                            | SIC: Self-employed Social Insurance contribution
   19: tin_se           | on                            | TAX: Personal Income tax
   20: tinkt_se         | on                            | TAX: Tax on Capital Income
   21: bch_se           | on                            | BEN: Child benefit
   22: bho_se           | on                            | BEN: Housing allowance
   23: bhope_se         | on                            | BEN: Housing allowance for pensioners
   24: bsamt_se         | on                            | BEN: Social Assistance (means-tested)
   25: output_std_se    | on                            | DEF: STANDARD OUTPUT INDIVIDUAL LEVEL
   26: output_std_hh_se | off                           | DEF: STANDARD OUTPUT HOUSEHOLD LEVEL

Here we see that some policies are turned off by default. Note that the behaviour of the policies can be controlled from the connector. We can for example switch the policy bunct_se to on. Let us first look at the policy: 

mod.countries('SE').systems('SE_2021').policies(13)    
1×1 PolicyInSystem with properties:

    polID: "01f1c7ff-3b6d-4191-bc71-bb86db5603d6"
    Switch: "off"
     sysID: "bde78132-3f44-4d2e-a1ea-4849f88c2776"
   comment: "BEN: unemployment benefit (contributory)"
 functions: [16×1 FunctionInSystem]
   private: "no"
extensions: [0×1 Extension]
        ID: "bde78132-3f44-4d2e-a1ea-4849f88c277601f1c7ff-3b6d-4191-bc71-bb86db5603d6"
      name: "bunct_se"
     order: "13"
    parent: [1×1 System]
spineOrder: "13"

We see here the property Switch that is part of the PolicyInSystem class. This property, and similarly the other properties of the object, is modifiable. The changes that you will make will be passed to the EUROMOD software when simulating.

Note that currently, the Matlab connector does not support the save option. Therefore, changes implemented during a Matlab session cannot be saved.

To apply permanent changes to the model, we recommend using the User Interface of EUROMOD.

Note that the Matlab connector is not checking what kind of modifications you make to the model. Changing values of attributes like ID are definitely not recommended.

Here we see that the average benefit, which is represented by ils_ben, is indeed larger by switching on the extension of the bunct_se policy: 

mod.countries("SE").systems("SE_2021").policies(14).Switch="on" 
S=mod.countries("SE").systems("SE_2021").run(data,"SE_2021_b1") 
mean(out_baseline.outputs{1}{:,"ils_ben"}) - mean(S.outputs{1}{:,"ils_ben"}) 
 0.0

As mentioned before, the connector mimicks the hierarchical structure of the UI. Hence, the definition of functions and parameters are defined on the Country level, and their actual implementation are also accessible via the Tax System. Note that also here, the values of a Parameter and the Switch of a Function can be manipulated through the Matlab Connector without saving the changes permanently.

Display the functions defined in the bho_se policy: 

mod.countries("SE").policies(23).functions 
19×1 Function array:
    1: DefVar   | Temporary variables for Housing Allowance for pensioners
    2: Elig     | Living with partner
    3: ArithOp  | Wealth to be included in the means
    4: Elig     | Living without partner
    5: ArithOp  | Wealth to be included in the means
    6: Allocate | Allocation of wealth to the partners
    7: Elig     | Elderly or disabled adult (i.e. head or partner)
    8: BenCalc  | "Reserved amount (""income disregard"")"
    9: BenCalc  | Change in definition of Income Means for for Housing Allowance for pensioners (preliminary) since 2014
   10: DefIl    | Income Means for Housing Allowance for pensioners
   11: BenCalc  | Income of children is not take into account in the means
   12: BenCalc  | Maximum housing allowance
   13: BenCalc  | 
   14: BenCalc  | Maximum housing allowance
   15: BenCalc  | Maximum housing allowance
   16: Allocate | Allocation of income to the partners
   17: BenCalc  | Final housing allowance for pensioners
   18: Allocate | Sharing housing cost
   19: BenCalc  | Housing allowance for pensioners

Display the functions defined in the bho_se policy and implemented in system SE_2021: 

mod.countries("SE").systems("SE_2021").policies(23).functions 
19×1 FunctionInSystem array:
    1: DefVar   | on   | Temporary variables for Housing Allowance for pensioners
    2: Elig     | on   | Living with partner
    3: ArithOp  | on   | Wealth to be included in the means
    4: Elig     | on   | Living without partner
    5: ArithOp  | on   | Wealth to be included in the means
    6: Allocate | on   | Allocation of wealth to the partners
    7: Elig     | on   | Elderly or disabled adult (i.e. head or partner)
    8: BenCalc  | on   | "Reserved amount (""income disregard"")"
    9: BenCalc  | on   | Change in definition of Income Means for for Housing Allowance for pensioners (preliminary) since 2014
   10: DefIl    | on   | Income Means for Housing Allowance for pensioners
   11: BenCalc  | on   | Income of children is not take into account in the means
   12: BenCalc  | on   | Maximum housing allowance
   13: BenCalc  | off  | 
   14: BenCalc  | off  | Maximum housing allowance
   15: BenCalc  | on   | Maximum housing allowance
   16: Allocate | on   | Allocation of income to the partners
   17: BenCalc  | on   | Final housing allowance for pensioners
   18: Allocate | on   | Sharing housing cost
   19: BenCalc  | on   | Housing allowance for pensioners

"Overview of the parameters defined in the bho_se policy: 

mod.countries("SE").policies(23).functions(1).parameters 
1×1 Parameter with properties:
   comment: ""
extensions: [0×1 Extension]
     funID: "7eb7c6ef-a589-4725-bcce-3071684b38bb"
     group: "1"
        ID: "cecb57a5-273b-4ab0-b5cc-70dea318f4eb"
      name: "i_means_bhope_prel"
     order: "1"
    parent: [1×1 Function]
spineOrder: "23.1.1"

"Overview of the parameters defined in the bho_se policy and implemented in system SE_2021: 

mod.countries("SE").systems("SE_2021").policies(23).functions(1).parameters 
1×1 ParameterInSystem  with properties:
      parID: "cecb57a5-273b-4ab0-b5cc-70dea318f4eb"
      value: "0"
      sysID: "bde78132-3f44-4d2e-a1ea-4849f88c2776"
    comment: ""
 extensions: [0×1 Extension]
      funID: "7eb7c6ef-a589-4725-bcce-3071684b38bb"
      group: "1"
         ID: "bde78132-3f44-4d2e-a1ea-4849f88c2776cecb57a5-273b-4ab0-b5cc-70dea318f4eb"
       name: "i_means_bhope_prel"
      order: "1"
     parent: [1×1 FunctionInSystem]
 spineOrder: "23.1.1"

Central to the EUROMOD project, next to the coding of the policies is the microdata. How datasets should be treated by the model is configured in the model already. The property datasets is a class array with properties accessible and modifiable just like the spine-elements. 

mod.SE.datasets 
27×1 Dataset array:
     
       1: SE_2007_a4
       2: SE_2008_a3
       3: training_data
       4: SE_2010_a1
       5: SE_2012_a2
       6: SE_2015_a1
       7: SE_2009_hhot
       8: SE_2010_hhot
       9: SE_2011_hhot
      10: SE_2012_hhot
      11: SE_2013_hhot
      12: SE_2014_hhot
      13: SE_2015_hhot
      14: SE_2016_hhot
      15: SE_2017_hhot
      16: SE_2016_a1
      17: SE_2018_hhot
      18: SE_2019_hhot
      19: SE_2018_a2
      20: SE_2017_a3
      21: SE_2020_hhot
      22: SE_2019_a1
      23: SE_2020_b1
      24: SE_2021_hhot
      25: SE_2022_hhot
      26: SE_2021_b1
      27: SE_2023_hhot

In the previous section we used SE_2021_b1. Let us have a look at it: 

mod.SE.datasets("SE_2021_b1")     
1×1 Dataset with properties:

   coicopVersion: ""
         comment: ""
        currency: "national"
     decimalSign: "."
              ID: "c7b651ed-b311-4e39-80b4-18ca19957ce7"
listStringOutVar: ""
            name: "SE_2021_b1"
          parent: [1×1 Country]
         private: "no"
  readXVariables: "no"
useCommonDefault: "no"
  yearCollection: "2021"
         yearInc: "2020"

Similarly to the properties in the Policy, Function and Parameter objects, the properties of the Dataset can be modified here.

We can further check what datasets are implemented for a given system, for example SE_2021, as follows: 

mod.SE.SE_2021.datasets 
5×1 DatasetInSystem array:
  
   1: training_data | 
   2: SE_2019_a1    | 
   3: SE_2020_b1    | 
   4: SE_2021_hhot  | 
   5: SE_2021_b1    | best match

Another important concept in EUROMOD are extensions that are defined globally on the Model level: 

mod.extensions 
11×1 Extension array:
  
   1: BTA      | Benefit Take-up Adjustments
   2: TCA      | Tax Compliance Adjustments
   3: FYA      | Full Year Adjustments
   4: UAA      | Uprating by Average Adjustment
   5: EPS      | Extended Policy Simulation
   6: PBE      | Parental leave benefits
   7: MWA      | Minimum Wage Adjustments
   8: HHoT_un  | HHoT unemployment extension
   9: WEB      | EUROMOD JRC-Interface
  10: HHoT_ext | HHoT - Extended Simulation
  11: HHoT_ncp | HHoT - Non Compulsory Payments

Or locally on the Country level: 

mod.countries("SE").extensions 
12×1 Extension array:
  
   1: COVID    | COVID benefit
   2: BTA      | Benefit Take-up Adjustments
   3: TCA      | Tax Compliance Adjustments
   4: FYA      | Full Year Adjustments
   5: UAA      | Uprating by Average Adjustment
   6: EPS      | Extended Policy Simulation
   7: PBE      | Parental leave benefits
   8: MWA      | Minimum Wage Adjustments
   9: HHoT_un  | HHoT unemployment extension
  10: WEB      | EUROMOD JRC-Interface
  11: HHoT_ext | HHoT - Extended Simulation
  12: HHoT_ncp | HHoT - Non Compulsory Payments

The extensions property is a class array. If we want to access the information stored in the Minimum Wage Adjustments extension for example, we can simply use the following command: 

mod.countries("SE").extensions("Minimum Wage Adjustments") 
1×1 Extension with properties:
   
       ID: "557c232a-9ce6-4808-b52f-ca5e02fe8cf4"
     name: "Minimum Wage Adjustments"
   parent: [1×1 Country]
shortName: "MWA"

References

[1] Documentation EUROMOD - Tax-benefit microsimulation model for the European Union.

Extended Capabilities

See Also

Introduced in R2023a