votesim.models.vcalcs

Simulate voting behavior. Convert voter preferences into preferences & rankings for candidates.

Typical function inputs

votersarray shape (a, n)

Voter preferences; a-dimensional voter preferences for n issues.

  • Each row of the array represents a voter’s preferences

  • Each column represents a difference issue.

candidatesarray shape (b, n)

Candidate preferences for n-dimensional issues.

  • Each row represents a candidate’s preference

  • Each column represents a difference issue.

Types of voting behavior to simulate

Preference Tolerance

Assume that voters have a threshold of preference distance, at which if a candidate exceeds the tolerance threshold, they will give zero score or refuse to rank the candidate.

Preference Tolerance – Last Hope

Assume that for some voters, if all candidates exceed their threshold of preference tolerance, they might decide still vote for the single closet candidate.

Memory limitation

Assume that voters might only rate/rank so many candidates, for example, up to a limit of about 7.

Preference Error

Voters might miscalculate their preference distance from a candidate.

Function Summary

voter_distance_error(distances, error_std[, …])

Add error to voter distances from candidates

voter_distances(voters, candidates[, …])

Calculate preference distance of voters away from candidates.

voter_rankings(voters, candidates[, cnum, …])

Create rankings of voter for candidates, by considering only a top cnum of candidates and ignoring the rest.

voter_scores_by_rank(voters, candidates[, cnum])

Calculate scores by assuming voters will only rate a set number cnum of candidates from 0 to 1.

voter_scores_by_tolerance(voters, candidates)

Creating ratings from 0 to 1 of voter for candidates using a tolerance circle.

zero_out_random(ratings, limits[, weights, rs])

Zero-out scores or ranks by random.

Module Functions

voter_distance_error

votesim.models.vcalcs.voter_distance_error(distances, error_std, rstate=None)

Add error to voter distances from candidates

Parameters

  • distances (array shape (a,b)) – Distances generated by function voter_distances

  • error_std (array shape (a,)) – standard deviation of distance error for each voter. Each voter has an accuracy represented by this.

Returns

distances – New voter distances including voter error.

Return type

array shape (a,b)

voter_distances

votesim.models.vcalcs.voter_distances(voters, candidates, weights=None, order=1)

Calculate preference distance of voters away from candidates.

Parameters

  • voters (array shape (a, n)) – Voter preferences; a number of voters, cardinal preferences for n issues.

  • candidates (array shape (b, n)) – b-number of Candidate preferences for n-dimensional issues.

  • weights (None or array shape (a, n)) – Dimensional weightings of each voter for each dimension. Only relevant if n > 1

orderint

Order of norm

  • 1 = taxi-cab norm; preferences for each issue add up

  • 2 = euclidean norm; take the sqrt of squares.

Returns

distances – Candidate b preference distance away from voter, for each voter a

Return type

array shaped (a, b)

voter_rankings

votesim.models.vcalcs.voter_rankings(voters, candidates, cnum=None, _distances=None)

Create rankings of voter for candidates, by considering only a top cnum of candidates and ignoring the rest. The last candidate is rated 0. The closest candidate is rated 1. Others are linearly scaled in between.

Parameters

  • voters (array shape (a, n)) – Voter preferences; a number of voter cardinal preferences for n issues.

  • candidates (array shape (b, n)) – Candidate preferences for n-dimensional issues.

  • cnum (None (default), int, or int array shaped (a,)) – Max number of candidates that will be ranked. Can be set for each voter.

Returns

rankings – Voter rankings for each candidate

Return type

array shaped (a, b)

voter_scores_by_rank

votesim.models.vcalcs.voter_scores_by_rank(voters, candidates, cnum=None)

Calculate scores by assuming voters will only rate a set number cnum of candidates from 0 to 1. Tolerance is based on number of candidates rather than preference distance.

Parameters

  • voters (array shape (a, n)) – Voter preferences; n-dimensional voter cardinal preferences for n issues.

  • candidates (array shape (b, n)) – Candidate preferences for n-dimensional issues.

  • cnum (None (default), int, or int array shaped (a,)) – Max number of candidates that will be ranked. Can be set for each voter.

Returns

out – Utility scores from a-voters for each b-candidate.

Return type

array shaped (a, b)

voter_scores_by_tolerance

votesim.models.vcalcs.voter_scores_by_tolerance(voters, candidates, distances=None, weights=None, tol=1, cnum=None, error_std=0, strategy='abs')

Creating ratings from 0 to 1 of voter for candidates using a tolerance circle.

  • Assume that all voters are honest.

  • Assume that voters have a preference “tolerance”. Candidates whose preference distance exceeds this tolerance have utility set to zero. - Linear mapping of preference distance and utility. - Utility = 1 if candidate preference is exactly voter preference. - Utility = 0 if candidate preference is exactly the tolerance distance.

  • Assume that voters will give strongest possible preference to closest candidate, unless that candidate is outside their preference tolerance.

Parameters

  • voters (array shape (a, n)) – Voter preferences; a voter cardinal preferences for n issues.

  • candidates (array shape (b, n)) – b number of candidate preferences for n-dimensional issues.

  • tol (float, or array shaped (a,)) – Voter candidate tolerance distance. If cardinal preference exceed tol, utility set to zero. Toleranace is in same units as voters & candidates

  • cnum (None (default), int, or int array shaped (a,)) – Max number of candidates that will be ranked. Can be set for each voter.

  • strategy (str) –

    Tolerance determination strategy. Use the following string options:

    • ”abs” – set tol as an absolute value to compare to distance.

    • ”voter” – set tol as factor of the average voter distance from the centroid. - At tol=1, candidates farther than 1 x avg voter distance are rated zero - At tol=2, candidates farther than 2 x avg voter distance are rated zero.

    • ”candidate” – set tol relative to farthest distance of candidate to voter. - At tol=1, the max distance candidate is rated zero. - At tol=0.5, candidates at half of the max distance are rated zero

Returns

out – Utility scores from a-voters for each b-candidate.

Return type

array shaped (a, b)

zero_out_random

votesim.models.vcalcs.zero_out_random(ratings, limits, weights=None, rs=None)

Zero-out scores or ranks by random. Simluation of limits of voter information, where for many candidates, voters may not be informed of all of them.

Parameters

  • ratings (array shaped (a, b)) – Ratings, scores, ranks from a-voters for each b-candidate.

  • limits (int array shaped (a,)) – Number of canidates each voter has knowledge about

  • weights (array shaped (b,)) – Media model, probability weighting for each candidate where some candidates are more likely to be known than others.

Returns

out – Adjusted ratings, scores, ranks with candidate limits applied.

Return type

array shaped (a,b)