xai4tsc.data.base

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

Attributes

logger

Classes

MultiHotLabelEncoder

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

DatasetBase

Base class for all datasets in xai4tsc.

Module Contents

xai4tsc.data.base.logger
class xai4tsc.data.base.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 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; _split_dataset() / 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 LabelEncoder.

fit(y: numpy.ndarray) → MultiHotLabelEncoder

Record the sorted unique multi-hot rows as classes_.

transform(y: numpy.ndarray) → numpy.ndarray

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

fit_transform(y: numpy.ndarray) → numpy.ndarray

Fit then transform in one call.

inverse_transform(indices: numpy.ndarray) → numpy.ndarray

Map class indices back to their multi-hot rows.

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

Bases: 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 load().

name: str = None

Human-readable dataset identifier.

abstractmethod load() → tuple

Load raw (unsplit) data from the source.

Returns:

(data, labels, metadata) where data has shape (n_samples, n_channels, n_timesteps).

Return type:

tuple[np.ndarray, array-like, pd.DataFrame | None]

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.

Parameters:

  • train_split (float) – Fraction of samples for training.

  • val_split (float) – Fraction of samples for validation (0 disables validation set).

  • random_state (int) – Seed for reproducible splits. Ignored when rng is provided.

  • encode (str) – Label encoding scheme: "label" (default), "onehot", or "ordinal".

  • impute_missing (bool) – If True, NaN values are replaced with the per-channel mean before splitting. If False (default), a ValueError is raised when NaN values are detected.

  • rng (np.random.Generator | None) – 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.

  • stratify (bool) – 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.

Returns:

(splits, fitted_encoder) where splits is a list of (X, y, metadata) tuples in order [train, test, val].

Return type:

tuple[list, encoder]

get_splits() → tuple

Return the cached splits produced by split().

Raises:

RuntimeError – If split() has not been called yet.

save_splits(save_path: pathlib.Path | str) → None

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

Parameters:

save_path (Path or str) – Parent directory. A splits/ sub-directory is created inside it.

Raises:

RuntimeError – If no splits are available yet.

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.

Parameters:

  • directory (Path or str) – Directory containing the split files.

  • encode (str) – Label encoding scheme.

Returns:

(splits, fitted_encoder).

Return type:

tuple[list, encoder]