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, diversimax, 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
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). Other relevant papers are linked to from the docs
Installing the library
pip install sortition-algorithms
(Or uv add ... or ...)
Optional dependencies
There are two sets of optional dependencies:
# 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:
# 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 - Get up and running quickly
- Core Concepts - Understand sortition and stratified selection
- API Reference - Complete function documentation
- CLI Usage - Command line interface examples
- Data Adapters - Working with CSV, Google Sheets, and custom data sources
Starting Development
Prerequisites
The recommended prerequisites are:
Set Up
To install a virtualenv with the required dependencies and set up pre-commit hooks:
just install
Get going
# 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.
Releasing a new version
Releases are published to PyPI via Trusted Publishing — no API token is stored in the repo. To cut a release:
- Create a new release on Github.
- Create a new tag in the form
*.*.*.
For one-time setup (or if the trusted publisher needs reconfiguring), see docs/pypi-trusted-publisher-setup.md.
Repository initiated with fpgmaas/cookiecutter-uv.
1 maintainer
Metadata
1 maintainer
Release files for sortition-algorithms 0.12.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sortition_algorithms-0.12.11.tar.gz | 429.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sortition_algorithms-0.12.11-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 527.5 kB
Release files / sortition_algorithms-0.12.11.tar.gz
| Download URL | sortition_algorithms-0.12.11.tar.gz |
|---|---|
| Size | 429.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2671314eb1c2155867921f45d979f5b7defdf3d9f4f2ee010a6c93816282e799
|
|
BLAKE2b-256 checksum How to use checksums |
c05ed3119111aa0aad51f334db621d0982e48ae490d08534baa1825fadbcbf6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / sortition_algorithms-0.12.11-py3-none-any.whl
| Download URL | sortition_algorithms-0.12.11-py3-none-any.whl |
|---|---|
| Size | 98.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
da8ad642046ef1bf37657ab6b128ca290e4ebda0b2b08cb486c654ec1e279a1c
|
|
BLAKE2b-256 checksum How to use checksums |
8fd9ad2917df456c457f3677b4888bb28942e8fc1ba25762a7f6b78f89ecca78
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency log
