⚖️ K-IPO: Kendall-constrained Importance Preserving Oversampling for Imbalanced Tabular Data

K-IPO is a generator-agnostic, generate-then-select Python framework for imbalanced tabular data classification that preserves the original feature importance ranking during data augmentation. K-IPO iteratively generates minority-class candidates and accepts them only if their inclusion maintains a user-defined minimum Kendall’s tau ($\tau$) correlation with the reference feature importance ranking. Optionally, stricter constraints can be enforced on the highest-ranked top-k features. Evaluated on 20 imbalanced binary classification datasets using three classifiers and multiple explanation methods, K-IPO achieved the best or tied-best results in feature importance preservation, explanation consistency, and class separability compared with existing oversampling methods, including both conventional and generative approaches. It also generally improved predictive performance while maintaining competitive computational overhead.

Table of Contents

• Prerequisites & Installation
• Usage
  • Demo Example (API)
  • End-to-End Pipeline for AI4I2020
• Datasets
  • YAML Configuration Files
• Performance Evaluation
• File Structure
• Citation
• Acknowledgments

Prerequisites & Installation

Before installing the project, make sure the following requirements are satisfied:

1. Python (3.10 <= version < 3.11) is installed on your system (experiments were conducted with Python 3.10.20).

2. An MPI implementation is installed on your system, such as OpenMPI (recommended) or MPICH.

Warning

Make sure that the mpirun command is available in your system's PATH, as it is required to launch MPI processes.

Clone the repository:

git clone https://github.com/CEID-HPCLAB/K-IPO.git
cd K-IPO

Install the K-IPO package and external dependencies:

# (Recommended) Create and activate a Python virtual environment using Python 3.10
python3.10 -m venv venv
source venv/bin/activate # POSIX (bash/zsh)

chmod +x ./setup.sh
./setup.sh 

Warning

The PiML toolbox requires pandas (<2.0.0), numpy (<1.24.0), and scipy (==1.5.3). These outdated dependencies conflict with other packages required by K-IPO, and pip may fail to automatically resolve the resulting dependency conflicts. To avoid installation issues, a setup.sh script is provided to manually install the required dependency versions and configure the K-IPO environment.

Usage

Demo Example (API)

The code listing below illustrates a representative example of how K-IPO can be applied to oversample an imbalanced tabular binary classification dataset. TAU_THRESHOLD, TOPK_OVERLAP, TOPK_ORDERING, and BALANCE_RATIO are configuration parameters that control the oversampling process. Their values are specified in a YAML configuration file, which, among other settings, defines the underlying generator used by K-IPO to generate new samples and the dataset on which the oversampling process is performed.

from kipo.selector import KIPOSelector as KIPO

kipo = KIPO(num_features, tau_threshold = TAU_THRESHOLD, topk_ordering = TOPK_ORDERING, 
           topk_overlap = TOPK_OVERLAP)

kipo_X_aug, kipo_y_aug, info = kipo.select(X_train, y_train, X_test, y_test, 
                                           ratio = BALANCE_RATIO, 
                                           generator = gen_conf["method"], 
                                           preprocessing = pipeline, 
                                           **gen_conf["params"])

Note

For a complete example demonstrating the K-IPO synthetic data generation workflow, we refer the reader to the example.py script.

Important

The K-IPO API does not currently support the direct integration of TabDDPM as an underlying generator for synthetic sample generation. Unlike the other supported generators (i.e., CTGAN, TVAE, Gaussian Copula, and SMOTENC), TabDDPM does not follow the widely adopted fit()-sample() interface. Nevertheless, TabDDPM can be used as the underlying generator through the driver code provided in example.py under the experiments/tab-ddpm/code directory. This implementation follows the iterative generate-then-select scheme of K-IPO and allows synthetic sample generation under a user-defined Kendall's tau ($\tau$) correlation constraint.

End-to-End Pipeline for AI4I2020

The demo.ipynb notebook presents an end-to-end pipeline for augmenting the AI4I2020 predictive maintenance dataset. The pipeline evaluates and compares K-IPO against several state-of-the-art data generation and oversampling methods, including CTGAN, TVAE, Gaussian Copula and SMOTENC.

Note

Due to its different API, TabDDPM is not integrated into the end-to-end augmentation pipeline presented in this notebook. However, using the generator.py script and appropriately configuring the dataset field in the corresponding YAML configuration file, the augmented version of the AI4I2020 dataset can still be generated using TabDDPM.

Datasets

To download and install the datasets used in the manuscript, along with the corresponding YAML configuration files, run the following commands:

chmod +x ./datasets/download.sh
./datasets/download.sh 

YAML Configuration Files

Each dataset is paired with a corresponding YAML configuration file that provides K-IPO with the required information to perform the data augmentation process. A representative YAML configuration file is structured as follows:

# Columns to be dropped before augmentation
drop_cols:
  - column 1
  - column 2

# Target variable configuration
target_col:
  name: name of the target variable
  encoding: True # Set to True if the target variable is already label encoded, False otherwise

# Names of numerical columns
num_cols:
  - column 1
  - column 2

# Names and optional ordering of categorical columns
cat_cols:
  - column 1:
      order: # Specify an order if a hierarchical pattern exists

# CSV separator (default: ',')
sep: ;

Important

The AI4I2020 dataset and its YAML configuration file are bundled with the repository under the datasets/ folder and can be used directly for the K-IPO API demonstration and end-to-end performance evaluation workflow without any additional setup.

Warning

As discussed earlier, TabDDPM follows a completely different API design compared to K-IPO and the other generators considered in this work. The main differences are summarized below:

• TabDDPM assumes that the input data are already prepared, split into training and testing subsets, and serialized into separate .npy files corresponding to numerical features, categorical features, and the target variable. Therefore, unlike the other generators, it does not accept a Pandas DataFrame or a NumPy array as input. Instead, it expects the input data to be loaded from predefined file paths.

• The generation of synthetic samples with TabDDPM requires two additional configuration files: (i) a TOML file that defines the parameters of the generation pipeline and (ii) a JSON file that describes the schema of the input dataset (e.g., the number of numerical and categorical features).

Consequently, downloading the raw datasets using the commands provided above is not sufficient to run the TabDDPM-based augmentation workflow. Additional steps are required, including the generation of the corresponding configuration files and the preparation of each dataset in the required .npy format. The following commands automate this process:

# Install the required dependencies and download the corresponding TOML and JSON configuration files
# The TOML files are stored under experiments/tab-ddpm/datasets/config/
# The JSON files are stored in the corresponding dataset directories under K-IPO/experiments/tab-ddpm/datasets/data/
chmod +x ./experiments/tab-ddpm/setup.sh
./experiments/tab-ddpm/setup.sh

# Split each raw dataset into training and testing subsets and store them as .npy files
# in the corresponding dataset directories under experiments/tab-ddpm/datasets/data/
chmod +x ./experiments/tab-ddpm/scripts/split.sh
./experiments/tab-ddpm/scripts/split.sh

For a detailed description of the TabDDPM API, please refer to the official repository.

Important

For the AI4I2020 dataset, the train-test split and the corresponding .npy files, along with the two required configuration files (TOML and JSON), are already bundled with the repository under the experiments/tab-ddpm/datasets/ folder. These files can be directly used for TabDDPM-based augmentation. Use example.py to generate synthetic samples under a user-defined Kendall's tau ($\tau$) correlation constraint (specified in the YAML configuration file), or generator.py for unconstrained oversampling.

Performance Evaluation

The experimental evaluation presented in the manuscript consists of three stages: (a) selecting the most suitable candidate data generator to be used as the basis for K-IPO synthetic sample generation, (b) performing a sensitivity analysis across the 20 evaluated datasets to determine the optimal K-IPO configuration parameters, namely the Kendall's tau ($\tau$) threshold and the top-k ordering constraint, for each dataset, and (c) evaluating K-IPO against existing data generation and oversampling approaches in terms of feature importance preservation, explanation consistency, class separability, and predictive performance.

The results from all three evaluation stages can be reproduced using the eval.sh script located in the experiments folder (experiments/), as follows:

chmod +x ./experiments/eval.sh

# Run the base generator selection stage
./experiments/eval.sh A

# Run the K-IPO sensitivity analysis stage
./experiments/eval.sh B

# Run the K-IPO performance evaluation stage
./experiments/eval.sh C 

Important

The execution of the above commands requires all 20 raw datasets to be available locally. Therefore, the datasets must be downloaded beforehand using the commands provided in the Datasets section.

Using the heatmap.pyscript located in the experiments/folder, you can generate the heatmaps presented in Figure 3 of the manuscript. To generate the heatmaps, run:

python ./experiments/heatmap.py 

The evaluation.ipynb notebook can be used to generate Tables 5, 6, and 9 (Friedman test results) and Figure 5 (critical difference diagrams) reported in the manuscript.

Note

The f-score_anova.py and perftime_analysis.py scripts can be used to generate the Figures 2 and 4 of the manuscript, respectively.

File Structure

• datasets/: Evaluated datasets (demo: AI4I2020)
  • config/: YAML configuration files for the datasets
  • data/: Raw imbalanced datasets
  • download.sh: Script for downloading the datasets and their corresponding YAML configuration files
• experiments/: Experiments folder
  • evaluation/: Augmented datasets and evaluation results per dataset (in total: 20)
    • abalone/: Results for abalone dataset
      • datasets/: Augmented datasets
        • CTGAN/: Datasets generated with CTGAN (in total: 10)
        • GaussianCopula/: Datasets generated with GaussianCopula (in total: 10)
        • K-IPO/: Datasets generated with K-IPO (in total: 10)
        • SMOTENC/: Datasets generated with SMOTENC (in total: 10)
        • TabDDPM/: Datasets generated with TabDDPM (in total: 10)
        • TVAE/: Datasets generated with TVAE (in total: 10)
      • importance/: Feature importance rankings
        • CTGAN/: Feature importance rankings for datasets generated with CTGAN (in total: 10)
        • GaussianCopula/: Feature importance rankings for datasets generated with GaussianCopula (in total: 10)
        • K-IPO/: Feature importance rankings for datasets generated with K-IPO (in total: 10)
        • SMOTENC/: Feature importance rankings for datasets generated with SMOTENC (in total: 10)
        • TabDDPM/: Feature importance rankings for datasets generated with TabDDPM (in total: 10)
        • TVAE/: Feature importance rankings for datasets generated with TVAE (in total: 10)
      • results/: Evaluation results
        • CTGAN.csv: Detailed results for the 10 CTGAN augmented datasets
        • GaussianCopula.csv: Detailed results for the 10 GaussianCopula augmented datasets
        • K-IPO.csv: Detailed results for the 10 K-IPO augmented datasets
        • SMOTENC.csv: Detailed results for the 10 SMOTENC augmented datasets
        • TabDDPM.csv: Detailed results for the 10 TabDDPM augmented datasets
        • TVAE.csv: Detailed results for the 10 TVAE augmented datasets
    • (The same pattern is repeated for each of the 20 datasets)
  • external/: External figures included in the manuscript
    • pdf/: .pdf format
      • f-score_anova.pdf: Figure 2 from the manuscript
      • runtime.pdf: Figure 4 from the manuscript
    • png/: .png format, DPI: 1200
      • f-score_anova.png: Figure 2 from the manuscript
      • runtime.png: Figure 4 from the manuscript
  • performance_analysis/: Reported execution times of the evaluated generators for data generation
    • abalone/: Runtime results for abalone dataset
      • CTGAN.csv: Detailed runtime results for CTGAN
      • GaussianCopula.csv: Detailed runtime results for CTGAN
      • K-IPO.csv: Detailed runtime results for K-IPO
      • SMOTENC.csv: Detailed runtime results for SMOTENC
      • TabDDPM.csv: Detailed runtime results for TabDDPM
      • TVAE.csv: Detailed runtime results for TVAE
    • (The same pattern is repeated for each of the 20 datasets)
  • selection/: Augmented datasets and evaluation results for selecting the K-IPO backbone generator (in total: 20)
    • abalone/: Results for abalone dataset
      • datasets/: Augmented datasets
        • CTGAN/: Datasets generated with CTGAN (in total: 10)
        • GaussianCopula/: Datasets generated with GaussianCopula (in total: 10)
        • SMOTENC/: Datasets generated with SMOTENC (in total: 10)
        • TabDDPM/: Datasets generated with TabDDPM (in total: 10) (for the abalone dataset, TabDDPM failed to satisfy the required Kendall's $\tau$ threshold of 0.7)
        • TVAE/: Datasets generated with TVAE (in total: 10)
      • results/: Evaluation results
        • CTGAN.csv: Detailed results for the ten CTGAN augmented datasets
        • GaussianCopula.csv: Detailed results for the ten GaussianCopula augmented datasets
        • SMOTENC.csv: Detailed results for the ten SMOTENC augmented datasets
        • TabDDPM.csv: Detailed runtime results for the ten TabDDPM augmented datasets (for the abalone dataset, TabDDPM failed to satisfy the required Kendall's $\tau$ threshold of 0.7)
        • TVAE.csv: Detailed results for the ten TVAE augmented datasets
    • (The same pattern is repeated for each of the 20 datasets)
  • sensitivity_analysis/: Sensitivity analysis of K-IPO on the evaluated datasets
    • datasets/: Augmented datasets
      • abalone/: Abalone augmented datasets (in total: 12)
      • (The same pattern is repeated for each of the 20 datasets)
    • heatmaps/: Heatmaps of generated datasets (Figure 3 from the manuscript)
      • pdf/: Heatmaps of generated datasets (.pdf format)
        • abalone.pdf: Heatmap for the abalone dataset (.pdf format)
        • (The same pattern is repeated for each of the 20 datasets)
      • png/: Heatmaps of generated datasets (.png format, DPI: 1200)
        • abalone.png: Heatmap for the abalone dataset (.png format)
        • (The same pattern is repeated for each of the 20 datasets)
    • results/: Evaluation results from the sensitivity analysis
      • abalone.csv: Detailed sensitivity analysis results for the abalone dataset
      • (The same pattern is repeated for each of the 20 datasets)
  • tab-ddpm/: TabDDPM integration
    • code/: Core implementation of the TabDDPM
      • lib/: Unmodified from the official repository
      • tab_ddpm/: Unmodified from the official repository
      • eval_simple.py: Unmodified from the official repository
      • example.py: TabDDPM-based augmentation with Kendall's tau ($\tau$) constraint
      • generator.py: TabDDPM API demonstration
      • sample.py: Modified version of the original script to support the K-IPO generation workflow
      • split.py: Performs train-test splitting and stores numerical features, categorical features, and the target variable as separate .npy files
      • split.sh: Script for generating the .npy files for the 20 evaluated datasets
      • train.py: Unmodified from the official repository
      • utils_train.py: Modified version of the original script to support the K-IPO generation workflow
    • datasets/: Raw evaluated datasets following the TabDDPM data format (demo: AI4I2020)
      • config/: TOML configuration files for the datasets
      • data/: TabDDPM files for the raw imbalanced datasets
        • ai4i2020/: TabDDPM files for the AI4I2020 dataset
          • info.json: Describes the schema of the AI4I2020 dataset
          • X_cat_test.npy: Categorical features of the test split of the AI4I2020 dataset
          • X_cat_train.npy: Categorical features of the train split of the AI4I2020 dataset
          • X_num_test.npy: Numerical features of the test split of the AI4I2020 dataset
          • X_num_train.npy: Numerical features of the train split of the AI4I2020 dataset
          • y_test.npy: Target variable of the test split of the AI4I2020 dataset
          • y_train.npy: Target variable of the train split of the AI4I2020 dataset
        • (The same pattern is repeated for each of the 20 datasets)
    • config.yml: TabDDPM experiment configuration file
    • requirements.txt: Additional Python dependencies required for executing the TabDDPM pipeline
    • setup.sh: Environment setup script for TabDDPM
  • config.yml: Experiments configuration file
  • eval.py: Evaluation of augmented datasets (both predictive capabilites and top-K overlap)
  • eval.sh: Script for running the three stages of the experimental evaluation
  • evaluation.ipynb: Notebook for generating Tables 5, 6, and 9 and Figure 5 reported in the manuscript
  • f-score_anova.py: Generates Figure 2 from the manuscript
  • generator.py: Generation of augmented datasets
  • heatmap.py: Generation of heatmaps (Figure 5 from the manuscript)
  • imbalance.py: Converts a balanced dataset into an imbalanced one
  • perftime_analysis.py: Generates Figure 4 from the manuscript
  • topk_features.yml: Number of top features per dataset (>= 90% cumulative ANOVA F-score)
  • utils.py: Helper functions for running experiments
• ground_truth/: Ground truth for the evaluated datasets
  • data/: Feature importance rankings for the evaluated datasets
  • extract.py: Ground truth computation using the seven supported methods
  • extract.sh: Script for generating the ground-truth feature importance rankings for the 20 evaluated datasets
  • gini.py: Script for computing the Gini index (ACK: scikit-feature)
  • laplacian.py: Script for computing Laplacian Scores (ACK: scikit-feature)
  • utils.py: Helper functions for ground truth extraction
• src/kipo/: Core implementation of the K-IPO package
  • generator.py: Generation of augemented datasets using the supported generators
  • importance.py: Feature importance computation using the three supported XAI methods
  • models.py: Definition of models used for evaluation in the experiments
  • selector.py: Core backbone class of K-IPO
  • sofi.py: Source code of Sparseness-Optimized Feature Importance (SOFI) explainer
  • utils.py: Helper functions
• config.yml: Configuration file for demo example
• demo.ipynb: End-to-end pipeline for data generation and evaluation on the AI4I2020 predictive maintenance dataset
• example.py: K-IPO API demonstration
• pyproject.toml: Project configuration file containing package metadata and dependency specifications
• requirements.txt: Python dependencies
• setup.py: Deprecated setup script for the K-IPO package
• setup.sh: Script for setting up the K-IPO package environment and installing the required dependencies

Citation

If you find K-IPO useful for your research, please cite:

@article{Tyrovolas2026,
    title = {K-IPO: Kendall-constrained Importance Preserving Oversampling for Imbalanced Tabular Data}, 
    author = {Marios Tyrovolas and Argiris Sofotasios and Dimitris Metaxakis and Georgios Mermigkis and 
              George Georgoulas and Panagiotis Hadjidoukas and Chrysostomos Stylios},
    year = {2026},
    eprint = {2607.16478},
    archivePrefix = {arXiv}
}

Acknowledgments

This work has been supported by project MIS 5154714 of the National Recovery and Resilience Plan Greece 2.0, funded by the European Union under the NextGenerationEU Program.