Package: fairdo
Fairness-Agnostic Data OptimizationFairDois a Python package for mitigating bias in data.Official repositoryof:Towards Fairness and Privacy: A Novel Data Pre-processing Optimization Framework for Non-binary Protected AttributesDocumentation:https://fairdo.readthedocs.io/en/latest/Source Code:https://github.com/mkduong-ai/fairdo/tree/mainFairDoworks specifically for tabular data (pandas.DataFrame) where the data is pre-processed in
such a way that it becomes fair according to a user-given fairness metric.
The pre-processing approach isfairness-agnostic, enabling the optimization
of different fairness criteria.
The framework is able to deal withnon-binaryprotected attributes
such as nationality, race, and gender that arise in real-world datasets.
Due to the possibility of choosing between any of the available fairness metrics,
it is possible to aim for theleast fortunate group
(Rawls' A Theory of Justice [2]) or the general utility of all groups
(Utilitarianism).How does it work?The pre-processing methods (fairdo.preprocessing.HeuristicWrapperandfairdo.preprocessing.DefaultPreprocessing)
work byremoving discriminatory data points.
By doing so, the dataset becomes much more balanced and less biased towards
a particular social group.
We approach this task as acombinatorial optimization problem, which
means selecting a subset of the dataset that minimizes the discrimination score.
Because there are exponentially many possibilities for selecting a subset,
our approach usesgenetic algorithmsto find a fair subset.Advices:rocket:For a quick start, use theDefaultPreprocessingclass with the default settings.
An example is given intutorials/1. Default Preprocessorand below.:white_check_mark:For data integrity, you want to keep the original data $D$
and only add fair synthetic data $G$ on top of it.
(We include examples intutorials/where we use the (SDV)[https://github.com/sdv-dev/SDV] package
to generate synthetic data.)
For this, you need to specify.fit_transform(approach='add')for the pre-processorsfairdo.preprocessing.HeuristicWrapperandfairdo.preprocessing.DefaultPreprocessing.
This will only add the fair pre-processed synthetic data
to the original data.:dash:When having limited data, we advise employing synthetic data $G$ additionally
and merge it with the original data $D$, i.e., $D \cup G$.
The pre-processor can then be used on the merged data $D \cup G$ to ensure fairness.
It is also possible to use the methodology fordata integrity, as described above.:briefcase:When anonymity is required, only use synthetic data $G$ and do not
merge it with the original data $D$. The generated data $G$ can then be
pre-processed with our methods to ensure fairness.InstallationDependenciesPython (==3.8),numpy,scipy,pandas,sklearnSetup Python Environment# Create a virtual environmentpython-mvenv.venv# Activate the virtual environment# On Windows:.venv\Scripts\activate# On macOS and Linux:source.venv/bin/activatePyPI Distribution (recommended)The package is distributed via PyPI and can be directly installed with:pipinstallfairdoManual Installation (latest version)To install the latest version, execute following commands:# Clone repogitclonehttps://github.com/mkduong-ai/fairdo.git# Move to repo foldercdfairdo# Install from sourcepythonsetup.pyinstallDevelopment InstallationInstalling in development mode is useful to make changes in the source code take effect instantly.
This means that the package is installed in such a way that changes to the source code
are immediately reflected without the need to reinstall the package. This can be done in the following
way:# Clone repogitclonehttps://github.com/mkduong-ai/fairdo.git# Move to repo foldercdfairdo# Development installationpipinstall-e.Install Optional DependenciesTo use the synthetic data generation, you can install theSDVpackage
by executing the following command:pipinstallsdv==1.10.0We did not include theSDVpackage as a dependency, because it is not required
for the core functionality of theFairDopackage.
Using any other synthetic data generation package is also possible.
Still, some examples in thetutorials/folder use theSDVpackage.Example UsageIn the following example, we use the COMPAS [1] dataset.
The protected attribute israceand the label isrecidivism.
Here, we deploy thedefault pre-processor, which internally uses a genetic algorithm,
to remove discriminatory samples of the given dataset.
The default pre-processor prevents removing all individuals of a single group.# fairdo packagefromfairdo.utils.datasetimportload_datafromfairdo.preprocessingimportDefaultPreprocessing# fairdo metricsfromfairdo.metricsimportstatistical_parity_abs_diff_max# Loading a sample dataset with all required information# data is a pandas.DataFramedata,label,protected_attributes=load_data('compas',print_info=False)# Initialize DefaultPreprocessing objectpreprocessor=DefaultPreprocessing(protected_attribute=protected_attributes[0],label=label)# Fit and transform the datadata_fair=preprocessor.fit_transform(dataset=data)# Print no. samples and discrimination before and afterdisc_before=statistical_parity_abs_diff_max(data[label],data[protected_attributes[0]].to_numpy())disc_after=statistical_parity_abs_diff_max(data_fair[label],data_fair[protected_attributes[0]].to_numpy())print(len(data),disc_before)print(len(data_fair),disc_after)By running this example, theresulting datasetusually has a statisticaldisparity score of <1%(max. score between all five races),
while theoriginal dataset exhibits 27% statistical disparity.DocumentationThe documentation is available athttps://fairdo.readthedocs.io/en/latest/.
To build the documentation manually, follow this guide:The package follows the PEP8 style guide and is documented with NumPy style
DocStrings. To build the HTML pages from the documentation manually,
follow these instructions:Activate virtual environment and install sphinx.# Activate the virtual environment# On Windows:.venv\Scripts\activate# On macOS and Linux:source.venv/bin/activate# Install Sphinx and a required themepipinstallsphinxfuroRun document generation script in UNIX-Systems:# Move to /docscddocs# Run script to generate documentationbashgenerate_docs.shThe HTML pages are then located indocs/_build/html.
Opendocs/_build/html/index.htmlto view the front page.CitationWhen usingFairDoin your work, cite our paper:@inproceedings{duong2023framework,title={Towards Fairness and Privacy: A Novel Data Pre-processing Optimization Framework for Non-binary Protected Attributes},author={Duong, Manh Khoi and Conrad, Stefan},booktitle={The 21st Australasian Data Mining Conference 2023},year={2023},organization={Springer Nature}}References[1] Larson, J., Angwin, J., Mattu, S.,  Kirchner, L.: Machine
bias (May 2016),https://www.propublica.org/article/machine-bias-risk-assessments-in-criminal-sentencing[2] Rawls, J.: A Theory of Justice (1971), Belknap Press, ISBN: 978-0-674-00078-0