euromod_linking.methods.lma_labour_alignment.imputation
=======================================================

.. py:module:: euromod_linking.methods.lma_labour_alignment.imputation

.. autoapi-nested-parse::

   Nearest-neighbour earnings imputation — the FALLBACK for entrants' wages.

   The method's standard assumption is full-time take-up at the person's own
   predicted hourly wage (`yivwg`, estimated by the national team for every
   working-age person). This module covers the remainder: entrants for whom no
   predicted wage exists, because the national wage equation excludes them
   (students, the self-employed, pensioners in some countries) or the value is
   missing.

   Economic intuition
   ------------------
   Someone who enters employment needs a wage before EUROMOD can tax it — but new
   entrants have no observed earnings. Statistical matching answers "what would
   this person plausibly earn?" with "what observably similar people currently
   earn": each entrant is matched to the k=5 most similar continuing workers on
   the classic wage-equation observables (age, gender, education, marital status,
   region), and their earnings/months/hours are averaged with inverse-distance
   weights (closer matches count more). This preserves realistic wage
   heterogeneity across entrants — a flat assumption, everyone at the minimum wage
   say, would compress the bottom of the earnings distribution and mechanically
   overstate redistribution effects.

   Donors exclude other entrants (lma==0 filter): imputing from imputed values
   would let assumptions compound.

   Fixed methodology (matching variables, k=5, inverse-distance weighting).
   Deterministic: donors and recipients processed in idperson order; scaler and
   KNN are deterministic given pinned input order.



Attributes
----------

.. autoapisummary::

   euromod_linking.methods.lma_labour_alignment.imputation.INCOME_VARS
   euromod_linking.methods.lma_labour_alignment.imputation.MATCHING_VARS
   euromod_linking.methods.lma_labour_alignment.imputation.N_NEIGHBORS


Functions
---------

.. autoapisummary::

   euromod_linking.methods.lma_labour_alignment.imputation.impute_transition_incomes


Module Contents
---------------

.. py:function:: impute_transition_incomes(df: pandas.DataFrame, eligible: pandas.Series, region_label_col: str | None, recipients: pandas.Index | None = None) -> tuple[pandas.DataFrame, dict]

   Overwrite yem_a/yemmy_a/lhw_a for `recipients` with donor-matched values.

   `recipients` defaults to every entrant (lma==1). The method normally passes
   only the entrants with no usable predicted wage, since the standard
   assumption is full-time take-up at the person's own yivwg — this matching is
   the fallback for people the wage equation does not cover.
   Returns (df, diagnostics).


.. py:data:: INCOME_VARS
   :value: ('yem', 'yemmy', 'lhw')


.. py:data:: MATCHING_VARS
   :value: ('dag', 'dgn', 'deh', 'dms')


.. py:data:: N_NEIGHBORS
   :value: 5