euromod_linking.income_lists ============================ .. py:module:: euromod_linking.income_lists .. autoapi-nested-parse:: The standardised ``ils_udb_*`` income lists, and the descriptive names for them. A ``scale`` shock names what it moves. That can be a raw input variable (``yem``), an income list (``ils_udb_yem``), or — because neither of those is how anyone says it out loud — the concept itself: ``"employment income"``. Why the list and not the variable --------------------------------- "Employment income" as an economic concept is not one column. The model's own ``ils_udb_yem`` covers every component EUROMOD counts under that concept, which is country- and extension-specific: 26 distinct data-reported components across the EU-27, and a different subset in each country. Naming the list keeps a shock consistent with the model's own accounting instead of a guess about which raw variables belong to it. So the catalogue below is a *naming* aid only. Membership is never tabulated here — it is resolved against the live model at run time by :func:`euromod_linking.query.income_list_components`, and a name a given system does not define fails with the names it does. Where the names come from ------------------------- ``label`` is the list's own ``DefIl`` comment in the country XML, taken as the majority spelling across the EU-27 country files. ``aliases`` are the other comments the model itself uses for the same list in other countries, plus the short forms an analyst is likely to type. Both are accepted; matching ignores case, underscores, hyphens and punctuation, so ``"Employment income"``, ``employment_income`` and ``EMPLOYMENT INCOME`` are one name. Resolution happens in :func:`euromod_linking.shock_table.normalize`, the way group keys are canonicalised there, so the canonical table always holds the ``ils_udb_*`` name. That is what keeps the content id a property of the *scenario* rather than of how it was spelled. What is worth scaling --------------------- ``group`` splits the catalogue by what its components actually are, counted over all 27 country files: ``market income`` Data-reported throughout — ``ils_udb_yiy``, ``ypr``, ``ypp``, ``ypt``, ``yot``, ``kfbcc`` and ``xmp`` resolve to *no* simulated component in any country, and ``yem``/``yse`` to three apiece against 26 and 23 reported ones. Scaling these changes what the model is given, which is the point. ``benefits and taxes`` Mixed to overwhelmingly simulated: ``ils_udb_tis`` is one reported component against 121 simulated ones. EUROMOD recomputes a simulated component from the rules during the run, so scaling it changes nothing and it is reported as ``skipped_not_in_input``. To change what a benefit or tax pays out, shock its policy parameters through the ``constant`` channel instead. ``aggregate`` ``ils_udb_yds`` is disposable income: it holds no variables of its own, only the other twenty lists, taxes included. Scaling it fans out over all of them at once, which is almost never a shock anyone meant to write. Attributes ---------- .. autoapisummary:: euromod_linking.income_lists.BY_NAME euromod_linking.income_lists.CATALOGUE euromod_linking.income_lists.GROUPS euromod_linking.income_lists.GROUP_NOTES Classes ------- .. autoapisummary:: euromod_linking.income_lists.IncomeList Functions --------- .. autoapisummary:: euromod_linking.income_lists.canonical_metric euromod_linking.income_lists.catalogue euromod_linking.income_lists.names euromod_linking.income_lists.resolve_metric euromod_linking.income_lists.suggestions Module Contents --------------- .. py:class:: IncomeList One standardised ``ils_udb_*`` list and the names that reach it. .. py:property:: accepted :type: tuple[str, ...] Every descriptive spelling that resolves to this list, label first. .. py:attribute:: aliases :type: tuple[str, ...] :value: () .. py:attribute:: group :type: str .. py:attribute:: label :type: str .. py:attribute:: name :type: str .. py:attribute:: note :type: str :value: '' .. py:property:: scalable :type: bool Whether scaling this list is a meaningful shock. See module docstring. .. py:function:: canonical_metric(metric: str) -> str | None The ``ils_udb_*`` name a descriptive metric denotes, or None. Returns None for anything not in the catalogue — a raw variable name, an ``align`` metric, a list this catalogue does not carry. .. py:function:: catalogue() -> dict The catalogue as plain data: what each list covers and what it answers to. .. py:function:: names() -> list[str] The catalogued ``ils_udb_*`` names, in catalogue order. .. py:function:: resolve_metric(metric: str) -> tuple[str, str | None] ``(canonical metric, problem)`` for a ``scale`` metric. A catalogued spelling resolves to its ``ils_udb_*`` name. Anything else is returned unchanged — *except* a metric carrying whitespace, which no EUROMOD variable or income list name ever does: whoever wrote it meant a concept and misspelled it, and saying so here is cheaper than a later "not a column of the input dataset". .. py:function:: suggestions(metric: str, n: int = 3) -> list[str] The catalogued names closest to what was written, for an error message. .. py:data:: BY_NAME :type: dict[str, IncomeList] .. py:data:: CATALOGUE :type: tuple[IncomeList, ...] .. py:data:: GROUPS :value: ('market income', 'benefits and taxes', 'aggregate') .. py:data:: GROUP_NOTES