votesim.models.spatial.base

Simulate elections.

Elements of an election

  1. Create voter preferences

  • Create voter preference distributions

  • Create voter preference tolerance distribution

  1. Create candidate preferences

  2. Simulate voter behavior, strategy

  3. Transform voter preferences into candidate scores or rankings

  4. Input scores/ranks into election system.

  5. Run the election.

  6. Measure the results.

Class Summary

Candidates(voters[, seed])

Create candidates for spatial model

Election([voters, candidates, seed, …])

Run an Election with Voters and Candidates

SimpleVoters([seed, strategy, stol])

Create simple normal distribution of voters.

VotersGroup([group])

Group together multiple voter objects

Function Summary

gaussian_preferences(coords, sizes, scales)

Generate gaussian preference distributions at coordinate and specified size

generate_preferences(numfactions, size[, …])

Create multi-peaked gaussian distributions of preferences

load_election(fname)

Load a pickled Election object from file

ltruncnorm(loc, scale, size[, random_state])

Truncated normal random numbers, cut off at locations less than 0.

Module Classes

Candidates

class votesim.models.spatial.base.Candidates(voters: votesim.models.spatial.base.SimpleVoters, seed=None)

Create candidates for spatial model

Parameters

voters (Voters from votesim.voters) –

Method/Attribute Summary

Candidates.set_seed(seed)

Set pseudorandom seed

Candidates.reset()

Reset candidates for a given Voters.

Candidates.add_random(cnum[, sdev])

Add random candidates, uniformly distributed.

Candidates.add(candidates)

Add 2d array of candidates to election, record actions

Candidates.add_median()

Add candidate located at voter median coordinate

Candidates.add_faction(vindex)

Add a candidate lying on the centroid of a faction generated using Voters.add_faction.
Candidates.set_seed(seed)

Set pseudorandom seed

Candidates.reset()

Reset candidates for a given Voters. Delete candidate preferences and records

Candidates.add_random(cnum, sdev=2)

Add random candidates, uniformly distributed.

Parameters

  • cnum (int) – Number of candidates for election

  • sdev (float) – +- Width of standard deviations to set uniform candidate generation across voter population

Candidates.add(candidates)

Add 2d array of candidates to election, record actions

Parameters

candidates (array shape (a, n)) –

Candidate preference coordinates.

  • a = number of candidates

  • n = number of preference dimensions

Candidates.add_median()

Add candidate located at voter median coordinate

Candidates.add_faction(vindex)

Add a candidate lying on the centroid of a faction generated using Voters.add_faction.

Parameters

vindex (int) – Index of faction, found in self.voter_ags[‘coords’]

Election

class votesim.models.spatial.base.Election(voters: votesim.models.spatial.base.SimpleVoters = None, candidates: votesim.models.spatial.base.Candidates = None, seed=None, numwinners=1, scoremax=5, name='', save_args=True)

Run an Election with Voters and Candidates

Parameters

  • voters (None, SimpleVoters, or Voters) – Voters object specifying the voter preferences and behavior.

  • candidate (None or Canidates) – Candidates object specifying candidate preferences

  • seed (int or None) – Seed for pseudo-random number generation

  • numwinners (int >= 1) – Number of winners for the election

  • scoremax (int) – Maximum score for ballot generation

  • name (str) – Name of election model, used to identify different benchmark models.

  • save_args (bool (default True)) –

    • If True, save all parameters input into method calls. These parameters can be used to regenerate specific elections.

    • If False, only save parameters input into self.user_data.

Method/Attribute Summary

Election.init(seed, numwinners, scoremax, name)

Initialize some election properties

Election.set_models([voters, candidates])

Set new voter or candidate model

Election.user_data([d])

Record any additional data the user wishes to record.

Election.reset()

Delete election data for the current run – voter preferences, candidate preferences, and ballots, Clear the kind of data that can be regenerated if desired.

Election.run([etype, method, btype, kwargs])

Run the election using votesystems.eRunner.

Election.electionData

model election data

Election.electionStats

Election.get_results()

Retrieve election statistics and post-process calculations

Election.get_parameter_keys()

Retrieve election input parameter keys

Election.get_parameters()

Retrieve election input parameters

Election.get_output_docs()

Retrieve output documentation

Election.dataseries([index])

Retrieve pandas data series of output data

Election.dataframe()

Construct data frame from results history

Election.save(name[, reset])

Pickle election data

Election.rerun(d)

Re-run an election found in dataframe.
Election.init(seed, numwinners, scoremax, name)

Initialize some election properties

Election.set_models(voters=None, candidates=None)

Set new voter or candidate model

Parameters

  • voters (SimpleVoters or None) – New voters object

  • candidates (Candidates or None) – New candidates object

Election.user_data(d=None, **kwargs)

Record any additional data the user wishes to record.

Parameters

**d (dict) – Write any keys and associated data here

Election.reset()

Delete election data for the current run – voter preferences, candidate preferences, and ballots, Clear the kind of data that can be regenerated if desired.

Do not clear statistics.

Election.run(etype=None, method=None, btype=None, kwargs=None)

Run the election using votesystems.eRunner.

Election.electionData()

model election data

Election.electionStats()
Election.get_results() → dict

Retrieve election statistics and post-process calculations

Election.get_parameter_keys()

Retrieve election input parameter keys

Election.get_parameters()

Retrieve election input parameters

Election.get_output_docs()

Retrieve output documentation

Election.dataseries(index=None)

Retrieve pandas data series of output data

Election.dataframe()

Construct data frame from results history

Election.save(name, reset=True)

Pickle election data

Parameters

  • name (str) – Name of new pickle file to dump Election ito

  • reset (bool) – If True (default), delete election data that can be regenerated.

Election.rerun(d)

Re-run an election found in dataframe. Find the election data from the dataframe index

Parameters

  • index (int or None) – Election index from self._dataframe

  • d (dict or None) – Dictionary or Series of election data, generated from self.dataseries.

Returns

out – Newly constructed election object with re-run parameters.

Return type

Election

SimpleVoters

class votesim.models.spatial.base.SimpleVoters(seed=None, strategy='candidate', stol=1.0)

Create simple normal distribution of voters.

Parameters

  • seed (int or None) – Integer seed for pseudo-random generation. None for random numbers.

  • strategy (str) –

    Voter regret-to-ratings conversion strategy. Options are

    • ’candidate’ – Tolerance defiend by candidates

    • ’voter’ – Tolerance defined by voter population std deviation

  • stol (float (default 1.0)) – Tolerance factor for strategy

Score & ratings are constructed based on candidate coordinates

voters

Voter preferences, a number of voters, b number of preference dimensions

Type

array shape (a, b)

ratings

Voter ratings for c candidates, calculated using self.calc_ratings

Type

array shape (a, c)

distances

Voter distances for c candidates, calculated using self.calc_ratings

Type

array shape (a, c)

Method/Attribute Summary

SimpleVoters.set_seed(seed)

Set pseudorandom seed

SimpleVoters.set_strategy(strategy, stol)

SimpleVoters.add_random(numvoters[, ndim, loc])

Add random normal distribution of voters

SimpleVoters.add_points(avgnum, pnum[, ndim])

Add a random point with several clone voters at that point

SimpleVoters.add(voters)

SimpleVoters.calc_ratings(candidates)

`

SimpleVoters.electionStats

SimpleVoters.reset()

Reset method records.
SimpleVoters.set_seed(seed)

Set pseudorandom seed

SimpleVoters.set_strategy(strategy, stol)
SimpleVoters.add_random(numvoters, ndim=1, loc=None)

Add random normal distribution of voters

Parameters

  • numvoters (int) – Number of voters to generate

  • ndim (int) – Number of preference dimensions of population

  • loc (array shaped (ndim,)) – Coordinate of voter centroid

SimpleVoters.add_points(avgnum, pnum, ndim=1)

Add a random point with several clone voters at that point

Parameters

  • avgnum (int) – Avg. Number of voters per unique point

  • pnum (int) – Number of unique points

  • ndim (int) – Number of dimensions

SimpleVoters.add(voters)
SimpleVoters.calc_ratings(candidates)

` Calculate preference distances & candidate ratings for a given set of candidates.

Parameters

candidates (array shaped (a, b)) – Candidate preference data

Returns

out – Voter ratings for each candidate

Return type

array shaped (c, a)

SimpleVoters.electionStats()
SimpleVoters.reset()

Reset method records. Delete voter preferences and records.

VotersGroup

class votesim.models.spatial.base.VotersGroup(group=None)

Group together multiple voter objects

Method/Attribute Summary

VotersGroup.calc_ratings(candidates)

VotersGroup.voters

VotersGroup.ElectionStats()

VotersGroup.calc_ratings(candidates)
VotersGroup.voters()
VotersGroup.ElectionStats()

Module Functions

gaussian_preferences

votesim.models.spatial.base.gaussian_preferences(coords, sizes, scales, rstate=None)

Generate gaussian preference distributions at coordinate and specified size

Parameters

  • coords (array shaped (a, b)) –

    Centroids of a faction voter preferences.

    • rows a = coordinate for each faction

    • columns `b’ = preference dimensions. The more columns, the more preference dimensions.

  • sizes (array shaped (a,)) – Number of voters within each faction, with a total of a factions. Use this array to specify how many people are in each faction.

  • scales (array shaped (a, b)) – The preference spread, width, or scale of the faction. These spreads may be multidimensional. Use columns to specify additional dimensions.

Returns

out – Population preferences of c number of voters in b preference dimensions.

Return type

array shaped (c, b)

generate_preferences

votesim.models.spatial.base.generate_preferences(numfactions, size, ndim=1, sepfactor=1, rstate=None)

Create multi-peaked gaussian distributions of preferences

Parameters

  • numvoters (int array of shape (a,), or int) – Number of voter preferences to generate. If list/array, generate multiple gaussian voter preference peaks.

  • ndim (int, default=1) – Number of preference dimensions to consider

  • sepfactor (float) – Scaling factor of typical distance of peak centers away from one another

  • seed (None (default) or int) –

    Convert preference generation to become deterministic & pseudo-random for testing purposes.

    • If None, use internal clock for seed generation

    • If int, use this seed to generate future random variables.

Returns

out – Voter preferences for ndim number of dimensions.

Return type

array shaped (c, ndim)

Example

Create a 2-dimensional preference spectrum, with 3 factions/preference peaks with:

  • 200 voters in the 1st faction

  • 400 voters in the 2nd faction

  • 100 voters in the 3rd faction

>>> p = generate_voter_preference((200, 400, 100), 2)

Create a 1-dimensional preference spectrum with gaussian distribution for 500 voters.

>>> p = generate_voter_preferences(500, 1)

load_election

votesim.models.spatial.base.load_election(fname)

Load a pickled Election object from file

ltruncnorm

votesim.models.spatial.base.ltruncnorm(loc, scale, size, random_state=None)

Truncated normal random numbers, cut off at locations less than 0.

Parameters

  • loc (float) – Center coordinate of gaussian distribution

  • scale (float) – Std deviation scale

  • size (int) – Number of random numbers to generate

  • random_state (None or numpy.random.RandomState) – Random number seeding object, or None.

Returns

out – Output samples

Return type

array shaped (size)