Metadata-Version: 2.4
Name: tabfairgdt
Version: 0.1.1
Summary: Fast Fair Tabular Data Generator using Autoregressive Decision Trees
Author-email: Emmanouil Panagiotou <emmanouil.panagiotou@fu-berlin.de>, Benoît Ronval <benoit.ronval@uclouvain.be>
License: MIT
Project-URL: Homepage, https://arxiv.org/abs/2509.19927
Project-URL: Repository, https://github.com/emapanagiotou/tabfairgdt
Keywords: synthetic data,fairness,decision trees,tabular data,generative model
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: scipy>=1.7
Requires-Dist: tqdm>=4.60
Requires-Dist: joblib>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# TabFairGDT

**TabFairGDT** — Fast Fair Tabular Data Generator using Autoregressive Decision Trees.

Generates synthetic tabular data with built-in fairness constraints via leaf-relabeling of CART models.

## Installation

```bash
pip install tabfairgdt
```

## Quick Start

```python
import pandas as pd
from tabfairgdt import TABFAIRGDT

df = pd.read_csv("data.csv")
df["income"] = df["income"].astype("category")
df["sex"] = df["sex"].astype("category")

dtype_map = {col: str(df[col].dtype) for col in df.columns}
# Map pandas dtypes to tabfairgdt types
dtype_map = {
    col: "category" if df[col].dtype.name in ("category", "object", "bool")
    else "float" if df[col].dtype.kind == "f"
    else "int"
    for col in df.columns
}

generator = TABFAIRGDT(
    protected_attribute="sex",
    target="income",
    criterion="dp",          # demographic parity
    dtype_map=dtype_map,
    seed=42,
)
generator.fit(df, lamda=0.5)   # lamda=0: no fairness, lamda=1: max fairness
synthetic_df = generator.generate(k=1000)
```

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `protected_attribute` | required | Column name of the sensitive/protected attribute |
| `target` | required | Column name of the target variable |
| `dtype_map` | required | Dict mapping column names to dtypes (`'int'`, `'float'`, `'category'`, `'bool'`, `'datetime'`) |
| `criterion` | `"dp"` | Fairness criterion: `"dp"` (demographic parity) |
| `lamda` | `0.5` | Fairness–utility tradeoff passed to `fit()`: `0` = no fairness, `1` = max fairness |
| `acc_threshold` | `-1` | Max allowed accuracy drop as a fraction (e.g., `0.05` = 5%); `-1` = no limit |
| `seed` | `None` | Random seed for reproducibility |
| `parallel` | `True` | Use parallel fitting across columns |
| `re_order` | `False` | Reorder features by correlation (`"corr_asc_target"`, `"corr_desc_target"`, etc.) |
| `smoothing` | `False` | Apply kernel smoothing to continuous columns (`"density"` or column dict) |
| `proper` | `False` | Bootstrap training data during fitting |

## Citation

```bibtex
@inproceedings{panagiotou2025tabfairgdt,
  title     = {TABFAIRGDT: A Fast Fair Tabular Data Generator using Autoregressive Decision Trees},
  author    = {Panagiotou, Emmanouil and Ronval, Benoît and Roy, Arjun and Bothmann, Ludwig and Bischl, Bernd and Nijssen, Siegfried and Ntoutsi, Eirini},
  booktitle = {IEEE ICDM 2025},
  year      = {2025},
  url       = {https://arxiv.org/abs/2509.19927}
}
```
