euromod_linking.dimensions
==========================

.. py:module:: euromod_linking.dimensions

.. autoapi-nested-parse::

   Population cells: how a shock's ``group`` selects rows of the microdata.

   A group key is either a **EUROMOD input variable** (``deh=3-4``, ``dgn=1``,
   ``dag=25-34``, ``les=5``) or the one named dimension with real structure,
   ``region``, which resolves to the finest regional column the dataset carries
   (drgn2, else drgn1, else country) and understands the NUTS hierarchy.

   Expressing cells in the model's own variables is deliberate. Recoded category
   labels — an external model's own "low/medium/high skill" classes, say — are
   meaningless outside the binding that invented them, cannot be looked up
   anywhere, and silently fix an aggregation an analyst may not want. ``deh=3-4`` is
   self-describing, verifiable against the dataset, and needs no registry entry —
   what a variable means and which coded values it takes are documented by EUROMOD
   itself. An external model that publishes its own classes translates them to
   variable ranges in its mapping spec, where model-specific semantics belong.

   Value specs
   -----------
   ::

       deh=3        exact value
       deh=3-4      inclusive range (``ddi=-1-0`` parses: signs are handled)
       dag=65+      open upper bound
       deh=3,5      set of values

   Non-numeric values compare as strings (exact / set only).



Attributes
----------

.. autoapisummary::

   euromod_linking.dimensions.REGION


Exceptions
----------

.. autoapisummary::

   euromod_linking.dimensions.DimensionError


Classes
-------

.. autoapisummary::

   euromod_linking.dimensions.Dimension
   euromod_linking.dimensions.ValueSpec


Functions
---------

.. autoapisummary::

   euromod_linking.dimensions.canonical_group
   euromod_linking.dimensions.derive_region
   euromod_linking.dimensions.get
   euromod_linking.dimensions.matches
   euromod_linking.dimensions.parse_group
   euromod_linking.dimensions.parse_value_spec
   euromod_linking.dimensions.region_column
   euromod_linking.dimensions.registered
   euromod_linking.dimensions.specs_overlap
   euromod_linking.dimensions.validate_group_columns
   euromod_linking.dimensions.validate_group_syntax


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

.. py:exception:: DimensionError



   Inappropriate argument value (of correct type).


.. py:class:: Dimension

   .. py:attribute:: column
      :type:  str


   .. py:attribute:: description
      :type:  str
      :value: ''



   .. py:attribute:: fallback_columns
      :type:  tuple[str, ...]
      :value: ()



   .. py:attribute:: name
      :type:  str


.. py:class:: ValueSpec

   A parsed group value: what rows of one variable it selects.


   .. py:method:: bounds() -> tuple[float, float] | None

      Numeric interval covered, for overlap detection (None if string-valued).



   .. py:attribute:: hi
      :type:  float | None
      :value: None



   .. py:attribute:: kind
      :type:  str


   .. py:attribute:: lo
      :type:  float | None
      :value: None



   .. py:attribute:: raw
      :type:  str


   .. py:attribute:: values
      :type:  tuple
      :value: ()



.. py:function:: canonical_group(pairs: Mapping[str, str] | str) -> str

   Canonical form: keys sorted, "k=v;k2=v2".


.. py:function:: derive_region(df: pandas.DataFrame) -> pandas.Series

   Region code label per row; empty when the dataset has no region column.


.. py:function:: get(name: str) -> Dimension | None

.. py:function:: matches(series: pandas.Series, spec: ValueSpec) -> pandas.Series

   Boolean mask: which rows of `series` the spec selects.


.. py:function:: parse_group(group: str) -> dict[str, str]

   Parse a canonical group string "k=v;k2=v2" into a dict ("" -> {}).


.. py:function:: parse_value_spec(spec: str) -> ValueSpec

   Parse a group value into a ValueSpec. Raises DimensionError.


.. py:function:: region_column(df_columns, dim: Dimension = REGION) -> str | None

   Finest available region column ("" -> country level). Deterministic:
   the declared column first, then fallbacks in declared order.


.. py:function:: registered() -> dict[str, Dimension]

.. py:function:: specs_overlap(a: ValueSpec, b: ValueSpec) -> bool

   True when two specs can select the same row — ambiguous cell membership.


.. py:function:: validate_group_columns(group: str, columns) -> list[str]

   Dataset-aware problems: every key must be `region` or a dataset column.


.. py:function:: validate_group_syntax(group: str) -> list[str]

   Syntax-only problems with a group string ([] = ok).

   Deliberately does NOT check that a key is a real dataset column — that is a
   dataset-aware check (see validate_group_columns), applied once the dataset
   is known.


.. py:data:: REGION