mmm-fair 0.3.1

A multi-objective multi-fairness boosting classifier

MMM-Fair is a multi-objective, fairness-aware boosting classifier originally inspired by the paper: "Multi-fairness Under Class-Imbalance"

https://link.springer.com/chapter/10.1007/978-3-031-18840-4_21

The original algorithm targeted Equalized Odds (a.k.a. Disparate Mistreatment). This MMM-Fair implementation generalizes to multiple fairness objectives:

• Demographic Parity (DP)

• Equal Opportunity (EP)

• Equalized Odds (EO)

We further improve the approach by:

1. Flexible Base Learners: Any scikit-learn estimator (e.g. DecisionTreeClassifier, LogisticRegression, ExtraTreeClassifier, etc.) can be used as the base learner.
2. Fairness-Weighted Alpha: The boosting weight (alpha) accounts for fairness metrics alongside classification error.
3. Dynamic Handling of Over-Boosted Samples: Reduces excessive emphasis on specific samples once fairness goals are partially met.

Installation

pip install mmm-fair

Requires Python 3.11+.

Dependencies: numpy, scikit-learn, tqdm, pymoo, pandas, ucimlrepo, skl2onnx, etc.

Usage Overview

You can import and use MMM-Fair directly:

from mmm_fair import MMM_Fair 
from sklearn.tree import DecisionTreeClassifier

Suppose you have X (features), y (labels)

mmm = MMM_Fair(
estimator=DecisionTreeClassifier(max_depth=5),
constraints="EO",        # or "DP", "EP"
n_estimators=1000,
random_state=42,
# other parameters, e.g. gamma, saIndex, saValue...
)

mmm.fit(X, y)
preds = mmm.predict(X_test)

Fairness Constraints

• constraints="DP" → Demographic Parity

• constraints="EP" → Equal Opportunity

• constraints="EO" → Equalized Odds

Pass the relevant saIndex (sensitive attribute array) and saValue (dictionary of protected vs. non-protected group mappings) to MMM-Fair if you want it to track fairness properly for subgroups.

Train & Deploy Script

This package provides a script, train_and_deploy.py, which:

1. Loads data (from a known UCI dataset or a local CSV).
2. Specifies fairness constraints, protected attributes, and base learner.
3. Trains MMM-Fair with your chosen hyperparameters.
4. Deploys the model in ONNX or pickle format.

Example command:

using UCI library

python -m mmm_fair.train_and_deploy \
  --dataset Adult \
  --prots race sex \
  --nprotgs White Male \
  --constraint EO \
  --base_learner Logistic \
  --deploy onnx

using local "csv" data

python -m mmm_fair.train_and_deploy \
  --dataset mydata.csv \
  --target label_col \
  --prots prot_1 prot_2 prot_3 \
  --nprotgs npg1 npg2 npg3 \
  --constraint EO \
  --base_learner tree \
  --deploy onnx

Currently the fairness intervention only implemented for categorical groups. So if protected attribute is numerical e.g. "age" then for non-protected value i.e. --nprotgs provide a range like 30_60 as argument.

Additional options

If you want to select theta from Pareto optimal ensembles (default is False) set:

--pareto True

If you want to provide test data:

--test 'your_test_file.csv'

Or just test split:

--test 0.3

If you want change style (default is table, choose from {table, console, html}) of report displayed (Check FairBench Library for more details):

--report_type Console

Result: Multiple ONNX files (one per boosting round) plus a model_params.npy inside a directory. It’s then zipped into a .zip archive for distribution or analysis.

MAMMOth Toolkit Integration

For the bias exploration using MAMMOth pipeline it is really important to select 'onnx' as the '--deploy' argument. The ONNX model accelerator and model_params.npy are used to integrate with the MAMMOth-toolkit or the demonstrator app from the mammoth-commons project.

By providing the .zip archive, you can:

• Upload it to MAMMOth,

• Examine bias and performance metrics across subgroups,

• Compare fairness trade-offs with a user-friendly interface.

Example Workflow

1. Choose Fairness Constraint: e.g., DP, EO, or EP.
2. Define sensitive attributes in saIndex and the protected-group condition in saValue.
3. Pick base learner (e.g., DecisionTreeClassifier(max_depth=5)).
4. Train with a large number of estimators (n_estimators=300 or 1000) for best performance.
5. Optionally do partial ensemble selection with update_theta(criteria="all") or update_theta(criteria="fairness") .
6. Export to ONNX or pickle for downstream usage.

References

“Multi-Fairness Under Class-Imbalance,” Roy, Arjun, Vasileios Iosifidis, and Eirini Ntoutsi. International Conference on Discovery Science. Cham: Springer Nature Switzerland, 2022.

License & Contributing

This project is released under [Apache License Version 2.0]. Contributions are welcome—please open an issue or pull request on GitHub.

Contact

For questions or collaborations, please contact [e-mail] Check out the source code at: GITHUB.