| Name | sortition-algorithms JSON |
| Version |
0.10.4
JSON |
| download |
| home_page | None |
| Summary | A package containing algorithms for sortition - democratic lotteries. |
| upload_time | 2025-10-06 15:41:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.11 |
| license | None |
| keywords |
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sortition-algorithms
[](https://img.shields.io/github/v/release/sortitionfoundation/sortition-algorithms)
[](https://github.com/sortitionfoundation/sortition-algorithms/actions/workflows/main.yml?query=branch%3Amain)
[](https://codecov.io/gh/sortitionfoundation/sortition-algorithms)
[](https://img.shields.io/github/commit-activity/m/sortitionfoundation/sortition-algorithms)
[](https://img.shields.io/github/license/sortitionfoundation/sortition-algorithms)
A package containing algorithms for sortition - democratic lotteries.
- **Github repository**: <https://github.com/sortitionfoundation/sortition-algorithms/>
- **Documentation** <https://sortitionfoundation.github.io/sortition-algorithms/>
## About
This library implements algorithms for **sortition** - the random selection of representative citizen panels (also known as citizens' assemblies, juries, or deliberative panels). Unlike simple random sampling, these algorithms use **stratified selection** to ensure the chosen panel reflects the demographic composition of the broader population.
### What is Sortition?
Sortition creates representative groups by randomly selecting people while respecting demographic quotas. For example, if your population is 52% women and 48% men, sortition ensures your panel maintains similar proportions rather than risking an all-male or all-female selection through pure chance.
### Key Features
- **Stratified Random Selection**: Respects demographic quotas while maintaining randomness
- **Household Diversity**: Optional address checking to ensure geographic and household spread
- **Multiple Algorithms**: Choose from maximin, leximin, nash, or legacy selection methods
- **Flexible Data Sources**: Works with CSV files, Google Sheets, or direct Python data structures
- **Transparency**: Detailed reporting of selection process and quota fulfillment
### Quick Example
```python
from sortition_algorithms import run_stratification, read_in_features, read_in_people, Settings
# Load your data
features = read_in_features("demographics.csv") # Age, Gender, Location quotas
people = read_in_people("candidates.csv", Settings(), features)
# Select a representative panel of 100 people
success, selected_panels, messages = run_stratification(
features, people, number_people_wanted=100, settings=Settings()
)
if success:
panel = selected_panels[0] # Set of selected person IDs
print(f"Selected {len(panel)} people for the panel")
```
### Research Background
The algorithms are described in [this paper (open access)](https://www.nature.com/articles/s41586-021-03788-6). Other relevant papers are linked to [from the docs](https://sortitionfoundation.github.io/sortition-algorithms/concepts/#research-background)
## Installing the library
```sh
pip install sortition-algorithms
```
(Or `uv add ...` or ...)
### Optional dependencies
There are two sets of optional dependencies:
```sh
# Install the library to use the leximin algorithm
# This requires a commercial/academic license to use
pip install 'sortition-algorithms[gurobi]'
# Install the basic Command Line Interface
pip install 'sortition-algorithms[cli]'
```
## The Command Line Interface
The library includes a CLI for common operations:
```bash
# CSV workflow
python -m sortition_algorithms csv \
--settings config.toml \
--features-csv demographics.csv \
--people-csv candidates.csv \
--selected-csv selected.csv \
--remaining-csv remaining.csv \
--number-wanted 100
```
## Documentation
For detailed usage instructions, API reference, and advanced examples:
- **[Quick Start Guide](https://sortitionfoundation.github.io/sortition-algorithms/quickstart/)** - Get up and running quickly
- **[Core Concepts](https://sortitionfoundation.github.io/sortition-algorithms/concepts/)** - Understand sortition and stratified selection
- **[API Reference](https://sortitionfoundation.github.io/sortition-algorithms/api-reference/)** - Complete function documentation
- **[CLI Usage](https://sortitionfoundation.github.io/sortition-algorithms/cli/)** - Command line interface examples
- **[Data Adapters](https://sortitionfoundation.github.io/sortition-algorithms/adapters/)** - Working with CSV, Google Sheets, and custom data sources
## Starting Development
### Prerequisites
The recommended prerequisites are:
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- [justfile](https://github.com/casey/just?tab=readme-ov-file#installation)
- [pre-commit](https://pre-commit.com/)
### Set Up
To install a virtualenv with the required dependencies and set up pre-commit hooks:
```sh
just install
```
### Get going
```sh
# run all the tests
just test
# run all the tests that aren't slow
just test
# run all the code quality checks
just check
```
The CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release.
To enable the code coverage reports, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/codecov/).
## Releasing a new version
- Create an API Token on [PyPI](https://pypi.org/).
- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting [this page](https://github.com/sortitionfoundation/sortition-algorithms/settings/secrets/actions/new).
- Create a [new release](https://github.com/sortitionfoundation/sortition-algorithms/releases/new) on Github.
- Create a new tag in the form `*.*.*`.
For more details, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/cicd/#how-to-trigger-a-release).
---
Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).
Raw data
{
"_id": null,
"home_page": null,
"name": "sortition-algorithms",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "python",
"author": null,
"author_email": "\"Hamish Downer (Sortition Foundation)\" <hamish@sortitionfoundation.org>, \"Brett Hennig (Sortition Foundation)\" <brett@sortitionfoundation.org>, \"Nick Gill (Sortition Foundation)\" <nick@sortitionfoundation.org>, Paul Go\u0308lz <pgoelz@cs.cmu.edu>",
"download_url": "https://files.pythonhosted.org/packages/ee/dc/8bbce43ee53653f5644996aa7fc13e452473d67fa278b5f28ea5f9129cd3/sortition_algorithms-0.10.4.tar.gz",
"platform": null,
"description": "# sortition-algorithms\n\n[](https://img.shields.io/github/v/release/sortitionfoundation/sortition-algorithms)\n[](https://github.com/sortitionfoundation/sortition-algorithms/actions/workflows/main.yml?query=branch%3Amain)\n[](https://codecov.io/gh/sortitionfoundation/sortition-algorithms)\n[](https://img.shields.io/github/commit-activity/m/sortitionfoundation/sortition-algorithms)\n[](https://img.shields.io/github/license/sortitionfoundation/sortition-algorithms)\n\nA package containing algorithms for sortition - democratic lotteries.\n\n- **Github repository**: <https://github.com/sortitionfoundation/sortition-algorithms/>\n- **Documentation** <https://sortitionfoundation.github.io/sortition-algorithms/>\n\n## About\n\nThis library implements algorithms for **sortition** - the random selection of representative citizen panels (also known as citizens' assemblies, juries, or deliberative panels). Unlike simple random sampling, these algorithms use **stratified selection** to ensure the chosen panel reflects the demographic composition of the broader population.\n\n### What is Sortition?\n\nSortition creates representative groups by randomly selecting people while respecting demographic quotas. For example, if your population is 52% women and 48% men, sortition ensures your panel maintains similar proportions rather than risking an all-male or all-female selection through pure chance.\n\n### Key Features\n\n- **Stratified Random Selection**: Respects demographic quotas while maintaining randomness\n- **Household Diversity**: Optional address checking to ensure geographic and household spread\n- **Multiple Algorithms**: Choose from maximin, leximin, nash, or legacy selection methods\n- **Flexible Data Sources**: Works with CSV files, Google Sheets, or direct Python data structures\n- **Transparency**: Detailed reporting of selection process and quota fulfillment\n\n### Quick Example\n\n```python\nfrom sortition_algorithms import run_stratification, read_in_features, read_in_people, Settings\n\n# Load your data\nfeatures = read_in_features(\"demographics.csv\") # Age, Gender, Location quotas\npeople = read_in_people(\"candidates.csv\", Settings(), features)\n\n# Select a representative panel of 100 people\nsuccess, selected_panels, messages = run_stratification(\n features, people, number_people_wanted=100, settings=Settings()\n)\n\nif success:\n panel = selected_panels[0] # Set of selected person IDs\n print(f\"Selected {len(panel)} people for the panel\")\n```\n\n### Research Background\n\nThe algorithms are described in [this paper (open access)](https://www.nature.com/articles/s41586-021-03788-6). Other relevant papers are linked to [from the docs](https://sortitionfoundation.github.io/sortition-algorithms/concepts/#research-background)\n\n## Installing the library\n\n```sh\npip install sortition-algorithms\n```\n\n(Or `uv add ...` or ...)\n\n### Optional dependencies\n\nThere are two sets of optional dependencies:\n\n```sh\n# Install the library to use the leximin algorithm\n# This requires a commercial/academic license to use\npip install 'sortition-algorithms[gurobi]'\n\n# Install the basic Command Line Interface\npip install 'sortition-algorithms[cli]'\n```\n\n## The Command Line Interface\n\nThe library includes a CLI for common operations:\n\n```bash\n# CSV workflow\npython -m sortition_algorithms csv \\\n --settings config.toml \\\n --features-csv demographics.csv \\\n --people-csv candidates.csv \\\n --selected-csv selected.csv \\\n --remaining-csv remaining.csv \\\n --number-wanted 100\n```\n\n## Documentation\n\nFor detailed usage instructions, API reference, and advanced examples:\n\n- **[Quick Start Guide](https://sortitionfoundation.github.io/sortition-algorithms/quickstart/)** - Get up and running quickly\n- **[Core Concepts](https://sortitionfoundation.github.io/sortition-algorithms/concepts/)** - Understand sortition and stratified selection\n- **[API Reference](https://sortitionfoundation.github.io/sortition-algorithms/api-reference/)** - Complete function documentation\n- **[CLI Usage](https://sortitionfoundation.github.io/sortition-algorithms/cli/)** - Command line interface examples\n- **[Data Adapters](https://sortitionfoundation.github.io/sortition-algorithms/adapters/)** - Working with CSV, Google Sheets, and custom data sources\n\n## Starting Development\n\n### Prerequisites\n\nThe recommended prerequisites are:\n\n- [uv](https://docs.astral.sh/uv/getting-started/installation/)\n- [justfile](https://github.com/casey/just?tab=readme-ov-file#installation)\n- [pre-commit](https://pre-commit.com/)\n\n### Set Up\n\nTo install a virtualenv with the required dependencies and set up pre-commit hooks:\n\n```sh\njust install\n```\n\n### Get going\n\n```sh\n# run all the tests\njust test\n\n# run all the tests that aren't slow\njust test\n\n# run all the code quality checks\njust check\n```\n\nThe CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release.\n\nTo enable the code coverage reports, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/codecov/).\n\n## Releasing a new version\n\n- Create an API Token on [PyPI](https://pypi.org/).\n- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting [this page](https://github.com/sortitionfoundation/sortition-algorithms/settings/secrets/actions/new).\n- Create a [new release](https://github.com/sortitionfoundation/sortition-algorithms/releases/new) on Github.\n- Create a new tag in the form `*.*.*`.\n\nFor more details, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/cicd/#how-to-trigger-a-release).\n\n---\n\nRepository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).\n",
"bugtrack_url": null,
"license": null,
"summary": "A package containing algorithms for sortition - democratic lotteries.",
"version": "0.10.4",
"project_urls": {
"Documentation": "https://sortitionfoundation.github.io/sortition-algorithms/",
"Homepage": "https://sortitionfoundation.github.io/sortition-algorithms/",
"Repository": "https://github.com/sortitionfoundation/sortition-algorithms"
},
"split_keywords": [
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1ed9d410d7439ac816b55792fd13e365d1aabe381b507aba7196172b0b5439c4",
"md5": "93aec749137217060375c2c294b028ec",
"sha256": "ad41c4dc1980d61efb75c5025a30e76771ddc89e2694123d246e832f05dea7cc"
},
"downloads": -1,
"filename": "sortition_algorithms-0.10.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "93aec749137217060375c2c294b028ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 62992,
"upload_time": "2025-10-06T15:41:31",
"upload_time_iso_8601": "2025-10-06T15:41:31.850217Z",
"url": "https://files.pythonhosted.org/packages/1e/d9/d410d7439ac816b55792fd13e365d1aabe381b507aba7196172b0b5439c4/sortition_algorithms-0.10.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eedc8bbce43ee53653f5644996aa7fc13e452473d67fa278b5f28ea5f9129cd3",
"md5": "7c93531a9ab71d57f811e1e28e69d637",
"sha256": "8ed35c706278b1efa014da47bccdb162e554386834c0be9f686b46922efc3872"
},
"downloads": -1,
"filename": "sortition_algorithms-0.10.4.tar.gz",
"has_sig": false,
"md5_digest": "7c93531a9ab71d57f811e1e28e69d637",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 157274,
"upload_time": "2025-10-06T15:41:33",
"upload_time_iso_8601": "2025-10-06T15:41:33.072194Z",
"url": "https://files.pythonhosted.org/packages/ee/dc/8bbce43ee53653f5644996aa7fc13e452473d67fa278b5f28ea5f9129cd3/sortition_algorithms-0.10.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 15:41:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sortitionfoundation",
"github_project": "sortition-algorithms",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sortition-algorithms"
}
