{
    "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 DELTR for Python\n\n[![image](https://img.shields.io/pypi/status/fairsearchdeltr.svg)](https://pypi.org/project/fairsearchdeltr/)\n[![image](https://img.shields.io/pypi/v/fairsearchdeltr.svg)](https://pypi.org/project/fairsearchdeltr/)\n[![image](https://img.shields.io/pypi/pyversions/fairsearchdeltr.svg)](https://pypi.org/project/fairsearchdeltr/)\n[![image](https://img.shields.io/pypi/l/fairsearchdeltr.svg)](https://pypi.org/project/fairsearchdeltr/)\n[![image](https://img.shields.io/pypi/implementation/fairsearchdeltr.svg)](https://pypi.org/project/fairsearchdeltr/)\n\nThis is the Python library that implements the [DELTR](https://arxiv.org/pdf/1805.08716.pdf) model for fair ranking.\n\n## Installation\n\nTo install `fairsearchdeltr`, simply use `pip` (or `pipenv`):\n```bash\npip install fairsearchdeltr\n```\nAnd, that's it!\n\n## Using it in your code\n\nYou need to import the class from the package first: \n```python\nfrom fairsearchdeltr import Deltr\n```\n\n### Train a model\n\nYou need to train the model before it can rank documents.\n```python\n# import other helper libraries\nimport pandas as pd\nfrom io import StringIO\n\n# load some train data (this is just a sample - more is better)\ntrain_data_raw = \"\"\"q_id,doc_id,gender,score,judgment\n    1,1,1,0.962650646167003,1\n    1,2,0,0.940172822166108,0.98\n    1,3,0,0.925288002880488,0.96\n    1,4,1,0.896143226020877,0.94\n    1,5,0,0.89180775633204,0.92\n    1,6,0,0.838704766545679,0.9\n    \"\"\"\ntrain_data = pd.read_csv(StringIO(train_data_raw))\n\n# setup the DELTR object\nprotected_feature = \"gender\" # column name of the protected attribute (index after query and document id)\ngamma = 1 # value of the gamma parameter\nnumber_of_iterations = 10000 # number of iterations the training should run\nstandardize = True # let's apply standardization to the features\n\n# create the Deltr object\ndtr = Deltr(protected_feature, gamma, number_of_iterations, standardize=standardize)\n\n# train the model\ndtr.train(train_data)\n>> array([0.02527054, 0.07692437])\n# your run should have approximately same results  \n```\n\n### Use the model to rank \n\nNow, you can use the obtained model to rank some data.\n```python\n# load some test/prediction data\nprediction_data_raw = \"\"\"q_id,doc_id,gender,score\n    1,7,0,0.9645\n    1,8,0,0.9524\n    1,9,0,0.9285\n    1,10,0,0.8961\n    1,11,1,0.8911\n    1,12,1,0.8312\n    \"\"\"\nprediction_data = pd.read_csv(StringIO(prediction_data_raw))\n\n# use the model to rank the data  \ndtr.rank(prediction_data)\n>> doc_id  gender  judgement\n4      11       1   0.074849\n5      12       1   0.063770\n0       7       0   0.063486\n1       8       0   0.061248\n2       9       0   0.056828\n3      10       0   0.050836\n# the result will be a re-ranked dataframe\n```\nThe library contains sufficient code documentation for each of the functions.\n\n### Checking the model a bit deeper\n\nYou can check how the training of the model progressed using a special property called `log`.\n```python\ndtr.log\n>> [<TrainStep [1553844278383,[0.01926469 0.00976336],[[-0.00125304 -0.0014605 ]\n  [-0.00125304 -0.0014605 ]\n  [-0.00125304 -0.0014605 ]\n  [-0.00125304 -0.0014605 ]\n  [-0.00125304 -0.0014605 ]\n  [-0.00125304 -0.0014605 ]],5.999620187652397,0.0]>,\n ...]\n```\nThe `log` returns a list of objects from the `fairsearchdeltr.models.TrainStep` class. The class is a representation of the parameters in each step of the training.\n    Contains a `timestamp`, `omega`, `omega_gradient`, `loss`, `loss_standard`, `loss_exposure`.\n\n## Development\n\n1. Clone this repository `git clone https://github.com/fair-search/fairsearchdeltr-python`\n2. Change directory to the directory where you cloned the repository `cd WHERE_ITS_DOWNLOADED/fairsearchdeltr-python`\n3. Use any IDE to work with the code\n\n## Testing\n\nJust run:\n```\npython setup.py test \n```\n\n## Credits\n\nThe DELTR algorithm is described in this paper:\n\n* Meike Zehlike, Gina-Theresa Diehn, Carlos Castillo. \"[Reducing Disparate Exposure in Ranking:\nA Learning to Rank Approach](https://doi.org/10.1145/3132847.3132938).\" preprint arXiv:1805.08716 (2018).\n\nThis library was developed by [Ivan Kitanovski](http://ivankitanovski.com/) based on the paper. See the [license](https://github.com/fair-search/fairsearch-deltr-python/blob/master/LICENSE) file for more information.\n\nFor any questions contact [Mieke Zehlike](https://de.linkedin.com/in/meike-zehlike-366bba131)\n\n## See also\n\nYou can also see the [DELTR for ElasticSearch](https://github.com/fair-search/fairsearch-deltr-for-elasticsearch)\n and [DELTR Java library](https://github.com/fair-search/fairsearchdeltr-java).",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/fair-search/fairsearchdeltr-python",
        "keywords": "search,fairness,deltr,disparate exposure in ranking,learning to rank",
        "license": "Apache 2.0",
        "maintainer": "",
        "maintainer_email": "",
        "name": "fairsearchdeltr",
        "package_url": "https://pypi.org/project/fairsearchdeltr/",
        "platform": "",
        "project_url": "https://pypi.org/project/fairsearchdeltr/",
        "project_urls": {
            "Homepage": "https://github.com/fair-search/fairsearchdeltr-python"
        },
        "release_url": "https://pypi.org/project/fairsearchdeltr/1.0.2/",
        "requires_dist": null,
        "requires_python": ">=3.0",
        "summary": "A Python library for disparate exposure in ranking (a learning to rank approach)",
        "version": "1.0.2"
    },
    "last_serial": 5405129,
    "releases": {
        "0.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b37dc183d2044170b52426609521b9e7",
                    "sha256": "314b36cbd14fb31a092b63f5037c824d07cf4ae1cf30131e5b132cce7d8ea753"
                },
                "downloads": -1,
                "filename": "fairsearchdeltr-0.0.3.tar.gz",
                "has_sig": false,
                "md5_digest": "b37dc183d2044170b52426609521b9e7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.0",
                "size": 7564,
                "upload_time": "2019-03-26T10:49:55",
                "url": "https://files.pythonhosted.org/packages/5d/92/b65175a709862bdf61b1668097e06a6b73c7bf8b00cea06c4956858aa6ff/fairsearchdeltr-0.0.3.tar.gz"
            }
        ],
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "333c5eeeb08a4141ee9235bbdf7d9050",
                    "sha256": "cc9ac9388aa364787a050443e890bc6f8362995197efe99536a90384dde06220"
                },
                "downloads": -1,
                "filename": "fairsearchdeltr-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "333c5eeeb08a4141ee9235bbdf7d9050",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.0",
                "size": 9412,
                "upload_time": "2019-03-31T16:45:11",
                "url": "https://files.pythonhosted.org/packages/17/37/f70077325a645c38969e44ee519f26a23b39427ea9b6f170c0854a0e2427/fairsearchdeltr-1.0.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4408a7c77dcffec9a7438d7304999317",
                    "sha256": "f5434dc115ac6165731b17e68d558d3ad04bfadcd3e0b5f22b73db88d9a4a78c"
                },
                "downloads": -1,
                "filename": "fairsearchdeltr-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "4408a7c77dcffec9a7438d7304999317",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.0",
                "size": 9751,
                "upload_time": "2019-04-10T21:39:53",
                "url": "https://files.pythonhosted.org/packages/41/56/e6904cb9dfc8652039f490eca8b1376d7f84f18618f9641cc1c4bb3c4dfc/fairsearchdeltr-1.0.1.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "1a72be0d5b01c2af9e3180872428e621",
                    "sha256": "111fb25121df415b3c808e42bdf7fa1f9005b3727fee0fd6cfc71b9a071e481b"
                },
                "downloads": -1,
                "filename": "fairsearchdeltr-1.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "1a72be0d5b01c2af9e3180872428e621",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.0",
                "size": 9610,
                "upload_time": "2019-06-15T23:04:23",
                "url": "https://files.pythonhosted.org/packages/65/45/96d0cb961d727f2052e529e46a9242b9b5078a3bd792c1a49b4b845f98e5/fairsearchdeltr-1.0.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "1a72be0d5b01c2af9e3180872428e621",
                "sha256": "111fb25121df415b3c808e42bdf7fa1f9005b3727fee0fd6cfc71b9a071e481b"
            },
            "downloads": -1,
            "filename": "fairsearchdeltr-1.0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "1a72be0d5b01c2af9e3180872428e621",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.0",
            "size": 9610,
            "upload_time": "2019-06-15T23:04:23",
            "url": "https://files.pythonhosted.org/packages/65/45/96d0cb961d727f2052e529e46a9242b9b5078a3bd792c1a49b4b845f98e5/fairsearchdeltr-1.0.2.tar.gz"
        }
    ]
}