euromod.eu_euromod.calibrate
============================

.. py:module:: euromod.eu_euromod.calibrate

.. autoapi-nested-parse::

   Calibrating a parametric tax-benefit function on the EU model.

   A tax-benefit system has many instruments. Macroeconomic models need it in a
   compact form: a function from a household's gross income to the taxes it pays net
   of the benefits it receives. This package estimates such a function from a EUROMOD
   simulation, for a baseline or for a reform.

   It works in two steps, one module each:

   :mod:`~euromod.eu_euromod.calibrate.data_preparation`
       Runs a system of the model and builds the household sample: one row per
       household, with gross and disposable income in multiples of mean income.

   :mod:`~euromod.eu_euromod.calibrate.estimation`
       Fits the function of Heathcote, Storesletten and Violante,
       ``net tax rate = 1 - (1 - lambda) * income**(-tau)``, and measures how well it
       fits.

   :mod:`~euromod.eu_euromod.calibrate.descriptives` describes the sample,
   :mod:`~euromod.eu_euromod.calibrate.weighted` holds the weighted statistics, and
   :mod:`~euromod.eu_euromod.calibrate.estimates` saves and loads estimates. The
   estimates for the 27 EU member states and the euro area, policy years 2022 to
   2025, ship with the package::

       from euromod.eu_euromod.calibrate import load_estimates, schedule

       portugal = schedule(load_estimates(), "PT_2022")
       portugal.net_tax_rate(1.0)            # 0.1925, the rate at mean income
       portugal.disposable_income(2.0)       # 1.4424, in multiples of mean income

   The functions need a path to the model and a path to the folder with the input
   data, and the name of a system::

       from euromod.eu_euromod.calibrate import prepare_sample, fit_hsv

       baseline = prepare_sample(MODEL, DATA, "PT_2022")
       fit_hsv(baseline)                     # {'lambda': 0.1925, 'tau': 0.1631, ...}

   A reform is a counterfactual system of the model, or a baseline system with some
   constants overridden::

       reform = prepare_sample(MODEL, DATA, "PT_2022_ref")
       reform = prepare_sample(MODEL, DATA, "PT_2022", constants={"$tin00_rate9": 0.58})

   This package is independent of :mod:`euromod.calibrate`, the connector's general
   engine for fitting arbitrary functional forms. :func:`to_calibration` turns a
   result of this package into an object of that engine.



Below are listed the main public classes of the euromod.eu_euromod.calibrate module.



.. toctree::
   :titlesonly:
   :maxdepth: 1

   data_preparation/index.rst
   descriptives/index.rst
   estimates/index.rst
   estimation/index.rst
   weighted/index.rst






.. list-table:: **Function**
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`calibrate_hsv <euromod.eu_euromod.calibrate.calibrate_hsv>`\ (model\_path, data\_path, systems, \*, household\_types, pooled, lambda\_fixed, constants, cache\_dir, \*\*sample\_options)
     - Estimate the HSV schedule for several systems and household types in one call.




Functions
---------
.. py:function:: calibrate_hsv(model_path, data_path, systems, *, household_types=HOUSEHOLD_TYPES, pooled=None, lambda_fixed=None, constants=None, cache_dir=None, **sample_options)

   Estimate the HSV schedule for several systems and household types in one call.

   :param model_path: Folder of the EUROMOD model.
   :type model_path: :obj:`str`
   :param data_path: Folder with the input datasets.
   :type data_path: :obj:`str`
   :param systems: System names, e.g. ``["PT_2022"]`` or
                   :func:`euromod.eu_euromod.eu27_systems` ``(2022)``.
   :type systems: list of :obj:`str`
   :param household_types: Conditions by name; default :data:`HOUSEHOLD_TYPES`.
   :type household_types: :obj:`dict`
   :param pooled: Groups of countries to estimate on a pooled sample as well, e.g.
                  ``{"EA_2022": euro_area(2022)}``. Every country of a group must be among
                  ``systems``.
   :type pooled: :obj:`dict`, optional
   :param lambda_fixed: Hold the level at this value and estimate only ``tau``.
   :type lambda_fixed: float, optional
   :param constants: As in :func:`simulate`. ``constants`` apply to every system.
   :param cache_dir: As in :func:`simulate`. ``constants`` apply to every system.
   :param \*\*sample_options: As in :func:`household_sample`.

   :returns: One row per system (or pooled group) and household type, with the columns
             of :func:`fit_hsv` and :func:`fit_diagnostics`. Keep it with
             :func:`save_estimates`.
   :rtype: pandas.DataFrame

   .. rubric:: Example

   >>> from euromod.eu_euromod import euro_area, eu27_systems
   >>> table = calibrate_hsv(MODEL, DATA, eu27_systems(2022),
   ...                       pooled={"EA_2022": euro_area(2022)})
   >>> table.loc[("PT_2022", "all"), ["lambda", "tau"]]