{"id":16492386,"url":"https://github.com/ibm/infairness","last_synced_at":"2025-03-15T11:33:19.487Z","repository":{"id":37835236,"uuid":"498414238","full_name":"IBM/inFairness","owner":"IBM","description":"PyTorch package to train and audit ML models for Individual Fairness","archived":false,"fork":false,"pushed_at":"2023-09-14T02:45:19.000Z","size":6521,"stargazers_count":64,"open_issues_count":12,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-02-27T01:11:07.872Z","etag":null,"topics":["fairness","fairness-ai","individual-fairness","machine-learning","pytorch","responsible-ai","trustworthy-machine-learning"],"latest_commit_sha":null,"homepage":"https://ibm.github.io/inFairness","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM.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":"2022-05-31T16:29:18.000Z","updated_at":"2025-01-05T17:34:16.000Z","dependencies_parsed_at":"2022-06-23T01:31:30.857Z","dependency_job_id":null,"html_url":"https://github.com/IBM/inFairness","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2FinFairness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2FinFairness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2FinFairness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2FinFairness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM","download_url":"https://codeload.github.com/IBM/inFairness/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243725072,"owners_count":20337660,"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":["fairness","fairness-ai","individual-fairness","machine-learning","pytorch","responsible-ai","trustworthy-machine-learning"],"created_at":"2024-10-11T14:05:36.516Z","updated_at":"2025-03-15T11:33:18.966Z","avatar_url":"https://github.com/IBM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ibm.github.io/inFairness\"\u003e\n     \u003cimg width=\"350\" height=\"350\" src=\"https://ibm.github.io/inFairness/_static/infairness-logo.png\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"https://pypi.org/project/infairness\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/infairness?color=important\u0026label=pypi%20package\u0026logo=PyPy\"\u003e\u003c/a\u003e\n   \u003ca href=\"./examples\"\u003e\u003cimg src=\"https://img.shields.io/badge/example-notebooks-red?logo=jupyter\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://ibm.github.io/inFairness\"\u003e\u003cimg src=\"https://img.shields.io/badge/documentation-up-green?logo=GitBook\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://fairbert.vizhub.ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/fairness-demonstration-yellow?logo=ibm-watson\"\u003e\u003c/a\u003e\n   \u003cbr/\u003e\n   \u003ca href=\"https://app.travis-ci.com/IBM/inFairness\"\u003e\u003cimg src=\"https://app.travis-ci.com/IBM/inFairness.svg?branch=main\"\u003e\u003c/a\u003e\n\u003c!--    \u003ca href=\"https://pypistats.org/packages/infairness\"\u003e\u003cimg alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/inFairness?color=blue\"\u003e\u003c/a\u003e --\u003e\n   \u003ca href=\"https://www.pepy.tech/projects/infairness\"\u003e\u003cimg alt=\"Total downloads for the project\" src=\"https://static.pepy.tech/badge/infairness\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.7+-blue?logo=python\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache-yellow\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n## Individual Fairness and inFairness\n\nIntuitively, an individually fair Machine Learning (ML) model treats similar inputs similarly. Formally, the leading notion of individual fairness is metric fairness [(Dwork et al., 2011)](https://dl.acm.org/doi/abs/10.1145/2090236.2090255); it requires:\n\n$$ d_y (h(x_1), h(x_2)) \\leq L d_x(x_1, x_2) \\quad \\forall \\quad x_1, x_2 \\in X $$\n\nHere, $h: X \\rightarrow Y$ is a ML model, where $X$ and $Y$ are input and output spaces; $d_x$ and $d_y$ are metrics on the input and output spaces, and $L \\geq 0$ is a Lipchitz constant. This constrained optimization equation states that the distance between the model predictions for inputs $x_1$ and $x_2$ is upper-bounded by the fair distance between the inputs $x_1$ and $x_2$. Here, the fair metric $d_x$ encodes our intuition of which samples should be treated similarly by the ML model, and in designing so, we ensure that for input samples considered similar by the fair metric $d_x$, the model outputs will be similar as well.\n\ninFairness is a PyTorch package that supports auditing, training, and post-processing ML models for individual fairness. At its core, the library implements the key components of individual fairness pipeline: $d_x$ - distance in the input space, $d_y$ - distance in the output space, and the learning algorithms to optimize for the equation above.\n\nFor an in-depth tutorial of Individual Fairness and the inFairness package, please watch this tutorial. Also, take a look at the [examples](./examples/) folder for illustrative use-cases and try the [Fairness Playground demo](https://fairbert.vizhub.ai). For more group fairness examples see [AIF360](https://aif360.mybluemix.net/).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ibm.box.com/v/fairness-tutorial-2022\" target=\"_blank\"\u003e\u003cimg width=\"700\" alt=\"Watch the tutorial\" src=\"https://user-images.githubusercontent.com/991913/178768336-2bfa5958-487f-4f14-a156-03dacfd68263.png\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Installation\n\ninFairness can be installed using `pip`:\n\n```\npip install inFairness\n```\n\n\nAlternatively, if you wish to install the latest development version, you can install directly by cloning this repository:\n\n```\ngit clone \u003cgit repo url\u003e\ncd inFairness\npip install -e .\n```\n\n\n\n## Features\n\ninFairness currently supports:\n\n1. Learning individually fair metrics : [[Docs]](https://ibm.github.io/inFairness/reference/distances.html)\n2. Training of individually fair models : [[Docs]](https://ibm.github.io/inFairness/reference/algorithms.html)\n3. Auditing pre-trained ML models for individual fairness : [[Docs]](https://ibm.github.io/inFairness/reference/auditors.html)\n4. Post-processing for Individual Fairness : [[Docs]](https://ibm.github.io/inFairness/reference/postprocessing.html)\n5. Individually fair ranking : [[Docs]](https://ibm.github.io/inFairness/reference/algorithms.html)\n\n\n## Contributing\n\nWe welcome contributions from the community in any form - whether it is through the contribution of a new fair algorithm, fair metric, a new use-case, or simply reporting an issue or enhancement in the package. To contribute code to the package, please follow the following steps:\n\n1. Clone this git repository to your local system\n2. Setup your system by installing dependencies as: `pip3 install -r requirements.txt` and `pip3 install -r  build_requirements.txt`\n3. Add your code contribution to the package. Please refer to the [`inFairness`](./inFairness) folder for an overview of the directory structure\n4. Add appropriate unit tests in the [`tests`](./tests) folder\n5. Once you are ready to commit code, check for the following:\n   1. Coding style compliance using: `flake8 inFairness/`. This command will list all stylistic violations found in the code. Please try to fix as much as you can\n   2. Ensure all the test cases pass using: `coverage run --source inFairness -m pytest tests/`. All unit tests need to pass to be able merge code in the package.\n6. Finally, commit your code and raise a Pull Request.\n\n\n## Tutorials\n\nThe [`examples`](./examples) folder contains tutorials from different fields illustrating how to use the package.\n\n### Minimal example\n\nFirst, you need to import the relevant packages\n\n```\nfrom inFairness import distances\nfrom inFairness.fairalgo import SenSeI\n```\n\nThe `inFairness.distances` module implements various distance metrics on the input and the output spaces, and the `inFairness.fairalgo` implements various individually fair learning algorithms with `SenSeI` being one particular algorithm.\n\nThereafter, we instantiate and fit the distance metrics on the training data, and \n\n\n```[python]\ndistance_x = distances.SVDSensitiveSubspaceDistance()\ndistance_y = distances.EuclideanDistance()\n\ndistance_x.fit(X_train=data, n_components=50)\n\n# Finally instantiate the fair algorithm\nfairalgo = SenSeI(network, distance_x, distance_y, lossfn, rho=1.0, eps=1e-3, lr=0.01, auditor_nsteps=100, auditor_lr=0.1)\n```\n\nFinally, you can train the `fairalgo` as you would train your standard PyTorch deep neural network:\n\n```\nfairalgo.train()\n\nfor epoch in range(EPOCHS):\n    for x, y in train_dl:\n        optimizer.zero_grad()\n        result = fairalgo(x, y)\n        result.loss.backward()\n        optimizer.step()\n```\n\n\n##  Authors\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://moonfolk.github.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/24443134?v=4?s=100\" width=\"120px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003cb\u003eMikhail Yurochkin\u003c/b\u003e\u003c/a\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://mayankagarwal.github.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/991913?v=4?s=100\" width=\"120px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003cb\u003eMayank Agarwal\u003c/b\u003e\u003c/a\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/aldopareja\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/7622817?v=4?s=100\" width=\"120px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003cb\u003eAldo Pareja\u003c/b\u003e\u003c/a\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/onkarbhardwaj\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/13560220?v=4?s=100\" width=\"120px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003cb\u003eOnkar Bhardwaj\u003c/b\u003e\u003c/a\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Finfairness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm%2Finfairness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Finfairness/lists"}