euromod.eu_euromod.calibrate.estimates ====================================== .. py:module:: euromod.eu_euromod.calibrate.estimates .. autoapi-nested-parse:: Estimates as files: the published baseline, and saving and loading your own. A table of estimates, as returned by :func:`~euromod.eu_euromod.calibrate.calibrate_hsv`, has one row per system and household type. :func:`save_estimates` writes such a table to a JSON file, together with any notes on how it was made, and :func:`load_estimates` reads it back, so a model can use estimates without running EUROMOD. The package ships one such file: the estimates for the 27 EU member states and the euro area, policy years 2022 to 2025. ``load_estimates()`` without a path returns them, and :func:`schedule` turns a row of any table into a :class:`Schedule` that computes tax rates, taxes and disposable incomes. Below are listed the main public classes of the euromod.eu_euromod.calibrate.estimates module. .. list-table:: **Classes** :header-rows: 0 :widths: auto :class: summarytable * - :py:obj:`Schedule ` - A fitted tax-benefit function, ready to use. .. list-table:: **Function** :header-rows: 0 :widths: auto :class: summarytable * - :py:obj:`load_estimates `\ (path) - Load a table of estimates. * - :py:obj:`save_estimates `\ (estimates, path, \*\*info) - Save a table of estimates as a JSON file. * - :py:obj:`schedule `\ (estimates, system, household\_type) - The fitted tax-benefit function of one system and household type, ready to use. .. toctree:: :titlesonly: :maxdepth: 3 .. py:class:: Schedule(lambda_, tau) A fitted tax-benefit function, ready to use. Incomes are in multiples of mean gross income, as numbers or arrays: 1.0 is mean income. Multiply by the mean gross income of the population you apply it to for amounts in currency. :param lambda_: Level: the net tax rate at mean income. :type lambda_: float :param tau: Progressivity. :type tau: float .. rubric:: Example >>> portugal = Schedule(0.1925, 0.1631) >>> portugal.net_tax_rate(2.0) # average rate at twice the mean income 0.2788 >>> portugal.net_taxes(2.0) # taxes net of benefits 0.5576 >>> portugal.disposable_income(2.0) 1.4424 .. rubric:: Overview .. list-table:: Methods :header-rows: 0 :widths: auto :class: summarytable * - :py:obj:`disposable_income `\ (income) - Gross income minus net taxes. * - :py:obj:`marginal_rate `\ (income) - Share of an extra unit of gross income that does not reach disposable income. * - :py:obj:`net_tax_rate `\ (income) - Average net tax rate: taxes net of benefits, as a share of gross income. * - :py:obj:`net_taxes `\ (income) - Taxes net of benefits. Negative when benefits exceed taxes. .. rubric:: Methods .. py:method:: disposable_income(income) Gross income minus net taxes. .. py:method:: marginal_rate(income) Share of an extra unit of gross income that does not reach disposable income. .. py:method:: net_tax_rate(income) Average net tax rate: taxes net of benefits, as a share of gross income. .. py:method:: net_taxes(income) Taxes net of benefits. Negative when benefits exceed taxes. Functions --------- .. py:function:: load_estimates(path=None) Load a table of estimates. :param path: A file written by :func:`save_estimates`. Default: the estimates that ship with the package, by household type, for the 27 EU member states (``"AT_2022"``, ..., ``"SK_2025"``) and the euro area (``"EA_2022"``, ..., ``"EA_2025"``: 19 members in 2022, 20 from 2023), policy years 2022 to 2025. :type path: :obj:`str`, optional :returns: Indexed by system and household type, with the columns of :func:`~euromod.eu_euromod.calibrate.fit_hsv` and :func:`~euromod.eu_euromod.calibrate.fit_diagnostics`. The notes saved with the estimates are in ``.attrs``. :rtype: pandas.DataFrame .. rubric:: Example >>> baseline = load_estimates() >>> baseline.loc[("PT_2022", "all"), ["lambda", "tau"]] lambda 0.1925 tau 0.1631 >>> baseline.attrs["model"] 'EUROMOD_RELEASES_J2.0+' .. py:function:: save_estimates(estimates, path, **info) Save a table of estimates as a JSON file. :param estimates: Estimates indexed by system and household type, as returned by :func:`~euromod.eu_euromod.calibrate.calibrate_hsv`. :type estimates: pandas.DataFrame :param path: File to write. :type path: :obj:`str` :param \*\*info: What should be remembered about the estimates: anything that JSON can hold, e.g. ``model="J2.0+"``, ``constants={"$tin00_rate9": 0.58}``, ``note="top income-tax rates raised by 10 points"``. .. rubric:: Example >>> estimates = calibrate_hsv(MODEL, DATA, ["PT_2022"], constants=reform) >>> save_estimates(estimates, "pt_reform.json", constants=reform) .. py:function:: schedule(estimates, system, household_type='all') The fitted tax-benefit function of one system and household type, ready to use. :param estimates: A table of estimates, from :func:`load_estimates` or :func:`~euromod.eu_euromod.calibrate.calibrate_hsv`. :type estimates: pandas.DataFrame :param system: A system in the table, e.g. ``"PT_2022"`` or ``"EA_2025"``. :type system: :obj:`str` :param household_type: A household type in the table; default all households. :type household_type: :obj:`str` :returns: Computes the net tax rate, net taxes, disposable income and the marginal rate at any gross income. Calling it gives the net tax rate. :rtype: Schedule .. rubric:: Example >>> portugal = schedule(load_estimates(), "PT_2022") >>> portugal.net_tax_rate([0.5, 1.0, 2.0]) array([0.0958, 0.1925, 0.2788]) >>> portugal.disposable_income(2.0) 1.4424