{"id":13393815,"url":"https://github.com/adebayoj/fairml","last_synced_at":"2025-12-30T09:08:59.087Z","repository":{"id":51733668,"uuid":"48899496","full_name":"adebayoj/fairml","owner":"adebayoj","description":null,"archived":false,"fork":false,"pushed_at":"2021-05-10T11:32:22.000Z","size":19440,"stargazers_count":362,"open_issues_count":14,"forks_count":72,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-02-21T08:49:50.788Z","etag":null,"topics":["auditing-predictive-models","discrimination","fairness","model-criticism","prediction-model","toolbox"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adebayoj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-02T05:14:16.000Z","updated_at":"2024-12-28T03:57:25.000Z","dependencies_parsed_at":"2022-08-22T11:40:11.644Z","dependency_job_id":null,"html_url":"https://github.com/adebayoj/fairml","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adebayoj%2Ffairml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adebayoj%2Ffairml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adebayoj%2Ffairml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adebayoj%2Ffairml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adebayoj","download_url":"https://codeload.github.com/adebayoj/fairml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243469220,"owners_count":20295713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auditing-predictive-models","discrimination","fairness","model-criticism","prediction-model","toolbox"],"created_at":"2024-07-30T17:01:00.678Z","updated_at":"2025-12-13T23:04:23.114Z","avatar_url":"https://github.com/adebayoj.png","language":"Python","readme":"========\n\n[![Build Status](https://travis-ci.org/adebayoj/fairml.svg?branch=master)](https://travis-ci.org/adebayoj/fairml/)\n[![Coverage Status](https://coveralls.io/repos/github/adebayoj/fairml/badge.svg?branch=master)](https://coveralls.io/github/adebayoj/fairml?branch=master)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/adebayoj/fairml/master/LICENSE)\n[![GitHub issues](https://img.shields.io/github/issues/adebayoj/fairml.svg)](https://github.com/adebayoj/fairml/issues)\n\nFairML: Auditing Black-Box Predictive Models\n=====================\nFairML is a python toolbox auditing the machine learning models for bias. \n\n\u003cimg src=\"https://raw.githubusercontent.com/adebayoj/fairml/master/doc/images/logo2.png\" width=\"700\"\u003e\n\n\n### Description\n\nPredictive models are increasingly been deployed for the purpose\nof determining access to services such as credit, insurance, and\nemployment. Despite societal gains in efficiency and \nproductivity through deployment of these models, potential \nsystemic flaws have not been fully addressed, particularly the\npotential for unintentional discrimination. This discrimination\ncould be on the basis of race, gender, religion, sexual orientation, or other characteristics. This project addresses\nthe question: how can an analyst determine the relative\nsignificance of the inputs to a black-box predictive model in \norder to assess the model’s fairness (or discriminatory extent)?\n\nWe present FairML, an end-to-end toolbox for auditing predictive\nmodels by quantifying the relative significance of the model’s\ninputs. FairML leverages model compression and four input ranking\nalgorithms to quantify a model’s relative predictive dependence\non its inputs. The relative significance of the inputs to a\npredictive model can then be used to assess the fairness (or\ndiscriminatory extent) of such a model. With FairML, analysts can\nmore easily audit cumbersome predictive models that are\ndifficult to interpret.s of black-box algorithms and corresponding input data.\n\n### Installation \n\nYou can pip install this package, via github - i.e. this repo - using the \nfollowing commands:\n\npip install https://github.com/adebayoj/fairml/archive/master.zip\n\nor you can clone the repository doing:\n\ngit clone https://github.com/adebayoj/fairml.git\n\nsudo python setup.py install\n\n### Methodology\n\n\n\u003cimg src=\"https://github.com/adebayoj/fairml/blob/master/doc/images/fairml_methodology_picture.png\" width=\"700\"\u003e\n\n### Code Demo\n\nNow we show how to use the fairml python package to audit\na black-box model.\n\n```python\n\"\"\"\nFirst we import modules for model building and data\nprocessing.\n\"\"\"\nimport pandas as pd\nimport numpy as np\nfrom sklearn.linear_model import LogisticRegression\n\n\"\"\"\nNow, we import the two key methods from fairml.\naudit_model takes:\n\n- (required) black-box function, which is the model to be audited\n- (required) sample_data to be perturbed for querying the function. This has to be a pandas dataframe with no missing data.\n\n- other optional parameters that control the mechanics of the auditing process, for example:\n  - number_of_runs : number of iterations to perform\n  - interactions : flag to enable checking model dependence on interactions.\n\naudit_model returns an overloaded dictionary where keys are the column names of input pandas dataframe and values are lists containing model  dependence on that particular feature. These lists of size number_of_runs.\n\n\"\"\"\nfrom fairml import audit_model\nfrom fairml import plot_generic_dependence_dictionary\n```\n\nAbove, we provide a quick explanation of the key fairml functionality. Now we move into building an example model that we'd like to audit.\n\n```python\n# read in the propublica data to be used for our analysis.\npropublica_data = pd.read_csv(\n    filepath_or_buffer=\"./doc/example_notebooks/\"\n    \"propublica_data_for_fairml.csv\")\n\n# create feature and design matrix for model building.\ncompas_rating = propublica_data.score_factor.values\npropublica_data = propublica_data.drop(\"score_factor\", 1)\n\n\n# this is just for demonstration, any classifier or regressor\n# can be used here. fairml only requires a predict function\n# to diagnose a black-box model.\n\n# we fit a quick and dirty logistic regression sklearn\n# model here.\nclf = LogisticRegression(penalty='l2', C=0.01)\nclf.fit(propublica_data.values, compas_rating)\n\n```\n\nNow let's audit the model built with FairML.\n\n```python\n\n#  call audit model with model\ntotal, _ = audit_model(clf.predict, propublica_data)\n\n# print feature importance\nprint(total)\n\n# generate feature dependence plot\nfig = plot_dependencies(\n    total.get_compress_dictionary_into_key_median(),\n    reverse_values=False,\n    title=\"FairML feature dependence\"\n)\nplt.savefig(\"fairml_ldp.eps\", transparent=False, bbox_inches='tight')\n```\n\nThe demo above produces the figure below. \n\n\u003cimg src=\"https://raw.githubusercontent.com/adebayoj/fairml/master/doc/images/feature_dependence_plot_fairml_propublica_linear_direct.png\" width=\"700\"\u003e\n\n\nFeel free to email the authors with any questions:  \n[Julius Adebayo](https://github.com/adebayoj) (julius.adebayo@gmail.com)   \n\n\n### Data\n\nThe data used for the demo above is available in the repo at: \n/doc/example_notebooks/propublica_data_for_fairml.csv\n\n","funding_links":[],"categories":["⚖️ Fairness, Bias \u0026 Ethics Testing","Toolkits and Open-source libraries","Model Explanation","Explaining Black Box Models and Datasets","Library \u0026 Toolkit","Explainability and Fairness","Python","Table of Contents","Technical Resources","Software and data sets"],"sub_categories":["Bias Detection","Others","Python packages","NLP","Open Source/Access Responsible AI Software Packages","Python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadebayoj%2Ffairml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadebayoj%2Ffairml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadebayoj%2Ffairml/lists"}