elsim.strategies module

Implements various strategies.

These take collections of utilities as inputs and return collections of ballots that voters cast for a voting method.

elsim.strategies.approval_optimal(utilities)[source]

Convert utilities to optimal approval voting ballots.

Given a set of utilities for each voter-candidate pair, each voter is modeled as maximizing their expected utility, by approving any candidate that exceeds their mean utility over all candidates. [1]_

Parameters:

utilities (array_like) –

A 2D collection of utilities.

Rows represent voters, and columns represent candidate IDs. Higher utility numbers mean greater approval of that candidate by that voter.

Returns:

election – A 2D collection of approval ballots.

Rows represent voters, and columns represent candidate IDs. A cell contains 1 if that voter approves of that candidate, otherwise 0.

Return type:

ndarray

References

Examples

Voter 0 loves Candidates A (index 0) and B (index 1), but hates C (2). Voter 1 dislikes A, likes B, and loves C. Voter 2 hates A, and is lukewarm about B and C.

>>> utilities = [[1.0, 1.0, 0.0],
...              [0.1, 0.8, 1.0],
...              [0.0, 0.5, 0.5],
...              ]

Each voter optimally chooses their approval threshold based on their mean utility: Voter 0 approves A and B. Voter 1 approves B and C. Voter 2 approves B and C.

>>> approval_optimal(utilities)
array([[1, 1, 0],
       [0, 1, 1],
       [0, 1, 1]], dtype=uint8)
elsim.strategies.honest_normed_scores(utilities, max_score=5)[source]

Convert utilities into scores using honest (but normalized) strategy.

Given a set of utilities for each voter-candidate pair, each voter is modeled as giving their favorite candidate a maximum score, least favorite candidate a minimum score, and proportional scores in between.

Parameters:

  • utilities (array_like) –

    A 2D collection of utilities.

    Rows represent voters, and columns represent candidate IDs. Higher utility numbers mean greater approval of that candidate by that voter.

  • max_score (int, optional) – The highest score on the ballot. If max_score = 3, the possible scores are 0, 1, 2, 3.

Returns:

election – A 2D collection of score ballots.

Rows represent voters, and columns represent candidate IDs. A cell contains a high score if that voter approves of that candidate, or low score if they disapprove

Return type:

ndarray

Examples

Voter 0 loves Candidates A (index 0) and B (index 1), but hates C (2). Voter 1 dislikes A, likes B, and loves C. Voter 2 hates A, and is lukewarm about B and C.

>>> utilities = [[1.0, 1.0, 0.0],
...              [0.1, 0.8, 1.0],
...              [0.0, 0.5, 0.5],
...              ]

Each voter fills out a 0-5 Score ballot with their favorite and least favorite scored at the max and min:

>>> honest_normed_scores(utilities, max_score=5)
array([[5, 5, 0],
       [0, 4, 5],
       [0, 5, 5]], dtype=uint8)
elsim.strategies.honest_rankings(utilities)[source]

Convert utilities into rankings using honest strategy.

Parameters:

utilities (array_like) –

A 2D collection of utilities.

Rows represent voters, and columns represent candidate IDs. Higher utility numbers mean greater approval of that candidate by that voter.

Returns:

election – A collection of ranked ballots. Rows represent voters and columns represent rankings, from best to worst, with no tied rankings. Each cell contains the ID number of a candidate, starting at 0.

For example, if a voter ranks Curie > Avogadro > Bohr, the ballot line would read [2, 0, 1] (with IDs in alphabetical order).

Return type:

array_like

Examples

Generate an election with 4 voters and 3 candidates:

>>> from elsim.elections import random_utilities
>>> utilities = random_utilities(4, 3, random_state=1984)  # for doctest
>>> utilities
array([[0.19746307, 0.00903803, 0.78376658],
       [0.08090381, 0.50265116, 0.55887602],
       [0.74867306, 0.21977523, 0.12586929],
       [0.64267652, 0.15365841, 0.77633876]])

Here, Voter 3 prefers Candidate 2, then 0, then 1, as we can see when converted to rankings:

>>> honest_rankings(utilities)
array([[2, 0, 1],
       [2, 1, 0],
       [0, 1, 2],
       [2, 0, 1]], dtype=uint8)
elsim.strategies.vote_for_k(utilities, k)[source]

Convert utilities to approval voting ballots, approving top k candidates.

Given a set of utilities for each voter-candidate pair, each voter is modeled as voting for the top k candidates. [1]_

Parameters:

  • utilities (array_like) –

    A 2D collection of utilities.

    Rows represent voters, and columns represent candidate IDs. Higher utility numbers mean greater approval of that candidate by that voter.

  • k (int or 'half') – The number of candidates approved of by each voter, or ‘half’ to make the number dependent on the number of candidates. If a negative int, then vote for n - k candidates, where n is the total number.

Returns:

election – A 2D collection of approval ballots.

Rows represent voters, and columns represent candidate IDs. A cell contains 1 if that voter approves of that candidate, otherwise 0.

Return type:

ndarray

References

Examples

Voter 0 loves Candidates A (index 0) and B (index 1), but hates C (2). Voter 1 dislikes A, likes B, and loves C. Voter 2 hates A, and is lukewarm about B and C.

>>> utilities = [[1.0, 1.0, 0.0],
...              [0.1, 0.8, 1.0],
...              [0.0, 0.5, 0.5],
...              ]

Each voter approves of their top-two candidates: Voter 0 approves A and B. Voter 1 approves B and C. Voter 2 approves B and C.

>>> vote_for_k(utilities, 2)
array([[1, 1, 0],
       [0, 1, 1],
       [0, 1, 1]], dtype=uint8)