experiment_runner.cache ======================= .. py:module:: experiment_runner.cache .. autoapi-nested-parse:: Cache utilities for the experiment runner. All caching decisions live here, never in the package (src/xai4tsc/). Cache layout ------------ The root cache directory (``cache_path`` from the experiment config) contains two independent sub-trees: ``{cache_path}/datasets/`` Raw UCR and UEA archive downloads. When ``UcrUeaDataset`` is given a ``cache_dir``, that path is forwarded to sktime as ``extract_path``. sktime stores the ``.ts`` files under ``datasets/{dataset_name}/{dataset_name}_TRAIN.ts`` (and ``_TEST.ts``). Deleting this sub-tree forces a fresh download on the next run; everything else (split cache) remains intact. ``{cache_path}/splits/`` Processed train / val / test splits ready for training. Each split is stored in its own folder whose name encodes **all** parameters that affect the split, so no external metadata file is needed — if the folder exists and is non-empty the split is valid. Deleting this sub-tree forces re-parsing from ``.ts`` and re-splitting on the next run. Folder naming convention:: {dataset}_tr{train:.4g}_v{val:.4g}_s{seed}_{encode}[_p][_i][_s{N}{c}][_t{T}{c}] Component meanings: ========= ============================================================ Component Meaning ========= ============================================================ dataset Human-readable dataset name (e.g. ``ECG5000``) tr… Training fraction (e.g. ``tr0.8``) v… Validation fraction (e.g. ``v0.1``) s… Integer random seed used for the split (e.g. ``s42``) encode Label encoding scheme: ``label``, ``onehot``, ``ordinal`` _p Suffix: variable-length series were zero-padded _i Suffix: NaN values were imputed before splitting _s{N}{c} Suffix: dataset was subsampled to N samples; c = first char of the strategy (**r**\ andom / **f**\ irst / **l**\ ast / **s**\ tratified) _t{T}{c} Suffix: series were truncated to T timesteps; c = first char of the position (**f**\ irst / **l**\ ast) ========= ============================================================ Examples:: ECG5000_tr0.8_v0.1_s42_label GunPoint_tr0.7_v0.1_s0_onehot AllGestureWiimoteX_tr0.8_v0.1_s42_label_p DodgerLoopDay_tr0.8_v0.1_s42_label_i InsectWingbeat_tr0.8_v0.1_s42_label_p_s5000s_t1000f Functions --------- .. autoapisummary:: experiment_runner.cache.get_dataset_cache_dir experiment_runner.cache.get_split_cache_path Module Contents --------------- .. py:function:: get_dataset_cache_dir(cache_path: pathlib.Path | None) -> pathlib.Path | None Return ``cache_path/datasets/``, or ``None`` if caching is disabled. .. py:function:: get_split_cache_path(cache_path: pathlib.Path | None, dataset_name: str, train_split: float, val_split: float, random_state: int, encode: str, allow_padding: bool = False, allow_imputation: bool = False, max_samples: int | None = None, sample_strategy: str = 'random', max_series_length: int | None = None, series_position: str = 'first', stratify: bool = True, use_predefined_splits: bool = False) -> pathlib.Path | None Return the path for a specific cached split, or ``None`` if disabled. The folder name encodes all split parameters so no separate metadata file is needed — if the folder exists the split is valid. Folder naming convention:: {dataset_name}_tr{train_split:.4g}_v{val_split:.4g}_s{random_state}_{encode}[_p][_i][_s{N}{strategy[0]}][_t{T}{position[0]}](_official|_strat|_rand) Suffixes: ``_p`` padding enabled ``_i`` imputation enabled ``_s{N}{c}`` max_samples=N, strategy first char (r/f/l/s) ``_t{T}{c}`` max_series_length=T, position first char (f/l) ``_official`` official archive train/test split (exclusive with _strat/_rand) ``_strat`` random split with stratification ``_rand`` random split without stratification Examples:: ECG5000_tr0.8_v0.1_s42_label_official ECG5000_tr0.8_v0.1_s42_label_strat AllGestureWiimoteX_tr0.8_v0.1_s42_label_p_strat InsectWingbeat_tr0.8_v0.1_s42_label_p_s5000r_t1000f_rand Full path: ``cache_path/splits/{folder_name}/`` :param cache_path: Root cache directory. ``None`` disables caching. :type cache_path: Path or None :param dataset_name: Human-readable dataset identifier used in the folder name. :type dataset_name: str :param train_split: Fraction of data used for training. :type train_split: float :param val_split: Fraction of data used for validation. :type val_split: float :param random_state: Seed used for the split, encoded in the folder name. :type random_state: int :param encode: Label encoding scheme (e.g. ``"label"``, ``"onehot"``). :type encode: str :param allow_padding: Whether variable-length series were zero-padded before splitting. :type allow_padding: bool :param allow_imputation: Whether NaN values were imputed before splitting. :type allow_imputation: bool :param max_samples: Maximum number of samples used; ``None`` means all samples. :type max_samples: int | None :param sample_strategy: Sample selection strategy (encoded as first character). :type sample_strategy: str :param max_series_length: Maximum series length used; ``None`` means full length. :type max_series_length: int | None :param series_position: Which end was retained (encoded as first character). :type series_position: str :param stratify: Whether splits were stratified by class label. Ignored when *use_predefined_splits* is ``True``. :type stratify: bool :param use_predefined_splits: Whether the official archive ``_TRAIN``/``_TEST`` files were used. :type use_predefined_splits: bool :returns: ``cache_path/splits/{folder_name}/``, or ``None`` if caching is disabled. :rtype: Path or None