*! version 1.1.0 January 10, 2023 @ 12:00:00

help euromod run (EUROMOD Connector v1.0.4)

euromod run -- Stata Connector to EUROMOD

Syntax

euromod run
[if],
model (Path to model)
system (EUROMOD system name)
dataset (EUROMOD dataset)
country (EU country)
[addons(addon name)
extensions(extension condition)
constants (constant condition)
replace
euro
prefix (prefix)
useLogger
publiccomponentsonly
repository
sequentialoutput
outputdataset (output name)
outputpath
il_output (income lists)
vars_output (variables)
extrainfo_output (Additional Information)
keep ]

Description

euromod run
is the Stata connector, built to facilitate and simplify the usage of the EUROMOD microsimulation model for research purposes. The connector passes the data stored in Stata directly in memory to the EUROMOD software. It is therefore a prerequisite that the EUROMOD software is installed.
The Stata connector to EUROMOD exists out of a main command euromod run and two additional commands:

- euromod getdata

- euromod getinfo

This command will execute a run of EUROMOD using the data stored in the memory of Stata as input data. Therefore, in order for the model to be able to run, data needs to be loaded into Stata’s memory with the necessary variables included in order for the model to be able to run.
When the run is successful, the EUROMOD output data will be loaded into the Stata DataFrame.

The syntax of the command is as follows: euromod run if, options [extra options]. The use of “if” allows the user to pass a subset of the full DataFrame to EUROMOD, but only a specific subset. Note that one should be careful not to split households accidentally by using the if clause.

model(string) This parameter is the root folder of the EUROMOD project, where the model is stored.

system(string) This parameter represents the name of a system in EUROMOD (e.g. DK_2023) that you want to run using the connector.

dataset(string) This parameter is the dataset name as configured in the EUROMOD model. The parameter will determine the uprating factors and extensions to be applied to the input data.

country(string) The official country code of the country of interest (for EU member states see:
https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Tutorial:Country_codes_and_protocol_order#Codes.2C_names_and_protocol_order_of_European_Union_.28EU.29_Member_States)

Note: In case the installation path of EUROMOD is not the standard one (i.e. it is not c:\Program Files), one needs to first set the global EUROMOD_PATH before using the Stata connector. This path is where the StataPlugin.plugin is stored and should therefore always end with “Executable/”.

Options

repository(string) This parameter specifies a path to a folder where there is a dataset stored with the name of the data set with the “.txt” extension.
When using this option the data held in memory is overwritten by the data contained in the input dataset.

addons(string)
This parameter takes a string which lists the names of the add-ons and their specific country implementation. |_. Multiple add-ons can be used by passing them in a comma separated fashion.
For example, integrating the of MTR and TCA add-ons for BG in the run of EUROMOD can be done with the following syntax:

euromod run, … addon("MTR|MTR_BG, TCA|TCA_BG")

extensions(string) This parameter allows to activate and deactivate global and country-specific extensions that deviate from the default configuration of the specific system-dataset combination.
This parameter takes a comma-separated list of =.
For example, activating the TCA and deactivating the UAA extensions can be done with the following syntax:

euromod run, … extensions(UAA=on, TCA=off)

constants(string) This parameter allows to overwrite the values of constants used in the model. The following types of constants can be modified:

- Uprating factors

- Constants that are defined by DefConst

- Constants specific to EUROMOD’s Indirect Tax Tool (ITT)

The mandatory dollar sign in EUROMOD constants has to be omitted when referring to it in this option, to avoid issues with Stata global macros, which also use the dollar sign. The syntax works as follows:

name_constant(Group Number or Year) = 'formula'

Multiple constants can be overwritten by applying the syntax multiple times and separate the constants by spaces. The group number or year parameter is optional in the syntax, but is necessary for the ITT and uprating constants to identify the constants to overwrite.
For example, overwriting the $flat_rate constant in the BG system and changing the uprating factor $f_cpi would works as follows:

euromod run, system("BG_2023") country("BG") dataset( "BG_2021_c1") constants("flat_rate = '0.2' f_cpi(2023) = '500'")

replace This option will replace the data held before the simulation by the data resulting from the simulation.

euro This will convert the output of the EUROMOD simulation to euro if the output was in national currency.

prefix(string)
Enables the specification of a prefix that will be added to the variable names of the EUROMOD output loaded into memory. For example, the following syntax will add the prefix sim1 to all the output variable names:

euromod run, … prefix(“sim1_”)

useLogger This option will open a Logger window which portrays the advancement of the simulation.
Note that the Logger is designed to stay open in case an Error has been produced while running EUROMOD.

publiccomponentsonly This option will run the model with only the public components and ignoring the private components.

sequentialoutput This option forces EUROMOD to let the spine run sequentially instead of in a parallelised way over all Households.

keep This option keeps the output of the simulation in memory and passes it to other simulation. One can keep only one simulation at a time in memory.

repository(string) This options accepts a string as a path. When provided, the connector will attempt to load the input-dataset specified by the dataset parameter from the path provided

outputdataset(string) In case there are multiple output dataset returned by the EUROMOD simulation, one can pass the filename in advance to the command such that the respective dataset will be loaded into memory afterwards.
Otherwise the data can be loaded in a second step by the euromod getdata command.

outputpath(string) In case this path is provided, the output will not only be passed through memory, but also generated as a text file stored on the specified path.

il_output(string): The usage of this option results into the creation of an additional DefOutput added to the spine which will be named “custom_output”. One can specify the income lists one likes to include by spacing them by commas.
For example, adding an additional DefOutput for the income lists ils_dispy and ils_tax would work as follows:

euromod run, system("BG_2023") country("BG") dataset("BG_2021_c1") il_output("ils_dispy, ils_tax")

Note that this parameter can be used together with vars_output

vars_output(string): vars_output The usage of this option results into the creation of an additional DefOutput added to the spine which will be named “custom_output”.
One can specify the variables one likes to include by spacing them by commas. For example, adding an additional DefOutput for the variables bsa_s and yem would work as follows:

euromod run, system("BG_2023") country("BG") dataset("BG_2021_c1") vars_output("bsa_s, yem")

Note that this parameter can be used together with il_output

extrainfo_output(string): This option allows for the addition of specific TaxUnit information to the custom_output. It has a specifc syntax that has the following structure

'taxUnitName1': 'Query1,Query2,…', 'taxUnitName2': 'Query3,Query4,…',…

taxUnitName# refers to the name of the Tax Unit in the model, Query# refers to a query such as IsDependentChild, IsPartner or a TaxUnit specific variable such as HeadID.
Note that the TaxUnit names and the Queries need to be enclosed by single quote marks and different Queries or TaxUnit specific variables that belong to the same Tax Unit should be separated by commas.
One can also include multiple TaxUnit Query combinations by separating them by commas.
Below one finds a working example that would run EUROMOD and retrieve the IsDependentChild condition for every individual for the tax units tu_bmaycct_bg and tu_bcheydc_bg,
and the HeadID for every individual according to the tax unit definition of tu_bcheydc_bg.

euromod run, system("BG_2023") country("BG") dataset("BG_2021_c1") extrainfo_output("'tu_bmaycct_bg':'IsDependentChild', 'tu_bcheydc_bg':'IsDependentChild,HeadID'")

Global variables

After a successful EUROMOD simulation, a series of global variables are stored in memory, what facilitates the user to validate and process the output of the simulation.
The following globals are available to the user after running euromod run command:

$n_euromod_errors The number of errors/warnings returned during the simulation.
Note the output of the simulation is not loaded into memory when an error occurs.

$EM_n_outputs: The number of output datasets stored after simulation.

$EM_outputs: A string containing the names of the outputs separated by spaces.

$EM_vars: Is a variable spaced list of the variables contained in the EUROMOD output data loaded into memory. Note that this is the name of the variable in EUROMOD and that this might deviate because of two reasons:

- Variable names in Stata can be maximum 32 characters and therefore can be truncated when the variable name in EUROMOD exceeds 32 characters.

- The usage of the prefix option.

Information stored in the return list

local Description

outputVars A space separated list containg the output variables of the simulation.
outputFiles A space separated list containg the output files of the simulation.
nOutputFiles Number of output files produced by the simulation. Note that the files are not written to the hard disk.
nErrors Number of errors/warnings produced by the simulation of the model.
errorMessages Macro containing the errorMessages produced by the simulation.

Examples

. euromod run, model(Path to model) system(BE_2020) dataset(BE_2020_c2) country(BE)

This example, is for running EUROMOD for Belgium for system BE_2020 in combination with dataset BE_2020_c2.

. euromod run, model(Path to model) system(SE_2023) dataset(SE_2021_b1) country(SE) constants("tinna_rate1='-0.01'") prefix(sim2_) euro

Running EUROMOD, changing a constant, creating a prefix and converting to Euro currency.

. euromod run, model(Path to model) system(SK_2022) dataset(SK_2020_b1) country(SK) extensions(BTA=on) prefix(sim2_)

Running EUROMOD, controlling the extensions and generating a new prefix.

. euromod run, model(Path to model) system(SK_2022) dataset(SK_2010_x1) country(SK) addons(ITT_XBASE|ITT_XBase) prefix(sim1_)

Running EUROMOD, multiple addons selection and generating a new prefix.

. euromod run, model(Path to model) system(SK_2022) dataset(SK_2010_x1) country(SK) addons(ITT_XBASE|ITT_XBase) prefix(sim2_) constants("tco_base_t_std(2022)='0.3'") outputdataset(sk_2022_xbase_std.txt)

Running EUROMOD, Addons selection, generating a new prefix, applying a constant and controlling data output.

. euromod run if dgn == 0, model(Path to model) system(SE_2022) dataset(SE_2021_b1) country(SE) prefix(sim_)

Running EUROMOD and Conditional if usage.

. euromod run, model(Path to model) system(SE_2022) dataset(SE_2022_x1) country(SE) constants("tinna_rate1='-0.01' tinna_rate2='0.4'") prefix(sim2_) euro

Running EUROMOD, applying multiple constants and converting to Euro currency.

Requirements

In order to use the Stata Connector to EUROMOD, please install the latest software version of EUROMOD.
This can be downloaded from here.

Authors

Hannes Serruys, B2-JRC Seville (Hannes.SERRUYS@ec.europa.eu)