xai4tsc.data.base
=================

.. py:module:: xai4tsc.data.base

.. autoapi-nested-parse::

   ``DatasetBase`` ABC: splitting, label encoding, saving, loading pre-split data.



Attributes
----------

.. autoapisummary::

   xai4tsc.data.base.logger


Classes
-------

.. autoapisummary::

   xai4tsc.data.base.MultiHotLabelEncoder
   xai4tsc.data.base.DatasetBase


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

.. py:data:: logger

.. py:class:: MultiHotLabelEncoder

   Collapse multi-hot label rows to single class indices, preserving the combos.

   Multi-label datasets emit a multi-hot label row per sample (e.g.
   ``[0, 1, 1]`` = attributes 1 and 2 present). Training uses
   :class:`~torch.nn.CrossEntropyLoss` on 1-D integer class indices, so each
   distinct combination is mapped to one class index. The combination itself is
   kept as the **class name** (``classes_``) so predictions can be decoded back
   to multi-hot later; :func:`_split_dataset` / :meth:`DatasetBase.load_saved_splits`
   log the index→name mapping.

   Implements the small subset of the sklearn encoder interface the framework
   uses (``fit`` / ``transform`` / ``fit_transform`` / ``inverse_transform`` and
   the ``classes_`` attribute), so it slots into the same code paths as
   :class:`~sklearn.preprocessing.LabelEncoder`.


   .. py:method:: fit(y: numpy.ndarray) -> MultiHotLabelEncoder

      Record the sorted unique multi-hot rows as ``classes_``.



   .. py:method:: transform(y: numpy.ndarray) -> numpy.ndarray

      Map each multi-hot row to its class index (1-D int64).



   .. py:method:: fit_transform(y: numpy.ndarray) -> numpy.ndarray

      Fit then transform in one call.



   .. py:method:: inverse_transform(indices: numpy.ndarray) -> numpy.ndarray

      Map class indices back to their multi-hot rows.



.. py:class:: DatasetBase(max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first')

   Bases: :py:obj:`abc.ABC`


   Base class for all datasets in xai4tsc.

   Provides concrete implementations of splitting, saving, and loading
   pre-split data.  Subclasses only need to implement :meth:`load`.


   .. py:attribute:: name
      :type:  str
      :value: None


      Human-readable dataset identifier.


   .. py:method:: load() -> tuple
      :abstractmethod:


      Load raw (unsplit) data from the source.

      :returns: ``(data, labels, metadata)`` where data has shape
                ``(n_samples, n_channels, n_timesteps)``.
      :rtype: tuple[np.ndarray, array-like, pd.DataFrame | None]



   .. py:method:: split(train_split: float = 0.8, val_split: float = 0.0, random_state: int = 42, encode: str = 'label', impute_missing: bool = False, rng: numpy.random.Generator | None = None, stratify: bool = True) -> tuple

      Load and split the dataset into train / test / (optional) val.

      :param train_split: Fraction of samples for training.
      :type train_split: float
      :param val_split: Fraction of samples for validation (0 disables validation set).
      :type val_split: float
      :param random_state: Seed for reproducible splits.  Ignored when *rng* is provided.
      :type random_state: int
      :param encode: Label encoding scheme: ``"label"`` (default), ``"onehot"``, or
                     ``"ordinal"``.
      :type encode: str
      :param impute_missing: If ``True``, NaN values are replaced with the per-channel mean
                             before splitting.  If ``False`` (default), a :class:`ValueError`
                             is raised when NaN values are detected.
      :type impute_missing: bool
      :param rng: A shared ``numpy`` Generator instance.  When supplied, *random_state*
                  is ignored and this generator is used for all random operations
                  (sample restriction, sklearn split seed) so that the entire pipeline
                  draws from a single reproducible random stream.
      :type rng: np.random.Generator | None
      :param stratify: If ``True`` (default), splits are stratified by class label so that
                       every class is proportionally represented in each split.  Falls back
                       to random splitting with a warning when a class has too few samples
                       to stratify.
      :type stratify: bool

      :returns: ``(splits, fitted_encoder)`` where *splits* is a list of
                ``(X, y, metadata)`` tuples in order ``[train, test, val]``.
      :rtype: tuple[list, encoder]



   .. py:method:: get_splits() -> tuple

      Return the cached splits produced by :meth:`split`.

      :raises RuntimeError: If :meth:`split` has not been called yet.



   .. py:method:: save_splits(save_path: pathlib.Path | str) -> None

      Save the current splits to *save_path/splits/* as ``.npy`` + ``.json`` files.

      :param save_path: Parent directory.  A ``splits/`` sub-directory is created inside it.
      :type save_path: Path or str

      :raises RuntimeError: If no splits are available yet.



   .. py:method:: load_saved_splits(directory: pathlib.Path | str, encode: str = 'label') -> tuple

      Load pre-split files from *directory*.

      Looks for ``train*.npy``, ``test*.npy``, ``val*.npy`` (optional) and
      matching ``*.json`` label files.

      :param directory: Directory containing the split files.
      :type directory: Path or str
      :param encode: Label encoding scheme.
      :type encode: str

      :returns: ``(splits, fitted_encoder)``.
      :rtype: tuple[list, encoder]