{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Examples\n", "\n", "## Loading and navigating the model\n", "We start with importing the euromod package and creating a Model object from a EUROMOD model. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```{seealso} \n", "See the installation guide on how to install the package and its dependencies.\n", "```" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "outputs": [ { "data": { "text/plain": [ "------------------------------\n", "Model\n", "------------------------------\n", "\t countries: 28 elements\n", "\t extensions: 11 elements\n", "\t model_path: 'C:\\\\EUROMOD_RELEASES_I6.0+'" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from euromod import Model\n", "mod=Model(r\"C:\\EUROMOD_RELEASES_I6.0+\")\n", "mod" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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:\n", "- countries\n", "- extensions\n", "- model_path\n", "\n", "The countries and extensions attributes contain elements of the respective objects. If we take a look at `countries`:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "0: AT \n", "1: BE \n", "2: BG \n", "3: CY \n", "4: CZ \n", "5: DE \n", "6: DK \n", "7: EE \n", "8: EL \n", "9: ES \n", "10: FI\n", "11: FR\n", "12: HR\n", "13: HU\n", "14: IE\n", "15: IT\n", "16: LT\n", "17: LU\n", "18: LV\n", "19: MT\n", "20: NL\n", "21: PL\n", "22: PT\n", "23: RO\n", "24: SE\n", "25: SI\n", "26: SK\n", "27: SL" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "mod.countries" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We see indeed that the euromod model contains 28 countries. In a similar fashion we can look what kind of extensions are stored in the model. The countries container can be indexed by both the number of the element and the country shortcode. Let us take a look at Sweden." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "------------------------------\n", "Country\n", "------------------------------\n", "\t datasets: 27 elements\n", "\t extensions: 12 elements\n", "\t local_extensions: COVID\n", "\t name: 'SE'\n", "\t policies: 26 elements\n", "\t systems: 18 elements" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "mod.countries[\"SE\"]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here we see again an informative representation of the Country object, which contains several attributes that can be accessed. We can for example take a look at the first 10 policies that are stored in the country." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "0: setdefault_se | | DEF: SET DEFAULT \n", "1: uprate_se | | DEF: UPRATING FACTORS \n", "2: ConstDef_se | | DEF: CONSTANTS \n", "3: IlsDef_se | | DEF: INCOME CONCEPTS (standardized) \n", "4: IlsUDBdef_se | | DEF: INCOME CONCEPTS (UDB) \n", "5: ildef_se | | DEF: INCOME CONCEPTS (non-standardized) \n", "6: random_se | | DEF: Random assignment \n", "7: TransLMA_se | | DEF: Modelling labour market transitions (DO NOT S ... \n", "8: tudef_se | | DEF: ASSESSMENT UNITS \n", "9: yem_se | (with switch set for MWA) | DEF: minimum wage " ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "mod.countries[\"SE\"].policies[0:10]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running a system with default configuration\n", "Say that we are interested in running the tax system for the year 2021 of Sweden. Building further on the previous example we can look at the tax-systems contained in the model for Sweden." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "0: SE_2006 \n", "1: SE_2007 \n", "2: SE_2008 \n", "3: SE_2009 \n", "4: SE_2010 \n", "5: SE_2011 \n", "6: SE_2012 \n", "7: SE_2013 \n", "8: SE_2014 \n", "9: SE_2015 \n", "10: SE_2016\n", "11: SE_2017\n", "12: SE_2018\n", "13: SE_2019\n", "14: SE_2020\n", "15: SE_2021\n", "16: SE_2022\n", "17: SE_2023" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "mod.countries[\"SE\"].systems" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In order to run the tax system we need a dataset that fits the requirement to use. The model however provides us with a list of datasets that are configured already." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "0: training_data | \n", "1: SE_2019_a1 | \n", "2: SE_2020_b1 | \n", "3: SE_2021_hhot | \n", "4: SE_2021_b1 | best match " ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "mod.countries[\"SE\"].systems[\"SE_2021\"].datasets" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here we see that there are multiple datasets configured, but that PL_2021_b1 is set as the best match dataset for this taxsystem. Provided that you have the microdata stored somewhere, you can then load it as a `pandas.DataFrame` and run the model in the following way:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Simulation for system SE_2021 with dataset SE_2021_b1 finished.\n" ] }, { "data": { "text/plain": [ "------------------------------\n", "Simulation\n", "------------------------------\n", "\t constantsToOverwrite: {}\n", "\t errors: []\n", "\t output_filenames: ['se_2021_std.txt']\n", "\t outputs: Pandas DataFrame of 240 variables and 21671 observations." ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import pandas as pd\n", "data=pd.read_csv(r\"C:\\EUROMOD_RELEASES_I6.0+\\Input\\SE_2021_b1.txt\",sep=\"\\t\")\n", "out = mod.countries[\"SE\"].systems[\"SE_2021\"].run(data,\"SE_2021_b1\")\n", "out" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [ "remove-input" ] }, "outputs": [], "source": [ "pd.set_option('display.max_rows', 11, 'display.max_columns',7)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This returns a Simulation object with multiple attributes. The one of interest here is outputs, which contains the outputdataset(s) returned by the microsimulation model." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idhhidpersonidmother...tu_bho_se_IsDependentChildtu_bho_se_IsLoneParenttu_bho_se_IsPartner
0200.020001.00.0...0.00.00.0
1300.030001.00.0...0.00.00.0
2300.030002.00.0...0.00.01.0
3500.050001.00.0...0.00.00.0
4500.050002.00.0...0.00.01.0
........................
216661936500.0193650002.00.0...0.00.01.0
216671936800.0193680001.00.0...0.00.01.0
216681936800.0193680002.00.0...0.00.00.0
216691936800.0193680003.0193680002.0...1.00.00.0
216701936800.0193680004.0193680002.0...1.00.00.0
\n", "

21671 rows × 240 columns

\n", "
" ], "text/plain": [ " idhh idperson idmother ... tu_bho_se_IsDependentChild \\\n", "0 200.0 20001.0 0.0 ... 0.0 \n", "1 300.0 30001.0 0.0 ... 0.0 \n", "2 300.0 30002.0 0.0 ... 0.0 \n", "3 500.0 50001.0 0.0 ... 0.0 \n", "4 500.0 50002.0 0.0 ... 0.0 \n", "... ... ... ... ... ... \n", "21666 1936500.0 193650002.0 0.0 ... 0.0 \n", "21667 1936800.0 193680001.0 0.0 ... 0.0 \n", "21668 1936800.0 193680002.0 0.0 ... 0.0 \n", "21669 1936800.0 193680003.0 193680002.0 ... 1.0 \n", "21670 1936800.0 193680004.0 193680002.0 ... 1.0 \n", "\n", " tu_bho_se_IsLoneParent tu_bho_se_IsPartner \n", "0 0.0 0.0 \n", "1 0.0 0.0 \n", "2 0.0 1.0 \n", "3 0.0 0.0 \n", "4 0.0 1.0 \n", "... ... ... \n", "21666 0.0 1.0 \n", "21667 0.0 1.0 \n", "21668 0.0 0.0 \n", "21669 0.0 0.0 \n", "21670 0.0 0.0 \n", "\n", "[21671 rows x 240 columns]" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "outputdata_baseline = out.outputs[0]\n", "outputdata_baseline" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running a system while changing a constant\n", "One of the advantages of using the Python Connectors is the ability to run many counterfactual scenario's for the EUROMOD model. One can for example change the Tax Free income limit in Poland. There are multiple ways to do this via the euromod package in Python, but one very straightforward way is to use the `constantsToOverwrite` option which is a a dictionary, having the targetted constant as a key and the value to overwrite with as a value.\n" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Simulation for system SE_2021 with dataset SE_2021_b1 finished.\n" ] }, { "data": { "text/plain": [ "-12247774.761818277" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "out=mod['SE']['SE_2021'].run(data,\"SE_2021_b1\",constantsToOverwrite={(\"$tinna_rate2\",\"\"):'0.4'})\n", "outputdata_changed= out.outputs[0]\n", "sum(outputdata_changed.ils_dispy - outputdata_baseline.ils_dispy)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The optional parameter ```constantsToOverwrite``` specifies which constants to overwrite in the policy spline. `constantsToOverwrite` must be a ```dict```, where the keys are ```tuples``` of two ```str``` objects: the first string is the name of the constant and the second string is its group number (**Note:** Pass an empty string if the group number is `None`); the values are ```str``` with the new values of the constants. The default is `None`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Run with add-ons\n", "Run the simulation for the Swedish system SE_2021 including the Marginal Tax-Rate add-on 'MTR'." ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Simulation for system SE_2021 with dataset SE_2021_b1 finished.\n" ] }, { "data": { "text/plain": [ "------------------------------\n", "Simulation\n", "------------------------------\n", "\t constantsToOverwrite: {}\n", "\t errors: []\n", "\t output_filenames: ['se_2021_base_mtr.txt', 'se_2021_mtr.txt']\n", "\t outputs: Pandas DataFrame of 246 variables and 21671 observations., Pandas DataFrame of 39 variables and 21671 observations." ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "out =mod['SE']['SE_2021'].run(data,\"SE_2021_b1\",addons=[(\"MTR\",\"MTR\")])\n", "out" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As one can see there are two datasets returned by the model. Both of them can be accessed. The average marginal tax rate for example can then be straightforwardly computed as" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "19.419071885518324" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "out.outputs['se_2021_mtr.txt'].mtrpc.mean()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The optional parameter `addons` that we passed to the run command is a ```list``` of EUROMOD Addons to be integrated in the spine . Each item of the ``list`` is a ```tuple``` with two ```str``` objects. The first ```str``` is the name of the Addon and the second `str` is the name of the system in the Addon to be integrated (typically, it is the name of the Addon ```_``` two-letter country code, e.g. LMA_AT). The default value here is []. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Run with extensions\n", "Run the simulation for the Swedish system SE_2021 switching on the Benefit Take-up Adjustment extension 'BTA'." ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Simulation for system SE_2021 with dataset SE_2021_b1 finished.\n" ] }, { "data": { "text/plain": [ "------------------------------\n", "Simulation\n", "------------------------------\n", "\t constantsToOverwrite: {}\n", "\t errors: []\n", "\t output_filenames: ['se_2021_base_mtr.txt', 'se_2021_mtr.txt']\n", "\t outputs: Pandas DataFrame of 246 variables and 21671 observations., Pandas DataFrame of 39 variables and 21671 observations." ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "out_BTA =mod['SE']['SE_2021'].run(data,\"SE_2021_b1\",switches=[(\"BTA\",True)])\n", "out" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "0.0" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "out_BTA.outputs[0].ils_ben.mean() - outputdata_baseline.ils_ben.mean()" ] }, { "cell_type": "markdown", "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "source": [ "The optional parameter `switches` must define a `list` of the [EUROMOD](https://euromod-web.jrc.ec.europa.eu \"https://euromod-web.jrc.ec.europa.eu\") extensions to be switched on or off in the simulation. Each item in the ``list`` is a ```tuple``` with two objects. The first object is a ```str``` short name of the Extension. The second object is a ```boolean```. The default is []. " ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.5" } }, "nbformat": 4, "nbformat_minor": 4 }