### 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](https://archive.ics.uci.edu)

    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](https://docs.python.org/3/library/csv.html)

    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](https://fairbench.readthedocs.io/material/visualization/)):

    --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](https://mammoth-ai.eu) pipeline it is really important to select 'onnx' as the '--deploy' argument. The [ONNX](https://onnxruntime.ai) model accelerator and model_params.npy are used to integrate with the [MAMMOth-toolkit](https://github.com/mammoth-eu/mammoth-toolkit-releases) or the demonstrator app from the [mammoth-commons](https://github.com/mammoth-eu/mammoth-toolkit-releases) 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](https://link.springer.com/chapter/10.1007/978-3-031-18840-4_21),”  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 [arjun.roy@unibw.de](mailto:arjun.roy@unibw.de) 
Check out the source code at: [GITHUB](https://github.com/arjunroyihrpa/MMM_fair).