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)