votesim.metrics¶
Output controller & metrics to measure performance of an election
Class Summary¶

Ballot marking statistics 

Base inheritance class for Stats objects. 

Candidate statistics dependent on 

Store temporary election results data here to make output calculations. 

ElectionStats collects election output data and reroutes that data towards various calculations and postprocess variables. 

Metrics for proportional representation 

Voter population statistics 

Determine whether majority, condorcet, or utility winner was elected 

Winner output statistics 
Function Summary¶

Calculate the voter regret for each candidate or winner. 

Measure overall average satisfaction of all winners for all voters. 

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





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¶
Number of ballots where voters only bullet voted for 1 candidate 

Ratio of ballots where voters only bullet voted for 1 candidate 

Number of ballots where all but one candidate is marked 

Ratio of ballots where all but one candidate is marked 

Total number of marked candidates for all ballots 

Average number of marked candidates per ballot 

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
¶ Toplevel output object
 Type

_electionData
¶ Temporary election data used for making calculations
 Type
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)
CandidateStats¶

class
votesim.metrics.
CandidateStats
(electionStats: votesim.metrics.ElectionStats)¶ Candidate statistics dependent on
voters
Method/Attribute Summary¶
Candidate preference coordinates 

voter regret for each candidate 

Best possible regret for the best candidate in election 

Average regret if a random candidate became winner 

Best utility candidate in election 

Condorcet winner of election, return 1 if no condorcet winner found. 

Plurality winning candidate of election 

Majority winner of election; return 1 if no majority found 

Ratio of plurality winning votes to total votes. 

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 standout 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¶

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 reroutes that data towards various calculations and postprocess variables. Output data tree
Method/Attribute Summary¶

Set new election data, delete cached statistics 

Set output categories to output. 
Retrieve available output categories 


Add an output object. 
Retrieve desired category key and values and return dict of dict. 

Retrieve all available statistic descriptions as dict 

Temporary election data used for output calculations 

See 

See 

See 

See 

See 

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 fromBaseStats
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¶
float Average voter regret for his nearest winner 

array shaped (b,): Avg voter regrets for each winner 

float: Standard deviation of nearest regrets for each 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¶
Regret of voters if winner is located at preference mean 

Regret of voters if winner is located at preference median 

Average regret of voters if winner is randomly selected from voter population 

Preference mean of voters for n preference dimensions 

Preference median of voters for n preference dimensions 

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¶
check whether condorcet winner was elected. 

check if majority winner was elected. 

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¶
overall satisfaction of all winners for all voters. 

Voter satisfaction efficiency, compared to random candidate 

voter satisfaction efficiency equation normalizing to voter population regret of an ideal winner vs a random voter. 

Voter regret normalized to ideal 

Index location of winners 

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; ndimensional voter cardinal preferences for n issues.
candidates (array (b, n)) – Candidate preferences for b candidates and ndimensional 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; ndimensional voter cardinal preferences for n issues.
winners (array, shape (b, n)) – Winner preferences for b winners and ndimensional 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; ndimensional 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).
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 = taxicab norm; preferences for each issue add up
2 = euclidean norm; take the sqrt of squares.
pnum (int) – Number of voters to calculate distances for atatime, 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,)