xai4tsc.data.datasets

Dataset classes: UcrUeaDataset, LocalDataset, SyntheticDataset.

Attributes

`logger`
`SYNTHETIC_DATASETS`

Classes

`UcrUeaDataset`	Download from the UCR/UEA archive and load raw (unsplit) data.
`LocalDataset`	Load a single-file dataset from a local directory.
`SyntheticDataset`	Base class for programmatically generated datasets.
`FreqShapesDataset`	Localized wave-packet dataset for XAI time-frequency localization evaluation.

Functions

`register_synthetic_dataset`(→ None)	Register a custom `SyntheticDataset` subclass under name.
`load_dataset`(→ xai4tsc.data.base.DatasetBase)	Resolve to the correct `DatasetBase` subclass.

Module Contents

xai4tsc.data.datasets.logger

class xai4tsc.data.datasets.UcrUeaDataset(name: str, cache_dir: pathlib.Path | None = None, download: bool = True, pad_series: bool = False, max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first', use_predefined_splits: bool = False)

Bases: xai4tsc.data.base.DatasetBase

Download from the UCR/UEA archive and load raw (unsplit) data.

name: Human-readable dataset identifier.

cache_dir

download = True

pad_series = False

use_predefined_splits = False

load() → tuple

Load raw data from the UCR/UEA archive via sktime.

sktime downloads and caches the .ts files under cache_dir (passed as extract_path). Restrictions (max_samples, max_series_length) are applied after loading. The caller (split()) saves the processed train / val / test arrays to the split cache.

split(train_split: float = 0.8, val_split: float = 0.0, random_state: int | None = DEFAULT_SEED, encode: str = 'label', impute_missing: bool = False, rng: numpy.random.Generator | None = None, stratify: bool = True, class_order: list | None = None) → tuple

Load and split the dataset.

When use_predefined_splits is True, loads the official _TRAIN.ts and _TEST.ts files directly and ignores train_split, val_split, and stratify. No validation set is produced.

Otherwise delegates to DatasetBase.split() for random / stratified splitting.

class xai4tsc.data.datasets.LocalDataset(path: str | pathlib.Path, name: str, data_format: str = 'numpy', layout: str = 'auto', data_domain: str | xai4tsc._domains.Domain = 'time', pad_series: bool = False, max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first')

Bases: xai4tsc.data.base.DatasetBase

Load a single-file dataset from a local directory.

The directory must contain one data*.npy file and one label*.json file (unsplit layout). For pre-split local data, use load_saved_splits() directly.

path

name: Human-readable dataset identifier.

data_format = 'numpy'

layout = 'auto'

data_domain: Signal domain the loaded arrays are expressed in (see above).

pad_series = False

load() → tuple

Load raw data from the local directory using the configured format loader.

Returns:: (data, labels, metadata) with data in (B, C, T) layout.
Return type:: tuple

class xai4tsc.data.datasets.SyntheticDataset(name: str, cache_dir: str | pathlib.Path | None = None, seed: int = DEFAULT_SEED, max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first')

Bases: xai4tsc.data.base.DatasetBase, abc.ABC

Base class for programmatically generated datasets.

Subclasses implement generate_dataset() (pure, deterministic given the constructor’s seed + parameters). The concrete load() here owns caching: it first looks for a previously generated dataset on disk and only regenerates on a miss.

Caching layout (under cache_dir/synthetic/<cache_key>/):

data.npy — generated array (B, C, T)
labels.json — labels as records ([{"label": ...}, ...]; multi-hot labels are stored as lists)
metadata.json — per-sample metadata records (optional)

Metadata convention: one row per sample, index-aligned with data in the same order. For ground-truth localization datasets it carries the discriminative regions keyed per class (ground_truth) plus distractors (non_discriminative); see the package data conventions.

Example:

class GaussianDataset(SyntheticDataset):
    def _cache_params(self):
        return {"n": self.n_samples, "c": self.n_classes, "t": self.length}

    def generate_dataset(self):
        rng = np.random.default_rng(self.seed)
        data = rng.standard_normal((self.n_samples, 1, self.length))
        labels = rng.integers(0, self.n_classes, self.n_samples)
        return data.astype("float32"), labels, None

name: Human-readable dataset identifier.

cache_dir

seed = 3735928559

abstractmethod generate_dataset() → tuple

Generate and return (data, labels, metadata) — deterministic.

data is (B, C, T) float32; labels is (B,) integer or (B, n_attrs) multi-hot (collapsed to class indices by the multihot encoder); metadata is the per-sample DataFrame (or None).

cache_subdir(root: str | pathlib.Path) → pathlib.Path: Return this dataset’s cache directory under root/synthetic/.

static is_split_layout(directory: str | pathlib.Path) → bool: Return True if directory holds a pre-split train/test layout.

static is_raw_layout(directory: str | pathlib.Path) → bool: Return True if directory holds a single generated blob (not split).

load() → tuple

Return raw (data, labels, metadata), generating + caching on a miss.

With no cache_dir the dataset is generated fresh. Otherwise the cache directory is checked first (first-look); on a hit the persisted blob is loaded without regeneration, on a miss it is generated and persisted.

class xai4tsc.data.datasets.FreqShapesDataset(name: str = 'freq_shapes', cache_dir: str | pathlib.Path | None = None, seed: int = DEFAULT_SEED, n_samples: int = 600, length: int = 500, class_freqs: tuple[int, ...] = (7, 19, 37), packet_len: int = 150, n_global_distractors: int = 3, n_local_distractors: int = 3, max_freq: int = 49, max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first')

Bases: SyntheticDataset

Localized wave-packet dataset for XAI time-frequency localization evaluation.

Each sample is a sum of windowed sinusoids (“wave packets”). A multi-hot label marks which discriminative attributes are present; attribute k adds a packet at its characteristic frequency class_freqs[k] placed at a random time window. Non-discriminative distractor packets — global background sinusoids and shorter local packets, all at other frequencies — are added so the discriminative signal must be localized in both time and frequency.

The per-sample metadata records the ground-truth regions under ground_truth plus distractors under non_discriminative, as the plain mappings that survive the JSON round-trip of save_splits. The evaluation side parses them into GroundTruthRegion when a metric needs them, so the stored shape is free to differ: both a flat region list and the per-class {class: [region, ...]} mapping are read, and the singular channel / freq / phase keys this dataset writes are accepted alongside their plural forms. This makes the dataset a ground truth for the localization metrics (e.g. TimeFrequencyAUC).

Note

The programmatic generator is currently disabled — generate_dataset() is a placeholder that raises. freq_shapes ships a fixed, paper-faithful pre-split dataset committed under the synthetic cache dir (cache/datasets/synthetic/freq_shapes/); the runner loads it directly as a pre-split layout via load_saved_splits when cache_path is set. The constructor still accepts the original generation init_params so existing configs do not break, but they are inert. This is a temporary arrangement until the generator is validated.

data_domain: xai4tsc._domains.Domain

the discriminative features are frequencies localized in time, while the arrays themselves are time-domain (B, 1, 500) float32.

Type:: Raw series, despite the name

n_samples = 600

length = 500

class_freqs = (7, 19, 37)

packet_len = 150

n_global_distractors = 3

n_local_distractors = 3

max_freq = 49

load_saved_splits(directory: pathlib.Path | str, encode: str = 'label') → tuple

Load the pre-split files and annotate each region with the classes it marks.

A label bit of this dataset means “the sample contains a packet at class_freqs[bit]”, so a ground-truth region’s frequency says which bit it belongs to. Under the multi-hot encoding every combination is its own class, so a region marks every class whose combination has that bit set, and the evaluation side can score a per-class explanation against the regions that actually belong to that class.

The annotation happens here rather than in the stored files: it depends on the label encoding, which is resolved at load time, and the committed data is deliberately left as produced.

Parameters:

directory (Path or str) – Directory containing the split files.
encode (str) – Label encoding scheme.

Returns:

As load_saved_splits(), with classes added to every ground-truth region.

Return type:

tuple[list, encoder]

abstractmethod generate_dataset() → tuple

Disabled placeholder — the programmatic generator is turned off for now.

freq_shapes ships a fixed pre-split dataset committed under the synthetic cache dir; the runner loads it directly (see the class docstring). This stub exists only to satisfy the SyntheticDataset ABC.

Raises:: NotImplementedError – Always — set cache_path so the runner loads the shipped pre-split layout instead of generating.

xai4tsc.data.datasets.SYNTHETIC_DATASETS: dict[str, type]

xai4tsc.data.datasets.register_synthetic_dataset(name: str, dataset_class: type) → None

Register a custom SyntheticDataset subclass under name.

The factory xai4tsc.data.load_dataset() dispatches a YAML dataset: <name> entry to the registered class (checked before the path/UCR branches), so registering a name makes it usable from config.

Parameters:

name (str) – Registry key (matched against the YAML dataset field).
dataset_class (type) – A SyntheticDataset subclass.

xai4tsc.data.datasets.load_dataset(name: str, path: str | None = None, cache_dir: str | None = None, pad_series: bool = False, max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first', layout: str = 'auto', data_domain: str = 'time', **kwargs: object) → xai4tsc.data.base.DatasetBase

Resolve to the correct DatasetBase subclass.

Parameters:

name (str) – Human-readable dataset name (always required). If name is in the SYNTHETIC_DATASETS registry, the matching SyntheticDataset is returned (checked first) and generation params are forwarded as **kwargs.
path (str | Path | None) – If provided, a LocalDataset is returned pointing at path. If None (and name is not a synthetic dataset), a UcrUeaDataset is returned.
cache_dir (Path | None) – Passed through to UcrUeaDataset when path is None, stores UCR / UEA datasets to mitigate multiple downloads.
pad_series (bool) – If True, variable-length series are zero-padded to the maximum series length before returning data. Passed to the selected subclass.
max_samples (int | None) – Subsample to at most this many samples before splitting. Prevents OOM on very large datasets (e.g. InsectWingbeat).
sample_strategy (str) – How to select the subset when max_samples is active: "random" (default), "first", "last", or "stratified".
max_series_length (int | None) – Truncate each series to at most this many timesteps. Applied before padding for variable-length datasets.
series_position (str) – Which end of a long series to retain: "first" (default) or "last".
layout (str) – Axis order of a local array: "auto" (default), "bct" or "btc". Only meaningful with path; UCR/UEA and synthetic data are already (B, C, T), so it is not forwarded to them.
data_domain (str) – Signal domain a local array is expressed in: "time" (default), "frequency" or "time_frequency". Only meaningful with path: UCR/UEA data is always raw series and a synthetic dataset declares its own domain, so a non-default value is ignored with a warning for those.
**kwargs – Forwarded to the selected subclass constructor (e.g. download, data_format).