Sortition Algorithms Documentation¶

Welcome to the documentation for sortition-algorithms - a Python library for democratic lotteries and stratified random selection.

What is Sortition?¶

Sortition is the random selection of representatives from a larger population, designed to create panels that reflect the demographic composition of the whole group. Unlike simple random sampling, sortition uses stratified random selection to ensure demographic balance while maintaining the randomness essential for fairness.

This library provides algorithms for:

Citizens' Assemblies: Representative groups for policy deliberation
Deliberative Polls: Research panels reflecting population diversity
Jury Selection: Fair selection respecting demographic quotas
Participatory Democracy: Community engagement with guaranteed representation

Quick Start¶

# Install the library
pip install sortition-algorithms

# Basic selection
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 Guide¶

Getting Started¶

Quick Start Guide - Get up and running in minutes with practical examples
Core Concepts - Understand sortition, features, quotas, and address checking
Installation & Setup - Install the library and optional dependencies

Using the Library¶

CLI Usage - Command line interface for common operations
Data Adapters - Working with CSV, Google Sheets, and custom data sources
API Reference - Extended documentation of key functions and classes
Modules - Complete documentation of all functions and classes

Advanced Topics¶

Advanced Usage - Performance optimization, complex scenarios, and troubleshooting
Algorithm Deep Dive - Understanding maximin, nash, and leximin algorithms
Integration Patterns - Web apps, batch processing, and monitoring

Key Features¶

🎯 Stratified Selection¶

Ensures demographic representativeness while maintaining randomness - no more accidentally all-male or all-young panels.

🏠 Household Diversity¶

Optional address checking prevents multiple selections from the same household, ensuring geographic and social diversity.

⚖️ Multiple Algorithms¶

Choose from maximin (default), nash, leximin, or legacy algorithms based on your fairness requirements.

📊 Flexible Data Sources¶

Works seamlessly with CSV files, Google Sheets, or custom data adapters for databases and APIs.

🔍 Full Transparency¶

Detailed reporting shows exactly how quotas were met and provides audit trails for democratic accountability.

Common Use Cases¶

Academic Research¶

from sortition_algorithms import run_stratification, Settings

# Reproducible results for research
settings = Settings(
    random_number_seed=42,
    selection_algorithm="leximin"  # Strongest fairness guarantees
)
success, panels, msgs = run_stratification(features, people, 150, settings)

Citizen Assemblies¶

# Ensure household diversity for community representation
settings = Settings(
    check_same_address=True,
    check_same_address_columns=["Address", "Postcode"],
    selection_algorithm="maximin"
)

Large-Scale Surveys¶

# Batch processing with CLI
python -m sortition_algorithms csv \
  --features-csv national_demographics.csv \
  --people-csv voter_registry.csv \
  --number-wanted 2000 \
  --settings survey_config.toml

Algorithm Comparison¶

Algorithm	Best For	Strengths	Requirements
Maximin	General use, citizen assemblies	Fair to minorities, intuitive	None
Nash	Large diverse pools	Balanced overall representation	None
Leximin	Academic research	Strongest fairness guarantees	Gurobi license
Legacy	Historical compatibility	Backwards compatible	None

Real-World Applications¶

Government & Democracy¶

Ireland's Citizens' Assembly: Used sortition for constitutional reform discussions
French Citizens' Convention: 150 citizens selected to address climate change
UK Citizens' Assemblies: Local and national policy deliberation

Research & Academia¶

Deliberative Polling: Stanford's Center for Deliberative Democracy
Policy Research: Representative samples for social science studies
Market Research: Demographically balanced focus groups

Community Engagement¶

Participatory Budgeting: Community members deciding local spending
Planning Consultations: Representative input on development projects
Local Government: Advisory panels for municipal decisions

Support & Community¶

Getting Help¶

Troubleshooting Guide - Solutions to common problems
GitHub Issues - Report bugs or request features
Discussion Forum - Community support and questions

Contributing¶

Contributing Guide - How to contribute to the project
Development Setup - Set up your development environment

Research & Citations¶

Core Paper - Academic foundation for the algorithms
Related Research - Additional academic resources

License & Usage¶

This library is open source under the GPL License. You're free to use it for:

✅ Academic research and education
✅ Government and civic applications
✅ Commercial projects and consulting
✅ Community organizing and activism

Note: The leximin algorithm requires Gurobi, which has commercial licensing requirements. All other algorithms use open-source solvers.