🧩 Stochastic Hierarchy Induction (SHI) for Time Series Classification

Author: Celal Alagoz
License: MIT
Python version: 3.10+
Last updated: November 2025

🌲 Overview
This repository contains the official implementation of Stochastic Hierarchy Induction (SHI) — a framework for classifier-informed automatic hierarchy generation and hierarchical classification (HC) applied to time series data.
The approach introduces Stochastic Splitting Functions (SSFs) — potr, srtr, and lsoo — that recursively partition class sets through performance-guided binary decisions, enabling discriminative top-down hierarchy construction.

Examples of hierarchies generated using SSFs: potr, srtr, and lsoo

🚀 Features

• Automatic hierarchy generation (HG) guided by classifier performance.
• Three stochastic splitting functions (SSFs):
  • potr – Pick-One-Then-Regroup
  • srtr – Split-Randomly-Then-Regroup
  • lsoo – Leave-Salient-One-Out
• Hierarchical classification (HC) using an extended Local Classifier Per Node (LCPN+) scheme.
• Comparison against flat classification (FC) with performance and runtime summaries.
• Support for multiple base classifiers (MiniRocket, Quant, Cfire).
• Visual examples of generated hierarchies for each SSF type.

📊 Dataset Information

The experiments in the accompanying manuscript use benchmark datasets from the UCR Time Series Classification Archive (2018 release).

Reference:

• Dau, H. A., et al. (2019). The UCR Time Series Classification Archive. https://www.cs.ucr.edu/~eamonn/time_series_data_2018/

The repository does not redistribute the datasets. They are downloaded automatically through the aeon package or can be obtained directly from the UCR website.

The provided demo (demo_quick.py) downloads the selected dataset automatically using:

from aeon.datasets import load_classification

💻 Code Information

The repository implements the complete Stochastic Hierarchy Induction (SHI) framework introduced in the accompanying manuscript.

Main components:

File	Description
shi.py	Stochastic Hierarchy Induction algorithm
hg_ssf.py	Stochastic Splitting Functions (potr, srtr, lsoo)
he_binary_tree.py	Hierarchical classifier (LCPN+)
utils.py	Utility functions (tree visualization, preprocessing, evaluation)
demo_quick.py	Minimal end-to-end example
examples/	Example hierarchies generated by each SSF

🧩 Environment Setup

We recommend creating a fresh conda environment (Python 3.11) and installing dependencies as follows:

conda create -n ts_gpu_311 python=3.11 -y
conda activate ts_gpu_311

# GPU-enabled PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

# Core dependencies
pip install pytorch-lightning aeon[all_extras] tsfresh>=0.20.1 prince>=0.16.0 
pip install xgboost catboost lightgbm seaborn

# Additional utilities
pip install PyWavelets dtaidistance tables statsmodels openpyxl nolds baycomp pytisean openml proglearn

📁 Repository Structure

.
├── demo_quick.py # Minimal example to run SHI + HC vs FC
├── utils.py # Helper functions (sorting, plotting, etc.)
├── hg_ssf.py # Hierarchy Generation using SSFs (potr, srtr, or lsoo)
├── shi.py # Stochastic Hierarchy Inductor (core)
├── he_binary_tree.py # BinaryTreeClassifier implementing LCPN+
├── examples/
│ ├── hierarchy_potr.png
│ ├── hierarchy_srtr.png
│ ├── hierarchy_lsoo.png
│ └── ...
├── results/
│ ├── supplementary_material.pdf
├── README.md
└── LICENSE

▶️ Usage Instructions

1. Create the conda environment and install the required packages.
2. Clone this repository.

git clone https://github.com/alagoz/hg4ts_ssf.git
cd hg4ts_ssf

You can modify the configuration section in demo_quick.py:

DATASET_NAME = "OliveOil"
TRANSFORM_MODEL = "MiniRocket"    # or "Quant", "Cfire"
SPLITTING_FUNCTION = "srtr"       # or "potr", "lsoo"
N_ITER = 3

## 🧮 Sample Output

📂 Loading dataset: Tools

🔄 Applying MiniRocket transformation...

🌳 Inducing Stochastic Hierarchy (SSF = 'srtr')...
Stochastic Hierarchy Induction with 3 iterations
Best hierarchy selected with score: 0.8202
   Hierarchy induction completed in 1.45s

⚙️  Training hierarchical classifier (LCPN+)...
   HC training completed in 0.24s

⚡ Running flat classification (FC baseline)...

🧩 Hierarchical (HC-lcpn+) Results:
   Accuracy: 0.8315
   F1-Macro: 0.8254
   Balanced Accuracy: 0.8032
   Train Time: 0.24s | Test Time: 0.00s | Total: 0.24s

🧩 Flat (FC) Results:
   Accuracy: 0.8202
   F1-Macro: 0.8344
   Balanced Accuracy: 0.8144
   Train Time: 0.07s | Test Time: 0.00s | Total: 0.07s

============================================================
📊 COMPARISON SUMMARY
============================================================
Δ Accuracy (HC - FC): +0.0112
Time Ratio (HC/FC): 3.24x
============================================================

🔬 Methodology

The SHI framework consists of four stages:

1. Time-series transformation using MiniRocket, Quant, or Cfire.
2. Hierarchy generation via stochastic hierarchy induction using one of the proposed splitting functions:
   • potr
   • srtr
   • lsoo
3. Hierarchy exploitation using the LCPN+ hierarchical classification strategy.
4. Evaluation by comparison against a flat classifier using identical base estimators.

The hierarchy is selected using internal validation during hierarchy generation and subsequently trained on the complete training set before evaluation on the test set.

📦 Requirements

Minimum requirements

• Python ≥ 3.11
• PyTorch
• aeon
• scikit-learn
• NumPy
• matplotlib

Optional packages are required for reproducing all experiments in the manuscript and are listed in the installation section.

🤝 Contributing

Bug reports, feature requests, and pull requests are welcome.

If you encounter problems reproducing the experiments or discover implementation issues, please open an issue on GitHub.

📚 Citation

If you use this software, please cite the GitHub repository.

@misc{hg4ts_ssf_2025,
  author = {Celal Alagöz},
  title = {HG4TS\_SSF: Hierarchy Generation for Time Series using Stochastic Splitting Functions},
  year = {2025},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/alagoz/hg4ts_ssf}}
}

🧭 Acknowledgments

This work builds upon:

• aeon time series framework
• MiniRocket, Quant, and Cfire transformations
• HIVE-COTE 2.0, Hydra, and related benchmark methods for TSC

📄 License

This project is released under the MIT License.

See the LICENSE file for details.

🔁 Reproducibility

The repository contains all source code required to reproduce the hierarchy induction and hierarchical classification experiments.

The full benchmark scripts used in the accompanying manuscript, together with supplementary results and generated hierarchies, are provided in the results/ and examples/ directories.

Random seeds are fixed wherever possible to facilitate reproducibility.