Unterhaltsvorschuss calculation on child level. (#739)

Closes #735

---------

Co-authored-by: Christian Zimpelmann <[email protected]>

Author: MImmesberger

CHANGES.md

@@ -6,6 +6,7 @@ releases are available on [Anaconda.org](https://anaconda.org/conda-forge/gettsi
 
 ## Unpublished
 
+- {gh}`739` Unterhaltsvorschuss calculation on child level ({ghuser}`MImmesberger`).
 - {gh}`722` Join columns to make target columns available at source level
   ({ghuser}`lars-reimann`).
 - {gh}`732` Change wealth input variable to individual-level (`vermögen_bedürft`)

docs/gettsim_objects/input_variables.md

@@ -477,7 +477,7 @@ Type: float
 ## `m_alg1_übergang`
 
 Total months of unemployment (only timeof Entgeltersatzleistungen, not ALGII),i.e.
-Arbeitslosengeld, Unterhaltsgeld,Übergangsgeld
+Arbeitslosengeld, Unterhaltsgeld, Übergangsgeld
 
 Type: float
 
@@ -599,13 +599,14 @@ Type: float
 
 ## `kind_unterh_anspr_m`
 
-Monthly gross child alimony payments to be received as determined by the court
+Monthly gross child alimony payments to be received as determined by the court on child
+level
 
 Type: float
 
 ## `kind_unterh_erhalt_m`
 
-Monthly actual child alimony payments received
+Monthly actual child alimony payments received on child level
 
 Type: float
 

src/_gettsim/transfers/unterhaltsvors.py

@@ -6,21 +6,22 @@
 from _gettsim.shared import join_numpy, policy_info
 
 aggregate_by_p_id_unterhaltsvors = {
-    "_unterhaltsvors_anspruch_eltern_m": {
+    "unterhaltsvors_zahlbetrag_eltern_m": {
         "p_id_to_aggregate_by": "p_id_kindergeld_empf",
-        "source_col": "_unterhaltsvors_anspruch_pro_kind_m",
+        "source_col": "unterhaltsvors_m",
         "aggr": "sum",
     },
 }
 
 
 @policy_info(params_key_for_rounding="unterhaltsvors")
 def unterhaltsvors_m(
-    alleinerz: bool,
     kind_unterh_erhalt_m: float,
-    _unterhaltsvors_anspruch_eltern_m: float,
+    _unterhaltsvors_anspruch_kind_m: float,
+    parent_alleinerz: bool,
 ) -> float:
-    """Advance alimony payments (Unterhaltsvorschuss).
+    """Advance alimony payments (Unterhaltsvorschuss) on child level after deducting
+    alimonies.
 
     Single Parents get alimony payments for themselves and for their child from the ex
     partner. If the ex partner is not able to pay the child alimony, the government pays
@@ -38,26 +39,53 @@ def unterhaltsvors_m(
 
     Parameters
     ----------
-    alleinerz
-        See basic input variable :ref:`alleinerz <alleinerz>`.
     kind_unterh_erhalt_m
         See :func:`kind_unterh_erhalt_m`.
-    _unterhaltsvors_anspruch_eltern_m
-        See :func:`_unterhaltsvors_anspruch_eltern_m`.
+    _unterhaltsvors_anspruch_kind_m
+        See :func:`_unterhaltsvors_anspruch_kind_m`.
+    parent_alleinerz
+        See :func:`parent_alleinerz`.
 
     Returns
     -------
 
     """
-
-    if alleinerz:
-        out = max(_unterhaltsvors_anspruch_eltern_m - kind_unterh_erhalt_m, 0.0)
+    if parent_alleinerz:
+        out = max(_unterhaltsvors_anspruch_kind_m - kind_unterh_erhalt_m, 0.0)
     else:
         out = 0.0
 
     return out
 
 
+@policy_info(skip_vectorization=True)
+def parent_alleinerz(
+    p_id_kindergeld_empf: np.ndarray[int],
+    p_id: np.ndarray[int],
+    alleinerz: np.ndarray[bool],
+) -> np.ndarray[bool]:
+    """Check if parent that receives Unterhaltsvorschuss is a single parent.
+
+    Only single parents receive Unterhaltsvorschuss.
+
+    Parameters
+    ----------
+    p_id_kindergeld_empf
+        See basic input variable :ref:`p_id_kindergeld_empf`.
+    p_id
+        See basic input variable :ref:`p_id`.
+    alleinerz
+        See basic input variable :ref:`alleinerz`.
+
+    Returns
+    -------
+
+    """
+    return join_numpy(
+        p_id_kindergeld_empf, p_id, alleinerz, value_if_foreign_key_is_missing=False
+    )
+
+
 @policy_info(start_date="2023-01-01", name_in_dag="_kindergeld_erstes_kind_m")
 def _kindergeld_erstes_kind_ohne_staffelung_m(
     kindergeld_params: dict,
@@ -102,14 +130,14 @@ def _kindergeld_erstes_kind_gestaffelt_m(
     return kindergeld_params["kindergeld"][1]
 
 
-def _unterhaltsvors_anspruch_pro_kind_m(
+def _unterhaltsvors_anspruch_kind_m(
     alter: int,
     _unterhaltsvorschuss_empf_eink_above_income_threshold: bool,
     _kindergeld_erstes_kind_m: float,
     unterhalt_params: dict,
     unterhaltsvors_params: dict,
 ) -> float:
-    """Claim for advance on alimony payment (Unterhaltsvorschuss) per child.
+    """Claim for advance on alimony payment (Unterhaltsvorschuss) on child level.
 
     Parameters
     ----------
@@ -157,7 +185,8 @@ def _unterhaltsvorschuss_empf_eink_above_income_threshold(
     p_id: np.ndarray[int],
     _unterhaltsvorschuss_eink_above_income_threshold: np.ndarray[bool],
 ) -> np.ndarray[bool]:
-    """Income of Unterhaltsvorschuss recipient above threshold.
+    """Income of Unterhaltsvorschuss recipient above threshold (this variable is
+    defined on child level).
 
     Parameters
     ----------

src/_gettsim_tests/test_data/unterhaltsvors/2018-1/hh_id_5.yaml

@@ -60,6 +60,9 @@ inputs:
       - 0.0
   assumed: {}
 outputs:
+  parent_alleinerz:
+    - false
+    - true
   unterhaltsvors_m:
-    - 205
-    - 0
+    - 0.0
+    - 205.0

src/_gettsim_tests/test_data/unterhaltsvors/2019-1/older_child_parent_with_income.yaml

@@ -78,7 +78,11 @@ inputs:
       - 0.0
   assumed: {}
 outputs:
+  parent_alleinerz:
+    - false
+    - true
+    - true
   unterhaltsvors_m:
-    - 494
-    - 0
-    - 0
+    - 0.0
+    - 212.0
+    - 282.0

src/_gettsim_tests/test_data/unterhaltsvors/2019-1/older_child_parent_without_income.yaml

@@ -78,7 +78,11 @@ inputs:
       - 0.0
   assumed: {}
 outputs:
+  parent_alleinerz:
+    - false
+    - true
+    - true
   unterhaltsvors_m:
-    - 212
-    - 0
-    - 0
+    - 0.0
+    - 212.0
+    - 0.0

src/_gettsim_tests/test_data/unterhaltsvors/2019-1/young_child_parent_without_income.yaml

@@ -78,7 +78,11 @@ inputs:
       - 0.0
   assumed: {}
 outputs:
+  parent_alleinerz:
+    - false
+    - true
+    - true
   unterhaltsvors_m:
-    - 372
-    - 0
-    - 0
+    - 0.0
+    - 160.0
+    - 212.0

src/_gettsim_tests/test_data/unterhaltsvors/2019-8/hh_id_1.yaml

@@ -60,6 +60,9 @@ inputs:
       - 0.0
   assumed: {}
 outputs:
+  parent_alleinerz:
+    - false
+    - true
   unterhaltsvors_m:
-    - 202
-    - 0
+    - 0.0
+    - 202.0