sortition-algorithms 0.9.0__py3-none-any.whl

sortition_algorithms-0.9.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: sortition-algorithms
+Version: 0.9.0
+Summary: A package containing algorithms for sortition - democratic lotteries.
+Project-URL: Homepage, https://sortitionfoundation.github.io/sortition-algorithms/
+Project-URL: Repository, https://github.com/sortitionfoundation/sortition-algorithms
+Project-URL: Documentation, https://sortitionfoundation.github.io/sortition-algorithms/
+Author-email: Sortition Foundation <hamish@sortitionfoundation.org>
+License-File: LICENSE
+Keywords: python
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.13,>=3.11
+Requires-Dist: attrs>=25.3.0
+Requires-Dist: cattrs>=25.1.0
+Requires-Dist: cvxpy>=1.6.5
+Requires-Dist: gspread>=6.2.1
+Requires-Dist: mip==1.15.0
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: oauth2client>=4.1.3
+Provides-Extra: cli
+Requires-Dist: click>=8.2.1; extra == 'cli'
+Provides-Extra: gurobi
+Requires-Dist: gurobipy>=12.0.2; extra == 'gurobi'
+Description-Content-Type: text/markdown
+
+# sortition-algorithms
+
+[![Release](https://img.shields.io/github/v/release/sortitionfoundation/sortition-algorithms)](https://img.shields.io/github/v/release/sortitionfoundation/sortition-algorithms)
+[![Build status](https://img.shields.io/github/actions/workflow/status/sortitionfoundation/sortition-algorithms/main.yml?branch=main)](https://github.com/sortitionfoundation/sortition-algorithms/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/sortitionfoundation/sortition-algorithms/branch/main/graph/badge.svg)](https://codecov.io/gh/sortitionfoundation/sortition-algorithms)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/sortitionfoundation/sortition-algorithms)](https://img.shields.io/github/commit-activity/m/sortitionfoundation/sortition-algorithms)
+[![License](https://img.shields.io/github/license/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:
+
+- Procaccia et al. [Is Sortition Both Representative and Fair?](https://procaccia.info/wp-content/uploads/2022/06/repfair.pdf)
+- Tiago c Peixoto
+  - [Reflections on the representativeness of citizens’ assemblies and similar innovations](https://democracyspot.net/2023/02/22/reflections-on-the-representativeness-of-citizens-assemblies-and-similar-innovations/) and
+  - [How representative is it really? A correspondence on sortition](https://www.publicdeliberation.net/how-representative-is-it-really-a-correspondence-on-sortition/)
+
+## 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
+
+# Google Sheets workflow
+python -m sortition_algorithms gsheet \
+  --settings config.toml \
+  --auth-json-file credentials.json \
+  --gsheet-name "Citizen Panel Selection" \
+  --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 finalize the set-up for publishing to PyPI, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/publishing/#set-up-for-pypi).
+For activating the automatic documentation with MkDocs, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/mkdocs/#enabling-the-documentation-on-github).
+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).

sortition_algorithms-0.9.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+sortition_algorithms/__init__.py,sha256=2uOa5Hz8fE50x1-oWkF-quK6gKncnCV1kMVzCk3I03o,609
+sortition_algorithms/__main__.py,sha256=KKdGi97C4ozUAb4JrgRo0ZWLL4euG4JXQrC2KTlIjD4,6738
+sortition_algorithms/adapters.py,sha256=pYqXnibZDzahKt5SQQoEc5CNqPlo2KRr4AxCRO7JJR4,12426
+sortition_algorithms/committee_generation.py,sha256=DB2-2aPO9pxkBaqHUJ351jqrikq1s8gophewZf_Ke-s,56969
+sortition_algorithms/core.py,sha256=OrT97X4pOK6Rlx82R0Peaj4oA41gjdBEY1IxPPiqOCc,22038
+sortition_algorithms/errors.py,sha256=Gq5ENu5jmIR2psELfJ1vv3PL9SOemFstwalLeDX9EDc,618
+sortition_algorithms/features.py,sha256=sV6KAOpM8LkPANsyQe1C91i9zbkxHTft3d5KxyOhfZA,13651
+sortition_algorithms/find_sample.py,sha256=J88IRPjnAxZcXOeQLYgAuR5amb4wTPifcBJCmQYZeV8,4183
+sortition_algorithms/people.py,sha256=lyYlhex_UbemqQiRbffaIDNx_v4nrs04Puj48kULur0,7577
+sortition_algorithms/people_features.py,sha256=cqfC9Icy6wxO5ypOWIDfFvnLuUCdWCtIOXVF2lemz3g,12386
+sortition_algorithms/settings.py,sha256=ji86f4t16s5H9UnrQtLt-2uhGgHOERitZxkuX_rjwhA,4191
+sortition_algorithms/utils.py,sha256=nvoKZCD25aZgwymlDDVvCqZQNRRa4fqlxIdUaasm6mo,2968
+sortition_algorithms-0.9.0.dist-info/METADATA,sha256=IzFlWJs9FBHB6peeOmjBZJA4doj1kqFOvM9cxpZjU4s,8312
+sortition_algorithms-0.9.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sortition_algorithms-0.9.0.dist-info/entry_points.txt,sha256=4KborwJYZ75Od1efKkTlHKZ4XBXEAO_2S7QwnVd-dQs,64
+sortition_algorithms-0.9.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+sortition_algorithms-0.9.0.dist-info/RECORD,,

sortition_algorithms-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sortition_algorithms-0.9.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sortition = sortition_algorithms.__main__:cli