Wohngeld on individual / BG level

docs/geps/gep-01.md

@@ -125,16 +125,22 @@ of aggregation.
 GETTSIM knows about the following units:
 
 - `p_id`: person identifier
-- `sn_id`: Steuernummer (same for spouses filing taxes jointly, not the same as the
-  Germany-wide Steuer-ID)
 - `hh_id`: Haushalt, the relevant unit for Wohngeld. Encompasses more people than the
   Bedarfsgemeinschaft (e.g., possibly more than 2 generations).
+- `wthh_id`: Wohngeldrechtlicher Teilhaushalt, i.e. members of a household for whom the
+  priority check for Wohngeld/ALG2 yields the same result. This unit is based on the
+  priority check via `wohngeld_vorrang_bg` and `wohngeld_kinderzuschl_vorrang_bg`.
 - `fg_id`: Familiengemeinschaft. Maximum of two generations, the relevant unit for
   Bürgergeld / Arbeitslosengeld 2. Another way to think about this is the potential
   Bedarfsgemeinschaft before making checks for whether children have enough income fend
   for themselves. Subset of `hh`.
 - `bg_id`: Bedarfsgemeinschaft, i.e., Familiengemeinschaft plus for whether children
   have enough income to fend for themselves. Subset of `fg_id`.
+- `eg_id`: Einstandsgemeinschaft, a couple whose members are deemed to be responsible
+  for each other.
+- `ehe_id`: Ehegemeinschaft, i.e. couples that are married or in a civil union.
+- `sn_id`: Steuernummer (same for spouses filing taxes jointly, not the same as the
+  Germany-wide Steuer-ID)
 
 Note that households do not include flat shares etc.. Such broader definition are
 currently not relevant in GETTSIM but may be added in the future (e.g., capping rules
@@ -159,7 +165,7 @@ general naming considerations here.
 - Parameter names should be generally be aligned with relevant column names. However,
   since the group is not repeated for the parameter, it is often better not to
   abbreviate them (e.g., `wohngeld_params["vermögensgrundfreibetrag"]` for the parameter
-  and `wohngeld_nach_vermög_check_m_hh` for a column derived from it).
+  and `_wohngeld_nach_vermög_check_m_wthh` for a column derived from it).
 
 ## Other Python identifiers (Functions, Variables)
 

docs/geps/gep-04.md

@@ -229,8 +229,8 @@ aggregate_by_group_demographic_vars = {
 }
 ```
 
-The group identifier (`hh_id`, `sn_id`, `fg_id`, `bg_id`, `eg_id`, `ehe_id`) will be
-automatically included as an argument; for `count` nothing else is necessary.
+The group identifier (`hh_id`, `wthh_id`, `fg_id`, `bg_id`, `eg_id`, `ehe_id`, `sn_id`)
+will be automatically included as an argument; for `count` nothing else is necessary.
 
 The output type will be the same as the input type. Exceptions:
 

docs/gettsim_objects/variables_out.md

@@ -40,7 +40,7 @@ You can find their individual calculation in the documentation of all {ref}`func
   - Monthly additional child benefit, household sum
 * - {func}`elterngeld_m <_gettsim.functions.elterngeld_m>`
   - Monthly parental leave benefit
-* - {func}`wohngeld_m_hh <_gettsim.functions.wohngeld_m_hh>`
+* - {func}`wohngeld_m_wthh <_gettsim.functions.wohngeld_m_wthh>`
   - Monthly housing benefit on household level
 * - {func}`grunds_im_alter_m_eg <_gettsim.functions.grunds_im_alter_m_eg>`
   - Monthly subsistence payment for retirees on household level

docs/tutorials/policy_functions.ipynb

@@ -77,15 +77,15 @@
    "source": [
     "def arbeitsl_geld_2_m_bg(\n",
     "    arbeitsl_geld_2_vor_vorrang_m_bg,\n",
-    "    # wohngeld_vorrang_hh,\n",
+    "    # wohngeld_vorrang_bg,\n",
     "    # kinderzuschl_vorrang_bg,\n",
-    "    # wohngeld_kinderzuschl_vorrang_hh,\n",
+    "    # wohngeld_kinderzuschl_vorrang_bg,\n",
     "    erwachsene_alle_rentner_hh,\n",
     "):\n",
     "    if (\n",
-    "        # wohngeld_vorrang_hh\n",
+    "        # wohngeld_vorrang_bg\n",
     "        # | kinderzuschl_vorrang_bg\n",
-    "        # | wohngeld_kinderzuschl_vorrang_hh\n",
+    "        # | wohngeld_kinderzuschl_vorrang_bg\n",
     "        erwachsene_alle_rentner_hh\n",
     "    ):\n",
     "        out = 0.0\n",
@@ -166,9 +166,15 @@
    "source": [
     "For this data we can now compare the results of using GETTSIM with the `policy_functions_no_check` and the usual `policy_functions`. \n",
     "\n",
-    "We should expect to see positive values for `wohngeld_m_hh`, `kinderzuschl_m_bg` and `arbeitsl_geld_2_m_bg` at the same time if we do not check which combination of transfers is optimal (`policy_functions_no_check`).\n",
+    "We should expect to see positive values for `wohngeld_m_wthh`, `kinderzuschl_m_bg` and\n",
+    "`arbeitsl_geld_2_m_bg` at the same time if we do not check which combination of\n",
+    "transfers is optimal (`policy_functions_no_check`).\n",
     "\n",
-    "On the other hand, if we use the default version of the `policy_functions`, `wohngeld_m_hh` and `kinderzuschl_m_bg` should be zero as long as `arbeitsl_geld_2_m_bg` is positive (and the other way around), as it is a characteristic of the German taxes and transfers system that *Wohngeld* and *Kinderzuschlag* cannot be received in combination with *Arbeitslosengeld 2*."
+    "On the other hand, if we use the default version of the `policy_functions`,\n",
+    "`wohngeld_m_wthh` and `kinderzuschl_m_bg` should be zero as long as\n",
+    "`arbeitsl_geld_2_m_bg` is positive (and the other way around), as it is a characteristic\n",
+    "of the German taxes and transfers system that *Wohngeld* and *Kinderzuschlag* cannot be\n",
+    "received in combination with *Arbeitslosengeld 2*."
    ]
   },
   {
@@ -177,7 +183,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "targets = [\"wohngeld_m_hh\", \"kinderzuschl_m_bg\", \"arbeitsl_geld_2_m_bg\"]"
+    "targets = [\"wohngeld_m_wthh\", \"kinderzuschl_m_bg\", \"arbeitsl_geld_2_m_bg\"]"
    ]
   },
   {
@@ -235,7 +241,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "On first glance, both figures look quite confusing because of the complexity of the German taxes and transfers system. But if we take a closer look, the figures confirm our expectations. If we let GETTSIM check for the most favorable combination of transfers, ```wohngeld_m_hh``` and ```kinderzuschl_m_bg``` are zero as long as `arbeitsl_geld_2_m_bg` is positive (i.e. the best option for the household) and the other way around. \n",
+    "On first glance, both figures look quite confusing because of the complexity of the German taxes and transfers system. But if we take a closer look, the figures confirm our expectations. If we let GETTSIM check for the most favorable combination of transfers, ```wohngeld_m_wthh``` and ```kinderzuschl_m_bg``` are zero as long as `arbeitsl_geld_2_m_bg` is positive (i.e. the best option for the household) and the other way around. \n",
     "\n",
     "If we do not let GETTSIM do this check, this does not hold any longer and all transfers can be positive at the same time (which is what we were trying to achieve). \n",
     "\n",
@@ -255,7 +261,7 @@
     "    params=policy_params,\n",
     "    functions=[policy_functions, arbeitsl_geld_2_m_bg],\n",
     "    targets=[\n",
-    "        \"wohngeld_m_hh\",\n",
+    "        \"wohngeld_m_wthh\",\n",
     "        \"kinderzuschl_m_bg\",\n",
     "        \"arbeitsl_geld_2_m_bg\",\n",
     "    ],\n",
@@ -363,7 +369,7 @@
     "    params=policy_params,\n",
     "    functions=[policy_functions, arbeitsl_geld_2_m_bg, kindergeld_m],\n",
     "    targets=[\n",
-    "        \"wohngeld_m_hh\",\n",
+    "        \"wohngeld_m_wthh\",\n",
     "        \"kinderzuschl_m_bg\",\n",
     "        \"arbeitsl_geld_2_m_bg\",\n",
     "        \"kindergeld_m\",\n",

src/_gettsim/config.py

@@ -75,6 +75,12 @@ def set_array_backend(backend: str):
         " unit for Wohngeld.",
         "potentially_endogenous": False,
     },
+    "wthh": {
+        "name": "wohngeldrechtlicher Teilhaushalt",
+        "description": "Members of a household for whom the Wohngeld priority check "
+        "yields the same result.",
+        "potentially_endogenous": True,
+    },
     "fg": {
         "name": "Familiengemeinschaft",
         "description": "Maximum of two generations, the relevant base unit for"
@@ -88,20 +94,21 @@ def set_array_backend(backend: str):
         " to fend for themselves. Relevant unit for Bürgergeld / Arbeitslosengeld 2",
         "potentially_endogenous": True,
     },
-    "sn": {
-        "name": "Steuernummer",
-        "description": "Spouses filing taxes jointly or individuals.",
+    "eg": {
+        "name": "Einstandsgemeinschaft / Einstandspartner",
+        "description": "A couple whose members are deemed to be responsible for each"
+        " other.",
         "potentially_endogenous": True,
     },
     "ehe": {
         "name": "Ehepartner",
         "description": "Couples that are either married or in a civil union.",
         "potentially_endogenous": True,
     },
-    "eg": {
-        "name": "Einstandsgemeinschaft / Einstandspartner",
-        "description": "A couple whose members are deemed to be responsible for each"
-        " other.",
+    "sn": {
+        "name": "Steuernummer",
+        "description": "Spouses filing taxes jointly or individuals.",
+        "potentially_endogenous": True,
     },
 }
 
@@ -133,7 +140,7 @@ def set_array_backend(backend: str):
     "kindergeld_m",
     "arbeitsl_geld_2_m_bg",
     "kinderzuschl_m_bg",
-    "wohngeld_m_hh",
+    "wohngeld_m_wthh",
     "unterhaltsvors_m",
     "grunds_im_alter_m_eg",
     "ges_rente_m",

src/_gettsim/groupings.py

@@ -11,6 +11,7 @@
         "eg_id": eg_id_numpy,
         "ehe_id": ehe_id_numpy,
         "sn_id": sn_id_numpy,
+        "wthh_id": wthh_id_numpy,
     }
 
 
@@ -211,3 +212,21 @@
         next_sn_id += 1
 
     return numpy.asarray(result)
+
+
+def wthh_id_numpy(
+    hh_id: numpy.ndarray[int],
+    wohngeld_vorrang_bg: numpy.ndarray[bool],
+    wohngeld_kinderzuschl_vorrang_bg: numpy.ndarray[bool],
+) -> numpy.ndarray[int]:
+    """
+    Compute the ID of the wohngeldrechtlicher Teilhaushalt.
+    """
+    result = []
+    for index, current_hh_id in enumerate(hh_id):
+        if wohngeld_vorrang_bg[index] or wohngeld_kinderzuschl_vorrang_bg[index]:
+            result.append(current_hh_id * 100 + 1)
+        else:
+            result.append(current_hh_id * 100)
+
+    return numpy.asarray(result)

src/_gettsim/parameters/wohngeld.yaml

@@ -1970,7 +1970,12 @@ klimakomponente_m:
     5: 39.20
     jede_weitere_person: 4.8
 rounding:
-  wohngeld_vor_vermög_check_m_hh:
+  wohngeld_vor_vermög_check_m_bg:
+    1970-01-01:
+      base: 1
+      direction: nearest
+      reference: § 19 WoGG Abs.2 Anlage 3
+  wohngeld_vor_vermög_check_m_wthh:
     1970-01-01:
       base: 1
       direction: nearest

src/_gettsim/transfers/arbeitsl_geld_2/arbeitsl_geld_2.py

@@ -3,9 +3,9 @@
 
 def arbeitsl_geld_2_m_bg(
     arbeitsl_geld_2_vor_vorrang_m_bg: float,
-    wohngeld_vorrang_hh: bool,
+    wohngeld_vorrang_bg: bool,
     kinderzuschl_vorrang_bg: bool,
-    wohngeld_kinderzuschl_vorrang_hh: bool,
+    wohngeld_kinderzuschl_vorrang_bg: bool,
     erwachsene_alle_rentner_hh: bool,
 ) -> float:
     """Calculate final monthly subsistence payment on household level.
@@ -16,12 +16,12 @@ def arbeitsl_geld_2_m_bg(
     ----------
     arbeitsl_geld_2_vor_vorrang_m_bg
         See :func:`arbeitsl_geld_2_vor_vorrang_m_bg`.
-    wohngeld_vorrang_hh
-        See :func:`wohngeld_vorrang_hh`.
+    wohngeld_vorrang_bg
+        See :func:`wohngeld_vorrang_bg`.
     kinderzuschl_vorrang_bg
         See :func:`kinderzuschl_vorrang_bg`.
-    wohngeld_kinderzuschl_vorrang_hh
-        See :func:`wohngeld_kinderzuschl_vorrang_hh`.
+    wohngeld_kinderzuschl_vorrang_bg
+        See :func:`wohngeld_kinderzuschl_vorrang_bg`.
     erwachsene_alle_rentner_hh
         See :func:`erwachsene_alle_rentner_hh`.
 
@@ -31,9 +31,9 @@ def arbeitsl_geld_2_m_bg(
 
     """
     if (
-        wohngeld_vorrang_hh
+        wohngeld_vorrang_bg
         or kinderzuschl_vorrang_bg
-        or wohngeld_kinderzuschl_vorrang_hh
+        or wohngeld_kinderzuschl_vorrang_bg
         or erwachsene_alle_rentner_hh
     ):
         out = 0.0
@@ -70,9 +70,9 @@ def arbeitsl_geld_2_regelbedarf_m_bg(
 
 def _arbeitsl_geld_2_alleinerz_mehrbedarf_m_bg(
     alleinerz_bg: bool,
-    anz_kinder_bg: int,
-    anz_kinder_bis_6_bg: int,
-    anz_kinder_bis_15_bg: int,
+    anz_kinder_fg: int,
+    anz_kinder_bis_6_fg: int,
+    anz_kinder_bis_15_fg: int,
     arbeitsl_geld_2_params: dict,
 ) -> float:
     """Compute additional need for single parents.
@@ -87,12 +87,12 @@ def _arbeitsl_geld_2_alleinerz_mehrbedarf_m_bg(
     ----------
     alleinerz_bg
         See :func:`alleinerz_bg`.
-    anz_kinder_bg
-        See :func:`anz_kinder_bg`.
-    anz_kinder_bis_6_bg
-        See :func:`anz_kinder_bis_6_bg`.
-    anz_kinder_bis_15_bg
-        See :func:`anz_kinder_bis_15_bg`.
+    anz_kinder_fg
+        See :func:`anz_kinder_fg`.
+    anz_kinder_bis_6_fg
+        See :func:`anz_kinder_bis_6_fg`.
+    anz_kinder_bis_15_fg
+        See :func:`anz_kinder_bis_15_fg`.
     arbeitsl_geld_2_params
         See params documentation :ref:`arbeitsl_geld_2_params <arbeitsl_geld_2_params>`.
 
@@ -110,13 +110,13 @@ def _arbeitsl_geld_2_alleinerz_mehrbedarf_m_bg(
             max(
                 # Minimal Mehrbedarf share. Minimal rate times number of children
                 arbeitsl_geld_2_params["mehrbedarf_anteil"]["min_1_kind"]
-                * anz_kinder_bg,
+                * anz_kinder_fg,
                 # Special case if 1 kid below 6 or 2,3 below 15.
                 (
                     arbeitsl_geld_2_params["mehrbedarf_anteil"][
                         "kind_unter_7_oder_mehr"
                     ]
-                    if (anz_kinder_bis_6_bg >= 1) or (2 <= anz_kinder_bis_15_bg <= 3)
+                    if (anz_kinder_bis_6_fg >= 1) or (2 <= anz_kinder_bis_15_fg <= 3)
                     else 0.0
                 ),
             ),

src/_gettsim/transfers/arbeitsl_geld_2/arbeitsl_geld_2_eink.py

@@ -3,40 +3,22 @@
 
 
 def arbeitsl_geld_2_eink_m(
-    _arbeitsl_geld_2_eink_ohne_kindergeldübertrag_m: float,
-    kindergeldübertrag_m: float,
-) -> float:
-    """SGB II income.
-
-    Relevant income according to SGB II. Includes child benefit transfer
-    (Kindergeldübertrag).
-
-    Parameters
-    ----------
-    _arbeitsl_geld_2_eink_ohne_kindergeldübertrag_m
-        See :func:`_arbeitsl_geld_2_eink_ohne_kindergeldübertrag_m`.
-    kindergeldübertrag_m
-        See :func:`kindergeldübertrag_m`.
-
-    Returns
-    -------
-    Income according to SGB II.
-
-    """
-    return _arbeitsl_geld_2_eink_ohne_kindergeldübertrag_m + kindergeldübertrag_m
-
-
-def _arbeitsl_geld_2_eink_ohne_kindergeldübertrag_m(
     _arbeitsl_geld_2_nettoeink_ohne_transfers_m: float,
     kind_unterh_erhalt_m: float,
     unterhaltsvors_m: float,
     kindergeld_zur_bedarfsdeckung_m: float,
+    kindergeldübertrag_m: float,
 ) -> float:
-    """SGB II income without Kindergeldübertrag.
+    """SGB II income.
 
-    Relevant income according to SGB II. Does not include child benefit transfer
+    Relevant income according to SGB II. Includes child benefit transfer
     (Kindergeldübertrag).
 
+    Note: When aggregating this target to the household level, deduct
+    `_diff_kindergeld_kindbedarf_m_hh`. This is necessary because the Kindergeld
+    received by the child may enter `arbeitsl_geld_2_eink_m_hh` two times: once as
+    Kindergeld and once as Kindergeldübertrag.
+
     Parameters
     ----------
     _arbeitsl_geld_2_nettoeink_ohne_transfers_m
@@ -47,17 +29,20 @@ def _arbeitsl_geld_2_eink_ohne_kindergeldübertrag_m(
         See :func:`unterhaltsvors_m`.
     kindergeld_zur_bedarfsdeckung_m
         See :func:`kindergeld_zur_bedarfsdeckung_m`.
+    kindergeldübertrag_m
+        See :func:`kindergeldübertrag_m`.
 
     Returns
     -------
-    Income without child benefit transfer.
+    Income according to SGB II.
 
     """
     return (
         _arbeitsl_geld_2_nettoeink_ohne_transfers_m
         + kind_unterh_erhalt_m
         + unterhaltsvors_m
         + kindergeld_zur_bedarfsdeckung_m
+        + kindergeldübertrag_m
     )