xai4tsc.data.data_loaders
=========================

.. py:module:: xai4tsc.data.data_loaders

.. autoapi-nested-parse::

   File-format loaders (``FORMAT_LOADERS``) and JSON / metadata I/O helpers.



Attributes
----------

.. autoapisummary::

   xai4tsc.data.data_loaders.logger
   xai4tsc.data.data_loaders.FORMAT_LOADERS


Functions
---------

.. autoapisummary::

   xai4tsc.data.data_loaders.load_json
   xai4tsc.data.data_loaders.load_metadata


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

.. py:data:: logger

.. py:data:: FORMAT_LOADERS

.. py:function:: load_json(path: pathlib.Path) -> tuple

   Load a labels JSON file.

   The file must contain a list of records.  A ``"label"`` key is required;
   all other keys are treated as metadata columns.

   :param path: Path to the ``.json`` file.
   :type path: Path

   :returns: ``(labels, metadata)`` — metadata is ``None`` when no extra columns exist.
   :rtype: tuple[pd.Series, pd.DataFrame | None]

   :raises ValueError: If no ``"label"`` key is found.


.. py:function:: load_metadata(path: pathlib.Path) -> pandas.DataFrame | None

   Load a standalone metadata JSON file into a one-row-per-sample DataFrame.

   Accepts two shapes:

   - a **records list** ``[{...}, {...}, ...]`` — the framework's own
     ``orient="records"`` output, and
   - an **index-keyed dict** ``{"0": {...}, "1": {...}, ...}`` — sorted by
     integer key into sample order.

   Nested values (lists / dicts, e.g. per-class ground-truth regions) are kept
   as-is in object columns.

   :param path: Path to the metadata ``.json`` file.
   :type path: Path

   :returns: One row per sample, or ``None`` if the file is empty.
   :rtype: pd.DataFrame | None