votesim.metrics ¶

Output controller & metrics to measure performance of an election

Contents

votesim.metrics

Class Summary ¶

`BallotStats`(electionStats)	Ballot marking statistics
`BaseStats`(electionStats)	Base inheritance class for Stats objects.
`CandidateStats`(electionStats)	Candidate statistics dependent on `voters`
`ElectionData`([voters, weights, order, …])	Store temporary election results data here to make output calculations.
`ElectionStats`([voters, weights, order, …])	ElectionStats collects election output data and re-routes that data towards various calculations and post-process variables.
`PrRegret`(electionStats)	Metrics for proportional representation
`VoterStats`(electionStats)	Voter population statistics
`WinnerCategories`(electionStats)	Determine whether majority, condorcet, or utility winner was elected
`WinnerStats`(electionStats)	Winner output statistics

Function Summary ¶

`candidate_regrets`(voters, candidates[, …])	Calculate the voter regret for each candidate or winner.
`consensus_regret`(voters, winners[, _distances])	Measure overall average satisfaction of all winners for all voters.
`mean_regret`(voters[, weights, order])	Measure overall regret of voters if a candidate located at the centroid was elected.
`median_regret`(voters[, weights, order])
`regret_std`(voters[, meanvoter, weights, order])
`voter_regrets`(voters[, weights, order, …])	Calculate the voter regrets for each other if voters became a candidate

Module Classes ¶

BallotStats¶

class votesim.metrics.BallotStats(electionStats: votesim.metrics.ElectionStats)¶: Ballot marking statistics

Method/Attribute Summary¶

`BallotStats.bullet_num`	Number of ballots where voters only bullet voted for 1 candidate
`BallotStats.bullet_ratio`	Ratio of ballots where voters only bullet voted for 1 candidate
`BallotStats.full_num`	Number of ballots where all but one candidate is marked
`BallotStats.full_ratio`	Ratio of ballots where all but one candidate is marked
`BallotStats.marked_num`	Total number of marked candidates for all ballots
`BallotStats.marked_avg`	Average number of marked candidates per ballot
`BallotStats.marked_std`	Std deviation of marked candidates per ballot

BallotStats.bullet_num()¶: Number of ballots where voters only bullet voted for 1 candidate

BallotStats.bullet_ratio()¶: Ratio of ballots where voters only bullet voted for 1 candidate

BallotStats.full_num()¶: Number of ballots where all but one candidate is marked

BallotStats.full_ratio()¶: Ratio of ballots where all but one candidate is marked

BallotStats.marked_num()¶: Total number of marked candidates for all ballots

BallotStats.marked_avg()¶: Average number of marked candidates per ballot

BallotStats.marked_std()¶: Std deviation of marked candidates per ballot

BaseStats¶

class votesim.metrics.BaseStats(electionStats: votesim.metrics.ElectionStats)¶

Base inheritance class for Stats objects. Use this to create new Statistic Output objects.

All attributse that do not start with underscore ‘_’ will be used as output variables to be stored.

Parameters: electionStats (ElectionStats) – ElectionStats parent object

_electionStats¶

Top-level output object

Type: ElectionStats

_electionData¶

Temporary election data used for making calculations

Type: ElectionData

Example

Create your new output object

>>> import numpy as np
>>>
>>> class MyStats(BaseStats):
>>>     @votesim.utilities.lazy_property
>>>     def stat1(self):
>>>         v = self._electionData.voters
>>>         return np.mean(v, axis=0)

Method/Attribute Summary¶

BaseStats.data_dependencies

BaseStats.data_dependencies()¶

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

CandidateStats¶

class votesim.metrics.CandidateStats(electionStats: votesim.metrics.ElectionStats)¶: Candidate statistics dependent on voters

Method/Attribute Summary¶

`CandidateStats.pref`	Candidate preference coordinates
`CandidateStats.regrets`	voter regret for each candidate
`CandidateStats.regret_best`	Best possible regret for the best candidate in election
`CandidateStats.regret_avg`	Average regret if a random candidate became winner
`CandidateStats.winner_utility`	Best utility candidate in election
`CandidateStats.winner_condorcet`	Condorcet winner of election, return -1 if no condorcet winner found.
`CandidateStats.winner_plurality`	Plurality winning candidate of election
`CandidateStats.winner_majority`	Majority winner of election; return -1 if no majority found
`CandidateStats.plurality_ratio`	Ratio of plurality winning votes to total votes.
`CandidateStats.utility_ratio`	Utility ratio of the best candidate compared to average candidate, normalized by the utility range from random to ideal candidate.

CandidateStats.pref()¶: array shape (a, b) : Candidate preference coordinates

CandidateStats.regrets()¶: array shape (c) : voter regret for each candidate

CandidateStats.regret_best()¶: Best possible regret for the best candidate in election

CandidateStats.regret_avg()¶: Average regret if a random candidate became winner

CandidateStats.winner_utility()¶: Best utility candidate in election

CandidateStats.winner_condorcet()¶: Condorcet winner of election, return -1 if no condorcet winner found.

CandidateStats.winner_plurality()¶: Plurality winning candidate of election

CandidateStats.winner_majority()¶: Majority winner of election; return -1 if no majority found

CandidateStats.plurality_ratio()¶: float : Ratio of plurality winning votes to total votes. This metric attempts to measure to competitiveness of an election.

CandidateStats.utility_ratio()¶: Utility ratio of the best candidate compared to average candidate, normalized by the utility range from random to ideal candidate. This metric attempts to measure if there’s a clear stand-out winner in the election.

ElectionData¶

class votesim.metrics.ElectionData(voters=None, weights=None, order=1, candidates=None, winners=None, distances=None, ballots=None, ties=None, **kwargs)¶

Store temporary election results data here to make output calculations. Not meant to be used directly by user, created by ElectionStats.

voters¶: Voter preferences

candidates¶: Candidate preferences

winners¶: Election winners

ballots¶: Ballot data used in election

distances¶: Regret of voters for candidate; opposite of utility.

\*\*kwargs

Type: any additional datas to set

Method/Attribute Summary¶

ElectionData.set(**kwargs)

set kwargs to attributes

ElectionData.set(**kwargs)¶: set kwargs to attributes

ElectionStats¶

class votesim.metrics.ElectionStats(voters=None, weights=- 1, order=None, candidates=None, winners=None, distances=None, ballots=None, **kwargs)¶: ElectionStats collects election output data and re-routes that data towards various calculations and post-process variables. Output data tree

Method/Attribute Summary¶

`ElectionStats.set_data`([voters, weights, …])	Set new election data, delete cached statistics
`ElectionStats.set_categories`(names[, fulloutput])	Set output categories to output.
`ElectionStats.get_categories`()	Retrieve available output categories
`ElectionStats.add_output`(name, output[, cache])	Add an output object.
`ElectionStats.get_dict`()	Retrieve desired category key and values and return dict of dict.
`ElectionStats.get_docs`()	Retrieve all available statistic descriptions as dict
`ElectionStats.electionData`	Temporary election data used for output calculations
`ElectionStats.voter`	See `VoterStats`
`ElectionStats.candidate`	See `CandidateStats`
`ElectionStats.winner`	See `WinnerStats`
`ElectionStats.winner_categories`	See `WinnerCategories`
`ElectionStats.ballot`	See `BallotStats`

ElectionStats.set_data(voters=None, weights=- 1, order=None, candidates=None, winners=None, distances=None, ballots=None, ties=None, **kwargs)¶: Set new election data, delete cached statistics

ElectionStats.set_categories(names, fulloutput=False)¶

Set output categories to output.

Parameters

names (list of str) – Output category names.
fulloutput (bool, optional) – If True output all avaialable ouputs. The default is False.

Returns

Return type

None.

ElectionStats.get_categories()¶: Retrieve available output categories

ElectionStats.add_output(name, output, cache='_cache_result')¶

Add an output object. This output’s base class must be BaseStats.

Parameters

name (str) – Name of output
output (subtype of BaseStats) – User defined output. Define this output by creating a class inherited from BaseStats
cache (str) –
Name of output cache to store results. This determines when output is retained and when it is deleted and regenerated during election model creation. The options are
- ’_cache_voter’ - Clear cache when voter data changes (least aggressive)
- ’_cache_candidate’ - Clear cache when candidate data changes
- ’_cache_result’ - Clear cache after every election (most aggressive)

Returns

Return type

None.

ElectionStats.get_dict()¶: Retrieve desired category key and values and return dict of dict.

ElectionStats.get_docs()¶: Retrieve all available statistic descriptions as dict

ElectionStats.electionData()¶: Temporary election data used for output calculations

ElectionStats.voter()¶: See VoterStats

ElectionStats.candidate()¶: See CandidateStats

ElectionStats.winner()¶: See WinnerStats

ElectionStats.winner_categories()¶: See WinnerCategories

ElectionStats.ballot()¶: See BallotStats

PrRegret¶

class votesim.metrics.PrRegret(electionStats: votesim.metrics.ElectionStats)¶: Metrics for proportional representation

Method/Attribute Summary¶

`PrRegret.avg_regret`	float Average voter regret for his nearest winner
`PrRegret.winners_regret`	array shaped (b,): Avg voter regrets for each winner
`PrRegret.winners_regret_std`	float: Standard deviation of nearest regrets for each winner.
`PrRegret.std_num_voters_per_winner`	float: Standard deviation of number of nearest voters for each winner

PrRegret.avg_regret()¶: float Average voter regret for his nearest winner

PrRegret.winners_regret()¶: array shaped (b,): Avg voter regrets for each winner

PrRegret.winners_regret_std()¶: float: Standard deviation of nearest regrets for each winner. An ideal proportional system ought to have low std deviation.

PrRegret.std_num_voters_per_winner()¶: float: Standard deviation of number of nearest voters for each winner

VoterStats¶

class votesim.metrics.VoterStats(electionStats: votesim.metrics.ElectionStats)¶: Voter population statistics

Method/Attribute Summary¶

`VoterStats.regret_mean`	Regret of voters if winner is located at preference mean
`VoterStats.regret_median`	Regret of voters if winner is located at preference median
`VoterStats.regret_random_avg`	Average regret of voters if winner is randomly selected from voter population
`VoterStats.pref_mean`	Preference mean of voters for n preference dimensions
`VoterStats.pref_median`	Preference median of voters for n preference dimensions
`VoterStats.pref_std`	Preference standard deviation of voters for n preference dimensions

VoterStats.regret_mean()¶: Regret of voters if winner is located at preference mean

VoterStats.regret_median()¶: Regret of voters if winner is located at preference median

VoterStats.regret_random_avg()¶: Average regret of voters if winner is randomly selected from voter population

VoterStats.pref_mean()¶: “array shape (n) : Preference mean of voters for n preference dimensions

VoterStats.pref_median()¶: array shape (n) : Preference median of voters for n preference dimensions

VoterStats.pref_std()¶: array shape (n) : Preference standard deviation of voters for n preference dimensions

WinnerCategories¶

class votesim.metrics.WinnerCategories(electionStats: votesim.metrics.ElectionStats)¶: Determine whether majority, condorcet, or utility winner was elected

Method/Attribute Summary¶

`WinnerCategories.is_condorcet`	check whether condorcet winner was elected.
`WinnerCategories.is_majority`	check if majority winner was elected.
`WinnerCategories.is_utility`	check if utility winner was elected

WinnerCategories.is_condorcet()¶: bool : check whether condorcet winner was elected.

WinnerCategories.is_majority()¶: bool : check if majority winner was elected.

WinnerCategories.is_utility()¶: bool : check if utility winner was elected

WinnerStats¶

class votesim.metrics.WinnerStats(electionStats: votesim.metrics.ElectionStats)¶: Winner output statistics

Method/Attribute Summary¶

`WinnerStats.regret`	overall satisfaction of all winners for all voters.
`WinnerStats.regret_efficiency_candidate`	Voter satisfaction efficiency, compared to random candidate
`WinnerStats.regret_efficiency_voter`	voter satisfaction efficiency equation normalizing to voter population regret of an ideal winner vs a random voter.
`WinnerStats.regret_normed`	Voter regret normalized to ideal
`WinnerStats.winners`	Index location of winners
`WinnerStats.ties`	Index location of ties

WinnerStats.regret()¶: overall satisfaction of all winners for all voters.

WinnerStats.regret_efficiency_candidate()¶: Voter satisfaction efficiency, compared to random candidate

WinnerStats.regret_efficiency_voter()¶: voter satisfaction efficiency equation normalizing to voter population regret of an ideal winner vs a random voter.

WinnerStats.regret_normed()¶: Voter regret normalized to ideal

WinnerStats.winners()¶: array of int : Index location of winners

WinnerStats.ties()¶: array of int : Index location of ties

Module Functions ¶

candidate_regrets¶

votesim.metrics.candidate_regrets(voters, candidates, weights=None, order=1)¶

Calculate the voter regret for each candidate or winner.

Parameters

voters (array (a, n)) – Voter preferences; n-dimensional voter cardinal preferences for n issues.
candidates (array (b, n)) – Candidate preferences for b candidates and n-dimensional issues.

Returns

out – Average preference distance of voters from each candidate numbering b.

Return type

array (b,)

consensus_regret¶

votesim.metrics.consensus_regret(voters, winners, _distances=None)¶

Measure overall average satisfaction of all winners for all voters.

Parameters

voters (array, shape (a, n)) – Voter preferences; n-dimensional voter cardinal preferences for n issues.
winners (array, shape (b, n)) – Winner preferences for b winners and n-dimensional issues.

Returns

regret – Consensus voter regret metric

Return type

float

mean_regret¶

votesim.metrics.mean_regret(voters, weights=None, order=1)¶

Measure overall regret of voters if a candidate located at the centroid was elected.

Parameters

voters (array, shape (a, n)) – Voter preferences; n-dimensional voter cardinal preferences for n issues.
weights (array, shape (a, n)) – Voter preference weights for each preference. (ie, voters care more about some preferences than others).

median_regret¶

votesim.metrics.median_regret(voters, weights=None, order=1)¶

regret_std¶

votesim.metrics.regret_std(voters, meanvoter=None, weights=None, order=1)¶

voter_regrets¶

votesim.metrics.voter_regrets(voters, weights=None, order=1, pnum=10, maxsize=5000, seed=None)¶

Calculate the voter regrets for each other if voters became a candidate

Parameters

voters (array shape (a, n)) – Voter preferences; a number of voters, cardinal preferences for n issues.
weights (None or array shape (a, n)) – Dimensional weightings of each voter for each dimension. Only relevant if n > 1
order (int) –
Order of norm
- 1 = taxi-cab norm; preferences for each issue add up
- 2 = euclidean norm; take the sqrt of squares.
pnum (int) – Number of voters to calculate distances for at-a-time, for memory issues
maxsize (int) – For large populations this calculation is expensive. Use this to sample a subset of the voter population. Default 5000. Set to None to use all voters.

Returns

out – Voter regrets for each voter as a proposed candidate.

c = a if maxsize <= number voters or maxsize==None
c = maxsize otherwise for sampled voters.

Return type

array shape (c,)

votesim.metrics ¶

Class Summary ¶

Function Summary ¶

Module Classes ¶

BallotStats¶

Method/Attribute Summary¶

BaseStats¶

Method/Attribute Summary¶

CandidateStats¶

Method/Attribute Summary¶

ElectionData¶

Method/Attribute Summary¶

ElectionStats¶

Method/Attribute Summary¶

PrRegret¶

Method/Attribute Summary¶

VoterStats¶

Method/Attribute Summary¶

WinnerCategories¶

Method/Attribute Summary¶

WinnerStats¶

Method/Attribute Summary¶

Module Functions ¶

candidate_regrets¶

consensus_regret¶

mean_regret¶

median_regret¶

regret_std¶

voter_regrets¶

Table of Contents

This Page

votesim.metrics¶

Class Summary¶

Function Summary¶

Module Classes¶

BallotStats¶

Method/Attribute Summary¶

BaseStats¶

Method/Attribute Summary¶

CandidateStats¶

Method/Attribute Summary¶

ElectionData¶

Method/Attribute Summary¶

ElectionStats¶

Method/Attribute Summary¶

PrRegret¶

Method/Attribute Summary¶

VoterStats¶

Method/Attribute Summary¶

WinnerCategories¶

Method/Attribute Summary¶

WinnerStats¶

Method/Attribute Summary¶

Module Functions¶

candidate_regrets¶

consensus_regret¶

mean_regret¶

median_regret¶

regret_std¶

voter_regrets¶

votesim.metrics ¶

Class Summary ¶

Function Summary ¶

Module Classes ¶

Module Functions ¶