{ "info": { "author": "Ivan Kitanovski", "author_email": "ivan.kitanovski@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Natural Language :: English", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: Implementation :: PyPy" ], "description": "# Fair search core for Python\n\n[![image](https://img.shields.io/pypi/status/fairsearchcore.svg)](https://pypi.org/project/fairsearchcore/)\n[![image](https://img.shields.io/pypi/v/fairsearchcore.svg)](https://pypi.org/project/fairsearchcore/)\n[![image](https://img.shields.io/pypi/pyversions/fairsearchcore.svg)](https://pypi.org/project/fairsearchcore/)\n[![image](https://img.shields.io/pypi/l/fairsearchcore.svg)](https://pypi.org/project/fairsearchcore/)\n[![image](https://img.shields.io/pypi/implementation/fairsearchcore.svg)](https://pypi.org/project/fairsearchcore/)\n\nThis is the Python library with the core algorithms used to do [FA*IR](https://arxiv.org/abs/1706.06368) ranking. \n\n## Installation\nTo install `fairsearchcore`, simply use `pip` (or `pipenv`):\n```bash\npip install fairsearcore\n```\nAnd, that's it!\n\n## Using it in your code\nYou need to import the package first: \n```{.sourceCode .python}\nimport fairsearchcore as fsc\n```\nCreating and analyzing mtables:\n```{.sourceCode .python}\nk = 20 # number of topK elements returned (value should be between 10 and 400)\np = 0.25 # proportion of protected candidates in the topK elements (value should be between 0.02 and 0.98) \nalpha = 0.1 # significance level (value should be between 0.01 and 0.15)\n\n# create the Fair object \nfair = fsc.Fair(k, p, alpha)\n\n# create an mtable using alpha unadjusted\nmtable = fair.create_unadjusted_mtable()\n>> [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3]\n\n# analytically calculate the fail probability\nanalytical = fair.compute_fail_probability(mtable)\n>> 0.11517506930977106 \n\n# create an mtable using alpha adjusted\nmtable = fair.create_adjusted_mtable()\n>> [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2]\n\n# again, analytically calculate the fail probability\nanalytical = fair.compute_fail_probability(mtable)\n>> 0.13421772800000065\n\n```\nGenerate random rankings and analyze them:\n```{.sourceCode .python}\nM = 10000 # number of rankings you want to generate (works better with big numbers)\n\n# generate rankings using the simulator (M lists of k objects of class fairsearchcore.models.FairScoreDoc) \nrankings = fsc.generate_rankings(M, k, p)\n>> [[, , , \n, , , \n, , , \n, , , \n, , , \n , , , \n , ],...]\n\n# experimentally calculate the fail probability\nexperimental = fsc.compute_fail_probability(mtable, rankings)\n>> 0.1076\n```\nApply a fair re-ranking to a given ranking:\n```\n# import the FairScoreDoc class\nfrom fairsearchcore.models import FairScoreDoc\n\n# let's manually create an unfair ranking (False -> unprotexted, True -> protected)\nunfair_ranking = [FairScoreDoc(20, 20, False), FairScoreDoc(19, 19, False), FairScoreDoc(18, 18, False),\n FairScoreDoc(17, 17, False), FairScoreDoc(16, 16, False), FairScoreDoc(15, 15, False),\n FairScoreDoc(14, 14, False), FairScoreDoc(13, 13, False), FairScoreDoc(12, 12, False),\n FairScoreDoc(11, 11, False), FairScoreDoc(10, 10, False), FairScoreDoc(9, 9, False),\n FairScoreDoc(8, 8, False), FairScoreDoc(7, 7, False), FairScoreDoc(6, 6, True),\n FairScoreDoc(5, 5, True), FairScoreDoc(4, 4, True), FairScoreDoc(3, 3, True),\n FairScoreDoc(2, 2, True), FairScoreDoc(1, 1, True)]\n\n# now re-rank the unfair ranking \nfair.re_rank(unfair_ranking)\n>> [, , , \n, , , \n, , , \n, , , \n, , ,\n, , , \n, ]\n```\n\nThe library contains sufficient code documentation for each of the functions.\n \n## Development\n\n1. Clone this repository `git clone https://github.com/fair-search/fairsearchcore-python.git`\n2. Change directory to the directory where you cloned the repository `cd WHERE_ITS_DOWNLOADED/fairsearchcore-python`\n3. Use any IDE to work with the code\n\n## Testing\n\nJust run:\n```\npython setup.py test \n```\n*Note*: The simulator tests take a *looong* time to execute. \n\n## Credits\n\nThe FA*IR algorithm is described on this paper:\n\n* Meike Zehlike, Francesco Bonchi, Carlos Castillo, Sara Hajian, Mohamed Megahed, Ricardo Baeza-Yates: \"[FA*IR: A Fair Top-k Ranking Algorithm](https://doi.org/10.1145/3132847.3132938)\". Proc. of the 2017 ACM on Conference on Information and Knowledge Management (CIKM).\n\nThis code was developed by [Ivan Kitanovski](http://ivankitanovski.com/) based on the paper. See the [license](https://github.com/fair-search/fairsearch-core/blob/master/python/LICENSE) file for more information.\n\n## See also\n\nYou can also see the [FA*IR plug-in for ElasticSearch](https://github.com/fair-search/fairsearch-elasticsearch-plugin).", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/fair-search/fairsearchcore-python", "keywords": "search,fairness,fa*ir,ranking,reranking", "license": "Apache 2.0", "maintainer": "", "maintainer_email": "", "name": "fairsearchcore", "package_url": "https://pypi.org/project/fairsearchcore/", "platform": "", "project_url": "https://pypi.org/project/fairsearchcore/", "project_urls": { "Homepage": "https://github.com/fair-search/fairsearchcore-python" }, "release_url": "https://pypi.org/project/fairsearchcore/1.0.4/", "requires_dist": null, "requires_python": ">=3.0", "summary": "A Python library with the core algorithms used to do fair search.", "version": "1.0.4" }, "last_serial": 4861966, "releases": { "0.0.2": [ { "comment_text": "", "digests": { "md5": "a8a92b987fab1598ab846e62124b8c28", "sha256": "76468c07469f738be84ff835d42a536e117a2cc7d1566d2f3f0214d105efa3cb" }, "downloads": -1, "filename": "fairsearchcore-0.0.2.tar.gz", "has_sig": false, "md5_digest": "a8a92b987fab1598ab846e62124b8c28", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 6713, "upload_time": "2019-02-22T21:40:52", "url": "https://files.pythonhosted.org/packages/5b/d5/13bae50e35ef6213c732c13abf65f674c8462ce1233e18a58bacf5e8de80/fairsearchcore-0.0.2.tar.gz" } ], "1.0.0": [ { "comment_text": "", "digests": { "md5": "8dd80fe63186aceb43257a2722384ab6", "sha256": "0b6aafaa1b98fc1b43444465f24a36c4d80c2dc3fa128b0d9341e45871301f3d" }, "downloads": -1, "filename": "fairsearchcore-1.0.0.tar.gz", "has_sig": false, "md5_digest": "8dd80fe63186aceb43257a2722384ab6", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 6775, "upload_time": "2019-02-22T23:04:12", "url": "https://files.pythonhosted.org/packages/72/07/c29927737ea685c7169a83a3b00d91b733796553e00784c20f168de28c1a/fairsearchcore-1.0.0.tar.gz" } ], "1.0.1": [ { "comment_text": "", "digests": { "md5": "92ed1288e185d6319d057d5e8e1fcedd", "sha256": "0861c41b95c3bb47970e8da3a1e42718574c5ab0f30329a7c4a8621eb041d91d" }, "downloads": -1, "filename": "fairsearchcore-1.0.1.tar.gz", "has_sig": false, "md5_digest": "92ed1288e185d6319d057d5e8e1fcedd", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 7086, "upload_time": "2019-02-22T23:08:55", "url": "https://files.pythonhosted.org/packages/f9/e7/56af462a2bb5a11b52ec67e3a0e3ddac4980b2b4f64b643bb37fa4240623/fairsearchcore-1.0.1.tar.gz" } ], "1.0.2": [ { "comment_text": "", "digests": { "md5": "7934c3561a0af7fcfb157883c06447c9", "sha256": "891613fd6cea8beab180fb8c3adf99abce8bd22ecdd14036c604469d73d1e6af" }, "downloads": -1, "filename": "fairsearchcore-1.0.2.tar.gz", "has_sig": false, "md5_digest": "7934c3561a0af7fcfb157883c06447c9", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 8650, "upload_time": "2019-02-24T19:52:58", "url": "https://files.pythonhosted.org/packages/10/9e/7bc7efe1984ec2dda84367758c851c1539ba7b6e55676528644ac206aa06/fairsearchcore-1.0.2.tar.gz" } ], "1.0.3": [ { "comment_text": "", "digests": { "md5": "24bbf99f865a09788d33b8e42e2f939b", "sha256": "0fbffa5665dd4ebe492ee70086088529a321b37b2ca36f29f63e99b5c243d726" }, "downloads": -1, "filename": "fairsearchcore-1.0.3.tar.gz", "has_sig": false, "md5_digest": "24bbf99f865a09788d33b8e42e2f939b", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 8649, "upload_time": "2019-02-24T20:18:37", "url": "https://files.pythonhosted.org/packages/55/e2/73a7ff132fd497d887b09be472b6e6ebad44ba69dfae6d3205542097ea85/fairsearchcore-1.0.3.tar.gz" } ], "1.0.4": [ { "comment_text": "", "digests": { "md5": "2364bcac2300e10f0b9086c3637a910b", "sha256": "ca15304579a0c9b3135246a1ad41a23367d963e144269553f6200ad608ac44d6" }, "downloads": -1, "filename": "fairsearchcore-1.0.4.tar.gz", "has_sig": false, "md5_digest": "2364bcac2300e10f0b9086c3637a910b", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 8632, "upload_time": "2019-02-24T20:45:32", "url": "https://files.pythonhosted.org/packages/5a/10/493100010291cc8f69fa8c3c9ff59a29d54f6149ba46c188fa50bee368e6/fairsearchcore-1.0.4.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "2364bcac2300e10f0b9086c3637a910b", "sha256": "ca15304579a0c9b3135246a1ad41a23367d963e144269553f6200ad608ac44d6" }, "downloads": -1, "filename": "fairsearchcore-1.0.4.tar.gz", "has_sig": false, "md5_digest": "2364bcac2300e10f0b9086c3637a910b", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.0", "size": 8632, "upload_time": "2019-02-24T20:45:32", "url": "https://files.pythonhosted.org/packages/5a/10/493100010291cc8f69fa8c3c9ff59a29d54f6149ba46c188fa50bee368e6/fairsearchcore-1.0.4.tar.gz" } ] }