fairtfm 1.0.0__tar.gz

fairtfm-1.0.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

fairtfm-1.0.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: fairtfm
+Version: 1.0.0
+Summary: A tabular foundation model pretrained with fairness constraints. It can make fair predictions in one forward pass.
+Author-email: patrikken <kenfackjoslin@gmail.com>
+Project-URL: Homepage, https://huggingface.co/patrikken/FairTFM
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.9
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: fairlearn>=0.13.0
+Requires-Dist: huggingface_hub>=0.20
+Provides-Extra: examples
+Requires-Dist: xgboost>=3.2.0; extra == "examples"
+Requires-Dist: seaborn>=0.13.2; extra == "examples"
+Requires-Dist: folktables>=0.0.12; extra == "examples"
+Requires-Dist: gdown; extra == "examples"
+Dynamic: license-file
+
+# FairTFM - Pretrained Tabular Foundation Model for fair predictions on Tabular Data
+
+This repository provides **inference-only** FairTFM. The training code will follow. 
+
+## Quick Start
+
+Install directly from source:
+
+```bash
+pip install .
+```
+
+or, for an editable/development install:
+
+```bash
+pip install -e .
+```
+
+This installs the `fairtfm` package along with its runtime dependencies (torch, numpy, pandas, scikit-learn, fairlearn, folktables, huggingface_hub). Extra dependencies used only by the paper reproduction / example scripts (xgboost, seaborn, gdown) can be installed with:
+
+```bash
+pip install -e ".[examples]"
+```
+
+### Model checkpoints
+
+By default, `FairTFMClassifier()` automatically downloads the default checkpoint (λ = 0.7) from the [Hugging Face Hub](https://huggingface.co/patrikken/FairTFM) — no manual download needed:
+
+```python
+from fairtfm import FairTFMClassifier
+
+classifier = FairTFMClassifier()  # downloads FairTFM-0.7-epoch_10000.pt from Hugging Face
+```
+
+You can also point it at a specific checkpoint, either a local file, or a full Hugging Face URL:
+
+```python
+classifier = FairTFMClassifier(model="https://huggingface.co/patrikken/FairTFM/blob/main/FairTFM-25-epoch_10000.pt")
+classifier = FairTFMClassifier(model="path/to/local/checkpoint.pt")
+```
+
+All checkpoints produced during training across lambda values (0.7, 1.0, 10, 25), which are used to generate the fairness/accuracy Pareto front, are also bundled and available for downloading from [this](https://drive.google.com/uc?export=download&id=1SBztiK9SZZ_6-3I8oT8KadOR0JmuN-j7) google drive link. Higher λ trades predictive performance for lower fairness-metric disparity, so depending on your use case a different checkpoint may give a stronger fairness/accuracy tradeoff — download the bundle and select the checkpoint that fits your needs:
+
+```sh
+pip install gdown
+gdown 1SBztiK9SZZ_6-3I8oT8KadOR0JmuN-j7
+
+```
+
+or use curl 
+
+```
+wget --no-check-certificate "https://drive.google.com/uc?export=download&id=1SBztiK9SZZ_6-3I8oT8KadOR0JmuN-j7" -o checkpoints.zip
+```
+
+### FairTFMClassifier interface overview
+
+```python
+from fairtfm import FairTFMClassifier, compute_fairness_metrics
+
+# Load the default checkpoint from the Hugging Face Hub
+classifier = FairTFMClassifier()
+
+# or load a specific checkpoint (local path, Hugging Face repo id/URL)
+classifier = FairTFMClassifier(model="path/to/checkpoint")
+
+# Fit on training data
+classifier.fit(X_train, y_train, s_train)
+
+# Predict
+predictions = classifier.predict(X_test, s_test)
+probabilities = classifier.predict_proba(X_test, s_test)
+
+# Get embeddings of the testing data
+embeddings = classifier.transform(X_test, s_test)
+
+# Fairness metrics (returns dict with performance metrics)
+compute_fairness_metrics(X_test, y_test, s_test)
+```
+
+### ACSPumsDataset
+
+```python
+from fairtfm.datasets import ACSPumsDataset
+
+dataset = ACSPumsDataset(
+    acs_task="acs_income",      # Income, employment, mobility, travel_time, public_coverage
+    states=["CA"],              # State codes
+    sensitive_attr_name="SEX"   # SEX, RAC1P (Race), AGEP (Age)
+)
+dataset.preprocess()
+X_train, X_test, y_train, y_test, s_train, s_test = dataset.get_splits()
+```
+
+
+## Supported Tasks
+
+- `acs_income` - Income prediction
+- `acs_employment` - Employment status
+- `acs_mobility` - Geographic mobility
+- `acs_public_coverage` - Public health insurance
+- `acs_travel_time` - Travel time to work
+
+## Sensitive Attributes
+
+- `SEX` - Gender
+- `RAC1P` - Race (White/Black)
+- `AGEP` - Age (binarized by median)
+
+## Code example
+For inference example use the [notebook](notebook.ipynb) or the [inference_example.py](inference_example.py)
+
+
+# Reproducing the paper main results.
+
+For reproducing the paper's results run:
+
+```python
+python paper_results.py --full-eval
+```
+
+This will evaluate all the models in [`eval_config/eval_models.csv`](eval_config/eval_models.csv) on all 120 tasks in [`eval_config/fairness_tasks_eval.csv`](eval_config/fairness_tasks_eval.csv).
+
+## Citation
+If you use FairTFM for research purposes, please cite our [paper](https://openreview.net/forum?id=ajIvCEbadL):
+
+```bibtex
+@inproceedings{
+kenfack2026training,
+title={Training Fair Tabular Foundation Models},
+author={Patrik Kenfack and Jesse C. Cresswell and Anthony L. Caterini and Samira Ebrahimi Kahou and Ulrich A{\"\i}vodji},
+booktitle={2nd ICML Workshop on Foundation Models for Structured Data},
+year={2026},
+url={https://openreview.net/forum?id=ajIvCEbadL}
+}
+```

fairtfm-1.0.0/README.md

@@ -0,0 +1,136 @@
+# FairTFM - Pretrained Tabular Foundation Model for fair predictions on Tabular Data
+
+This repository provides **inference-only** FairTFM. The training code will follow. 
+
+## Quick Start
+
+Install directly from source:
+
+```bash
+pip install .
+```
+
+or, for an editable/development install:
+
+```bash
+pip install -e .
+```
+
+This installs the `fairtfm` package along with its runtime dependencies (torch, numpy, pandas, scikit-learn, fairlearn, folktables, huggingface_hub). Extra dependencies used only by the paper reproduction / example scripts (xgboost, seaborn, gdown) can be installed with:
+
+```bash
+pip install -e ".[examples]"
+```
+
+### Model checkpoints
+
+By default, `FairTFMClassifier()` automatically downloads the default checkpoint (λ = 0.7) from the [Hugging Face Hub](https://huggingface.co/patrikken/FairTFM) — no manual download needed:
+
+```python
+from fairtfm import FairTFMClassifier
+
+classifier = FairTFMClassifier()  # downloads FairTFM-0.7-epoch_10000.pt from Hugging Face
+```
+
+You can also point it at a specific checkpoint, either a local file, or a full Hugging Face URL:
+
+```python
+classifier = FairTFMClassifier(model="https://huggingface.co/patrikken/FairTFM/blob/main/FairTFM-25-epoch_10000.pt")
+classifier = FairTFMClassifier(model="path/to/local/checkpoint.pt")
+```
+
+All checkpoints produced during training across lambda values (0.7, 1.0, 10, 25), which are used to generate the fairness/accuracy Pareto front, are also bundled and available for downloading from [this](https://drive.google.com/uc?export=download&id=1SBztiK9SZZ_6-3I8oT8KadOR0JmuN-j7) google drive link. Higher λ trades predictive performance for lower fairness-metric disparity, so depending on your use case a different checkpoint may give a stronger fairness/accuracy tradeoff — download the bundle and select the checkpoint that fits your needs:
+
+```sh
+pip install gdown
+gdown 1SBztiK9SZZ_6-3I8oT8KadOR0JmuN-j7
+
+```
+
+or use curl 
+
+```
+wget --no-check-certificate "https://drive.google.com/uc?export=download&id=1SBztiK9SZZ_6-3I8oT8KadOR0JmuN-j7" -o checkpoints.zip
+```
+
+### FairTFMClassifier interface overview
+
+```python
+from fairtfm import FairTFMClassifier, compute_fairness_metrics
+
+# Load the default checkpoint from the Hugging Face Hub
+classifier = FairTFMClassifier()
+
+# or load a specific checkpoint (local path, Hugging Face repo id/URL)
+classifier = FairTFMClassifier(model="path/to/checkpoint")
+
+# Fit on training data
+classifier.fit(X_train, y_train, s_train)
+
+# Predict
+predictions = classifier.predict(X_test, s_test)
+probabilities = classifier.predict_proba(X_test, s_test)
+
+# Get embeddings of the testing data
+embeddings = classifier.transform(X_test, s_test)
+
+# Fairness metrics (returns dict with performance metrics)
+compute_fairness_metrics(X_test, y_test, s_test)
+```
+
+### ACSPumsDataset
+
+```python
+from fairtfm.datasets import ACSPumsDataset
+
+dataset = ACSPumsDataset(
+    acs_task="acs_income",      # Income, employment, mobility, travel_time, public_coverage
+    states=["CA"],              # State codes
+    sensitive_attr_name="SEX"   # SEX, RAC1P (Race), AGEP (Age)
+)
+dataset.preprocess()
+X_train, X_test, y_train, y_test, s_train, s_test = dataset.get_splits()
+```
+
+
+## Supported Tasks
+
+- `acs_income` - Income prediction
+- `acs_employment` - Employment status
+- `acs_mobility` - Geographic mobility
+- `acs_public_coverage` - Public health insurance
+- `acs_travel_time` - Travel time to work
+
+## Sensitive Attributes
+
+- `SEX` - Gender
+- `RAC1P` - Race (White/Black)
+- `AGEP` - Age (binarized by median)
+
+## Code example
+For inference example use the [notebook](notebook.ipynb) or the [inference_example.py](inference_example.py)
+
+
+# Reproducing the paper main results.
+
+For reproducing the paper's results run:
+
+```python
+python paper_results.py --full-eval
+```
+
+This will evaluate all the models in [`eval_config/eval_models.csv`](eval_config/eval_models.csv) on all 120 tasks in [`eval_config/fairness_tasks_eval.csv`](eval_config/fairness_tasks_eval.csv).
+
+## Citation
+If you use FairTFM for research purposes, please cite our [paper](https://openreview.net/forum?id=ajIvCEbadL):
+
+```bibtex
+@inproceedings{
+kenfack2026training,
+title={Training Fair Tabular Foundation Models},
+author={Patrik Kenfack and Jesse C. Cresswell and Anthony L. Caterini and Samira Ebrahimi Kahou and Ulrich A{\"\i}vodji},
+booktitle={2nd ICML Workshop on Foundation Models for Structured Data},
+year={2026},
+url={https://openreview.net/forum?id=ajIvCEbadL}
+}
+```

fairtfm-1.0.0/fairtfm/__init__.py

@@ -0,0 +1,17 @@
+"""
+FairTFM - Fair Tabular Foundation Model 
+"""
+
+from .inference import FairTFMClassifier
+
+__version__ = "1.0.0"
+__all__ = [ 
+    "FairTFMClassifier",
+]
+
+
+def __getattr__(name):
+    if name == "ACSPumsDataset":
+        from .datasets import ACSPumsDataset
+        return ACSPumsDataset
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

fairtfm-1.0.0/fairtfm/datasets/__init__.py

@@ -0,0 +1,20 @@
+"""
+Fairness dataset loaders for ACS PUMS and other benchmark tasks.
+"""
+
+__all__ = [
+    "ACSPumsDataset",
+]
+
+
+def __getattr__(name):
+    if name == "ACSPumsDataset":
+        try:
+            from .loaders import ACSPumsDataset
+        except ImportError as e:
+            raise ImportError(
+                "ACSPumsDataset requires the 'folktables' package. "
+                "Install it with `pip install fairtfm[examples]` or `pip install folktables`."
+            ) from e
+        return ACSPumsDataset
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

fairtfm-1.0.0/fairtfm/datasets/loaders.py

@@ -0,0 +1,212 @@
+"""
+ACS PUMS dataset loader for fairness tasks.
+Used for testing inference on real fairness benchmark datasets.
+"""
+import pandas as pd
+import numpy as np
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+from folktables import (
+    ACSDataSource,
+    ACSEmployment,
+    ACSIncome,
+    ACSMobility,
+    ACSPublicCoverage,
+    ACSTravelTime,
+)
+
+
+class ACSPumsDataset:
+    """
+    Loads American Community Survey (ACS) Public Use Microdata Sample (PUMS) tasks.
+    Provides fairness benchmarks with configurable sensitive attributes.
+    
+    Example:
+        >>> dataset = ACSPumsDataset(
+        ...     acs_task="acs_income",
+        ...     states=["CA"],
+        ...     sensitive_attr_name="SEX"
+        ... )
+        >>> dataset.preprocess()
+        >>> X_train, X_test, y_train, y_test, s_train, s_test = dataset.get_splits()
+    """
+    
+    def __init__(
+        self,
+        acs_task: str = "acs_income",
+        states: list = None,
+        survey_year: int = 2018,
+        sensitive_attr_name: str = "SEX",
+        horizon: str = "1-Year",
+        seed_everything: int = 42,
+        max_samples: int = None,
+        test_size: float = 0.2
+    ):
+        """
+        Initialize ACS PUMS dataset loader.
+        
+        Args:
+            acs_task: Task name ('acs_income', 'acs_employment', 'acs_mobility', 
+                     'acs_public_coverage', 'acs_travel_time')
+            states: List of state codes to include (e.g., ['CA', 'NY'])
+            survey_year: Survey year (default 2018)
+            sensitive_attr_name: Sensitive attribute ('SEX', 'RAC1P', 'AGEP')
+            horizon: Survey horizon ('1-Year' or '5-Year')
+            seed_everything: Random seed for reproducibility
+            max_samples: Maximum samples to load (None = all)
+            test_size: Proportion of data to use for testing
+        """
+        self.sensitive_attr_name = sensitive_attr_name
+        self.acs_task = acs_task
+        self.states = states if states is not None else ["AL"]
+        self.survey_year = survey_year
+        self.horizon = horizon
+        self.seed = seed_everything
+        self.max_samples = max_samples
+        self.test_size = test_size
+        
+        # Validation
+        if sensitive_attr_name not in ["SEX", "RAC1P", "AGEP"]:
+            raise ValueError(f"Unsupported sensitive attribute: {sensitive_attr_name}")
+        
+        if acs_task not in [
+            "acs_income", "acs_employment", "acs_mobility",
+            "acs_public_coverage", "acs_travel_time",
+        ]:
+            raise ValueError(f"Unsupported ACS task: {acs_task}")
+        
+        state_name = "_".join(self.states) if self.states else "all_states"
+        self.name = f"{acs_task}_{state_name}_{sensitive_attr_name}"
+        
+        self.data = None
+        self.target = None
+        self.sensitive_attr = None
+        self.train_idx = None
+        self.test_idx = None
+        self.X_train = None
+        self.X_test = None
+        self.y_train = None
+        self.y_test = None
+        self.s_train = None
+        self.s_test = None
+
+    def _get_task_class(self):
+        """Get the appropriate task class for the ACS task."""
+        task_map = {
+            "acs_income": ACSIncome,
+            "acs_employment": ACSEmployment,
+            "acs_mobility": ACSMobility,
+            "acs_public_coverage": ACSPublicCoverage,
+            "acs_travel_time": ACSTravelTime,
+        }
+        return task_map[self.acs_task]
+
+    def preprocess(self):
+        """
+        Download and preprocess the ACS PUMS dataset.
+        Applies task-specific transformations and handles sensitive attributes.
+        """
+        # Download data
+        data_source = ACSDataSource(
+            survey_year=self.survey_year,
+            horizon=self.horizon,
+            survey="person",
+            root_dir="data"
+        )
+        acs_data = data_source.get_data(
+            states=self.states,
+            download=True,
+            random_seed=self.seed
+        )
+        
+        # Subsample if needed
+        nb_sample = min(len(acs_data), self.max_samples) if self.max_samples else len(acs_data)
+        if self.max_samples is not None or len(self.states) == 0:
+            acs_data = acs_data.sample(n=nb_sample, random_state=self.seed)
+        
+        # Apply task-specific transformations
+        task_class = self._get_task_class()
+        acs_data, self.target, _ = task_class.df_to_pandas(acs_data)
+        
+        # Extract sensitive attributes
+        self.sensitive_attr = acs_data[self.sensitive_attr_name]
+        
+        # Keep only relevant features
+        self.data = acs_data.drop(columns=[self.sensitive_attr_name])
+        
+        # Handle race attribute
+        if self.sensitive_attr_name == "RAC1P":
+            idx = acs_data[self.sensitive_attr_name].isin([1, 2])  # White and Black only
+            self.data = self.data[idx]
+            self.target = self.target[idx]
+            self.sensitive_attr = self.sensitive_attr[idx]
+        
+        # binary age attribute
+        elif self.sensitive_attr_name == "AGEP":
+            self.sensitive_attr = self.sensitive_attr.apply(
+                lambda x: 1 if x > 25 else 0
+            )
+        
+        # Create train/test split
+        self.train_idx, self.test_idx = train_test_split(
+            range(len(self.data)),
+            test_size=self.test_size,
+            random_state=self.seed,
+            stratify=self.target,
+        )
+        
+        self.data = pd.get_dummies(self.data, drop_first=True).values.astype(np.float32) 
+        y_sc = LabelEncoder()
+        self.target = y_sc.fit_transform(self.target.squeeze())
+
+        s_sc = LabelEncoder()
+        self.sensitive_attr = s_sc.fit_transform(self.sensitive_attr.squeeze())
+
+        self.train_idx, self.test_idx = train_test_split(
+            range(len(self.data)),
+            test_size=self.test_size,
+            random_state=self.seed,
+            stratify=self.target,
+        ) 
+        self.input_dim = self.data.shape[1]
+        return self
+
+    def get_splits(self):
+        """
+        Get train/test splits with features, labels, and sensitive attributes.
+        
+        Returns:
+            Tuple of (X_train, X_test, y_train, y_test, s_train, s_test)
+        """
+        if self.data is None or self.target is None or self.sensitive_attr is None:
+            raise ValueError("Dataset not preprocessed. Call preprocess() first.")
+        scaler = StandardScaler()
+        """ self.data = pd.DataFrame(
+            scaler.fit_transform(self.data), columns=self.data.columns
+        ) """
+
+        scaler = StandardScaler() 
+
+        self.X_train = self.data[self.train_idx]
+        self.X_test = self.data[self.test_idx]
+        self.y_train = self.target[self.train_idx]
+        self.y_test = self.target[self.test_idx]
+        self.s_train = self.sensitive_attr[self.train_idx]
+        self.s_test = self.sensitive_attr[self.test_idx]
+
+        self.X_train = scaler.fit_transform(self.X_train).astype("float32")
+        self.X_test = scaler.transform(self.X_test).astype("float32")
+        return (
+            self.X_train, self.X_test,
+            self.y_train, self.y_test,
+            self.s_train, self.s_test
+        )
+
+    def __len__(self):
+        """Return total number of samples."""
+        if self.data is None:
+            return 0
+        return len(self.data)
+
+    def __repr__(self):
+        return f"ACSPumsDataset({self.name}, n_samples={len(self)})"