The Feature-Time Map — Code

Source code of the experimental pipeline behind the manuscript

"The Feature-Time Map: Sobol-Index Attribution and an Attribution Calculus for Curve Visualizations" (submitted to Computers & Graphics, Elsevier).

Every number and table in the paper is produced by the code in this repository from publicly available datasets. Nothing is transcribed by hand.

What is and is not here

This repository holds code and experiment outputs only:

• the pipeline — the generalized Andrews transform, the Feature-Time Map, the Curve Overlap Index, the leakage-free cross-validated evaluation, one script per experiment, the plotting modules, and the test suite;
• the experiment outputs (results/data/*.csv) — the exact numbers the paper reports, so that any table can be re-derived in seconds without waiting for a full recomputation.

Deliberately not here:

• the datasets — they belong to their original publishers and are downloaded on first use, see Getting the data;
• the LaTeX sources of the manuscript and the rendered figures — the paper is distributed by the journal, not by this repository. The code that draws every figure is included, so the figures can be regenerated; only the resulting image files are omitted.

Repository layout

src/                    pipeline: transform, bases, metrics, preprocessing
src/feature_time_map.py the Feature-Time Map and its localization index
src/metrics.py          ICS, nDPE, NPS, VCI, COI, functional 1-NN accuracy
src/evaluation.py       leakage-free stratified k-fold protocol
src/experiments/        one checkpointed script per experiment
src/figures_scripts/    one module per figure of the paper
src/datasets.py         downloads, caches and verifies the nine datasets
src/data/               empty; the download cache lands here
tests/                  490 pytest checks (theoretical zeros as tolerances)
results/data/           experiment outputs (CSV) as used by the manuscript
results/tables/         table fragments regenerated from results/data
requirements.txt        pinned dependencies (Python 3.12)

Environment

Python 3.12 with pinned dependencies. The full environment the published numbers were computed with is recorded in results/data/_env_snapshot.txt.

Any platform:

python3.12 -m venv venv
venv/bin/pip install -r requirements.txt      # venv\Scripts\pip on Windows

Windows with conda, as used by the authors:

createEnv.bat              REM conda create --prefix .\venv python=3.12
install_requirements.bat   REM pip install -r requirements.txt

All commands below assume the repository root as the working directory and the environment's Python on PATH (on Windows: venv\python.exe).

Getting the data

The nine datasets are not redistributed here. src/datasets.py fetches each one from its public source on first use, caches it as CSV in src/data/, and verifies its shape and class count against DATASET_SPECS before anything is computed — so a silently changed or mis-parsed source is caught rather than analyzed.

Download and verify all nine at once:

python -c "from src.datasets import load_dataset; from src.config import DATASETS; [load_dataset(d) for d in DATASETS]"

An internet connection is needed only for this step. Afterwards the cache in src/data/ is used and everything runs offline. Delete a cached file to force a fresh download.

Dataset	Source	Note
Iris	UCI Iris	loaded through sklearn.datasets
Wine	UCI Wine	Forina et al., 3 cultivars; loaded through sklearn.datasets
Breast Cancer	UCI Breast Cancer Wisconsin (Diagnostic)	loaded through sklearn.datasets
Heart Disease	UCI 45 (Cleveland)	target num binarized (num > 0)
Wine Quality	UCI 186	white wine only (4 898 samples), quality 3-9, 7 classes, not discretized; a different dataset from Wine above
Dry Bean	UCI 602	7 classes
Rice	UCI 545 (Cammeo and Osmancik)	2 classes
Early Diabetes	UCI 529 (Early Stage Diabetes Risk Prediction)	Islam et al. 2020; 520 samples, 16 binary attributes, 2 classes; the case study of the paper
Seeds	UCI 236	3 classes

Quick validation (minutes)

python -m pytest tests -q                    # 490 checks
python -m src.generate_tables                # tables from results/data
python -m src.figures_scripts.generate_all   # figures from results/data

The test suite is where the theory is enforced numerically: for independent standardized attributes the Feature-Time Map columns must sum to one at every time, and for an orthonormal basis the transform is an isometry, so nDPE must be zero. Those identities are asserted as tolerances, not merely observed.

Table and figure generation is deterministic — fixed seeds, fixed SVG hash salt, stripped volatile metadata — so two runs over the same data produce byte-identical output.

Full recomputation (hours)

Every experiment is checkpointed per row: with results/data/*.csv present, a run verifies and skips the combinations already computed, so it resumes instead of recomputing. To recompute one from scratch, delete its CSV from results/data/ and run it:

python -m src.experiments.e3_weighting_impact

Experiments used by this paper:

Script	What it answers in the paper
e2_ordering_stability	spread of the separability score over random attribute orderings
e3_weighting_impact	effect of discriminative weighting (none / ANOVA / MI / RF)
e4_ordering_strategies	comparison of attribute-ordering strategies
e12_coi_sensitivity	bandwidth sensitivity of the Curve Overlap Index
e13_sigma_diagnostics	how far the case-study data are from the independence assumption
e14_weighting_equivalence	equivalence test: weighting buys legibility, not information
e16_coi_estimator_audit	audit of the COI estimator (shared with the companion paper)
e20_coi_argmin_stability	bootstrap stability of the located discrimination window

The remaining scripts in src/experiments/ belong to the companion paper; the two studies share one pipeline.

Evaluation protocol: standardization parameters, discriminative weights and any supervised ordering are estimated on the training fold only and the metrics are computed on the held-out fold, so the weights never see the labels against which the visualization is judged. Two diagnostics (e13, e20) deliberately depart from this and run on the full data, because they describe the displayed map rather than an out-of-sample estimate; the paper states this where the numbers are used.

Determinism: RANDOM_SEED = 42 in src/config.py covers fold splits, subsampling inside the metrics, bootstrap resampling and the weighting estimators; the batch scripts set PYTHONHASHSEED=0 and MPLBACKEND=Agg.

Companion paper

The geometric side of the framework — the classification of isometric generalized Andrews transforms, the distortion calculus and the controlled comparison against parallel coordinates, RadViz and Star Coordinates — is developed in a companion manuscript. This paper cites it for the classification theorem and the distortion calculus, which it uses but does not re-prove. The two papers share no result, and the dependency runs one way only.

License and citation

MIT, see LICENSE. If you use this software, please cite the paper; machine-readable metadata is in CITATION.cff.