simulate_election: Function to simulate a full election in a single district

In i3pack: Incentives for Inter- And Intra-Party Electoral Competition

Function to simulate a full election in a single district

Description

The function runs a complete election in a single district, using the simulation framework described in detail in Chapter 4 of Crisp et al. 2024.

Usage

simulate_election(
  voters = NULL,
  parties = NULL,
  cands = NULL,
  nominated = NULL,
  nvoters = 3000,
  nparties = 5,
  nvotes = 1,
  M = 5,
  rank_cand = TRUE,
  strategic = TRUE,
  strategic_error = 0.05,
  who_ranks = c("parties", "voters", "none"),
  gamma_val = NULL,
  gamma_rank = 1,
  elec_fun_name = "dhondt",
  ballot_type = "open",
  primary = FALSE,
  two_round = FALSE,
  pool_level = c("party_list", "party", "candidate"),
  ranked_vote = FALSE,
  free_vote = FALSE,
  max_cand = 0,
  threshold = 0,
  lists_per_party = 1,
  seed = 123,
  elec_results_only = FALSE,
  multiplier = 1,
  system_name,
  ...
)

Arguments

voters	Optional vector of voter positions in 1d ideological space.
parties	Optional vector of party positions in 1d ideological space. Maximum of 10 parties allowed.
cands	Optional matrix with three columns: candidate 1d ideological position, unique numerical candidate ID, and positive numerical candidate valence
nominated	Optional data.frame with five variables: rank (candidate ranking in the party list); candidate (numeric candidate ID); pos (1d ideological position of candidate); list (numeric list ID; equal to 1, unless parties are allowed to have multiple lists); party (numeric party ID).
nvoters	Number of voters; defaults to 3,000.
nparties	Number of parties; defaults to 5; maximum allowable: 10.
nvotes	Number of votes per voter; defaults to 1. Can also take on special values 0 (which then is internally replaced by the district magnitude) and -1 (which is then internally replaced by 1 fewer vote than the district magnitude).
M	District magnitude; defaults to 5.
rank_cand	Boolean: should candidates be ranked on the party list? Defaults to TRUE.
strategic	Boolean: do parties and voters behave strategically? Defaults to TRUE.
strategic_error	Numeric probability with which strategic actors fail to choose the optimal alternative.
who_ranks	Character actor who arranges party lists, one of parties, voters,none; defaults to parties.
gamma_val	Numeric weight assigned to the valence component of voters' utility function.
gamma_rank	Numeric weight assigned to the candidate ranking on the party list when computing the voter's utility.
elec_fun_name	Name of function implementing electoral system formula.
ballot_type	Character string indicating type of ballot, one of open,closed, or flexible; defaults to open.
primary	Boolean: should a primary election be conducted? Defaults to FALSE.
two_round	Boolean: should a second election round be conducted? Defaults to FALSE.
pool_level	Character level at which votes are pooled, one of party_list (or sub-party list),party, or candidate. Defaults to party_list
ranked_vote	Boolean: Do voters cast a ranked vote? Defaults to FALSE.
free_vote	Boolean: If voters can cast multiple votes, can the be for candidates in different parties? Defaults to FALSE.
max_cand	Numeric maximum number of candidates running in a party list; defaults to 0, which is internally interpreted as the district magnitude.
threshold	Numerical legal electoral threshold; defaults to 0 (i.e., no threshold).
lists_per_party	Integer allowed number of lists per party; defaults to 1.
seed	Random number generator seed; defaults to 123.
elec_results_only	Boolean: Should function return ancillary information on election, or just election results? Defaults to FALSE.
multiplier	Numeric factor by which to multiply the votes cast by voters with the same ideological position; defaults to 1.
system_name	Character name of electoral system used, one of 'AV', 'BC', 'STV', 'MNTV', 'LV', 'PR', or 'SMDP'
...	Additional arguments passed to elec_fun_name.

Value

data.frame with the following variables (if elec_results_only=FALSE, otherwise, data.frame with candidate id's, positions, valences, votes obtained, and whether they won a seat or not):

gamma_val

See Usage above

epsilon

Maximum acceptable ideological distance used in voters' utility function

hetero

Measure of elected candidate heterogeneity

pers

Average valence of elected candidates

lsq

Least Squares measure of disproportionality

enp_v

Effective number of electoral parties

enp_s

Effective number of legislative parties

avg_dist

Average distance between elected candidates and voters

var_elect

Variance of ideological positions of elected candidates

avg_vote_util

Average utility of voters w.r.t. candidates they voted for

avg_elect_util

Average utility of voters w.r.t. elected candidates

sample_parties

Parties that initially could have entered the election

ran_parties

Parties that decided to enter the election

Examples

# Simulate a PR (D'Hondt) election with 3 parties, 5 candidates per party,
# 100 voters, and a district magnitude of 2, allowing for strategic voting

simulate_election(parties = c(-1, 0, 1),
                  nvoters = 100,
                  M = 2,
                  strategic = TRUE,
                  elec_fun_name = "dhondt",
                  system_name = "PR")

i3pack documentation built on June 8, 2025, 11:43 a.m.