Update Elterngeld

.pre-commit-config.yaml

@@ -57,7 +57,7 @@ repos:
       - id: blacken-docs
       # exclude: docs/source/how_to_guides/optimization/how_to_specify_constraints.md
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.3
+    rev: v0.6.4
     hooks:
       - id: ruff
       #   args:

CHANGES.md

@@ -6,6 +6,8 @@ releases are available on [Anaconda.org](https://anaconda.org/conda-forge/gettsi
 
 ## Unpublished
 
+- {gh}`756` Refactor Elterngeld module and some small fixes ({ghuser}`MImmesberger`,
+  {ghuser}`ThOrtmann`).
 - {gh}`790` Add unterhaltsvors implementation 2009 to 2016 ({ghuser}`mjbloemer`).
 - {gh}`788` Pension benefit earnings test for early retirees ({ghuser}`MImmesberger`).
 - {gh}`786` Check directly whether child and parent are in same Bedarfsgemeinschaft for

docs/gettsim_objects/input_variables.md

@@ -247,11 +247,40 @@ Weekly working hours of individual
 
 Type: float
 
+(elterngeld_claimed)=
+
+## `elterngeld_claimed`
+
+Individual claims Elterngeld
+
+Type: bool
+
+(elterngeld_nettoeinkommen_vorjahr_m)=
+
+## `elterngeld_nettoeinkommen_vorjahr_m`
+
+Approximation of the net wage in the 12 months before birth of youngest child (according
+to simplified calculation rules). You may let GETTSIM compute this variable via the
+`elterngeld_nettolohn_approximation_m` target in a separate run, which would typically
+be for the previous calendar year.
+
+Type: float
+
+(elterngeld_zu_verst_eink_vorjahr_y_sn)=
+
+## `elterngeld_zu_verst_eink_vorjahr_y_sn`
+
+Taxable income in the 12 months before birth of youngest child. You may let GETTSIM
+compute this variable via the `_zu_verst_eink_mit_kinderfreib_y_sn` target in a separate
+run, which would typically be for the previous calendar year.
+
+Type: float
+
 (bruttolohn_vorj_m)=
 
 ## `bruttolohn_vorj_m`
 
-Monthly wage, previous year
+Gross wage in the previous year
 
 Type: float
 
@@ -295,27 +324,11 @@ Month of retirement
 
 Type: int
 
-(m_elterngeld)=
-
-## `m_elterngeld`
-
-Number of months hh received elterngeld
-
-Type: int
-
-(m_elterngeld_vat_hh)=
-
-## `m_elterngeld_vat_hh`
-
-Number of months father received elterngeld
-
-Type: int
-
-(m_elterngeld_mut_hh)=
+(monate_elterngeldbezug)=
 
-## `m_elterngeld_mut_hh`
+## `monate_elterngeldbezug`
 
-Number of months mother received elterngeld
+Number of months the individual received Elterngeld for the current youngest child.
 
 Type: int
 

docs/how_to_guides/calculating_elterngeld.ipynb

@@ -0,0 +1,243 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# How to calculate Elterngeld\n",
+    "\n",
+    "Elterngeld (parental leave benefit) is a financial support for parents in the first\n",
+    "months after the birth of a child. It replaces some share of the income before birth\n",
+    "(usually about 67% of net income). This net income is approximated using simplified\n",
+    "calculation rules. This document explains how to calculate Elterngeld\n",
+    "based on historical income data for a given household.\n",
+    "\n",
+    "In principle, one can compute Elterngeld in three steps:\n",
+    "1. Compute the average monthly gross income before birth in the data.\n",
+    "2. Call GETTSIM with the target `elterngeld_nettolohn_approximation_m` using the policy\n",
+    "   environment of the year **before** the child was born.\n",
+    "3. Call GETTSIM with the target `elterngeld_m` using the outcome of step 2 as the input\n",
+    "   for `elterngeld_nettoeinkommen_vorjahr_m` and the policy environment of the year the\n",
+    "   child was born.\n",
+    "\n",
+    "In the following, we will explain some more details."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example\n",
+    "\n",
+    "In the following, we compute Elterngeld for a child that is born in July 2024. The\n",
+    "parent that receives Elterngeld had a monthly gross wage of 2,000€ in the 12 months\n",
+    "before birth of the child.\n",
+    "\n",
+    "You can find an exemplary Elterngeld application form of the state of Bavaria\n",
+    "[here](https://www.zbfs.bayern.de/imperia/md/content/zbfs_intranet/produktgruppe_i/formulare/beeg-antrag/2021_09_anlage_n_mit_info_.pdf).\n",
+    "\n",
+    "### Step 1: Compute the average monthly gross income before birth\n",
+    "\n",
+    "If income from dependent employment is the only source of income, the basis for the\n",
+    "Elterngeld calculation is the average monthly gross income in the 12 months before the\n",
+    "birth of a child. In our case, this would be July 2023 until June 2024. If other income\n",
+    "sources exist, the basis is the average monthly gross income in the calendar year before\n",
+    "the birth of the child, 2023 in our example. We will stick to the first case here\n",
+    "because it is the only thing that GETTSIM will handle directly right now.\n",
+    "\n",
+    "> **Note**: The Elterngeld implementation in GETTSIM does currently not consider income\n",
+    "> from self-employment or other sources. See\n",
+    "> [this](https://github.com/iza-institute-of-labor-economics/gettsim/issues/613) issue.\n",
+    "\n",
+    "So let's assume that income from dependent employment is the only source of income. If\n",
+    "you have only annual income data (and thus cannot compute gross income 12 months before\n",
+    "birth exactly), you must choose an approximation. In most cases, a good approximation is\n",
+    "the income of the year before birth.\n",
+    "\n",
+    "Here, we use made-up data using the `create_synthetic_data` function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from gettsim import (\n",
+    "    compute_taxes_and_transfers,\n",
+    "    create_synthetic_data,\n",
+    "    set_up_policy_environment,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The correct point in time for the data, i.e., the relevant state variables for\n",
+    "determining the net wage, are an interesting case. Many of those may change over time.\n",
+    "The relevant part is:\n",
+    "\n",
+    "> Die entsprechenden Abzugsmerkmale werden den Lohn- oder Gehaltsabrechnungen entnommen.\n",
+    "> Grundsätzlich sind die Abzugsmerkmale maßgeblich, die in der überwiegenden Zahl der\n",
+    "> Monate des Bemessungszeitraums vor Geburt des Kindes gegolten haben.\n",
+    "\n",
+    "So it is up to the data preparer to find out which tax class (Lohnsteuerklasse), church\n",
+    "tax (Kirchensteuer), health insurance, etc. to set. The Lohnsteuerklasse, for example, is always set\n",
+    "on a yearly basis; if it changes with the start of the calendar year a child is born,\n",
+    "the date of birth matters. Up to June, the Lohnsteuerklasse from the previous calendar\n",
+    "year will be relevant; for July or later, the Lohnsteuerklasse from the current calendar\n",
+    "year will be relevant."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data_before_birth = create_synthetic_data(\n",
+    "    n_adults=2,\n",
+    "    n_children=0,\n",
+    "    specs_heterogeneous={\n",
+    "        \"bruttolohn_m\": [[2000.0, 0.0]],\n",
+    "    },\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 2: Approximate net wage before birth\n",
+    "\n",
+    "GETTSIM provides an easy way to compute the relevant net wage\n",
+    "`elterngeld_nettoeinkommen_vorjahr_m` based on step 1 using the target\n",
+    "`elterngeld_nettolohn_approximation_m`.\n",
+    "\n",
+    "We use the policy environment of January 1st of the year before the child was born (§2e\n",
+    "Abs. 1 S. 2 BEEG). Note that this is correct regardless of the point in time when the\n",
+    "child is born\n",
+    "\n",
+    "In our case, this is January 1st, 2023."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "params_2023, functions_2023 = set_up_policy_environment(2023)\n",
+    "\n",
+    "net_wage_approximation = compute_taxes_and_transfers(\n",
+    "    data=data_before_birth,\n",
+    "    functions=functions_2023,\n",
+    "    params=params_2023,\n",
+    "    targets=[\"elterngeld_nettolohn_approximation_m\"],\n",
+    ")\n",
+    "\n",
+    "net_wage_approximation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 3: Compute Elterngeld\n",
+    "\n",
+    "Finally, we can compute Elterngeld using the target `elterngeld_m` and the net wage\n",
+    "information from step 2.\n",
+    "\n",
+    "The reason for not doing this in one GETTSIM call (together with step 2) is that \n",
+    "1. we have to use different policy environment dates for the two steps, and\n",
+    "2. other state variables of the household (e.g. place of residence) might change\n",
+    "after birth of the child.\n",
+    "\n",
+    "First, we create the new data set after birth."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create data\n",
+    "params, functions = set_up_policy_environment(2023)\n",
+    "\n",
+    "data_after_birth = create_synthetic_data(\n",
+    "    n_adults=2,\n",
+    "    n_children=1,\n",
+    "    specs_heterogeneous={\n",
+    "        \"bruttolohn_m\": [[0.0, 0.0, 0.0]],\n",
+    "        \"geburtsjahr\": [[1980, 1980, 2024]],\n",
+    "        \"geburtsmonat\": [[1, 1, 7]],\n",
+    "        \"alter\": [[44, 44, 0]],\n",
+    "        \"elterngeld_claimed\": [[True, False, False]],  # First adult claims Elterngeld\n",
+    "    },\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then, we add `elterngeld_nettoeinkommen_vorjahr_m` to the data based on step 2."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Add net wage approximation\n",
+    "data_after_birth[\"elterngeld_nettoeinkommen_vorjahr_m\"] = net_wage_approximation[\n",
+    "    \"elterngeld_nettolohn_approximation_m\"\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then, we compute Elterngeld using the policy environment of the child's birthday."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "params_2024, functions_2024 = set_up_policy_environment(\"2024-07-01\")\n",
+    "\n",
+    "# Compute Elterngeld\n",
+    "results = compute_taxes_and_transfers(\n",
+    "    data=data_after_birth,\n",
+    "    functions=functions_2024,\n",
+    "    params=params_2024,\n",
+    "    targets=[\"elterngeld_m\"],\n",
+    ")\n",
+    "\n",
+    "results"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/how_to_guides/index.md

@@ -11,4 +11,5 @@ maxdepth: 1
 ---
 different_ways_to_load_policy_functions
 visualizing_the_system
+calculating_elterngeld
 ```

src/_gettsim/config.py

@@ -131,6 +131,7 @@ def set_array_backend(backend: str):
     "eink_st_y_sn",
     "soli_st_y_sn",
     "abgelt_st_y_sn",
+    "elterngeld_m",
     "sozialv_beitr_arbeitnehmer_m",
     "ges_rentenv_beitr_arbeitnehmer_m",
     "arbeitsl_v_beitr_arbeitnehmer_m",
@@ -171,6 +172,8 @@ def set_array_backend(backend: str):
     "eink_selbst_m": float,
     "in_priv_krankenv": bool,
     "priv_rentenv_beitr_m": float,
+    "elterngeld_nettoeinkommen_vorjahr_m": float,
+    "elterngeld_zu_verst_eink_vorjahr_y_sn": float,
     "bruttolohn_vorj_m": float,
     "arbeitsstunden_w": float,
     "geburtsjahr": int,
@@ -191,9 +194,8 @@ def set_array_backend(backend: str):
     "monat_renteneintr": int,
     "behinderungsgrad": int,
     "wohnfläche_hh": float,
-    "m_elterngeld": int,
-    "m_elterngeld_vat_hh": int,
-    "m_elterngeld_mut_hh": int,
+    "monate_elterngeldbezug": int,
+    "elterngeld_claimed": bool,
     "in_ausbildung": bool,
     "alleinerz": bool,
     "bewohnt_eigentum_hh": bool,