# rank-choicer
A Python package for calculating the winner of a poll using rank choice voting (Instant-runoff voting).
## Install
Use pip to install:
```shell
pip install rank-choicer
```
## Usage
First, set up the counter with the available options:
```python
from rank_choicer import RankChoiceCounter
counter = RankChoiceCounter(["A", "B", "C"])
```
Then, you can pass in the votes to its `count_votes` method which returns the winner:
```python
votes = {
"voter1": ["A", "B", "C"],
"voter2": ["B", "A", "C"],
"voter3": ["C", "A", "B"],
"voter4": ["A", "C", "B"],
"voter5": ["B", "C", "A"],
}
winner = counter.count_votes(votes)
print(f"Winner is: {winner}")
```
```shell
Winner is A
```
### Viewing Specific Rounds
Sometimes, you may want to review the different rounds of elimination for either analysis or visualization. You can do so by calling the `get_round_results` method:
```python
results = counter.get_round_results()
print(f"Eliminated in the first round: {results[0].eliminated_options}")
print(results[0].vote_counts)
```
```shell
Eliminated in the first round: [C]
```
### Handling Ties In Elimination
In rare cases, you may have more than one option with the lowest votes. In those cases, you can handle what to eliminate in two ways:
* Randomly eliminate one of the options with lowest votes
* Eliminate all options tied for lowest votes
The `RankChoiceCounter` defaults to random but you can change the strategy used using the `elimination_strategy` parameter:
```python
from rank_choicer import EliminationStrategy
counter = RankChoiceCounter(
["A", "B", "C", "D"], elimination_strategy=EliminationStrategy.BATCH
)
```
## Contributing
Community made feature requests, patches, bug reports, and contributions are always welcome.
Please review [our contributing guidelines](https://github.com/fpcorso/rank-choicer/blob/main/CONTRIBUTING.md) if you decide to make a contribution.
## License
This project is licensed under the MIT License. See [LICENSE](https://github.com/fpcorso/rank-choicer/blob/main/LICENSE) for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/fpcorso/rank-choicer",
"name": "rank-choicer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "poll, vote, instant-runoff, rank choice",
"author": "Frank Corso",
"author_email": "frank@frankcorso.me",
"download_url": "https://files.pythonhosted.org/packages/18/60/e6729751988a374af327ae677fdb38f71b90cd617d8fcfef72a462fcbc48/rank_choicer-1.0.1.tar.gz",
"platform": null,
"description": "# rank-choicer\n\nA Python package for calculating the winner of a poll using rank choice voting (Instant-runoff voting).\n\n## Install\n\nUse pip to install:\n\n\n```shell\npip install rank-choicer\n```\n\n## Usage\n\nFirst, set up the counter with the available options:\n\n```python\nfrom rank_choicer import RankChoiceCounter\ncounter = RankChoiceCounter([\"A\", \"B\", \"C\"])\n```\n\nThen, you can pass in the votes to its `count_votes` method which returns the winner:\n\n```python\nvotes = {\n \"voter1\": [\"A\", \"B\", \"C\"],\n \"voter2\": [\"B\", \"A\", \"C\"],\n \"voter3\": [\"C\", \"A\", \"B\"],\n \"voter4\": [\"A\", \"C\", \"B\"],\n \"voter5\": [\"B\", \"C\", \"A\"],\n}\nwinner = counter.count_votes(votes)\nprint(f\"Winner is: {winner}\")\n```\n```shell\nWinner is A\n```\n\n### Viewing Specific Rounds\n\nSometimes, you may want to review the different rounds of elimination for either analysis or visualization. You can do so by calling the `get_round_results` method:\n\n```python\nresults = counter.get_round_results()\nprint(f\"Eliminated in the first round: {results[0].eliminated_options}\")\nprint(results[0].vote_counts)\n```\n```shell\nEliminated in the first round: [C]\n```\n\n### Handling Ties In Elimination\n\nIn rare cases, you may have more than one option with the lowest votes. In those cases, you can handle what to eliminate in two ways:\n\n* Randomly eliminate one of the options with lowest votes\n* Eliminate all options tied for lowest votes\n\nThe `RankChoiceCounter` defaults to random but you can change the strategy used using the `elimination_strategy` parameter:\n\n```python\nfrom rank_choicer import EliminationStrategy \ncounter = RankChoiceCounter(\n [\"A\", \"B\", \"C\", \"D\"], elimination_strategy=EliminationStrategy.BATCH\n)\n```\n\n## Contributing\n\nCommunity made feature requests, patches, bug reports, and contributions are always welcome.\n\nPlease review [our contributing guidelines](https://github.com/fpcorso/rank-choicer/blob/main/CONTRIBUTING.md) if you decide to make a contribution.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](https://github.com/fpcorso/rank-choicer/blob/main/LICENSE) for more details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for calculating the winner of a poll using rank choice voting (Instant-runoff voting).",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/fpcorso/rank-choicer",
"Repository": "https://github.com/fpcorso/rank-choicer"
},
"split_keywords": [
"poll",
" vote",
" instant-runoff",
" rank choice"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e89b136a0146dd34f4cf845ef9411d9bdf38dffcd62a2e6c59e8f25c060d953",
"md5": "f017254a484c0b8a7dbf604ff643f32c",
"sha256": "4b242a9b056ceb63f6b3c52b98e09a39c18b56c08bdb47577dd6d05cd712cbd4"
},
"downloads": -1,
"filename": "rank_choicer-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f017254a484c0b8a7dbf604ff643f32c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6046,
"upload_time": "2025-02-15T21:11:01",
"upload_time_iso_8601": "2025-02-15T21:11:01.944281Z",
"url": "https://files.pythonhosted.org/packages/3e/89/b136a0146dd34f4cf845ef9411d9bdf38dffcd62a2e6c59e8f25c060d953/rank_choicer-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1860e6729751988a374af327ae677fdb38f71b90cd617d8fcfef72a462fcbc48",
"md5": "92eb6d5e9eaf2512c413e39fc95241f4",
"sha256": "447880f8ce5270a7e6bcb0fd28b94daf060cc515157b4503ea82d3eaa0cc14c2"
},
"downloads": -1,
"filename": "rank_choicer-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "92eb6d5e9eaf2512c413e39fc95241f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4791,
"upload_time": "2025-02-15T21:11:03",
"upload_time_iso_8601": "2025-02-15T21:11:03.637770Z",
"url": "https://files.pythonhosted.org/packages/18/60/e6729751988a374af327ae677fdb38f71b90cd617d8fcfef72a462fcbc48/rank_choicer-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-15 21:11:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fpcorso",
"github_project": "rank-choicer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rank-choicer"
}
JSON
