# socialchoicekit
[](https://app.netlify.com/sites/socialchoicekit/deploys)
socialchoicekit aims to be a comprehensive implementation of the most important rules in computational social choice theory. It is currently in development by Natsu Ozawa under the supervision of Dr. Aris Filos-Ratsikas at the University of Edinburgh.
This library supports Python 3.8 and above.
Documentation can be found [here](https://socialchoicekit.natsuozawa.com/)
# Concepts
## Social Choice Theory
Social choice theory [Sen, 1986] is the study of aggregating individual preferences into a collective decision. Social choice theory has been used to formulate, analyze, and evaluate decision making processes in a number of settings.
In this library, we use the following settings.
- Voting: The goal is to select a candidate or proposal that best represents individual votes by an electoral process. Also known as the general social choice setting, this setting is the most studied.
- Resource allocation: The goal is to match agents to items while respecting preferences of the agent. In this library, we simply call it allocation. Also known as matching with one sided preferences.
- Matching: The goal is to match agents from one group to agents in another while respecting preferences of all agents. Also known as matching with two sided preferences.
## Distortion
In this library, we especially focus on algorithms that are used in the study of distortion. Distortion is the worst case ratio between the optimal utility obtainable from cardinal information and the optimal utility obtainable from an algorithm using limited preference information.
# Installation
```
pip install socialchoicekit
```
# Usage
## Example Usage
```
from socialchoicekit.deterministic_scoring import Plurality
rule = Plurality()
profile = np.array([[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2], [3, 2, 1]])
rule.scf(profile)
```
## Development
Create a virtual environment and install from `requirements.txt`
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### Compile documentation
Sphinx with autodoc is used to compile documentation.
(Run this command when a new module is added)
```
sphinx-apidoc -e -o docs/ socialchoicekit/
```
```
cd docs
make html
```
To locally view the compiled documentation, use
```
cd docs/_build/html
python -m http.server
```
## Build
```
python setup.py sdist bdist_wheel
```
If there is an error: invalid command 'bdist_wheel', type:
```
pip install wheel
```
and try again.
Raw data
{
"_id": null,
"home_page": "https://github.com/natsuozawa/socialchoicekit",
"name": "socialchoicekit",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "computational social choice, social choice, voting, allocation, matching, algorithmic game theory, game theory",
"author": "Natsu Ozawa",
"author_email": "natsuozawa@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/ad/5e/e267b63e39e96b5e6b1f837c52eca5ded816f51d567bb0ad6c4018335550/socialchoicekit-1.0.0.tar.gz",
"platform": null,
"description": "# socialchoicekit\n\n[](https://app.netlify.com/sites/socialchoicekit/deploys)\n\nsocialchoicekit aims to be a comprehensive implementation of the most important rules in computational social choice theory. It is currently in development by Natsu Ozawa under the supervision of Dr. Aris Filos-Ratsikas at the University of Edinburgh.\n\nThis library supports Python 3.8 and above.\n\nDocumentation can be found [here](https://socialchoicekit.natsuozawa.com/)\n\n# Concepts\n\n## Social Choice Theory\n\nSocial choice theory [Sen, 1986] is the study of aggregating individual preferences into a collective decision. Social choice theory has been used to formulate, analyze, and evaluate decision making processes in a number of settings.\n\nIn this library, we use the following settings.\n\n- Voting: The goal is to select a candidate or proposal that best represents individual votes by an electoral process. Also known as the general social choice setting, this setting is the most studied.\n- Resource allocation: The goal is to match agents to items while respecting preferences of the agent. In this library, we simply call it allocation. Also known as matching with one sided preferences.\n- Matching: The goal is to match agents from one group to agents in another while respecting preferences of all agents. Also known as matching with two sided preferences.\n\n## Distortion\n\nIn this library, we especially focus on algorithms that are used in the study of distortion. Distortion is the worst case ratio between the optimal utility obtainable from cardinal information and the optimal utility obtainable from an algorithm using limited preference information.\n\n# Installation\n\n```\npip install socialchoicekit\n```\n\n# Usage\n\n## Example Usage\n\n```\nfrom socialchoicekit.deterministic_scoring import Plurality\n\nrule = Plurality()\nprofile = np.array([[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2], [3, 2, 1]])\nrule.scf(profile)\n```\n\n## Development\n\nCreate a virtual environment and install from `requirements.txt`\n```\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n### Compile documentation\nSphinx with autodoc is used to compile documentation.\n\n(Run this command when a new module is added)\n```\nsphinx-apidoc -e -o docs/ socialchoicekit/\n```\n\n```\ncd docs\nmake html\n```\n\nTo locally view the compiled documentation, use\n```\ncd docs/_build/html\npython -m http.server\n```\n\n## Build\n\n```\npython setup.py sdist bdist_wheel\n```\n\nIf there is an error: invalid command 'bdist_wheel', type:\n\n```\npip install wheel\n```\n\nand try again.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "socialchoicekit aims to be a comprehensive implementation of the most important rules in computational social choice theory.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/natsuozawa/socialchoicekit"
},
"split_keywords": [
"computational social choice",
" social choice",
" voting",
" allocation",
" matching",
" algorithmic game theory",
" game theory"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb10102372750f1457230e6e14b01186fb4279c19483b20f54845f377b171553",
"md5": "fa384ab2c282c7438998fa7bb57c75d2",
"sha256": "839c7836a69c9493264368ab4fb4e38c8d6ee830e81fe7809f25a25a730bb4e0"
},
"downloads": -1,
"filename": "socialchoicekit-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa384ab2c282c7438998fa7bb57c75d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 44671,
"upload_time": "2024-04-19T19:50:07",
"upload_time_iso_8601": "2024-04-19T19:50:07.019480Z",
"url": "https://files.pythonhosted.org/packages/eb/10/102372750f1457230e6e14b01186fb4279c19483b20f54845f377b171553/socialchoicekit-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad5ee267b63e39e96b5e6b1f837c52eca5ded816f51d567bb0ad6c4018335550",
"md5": "631bb8e00656b4f309612eb07ef606d4",
"sha256": "d17f1c198b4b0d83de8e51873037a2253ec4095f53187a11faf2b7071c3a45d0"
},
"downloads": -1,
"filename": "socialchoicekit-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "631bb8e00656b4f309612eb07ef606d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 34807,
"upload_time": "2024-04-19T19:50:09",
"upload_time_iso_8601": "2024-04-19T19:50:09.002742Z",
"url": "https://files.pythonhosted.org/packages/ad/5e/e267b63e39e96b5e6b1f837c52eca5ded816f51d567bb0ad6c4018335550/socialchoicekit-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 19:50:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "natsuozawa",
"github_project": "socialchoicekit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "socialchoicekit"
}
JSON
