Remove tax unit groupings.

CHANGES.md

@@ -8,6 +8,8 @@ releases are available on [Anaconda.org](https://anaconda.org/conda-forge/gettsi
 
 - {gh}`700` Data columns overwrite functions regardless of time unit
   ({ghuser}`lars-reimann`).
+- {gh}`694` Replace `tu` groupings with correct groupings. ({ghuser}`MImmesberger`,
+  {ghuser}`lars-reimann`, {ghuser}`hmgaudecker`).
 - {gh}`676` Add explicit parent-child links. ({ghuser}`MImmesberger`).
 - {gh}`684` New Issue template for yearly parameter updates. ({ghuser}`MImmesberger`).
 - {gh}`680` 2024 Parameter Update ({ghuser}`Eric-Sommer`, {ghuser}`MImmesberger`)

docs/geps/gep-01.md

@@ -42,7 +42,7 @@ a nutshell and without explanations, these conventions are:
      Internal variables should be used sparingly.
 
 1. If names need to be concatenated for making clear what a column name refers to (e.g.,
-   `arbeitsl_geld_2_vermög_freib_bg` vs. `grunds_im_alter_vermög_freib_hh`), the group
+   `arbeitsl_geld_2_vermög_freib_bg` vs. `grunds_im_alter_vermög_freib_eg`), the group
    (i.e., the tax or transfer) that a variable refers to appears first.
 
 1. Because of the necessity of concatenated column names, there will be conflicts
@@ -112,15 +112,15 @@ changed, even if it leads to long variable names (e.g., `kinderfreib`,
 less error-prone.
 
 If names need to be concatenated for making clear what a column name refers to (e.g.,
-`arbeitsl_geld_2_vermög_freib_bg` vs. `grunds_im_alter_vermög_freib_hh`), the group
+`arbeitsl_geld_2_vermög_freib_bg` vs. `grunds_im_alter_vermög_freib_eg`), the group
 (i.e., the tax or transfer) that a variable refers to appears first.
 
 If a column has a reference to a time unit (i.e., any flow variable like earnings or
 transfers), a column is indicated by an underscore plus one of {`y`, `m`, `w`, `d`}.
 
-The default unit a column refers to is an individual. In case a household or tax unit is
-the relevant unit, an underscore plus one of {`sn`, `hh`, `fg`, `bg`} will indicate the
-level of aggregation.
+The default unit a column refers to is an individual. In case of groupings of
+individuals, an underscore plus one of {`sn`, `hh`, `fg`, `bg`} will indicate the level
+of aggregation.
 
 GETTSIM knows about the following units:
 

docs/geps/gep-02.md

@@ -26,9 +26,9 @@ in the data provided by the user (if it comes in the form of a DataFrame) or cal
 by GETTSIM. All these arrays have the same length. This length corresponds to the number
 of individuals. Functions operate on a single row of data.
 
-If a column name is `[x]_id` with `x` {math}`\in \{` `hh`, `tu` {math}`\}`, it will be
-the same for all households, tax units, or any other grouping of individuals specified
-in {ref}`GEP 1 <gep-1-column-names>`.
+If a column name is `[x]_id` with `x` {math}`\in \{` `_hh`, `_bg`, `_fg`, `_ehe`, `_eg`,
+`_sn` {math}`\}`, it will be the same for all households, Bedarfsgemeinschaften, or any
+other grouping of individuals specified in {ref}`GEP 1 <gep-1-column-names>`.
 
 Any other column name ending in `_id` indicates a link to a different individual (e.g.,
 child-parent relations could be `parent_0_ind_id`, `parent_1_ind_id`; receiver of child
@@ -57,8 +57,9 @@ N-dimensional arrays, etc.. As usual, everything involves trade-offs, for exampl
 - Modern tools for vectorization (e.g., Jax) scale best when working with single rows of
   data.
 
-  Aggregation to groups of individuals (households, tax units) or referencing data from
-  other rows (parents, receiver of child benefits) is not trivial with these tools.
+  Aggregation to groups of individuals (households, Bedarfsgemeinschaften,...) or
+  referencing data from other rows (parents, receiver of child benefits) is not trivial
+  with these tools.
 
 ## Usage and Impact
 
@@ -113,24 +114,26 @@ that case, only the relevant steps apply.
 ### Grouped values and aggregation functions
 
 Often columns refer to groups of individuals. Such columns have a suffix indicating the
-group (see {ref}`GEP 1 <gep-1-column-names>`, currently `_hh` or `_tu`). These columns'
-values will be repeated for all individuals who form part of a group.
+group (see {ref}`GEP 1 <gep-1-column-names>`, currently `_hh`, `_bg`, `_fg`, `_ehe`,
+`_eg`, and `_sn`). These columns' values will be repeated for all individuals who form
+part of a group.
 
 By default, GETTSIM will check consistency on input columns in this respect. Users will
 be able to turn this check off.
 
 Aggregation functions will be provided by GETTSIM.
 
-- Aggregation will always start from the individual level. If aggregation from, say, tax
-  unit to household is required (and possible), users will first need to provide an
-  appropriate individual-level column (e.g., by dividing some tax unit-level aggregate
-  by the number of members in the tax unit)
+- Aggregation will always start from the individual level. If aggregation at the, say,
+  Bedarfsgemeinschaft-level to the household-level is required (and possible), users
+  will first need to provide an appropriate individual-level column (e.g., by dividing
+  some Bedarfsgemeinschaft-level aggregate by the number of indviduals within the same
+  Bedarfsgemeinschaft)
 
 - As outlined in {ref}`GEP 4 <gep-4-aggregation-by-group-functions>` users will need to
   specify:
 
   - The stringified name of the aggregated variable. This **must** end with a feasible
-    unit of aggregation, i.e., `_hh` or `_tu`
+    unit of aggregation, i.e., `_hh`, `_bg`, `_fg`, `_ehe`, `_eg`, or `_sn`
   - The stringified name of the original variable.
   - The type of aggregation {math}`\in \{` `sum`, `mean`, `max`, `min`, `any` {math}`\}`
 

docs/geps/gep-04.md

@@ -63,7 +63,7 @@ GETTSIM; this is irrelevant for the DAG.
 Function arguments can be of three kinds:
 
 - User-provided input variables (e.g., `bruttolohn_m`).
-- Outputs of other functions in the taxes and transfers system (e.g., `eink_st_y_tu`).
+- Outputs of other functions in the taxes and transfers system (e.g., `eink_st_y_sn`).
 - Parameters of the taxes and transfers system, which are pre-defined and always end in
   `_params` (e.g., `ges_rentenv_params`).
 
@@ -80,43 +80,44 @@ is able to replace this function with her own version.
 See the following example for capital income taxes.
 
 ```python
-def abgelt_st_y_tu(zu_verst_kapitaleink_y_tu: float, abgelt_st_params: dict) -> float:
-    """Calculate Abgeltungssteuer on tax unit level.
+def abgelt_st_y_sn(zu_verst_kapitaleink_y_sn: float, abgelt_st_params: dict) -> float:
+    """Calculate Abgeltungssteuer on Steuernummer-level.
 
     Parameters
     ----------
-    zu_verst_kapitaleink_y_tu
-        See :func:`zu_verst_kapitaleink_y_tu`.
+    zu_verst_kapitaleink_y_sn
+        See :func:`zu_verst_kapitaleink_y_sn`.
     abgelt_st_params
         See params documentation :ref:`abgelt_st_params <abgelt_st_params>`.
 
     Returns
     -------
 
     """
-    return abgelt_st_params["satz"] * zu_verst_kapitaleink_y_tu
+    return abgelt_st_params["satz"] * zu_verst_kapitaleink_y_sn
 ```
 
-The function {func}`abgelt_st_y_tu` requires the variable `zu_verst_kapital_eink_y_tu`,
-which is the amount of taxable capital income on tax unit level (the latter is implied
-by the `_tu` suffix, see {ref}`gep-1`). `zu_verst_kapital_eink_y_tu` must be provided by
-the user as a column of the input data or it has to be the name of another function.
-`abgelt_st_params` is a dictionary of parameters related to the calculation of
-`abgelt_st_y_tu`.
+The function {func}`abgelt_st_y_sn` requires the variable `zu_verst_kapital_eink_y_sn`,
+which is the amount of taxable capital income on the Steuernummer-level (the latter is
+implied by the `_sn` suffix, see {ref}`gep-1`). `zu_verst_kapital_eink_y_sn` must be
+provided by the user as a column of the input data or it has to be the name of another
+function. It is also possible to specify `zu_verst_kapital_eink_y` and aggregation to
+the `sn`-level will happen automatically. `abgelt_st_params` is a dictionary of
+parameters related to the calculation of `abgelt_st_y_sn`.
 
 Another function, say
 
 ```python
-def soli_st_y_tu(
-    eink_st_mit_kinderfreib_y_tu: float,
-    anz_erwachsene_tu: int,
-    abgelt_st_y_tu: float,
+def soli_st_y_sn(
+    eink_st_mit_kinderfreib_y_sn: float,
+    anz_personen_sn: int,
+    abgelt_st_y_sn: float,
     soli_st_params: dict,
 ) -> float: ...
 ```
 
-may use `abgelt_st_y_tu` as an input argument. The DAG backend ensures that the function
-`abgelt_st_y_tu` will be executed first.
+may use `abgelt_st_y_sn` as an input argument. The DAG backend ensures that the function
+`abgelt_st_y_sn` will be executed first.
 
 Note that the type annotations (e.g. `float`) indicate the expected type of each input
 and the output of a function, see {ref}`gep-2`.
@@ -223,13 +224,13 @@ For example, in `demographic_vars.py`, we could have:
 
 ```
 aggregate_by_group_demographic_vars = {
-    "anz_erwachsene_tu": {"source_col": "erwachsen", "aggr": "sum"},
-    "haushaltsgröße_hh": {"aggr": "count"},
+    "anz_kinder_hh": {"source_col": "kind", "aggr": "sum"},
+    "anz_personen_hh": {"aggr": "count"},
 }
 ```
 
-The group identifier (`tu_id`, `hh_id`) will be automatically included as an argument;
-for `count` no other variable is necessary.
+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 output type will be the same as the input type. Exceptions:
 

docs/gettsim_objects/input_variables.md

@@ -14,14 +14,6 @@ Household identifier
 
 Type: int
 
-(tu_id)=
-
-## `tu_id`
-
-Tax Unit identifier (married couples + kids)
-
-Type: int
-
 (kind)=
 
 ## `kind`
@@ -70,6 +62,54 @@ Single parent
 
 Type: bool
 
+(gemeinsam_veranlagt)=
+
+## `gemeinsam_veranlagt`
+
+Taxes are filed jointly
+
+Type: bool
+
+(p_id_elternteil_1)=
+
+## `p_id_elternteil_1`
+
+Identifier of the first parent
+
+Type: int
+
+(p_id_elternteil_2)=
+
+## `p_id_elternteil_2`
+
+Identifier of the second parent
+
+Type: int
+
+(p_id_ehepartner)=
+
+## `p_id_ehepartner`
+
+Identifier of married partner
+
+Type: int
+
+(p_id_einstandspartner)=
+
+## `p_id_einstandspartner`
+
+Identifier of Einstandspartner
+
+Type: int
+
+(p_id_einstandspartner)=
+
+## `p_id_kindergeld_empf`
+
+Identifier of person that claims Kindergeld for the particular child
+
+Type: int
+
 (wohnort_ost)=
 
 ## `wohnort_ost`
@@ -126,6 +166,14 @@ Monthly childcare expenses for a particular child under the age of 14
 
 Type: float
 
+(p_id_betreuungsk_träger)=
+
+## `p_id_betreuungsk_träger`
+
+Identifier of the person who paid childcare expenses.
+
+Type: float
+
 (sonstig_eink_m)=
 
 ## `sonstig_eink_m`
@@ -303,9 +351,9 @@ Construction year of dwelling
 
 Type: int
 
-(vermögen_bedürft_hh)=
+(vermögen_bedürft_bg)=
 
-## `vermögen_bedürft_hh`
+## `vermögen_bedürft_bg`
 
 Assets for means testing of
 household.{ref}`See this page for more details. <means_testing>`

docs/gettsim_objects/means_testing.md

@@ -10,7 +10,7 @@ This documentation shall help to understand the composition of the
 
 {ref}`basic input variable <input_variables>`
 
-'vermögen_bedürft_hh'. Despite small differences over the transfers, we decided, for
+'vermögen_bedürft_bg'. Despite small differences over the transfers, we decided, for
 now, to require only one wealth variable as input and use it for all transfers.
 
 ```{note}

docs/gettsim_objects/variables_out.md

@@ -20,14 +20,14 @@ You can find their individual calculation in the documentation of all {ref}`func
   - Monthly amount of unemployment assistance
 * - {func}`entgeltp_update <_gettsim.functions.entgeltp_update>`
   - Updated earning points for pension claim
-* - {func}`abgelt_st_y_tu <_gettsim.functions.abgelt_st_y_tu>`
-  - Capital income tax on tax unit level
-* - {func}`soli_st_y_tu <_gettsim.functions.soli_st_y_tu>`
-  - Solidarity surcharge on tax unit level
+* - {func}`abgelt_st_y_sn <_gettsim.functions.abgelt_st_y_sn>`
+  - Capital income tax on Steuernummer level
+* - {func}`soli_st_y_sn <_gettsim.functions.soli_st_y_sn>`
+  - Solidarity surcharge on Steuernummer level
 * - {func}`kindergeld_m <_gettsim.functions.kindergeld_m>`
   - Monthly child benefit
-* - {func}`eink_st_y_tu <_gettsim.functions.eink_st_y_tu>`
-  - Income Tax on tax unit level
+* - {func}`eink_st_y_sn <_gettsim.functions.eink_st_y_sn>`
+  - Income Tax on Steuernummer level
 * - {func}`lohnst_m` <_gettsim.functions.lohnst_m>`
   - Withholding tax
 * - {func}`soli_st_lohnst_m <_gettsim.functions.soli_st_lohnst_m>`
@@ -42,6 +42,6 @@ You can find their individual calculation in the documentation of all {ref}`func
   - Monthly parental leave benefit
 * - {func}`wohngeld_m_hh <_gettsim.functions.wohngeld_m_hh>`
   - Monthly housing benefit on household level
-* - {func}`grunds_im_alter_m_hh <_gettsim.functions.grunds_im_alter_m_hh>`
+* - {func}`grunds_im_alter_m_eg <_gettsim.functions.grunds_im_alter_m_eg>`
   - Monthly subsistence payment for retirees on household level
 ```

docs/how_to_guides/different_ways_to_load_policy_functions.ipynb

@@ -42,7 +42,7 @@
    "source": [
     "## A Single Function\n",
     "\n",
-    "One way to pass a single function to the tax and transfer system is alongside the `policy_functions`. As an example, we create a function called `kindergeld_m_hh`. The function has no body because it is irrelevant for this guide. The function can be passed to `compute_taxes_and_transfers` alongside the `policy_functions` by placing both objects in a list."
+    "One way to pass a single function to the tax and transfer system is alongside the `policy_functions`. As an example, we create a function called `kindergeld_m`. The function has no body because it is irrelevant for this guide. The function can be passed to `compute_taxes_and_transfers` alongside the `policy_functions` by placing both objects in a list."
    ]
   },
   {
@@ -51,7 +51,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def kindergeld_m_hh():\n",
+    "def kindergeld_m():\n",
     "    pass"
    ]
   },
@@ -65,8 +65,8 @@
     "df = compute_taxes_and_transfers(\n",
     "    data=data,\n",
     "    params=policy_params,\n",
-    "    functions=[policy_functions, kindergeld_m_hh],\n",
-    "    targets=\"kindergeld_m\",\n",
+    "    functions=[policy_functions, kindergeld_m],\n",
+    "    targets=\"kindergeld_m_hh\",\n",
     ")\n",
     "```\n",
     "\n",
@@ -76,12 +76,12 @@
     "\n",
     "2. In general, if there are multiple functions with the same name, internal functions have the lowest precedence. After that, the elements in the list passed to the `functions` argument are evaluated element by element. The leftmost element has the lowest precedence and the rightmost element the highest.\n",
     "\n",
-    "3. If `policy_functions` would not be necessary for this example, you can also directly pass the `kindergeld_m_hh` function to the `functions` argument.\n",
+    "3. If `policy_functions` would not be necessary for this example, you can also directly pass the `kindergeld_m` function to the `functions` argument.\n",
     "\n",
     "   ```python\n",
     "   df = compute_taxes_and_transfers(\n",
     "       ...,\n",
-    "       functions=kindergeld_m_hh,\n",
+    "       functions=kindergeld_m,\n",
     "       ...,\n",
     "   )\n",
     "   ```\n",