Aequitas Fairflow is built around two customizable components: Datasets and Methods.

Datasets

Datasets follow a standard lifecycle: instantiation $\rightarrow$ load $\rightarrow$ split. You can use GenericDataset to load local files.

Methods

Methods are categorized by when they intervene in the ML pipeline:

1. Pre-processing: Transforms the dataset before training (e.g., PrevalenceSampling).
2. In-processing: Scores the dataset during training (e.g., FairGBM).
3. Post-processing: Transforms the scores after prediction (e.g., GroupThreshold).

Example of a sequential pipeline using all three stages:

from aequitas.fairflow.datasets import GenericDataset
from aequitas.fairflow.methods.preprocessing import PrevalenceSampling
from aequitas.fairflow.methods.inprocessing import FairGBM
from aequitas.fairflow.methods.postprocessing import GroupThreshold

# 1. Dataset Setup
dataset = GenericDataset(path="dataset.csv")
dataset.load_data()
splits = dataset.create_splits()

# 2. Pre-processing
sampling = PrevalenceSampling()
sampling.fit(*splits["train"])
sampled_data = sampling.transform(*splits["train"])

# 3. In-processing
model = FairGBM()
model.fit(*sampled_data)
preds = model.predict_proba(*splits["validation"])

# 4. Post-processing
threshold = GroupThreshold()
threshold.fit(*splits["validation"], preds)
final_scores = threshold.transform(*splits["validation"], preds)

Aequitas provides interfaces for different types of fairness intervention algorithms. Depending on the algorithm type, the workflow varies:

Pre-processing

Used to transform the training data before model training (e.g., PrevalenceSampling).

In-processing

Used to train a model that incorporates fairness constraints directly during training (e.g., FairGBM).

Post-processing

Used to adjust model scores or thresholds after training to achieve fairness targets (e.g., BalancedGroupThreshold).

# --- Pre-processing example ---
from aequitas.flow.methods.preprocessing import PrevalenceSampling

sampler = PrevalenceSampling()
sampler.fit(dataset.train.X, dataset.train.y, dataset.train.s)
X_sample, y_sample, s_sample = sampler.transform(dataset.train.X, dataset.train.y, dataset.train.s)

# --- In-processing example ---
from aequitas.flow.methods.inprocessing import FairGBM

model = FairGBM()
model.fit(X_sample, y_sample, s_sample)
scores_val = model.predict_proba(dataset.validation.X, dataset.validation.y, dataset.validation.s)
scores_test = model.predict_proba(dataset.test.X, dataset.test.y, dataset.test.s)

# --- Post-processing example ---
from aequitas.flow.methods.postprocessing import BalancedGroupThreshold

# Example: Adjusting thresholds to achieve equal FPR
threshold = BalancedGroupThreshold("top_pct", 0.1, "fpr")
threshold.fit(dataset.validation.X, scores_val, dataset.validation.y, dataset.validation.s)
corrected_scores = threshold.transform(dataset.test.X, scores_test, dataset.test.s)