euromod_linking.shock_table
===========================

.. py:module:: euromod_linking.shock_table

.. autoapi-nested-parse::

   Canonical shock table — the interchange format every external-model shock
   must be expressed in before it can drive a EUROMOD scenario.

   One tidy record per shock::

       channel  align|constant|scale|reweight|inject   which EUROMOD lever
       metric   e.g. "employment", "$f_cpi", "yem"      channel-specific referent
       group    canonical "key=value;..." string        population cell ("" = all)
       period   external-model period label (str)
       op       set|grow|mult|add                       value semantics
       value    number
       unit     optional, documentation only
       source   optional provenance (file/sheet/row)

   A table's identity is its content: `content_id` hashes the canonical records
   into ``shk_`` + 12 hex digits, so the same economic scenario always has the same
   id whatever file or code path produced it. Nothing is stored — the id is derived
   on demand, and the table itself is a DataFrame the caller holds.



Attributes
----------

.. autoapisummary::

   euromod_linking.shock_table.CHANNELS
   euromod_linking.shock_table.COLUMNS
   euromod_linking.shock_table.OPS


Exceptions
----------

.. autoapisummary::

   euromod_linking.shock_table.ShockTableError


Functions
---------

.. autoapisummary::

   euromod_linking.shock_table.content_id
   euromod_linking.shock_table.describe
   euromod_linking.shock_table.normalize
   euromod_linking.shock_table.summarize


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

.. py:exception:: ShockTableError(problems: list[str])



   Inappropriate argument value (of correct type).


   .. py:attribute:: problems


.. py:function:: content_id(df: pandas.DataFrame) -> str

   Deterministic id from shock content (unit/source excluded, so identical
   shocks from different files dedupe).


.. py:function:: describe(df: pandas.DataFrame, **extra) -> dict

   The id and summary of a table, as it appears in a scenario result.


.. py:function:: normalize(records: list[dict]) -> pandas.DataFrame

   Validate + canonicalise raw records into the canonical DataFrame,
   sorted by (channel, metric, group, period). Raises ShockTableError.


.. py:function:: summarize(df: pandas.DataFrame) -> dict

.. py:data:: CHANNELS
   :value: ('align', 'constant', 'scale', 'reweight', 'inject')


.. py:data:: COLUMNS
   :value: ('channel', 'metric', 'group', 'period', 'op', 'value', 'unit', 'source')


.. py:data:: OPS
   :value: ('set', 'grow', 'mult', 'add')