In addition to being able to read real world voting data, VoteKit also has the ability to generate ballots using different models. This is useful when you want to run experiments or just play around with some data. We make no claims that these models accurately predict real voting behavior.
+Models listed below generate ballots by using the ballot simplex. This means we take a draw from the Dirichlet distribution, which gives us a probability distribution on full, linear rankings. We then generate ballots according to this distribution.
+The Impartial Culture model has \(\alpha = \infty\). As discussed in ballot simplex, this is not actually a valid parameter for the Dirichlet distribution, so instead VoteKit sets \(\alpha = 10^{20}\). This means that the point drawn from the ballot simplex has a very high probability of being in the center, which means it gives uniform probability to each linear ranking.
+The Impartial Anonymous Culture model has \(\alpha = 1\). This means that the point is uniformly drawn from the ballot simplex. This does not mean we have a uniform distribution on rankings; rather, we have a uniform chance of choosing any distribution on rankings.
+The name-Plackett-Luce model (n-PL) samples ranked ballots as follows. Assume there are \(n\) blocs of voters. Within a bloc, say bloc \(A\), voters have \(n\) preference intervals, one for each slate of candidates. A bloc also has a fixed \(n\)-tuple of cohesion parameters \(\pi_A = (\pi_{AA}, \pi_{AB},\dots)\); we require that \(\sum_B \pi_{AB}=1\). To generate a ballot for a voter in bloc \(A\), each preference interval \(I_B\) is rescaled by the corresponding cohesion parameter \(\pi_{AB}\), and then concatenated to create one preference interval. +Voters then sample without replacement from the combined preference interval.
+The name-Bradley-Terry model (n-BT) samples ranked ballots as follows. Assume there are \(n\) blocs of voters. Within a bloc, say bloc \(A\), voters have \(n\) preference intervals, one for each slate of candidates. A bloc also has a fixed \(n\)-tuple of cohesion parameters \(\pi_A = (\pi_{AA}, \pi_{AB},\dots)\); we require that \(\sum_B \pi_{AB}=1\). To generate a ballot for a voter in bloc \(A\), each preference interval \(I_B\) is rescaled by the corresponding cohesion parameter \(\pi_{AB}\), and then concatenated to create one preference interval. +Voters then sample ballots proportional to pairwise probabilities of candidates. That is, the probability that the ballot \(C_1>C_2>C_3\) is sampled is proprotional to \(P(C_1>C_2)P(C_2>C_3)P(C_1>C_3)\), where these pairwise probabilities are given by \(P(C_1>C_2) = C_1/(C_1+C_2)\). +Here \(C_i\) denotes the length of \(C_i\)'s share of the combined preference interval.
+The name-Cumulative model (n-C) samples ranked ballots as follows. Assume there are \(n\) blocs of voters. Within a bloc, say bloc \(A\), voters have \(n\) preference intervals, one for each slate of candidates. A bloc also has a fixed \(n\)-tuple of cohesion parameters \(\pi_A = (\pi_{AA}, \pi_{AB},\dots)\); we require that \(\sum_B \pi_{AB}=1\). To generate a ballot for a voter in bloc \(A\), each preference interval \(I_B\) is rescaled by the corresponding cohesion parameter \(\pi_{AB}\), and then concatenated to create one preference interval. To generate a ballot, voters sample with replacement from the combined interval as many times as determined by the length of the desired ballot.
+The slate-Plackett-Luce model (s-PL) samples ranked ballots as follows. Assume there are \(n\) blocs of voters. Within a bloc, say bloc \(A\), voters have \(n\) preference intervals, one for each slate of candidates. A bloc also has a fixed \(n\)-tuple of cohesion parameters \(\pi_A = (\pi_{AA}, \pi_{AB},\dots)\); we require that \(\sum_B \pi_{AB}=1\). Now the cohesion parameters play a different role than in the name models above. For s-PL, \(\pi_{AB}\) gives the probability that we put a \(B\) candidate in each position on the ballot. If we have already exhausted the number of \(B\) candidates, we remove \(\pi_{AB}\) and renormalize. Once we have a ranking of the slates on the ballot, we fill in candidate ordering by sampling without replacement from each individual preference interval (we do not concatenate them!).
+The slate-Bradley-Terry model (s-BT) samples ranked ballots as follows. We assume there are 2 blocs of voters. Within a bloc, say bloc \(A\), voters have 2 preference intervals, one for each slate of candidates. A bloc also has a fixed tuple of cohesion parameters \(\pi_A = (\pi_A, 1-\pi_A)\). Now the cohesion parameters play a different role than in the name models above. For s-BT, we again start by filling out a ballot with bloc labels only. Now, the probability that we sample the ballot \(A>A>B\) is proportional to \(\pi_A^2\); just like name-Bradley-Terry, we are computing pairwise comparisons. In \(A>A>B\), slate \(A\) must beat slate \(B\) twice. As another example, the probability of \(A>B>A\) is proportional to \(\pi_A(1-\pi_A)\). Once we have a ranking of the slates on the ballot, we fill in candidate ordering by sampling without replacement from each individual preference interval (we do not concatenate them!).
+The Alternating-Crossover model (AC) samples ranked ballots as follows. It assumes there are only two blocs. Within a bloc, voters either vote with the bloc, or they alternate. The proportion of such voters is determined by the cohesion parameter. If a voter votes with the bloc, they list all of their bloc's candidates above the other bloc's. If a voter alternates, they list an opposing candidate first, and then alternate between their bloc and the opposing until they run out of one set of candidates. In either case, the order of candidates is determined by a PL model.
+The AC model can generate incomplete ballots if there are a different number of candidates in each bloc.
+The AC model can be initialized from a set of preference intervals, along with which candidates belong to which bloc and a set of cohesion parameters.
+The AC model only works with two blocs.
+The AC model also requires information about what proportion of voters belong to each bloc.
+The Cambridge-Sampler (CS) samples ranked ballots as follows. Assume there is a majority and a minority bloc. If a voter votes with their bloc, they rank a bloc candidate first. If they vote against their bloc, they rank an opposing bloc candidate first. The proportion of such voters is determined by the cohesion parameter. Once a first entry is recorded, the CS samples a ballot type from historical Cambridge, MA election data. That is, if a voter puts a majorrity candidate first, the rest of their ballot type is sampled in proportion to the number of historical ballots that started with a majority candidate. Once a ballot type is determined, the order of candidates is determined by a PL model.
+Let's do an example. I am a voter in the majority bloc. I flip a coin weighted by the cohesion parameter, and it comes up tails. My ballot type will start with a minority candidate \(m\). The CS samples historical ballots that also started with \(m\), and tells me my ballot type is \(mmM\); two minority candidates, then a majority. Finally, CS uses a PL model to determine which minority/majority candidates go in the slots.
+CS can generate incomplete ballots since it uses historical data.
+The CS model can be initialized from a set of preference intervals, along with which candidates belong to which bloc and a set of cohesion parameters.
+The CS model only works with two blocs if you use the Cambridge data.
+The CS model also requires information about what proportion of voters belong to each bloc.
+You can give the CS model other historical election data to use.
+The 1-D Spatial model samples ranked ballots as follows. First, it assigns each candidate a position on the real number line according to a normal distribution. Then, it does the same with each voter. Finally, a voter's ranking is determined by their distance from each candidate.
+The 1-D Spatial model only generates full ballots.
+The 1-D Spatial model can be initialized from a list of candidates.
+The Earthmover distance is a measure of how far apart two distributions are over a given metric space. In our case, the metric space is the BallotGraph endowed with the shortes path metric. We then consider a PreferenceProfile to be a distribution that assigns the number of times a ballot was cast to a node of the BallotGraph. Informally, the Earthmover distance is the minimum cost of moving the "dirt" piled on the nodes by the first profile to the second profile given the distance it must travel.
The \(L_p\) distance is a metric parameterized by \(p\in (0,\infty]\). It is computed as \(d(P_1,P_2) = \left(\sum |P_1(b)-P_2(b)|^p\right)^{1/p}\), where the sum is indexed over all possible ballots, and \(P_i(b)\) denotes the number of times that ballot was cast.
+
+An STV election stands for single transferable vote. Voters cast ranked choice ballots. A threshold is set; if a candidate crosses the threshold, they are elected. The threshold defaults to the Droop quota. We also enable functionality for the Hare quota.
+In the first round, the first place votes for each candidate are tallied. If a candidate crosses the threshold, they are elected. Any surplus votes are distributed amongst the other candidates according to a transfer rule. If another candidate crosses the threshold, they are elected. If no candidate does, the candidate with the least first place votes is eliminated, and their ballots are redistributed according to the transfer rule. This repeats until all seats are filled.
+An STV election can use either the Droop or Hare quota.
+The current transfer methods are stored in the elections module.
+If there is a tiebreak needed, STV defaults to a random tiebreak. Other methods of tiebreak are given in the tie_broken_ranking function of the utils module.
+A preference interval stores information about a voter's preferences for candidates. We visualize this, unsurprisingly, as an interval. We take the interval \([0,1]\) and divide it into pieces, where each piece is proportional to the voter's preference for a particular candidate. If we have two candidates \(A,B\), we fix an order of our interval and say that the first piece will denote our preference for \(A,\) and the second for \(B\). As an abuse of notaton, one could write \((A,B)\), where we let \(A\) represent the candidate and the length of the interval. For example, if a voter likes candidate \(A\) a lot more than \(B\), they might have the preference interval \((0.9, 0.1)\). This can be extended to any number of candidates, as long as each entry is non-negative and the total of the entries is 1.
+We have not said how this preference interval actually gets translated into a ranked ballot for a particular voter. That we leave up to the ballot generator models, like the Plackett-Luce model.
+It should be remarked that there is a difference, at least to VoteKit, between the intervals \((0.9,0.1,0.0)\) and \((0.9,0.1)\). While both say there is no preference for a third candidate, if the latter interval is fed into VoteKit, that third candidate will never appear on a generated ballot. If we feed it the former interval, the third candidate will always appear at the bottom of the ballot.
+
VoteKit provides an option, from_params, which allows you to randomly generate preference intervals. For more on how this is done, see the page on Simplices.
+ + + + + + + + + + + + + +There is a unique correspondence between preference intervals and points in the candidate simplex. +This will be easiest to visualize with three candidates; let's call them \(A,B,C\). Our candidate simplex is a triangle, with each vertex representing one of the candidates. +If a point on the simplex is close to vertex \(A\), that means the point represents a preference interval with strong preference for \(A\) (likewise for \(B\) or \(C\)).
+
More formally, we have vectors \(e_A = (1,0,0), e_B = (0,1,0), e_C = (0,0,1)\). Each point on the triangle is a vector \((a,b,c)\) where \(a+b+c=1\) and \(a,b,c\ge 0\). That is, each point is a convex combination of the vectors \(e_A, e_B,e_C\). The value of \(a\) denotes someone's "preference" for \(A\). Thus, a point in the candidate simplex is precisely a preference interval for the candidates!
+The candidate simplex extends to an arbitrary number of candidates.
+The ballot simplex is the same thing as the candidate simplex, except now the vertices of the simplex represent full linear rankings.
+So in the case of 3 candidates, we have \(3!=6\) vertices, one for each permutation of the ranking \(A>B>C\).
+A point in the ballot simplex represents a probability distribution over these full linear rankings.
+This is much harder to visualize since we're stuck in 3 dimensions!
+
Read about the BallotSimplex object.
+Throughout VoteKit, it will be useful to be able to sample from the candidate simplex (if we want to generate preference intervals) or the ballot simplex (if we want a distribution on rankings). How will we sample from the simplex? The Dirichlet distribution!
+In what follows, we will presume we are discussing the candidate simplex, but it all applies to the ballot simplex as well. The Dirichlet distribution is a probability distribution on the simplex. We parameterize it with a value \(\alpha \in (0,\infty)\). +As \(\alpha\to \infty\), the mass of the distribution moves to the center of the simplex. This means we are more likely to sample preference intervals that have equal support for all candidates. As \(\alpha\to 0\), the mass moves to the vertices. This means we are more likely to sample preference intervals that have strong support for one candidate. +When \(\alpha=1\), all bets are off. In this regime, we have no knowledge of which candidates are likely to receive support.
+The value \(\alpha\) is never allowed to be 0 or \(\infty\), so VoteKit uses an arbitrary large number (\(10^{20}\)) and an arbitrary small number \((10^{-10})\). When members of MGGG have done experiments for studies, they have taken \(\alpha = 1/2\) to be small and \(\alpha = 2\) to be big.
+
When there are multiple blocs, or types, of voters, we utilize cohesion parameters to measure how much voters prefer candidates from their own bloc versus the opposing blocs. In our name models, like name_PlackettLuce or name_BradleyTerry, the cohesion parameters operate as follows. Suppose there are two blocs of voters, \(X,Y\). We assume that voters from the \(X\) bloc have some underlying preference interval \(I_{XX}\) for candidates within their bloc, and a different underlying preference interval \(I_{XY}\) for the candidates in the opposing bloc. In order to construct one preference interval for \(X\) voters, we take \(I_{XX}\) and scale it by \(\pi_X\), then we take \(I_{XY}\) and scale it by \(1-\pi_X\), and finally we concatenate the two. As a concrete example, if \(\pi_X = .75\), this means that 3/4 of the preference interval for \(X\) voters is taken up by candidates from the \(X\) bloc, and the other 1/4 by \(Y\) candidates.
In our slate models, like slate_PlackettLuce, the cohesion parameter is used to determine the probability of sampling a particular slate at each position in the ballot. How exactly this is done depends on the model. Then candidate names are filled in afterwards by sampling without replacement from each preference interval.
When there are multiple blocs of voters, we need more than one \(\alpha\) value for the Dirichlet distribution. Suppose there are two blocs of voters, \(X,Y\). Then we need four values, \(\alpha_{XX}, \alpha_{XY}, \alpha_{YX}, \alpha_{YY}\). The value \(\alpha_{XX}\) determines what kind of preferences \(X\) voters will have for \(X\) candidates. The value \(\alpha_{XY}\) determines what kind of preferences \(X\) voters have for \(Y\) candidates. We sample preference intervals from the candidate simplex using these \(\alpha\) values, and then use cohesion parameters to combine them into a single interval, one for each bloc. This is how from_params initializes different ballot generator models.
+ + + + + + + + + + + + + +Ballot
+
+
+¶Ballot class, contains ranking and assigned weight.
+Attributes
+ranking
+: tuple of candidate ranking. Entry \(i\) of the tuple is a frozenset of candidates ranked
+ in position \(i\).
weight
+: (Fraction) weight assigned to a given a ballot. Defaults to 1.
voter_set
+: optional set of voters who cast a given a ballot.
id
+: optional ballot id.
src/votekit/ballot.py8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 | |
PreferenceInterval
+
+
+¶PreferenceInterval class, contains preference for individual candidates stored as relative +share of the interval [0,1].
+Attributes
+interval
+: dictionary (candidate, support). A dictionary representing the given PreferenceInterval.
+ The keys are candidate names, and the values are floats representing that candidates
+ share of the interval. Does not have to sum to one, the init method will renormalize.
candidates
+: frozenset. A frozenset of candidates (with zero and non-zero support)
non_zero_cands
+: frozenset. A frozenset of candidates with non-zero support.
zero_cands
+: frozenset. A frozenset of candidates with zero support.
Methods
+from_dirichlet
+: sample a PreferenceInterval from the Dirichlet distribution on the candidate simplex.
normalize
+: normalize the support values of the PreferenceInterval to sum to 1.
remove_zero_support_cands
+: remove candidates with zero support from the interval and store them in the attribute
+ zero_cands.
src/votekit/pref_interval.py46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 | |
from_dirichlet(candidates, alpha)
+
+
+ classmethod
+
+
+¶Samples a PreferenceInterval from the Dirichlet distribution on the candidate simplex. +Alpha tends to 0 is strong support, alpha tends to infinity is uniform support, alpha = 1 +is all bets are off.
+ +src/votekit/pref_interval.py92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 | |
combine_preference_intervals(intervals, proportions)
+
+¶Combine a list of preference intervals given a list of proportions used to reweight each
+interval.
+Arguments
+intervals
+: list. A list of PreferenceInterval objects to combine.
proportions
+: list. A list of floats used to reweight the PreferenceInterval objects. Proportion \(i\) will
+reweight interval \(i\).
src/votekit/pref_interval.py6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 | |
PreferenceProfile
+
+
+¶
+ Bases: BaseModel
PreferenceProfile class, contains ballots and candidates for a given election.
+Attributes
+ballots
+: list of Ballot objects.
candidates
+: list of candidates.
Methods
+ +src/votekit/pref_profile.py11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 + 23 + 24 + 25 + 26 + 27 + 28 + 29 + 30 + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 | |
__add__(other)
+
+¶Add two PreferenceProfiles by combining their ballot lists.
+ +src/votekit/pref_profile.py307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 | |
condense_ballots()
+
+¶Groups ballots by rankings and updates weights.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile object with condensed ballot list. + |
+
src/votekit/pref_profile.py251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 | |
get_ballots()
+
+¶Returns:
+| Type | +Description | +
|---|---|
+ list[Ballot]
+ |
+
+
+
+ List of ballots. + |
+
src/votekit/pref_profile.py36 +37 +38 +39 +40 +41 | |
get_candidates(received_votes=True)
+
+¶Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
received_votes |
+
+ Optional[bool]
+ |
+
+
+
+ If True, only return candidates that received votes. Defaults + to True. + |
+
+ True
+ |
+
Returns: + List of candidates.
+ +src/votekit/pref_profile.py43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 | |
head(n, sort_by_weight=True, percents=False, totals=False)
+
+¶Displays top-n ballots in profile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
n |
+
+ int
+ |
+
+
+
+ Number of ballots to view. + |
+ + required + | +
sort_by_weight |
+
+ Optional[bool]
+ |
+
+
+
+ If True, rank ballot from most to least votes. Defaults to True. + |
+
+ True
+ |
+
percents |
+
+ Optional[bool]
+ |
+
+
+
+ If True, show voter share for a given ballot. + |
+
+ False
+ |
+
totals |
+
+ Optional[bool]
+ |
+
+
+
+ If True, show total values for Percent and Weight. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ DataFrame
+ |
+
+
+
+ A dataframe with top-n ballots. + |
+
src/votekit/pref_profile.py151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 | |
num_ballots()
+
+¶Counts number of ballots based on assigned weight.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ Fraction
+ |
+
+
+
+ Number of ballots cast. + |
+
src/votekit/pref_profile.py62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 | |
tail(n, sort_by_weight=True, percents=False, totals=False)
+
+¶Displays bottom-n ballots in profile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
n |
+
+ int
+ |
+
+
+
+ Number of ballots to view. + |
+ + required + | +
sort_by_weight |
+
+ Optional[bool]
+ |
+
+
+
+ If True, rank ballot from least to most votes. Defaults to True. + |
+
+ True
+ |
+
percents |
+
+ Optional[bool]
+ |
+
+
+
+ If True, show voter share for a given ballot. + |
+
+ False
+ |
+
totals |
+
+ Optional[bool]
+ |
+
+
+
+ If True, show total values for Percent and Weight. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ DataFrame
+ |
+
+
+
+ A data frame with bottom-n ballots. + |
+
src/votekit/pref_profile.py190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 | |
to_csv(fpath)
+
+¶Saves PreferenceProfile to CSV.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
fpath |
+
+ str
+ |
+
+
+
+ Path to the saved csv. + |
+ + required + | +
src/votekit/pref_profile.py103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 | |
to_dict(standardize=False)
+
+¶Converts to dictionary with keys = rankings and values = corresponding total weights.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
standardize |
+
+ Boolean
+ |
+
+
+
+ If True, divides the weight of each ballot + by the total weight. Defaults to False. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ A dictionary with ranking (keys) and corresponding total weights (values). + |
+
src/votekit/pref_profile.py75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 | |
ElectionState
+
+
+¶
+ Bases: BaseModel
Class for storing information on each round of an election and the final outcome.
+Attributes
+curr_round
+: current round number. Defaults to 0.
elected
+: list of candidates who pass a threshold to win.
eliminated_cands
+: list of candidates who were eliminated.
remaining
+: list of candidates who are still in the running.
profile
+: an instance of a PreferenceProfile object.
previous
+: an instance of ElectionState representing the previous round.
Methods
+ +src/votekit/election_state.py13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 + 23 + 24 + 25 + 26 + 27 + 28 + 29 + 30 + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 | |
changed_rankings()
+
+¶Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ A dictionary with keys = candidate(s) who changed ranking from previous round and values = a tuple of (previous rank, new rank). + |
+
src/votekit/election_state.py116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 | |
eliminated()
+
+¶Returns:
+| Type | +Description | +
|---|---|
+ list[set[str]]
+ |
+
+
+
+ A list of eliminated candidates ordered from current round to first round. + |
+
src/votekit/election_state.py60 +61 +62 +63 +64 +65 +66 +67 +68 | |
get_scores(round=curr_round)
+
+¶Returns a dictionary of the candidate scores for the inputted round. +Defaults to the last round
+ +src/votekit/election_state.py103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 | |
rankings()
+
+¶Returns:
+| Type | +Description | +
|---|---|
+ list[set[str]]
+ |
+
+
+
+ List of all candidates in order of their ranking after each round, first the winners, then the eliminated candidates. + |
+
src/votekit/election_state.py70 +71 +72 +73 +74 +75 +76 +77 +78 +79 | |
round_outcome(round)
+
+¶Finds the outcome of a given round.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
round |
+
+ int
+ |
+
+
+
+ Round number. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ A dictionary with elected and eliminated candidates. + |
+
src/votekit/election_state.py81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 | |
status()
+
+¶Returns:
+| Type | +Description | +
|---|---|
+ DataFrame
+ |
+
+
+
+ Data frame displaying candidate, status (elected, eliminated, +remaining), and the round their status updated. + |
+
src/votekit/election_state.py137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 | |
to_dict(keep=[])
+
+¶Returns election results as a dictionary.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
keep |
+
+ list
+ |
+
+
+
+ List of information to store in dictionary, should be subset of +"elected", "eliminated", "remaining", "ranking". Defaults to empty list, +which stores all information. + |
+
+ []
+ |
+
src/votekit/election_state.py170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 | |
to_json(file_path, keep=[])
+
+¶Saves election state object as a JSON file:
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
keep |
+
+ list
+ |
+
+
+
+ List of information to store in dictionary, should be subset of +"elected", "eliminated", "remaining", "ranking". Defaults to empty list, +which stores all information. + |
+
+ []
+ |
+
src/votekit/election_state.py203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 | |
winners()
+
+¶Returns:
+| Type | +Description | +
|---|---|
+ list[set[str]]
+ |
+
+
+
+ A list of elected candidates ordered from first round to current round. + |
+
src/votekit/election_state.py50 +51 +52 +53 +54 +55 +56 +57 +58 | |
BallotGraph
+
+
+¶
+ Bases: Graph
Class to build ballot graphs.
+Attributes
+source
+: data to create graph from, either PreferenceProfile object, number of
+ candidates, or list of candidates.
allow_partial
+: if True, builds graph using all possible ballots,
+ if False, only uses total linear ordered ballots.
+ If building from a PreferenceProfile, defaults to True.
fix_short
+: if True, auto completes ballots of length n-1 to n.
Methods
+ +src/votekit/graphs/ballot_graph.py14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 + 23 + 24 + 25 + 26 + 27 + 28 + 29 + 30 + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 | |
build_graph(n)
+
+¶Builds graph of all possible ballots given a number of candiates.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
n |
+
+ int
+ |
+
+
+
+ Number of candidates in an election. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Graph
+ |
+
+
+
+ A networkx graph. + |
+
src/votekit/graphs/ballot_graph.py94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 | |
draw(to_display=all_nodes, neighborhoods=[], show_cast=False, labels=False)
+
+¶Visualize the graph.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
to_display |
+
+ Callable
+ |
+
+
+
+ A boolean function that takes the graph and a node as input, +returns True if you want that node displayed. Defaults to showing all nodes. + |
+
+ all_nodes
+ |
+
neighborhoods |
+
+ Optional[list[tuple]]
+ |
+
+
+
+ A list of neighborhoods to display, given as tuple (node, radius). + (ex. (n,1) gives all nodes within one step of n). + |
+
+ []
+ |
+
show_cast |
+
+ Optional[bool]
+ |
+
+
+
+ If True, show only nodes with "cast" attribute = True. + If False, show all nodes. + |
+
+ False
+ |
+
labels |
+
+ Optional[bool]
+ |
+
+
+
+ If True, labels nodes with candidate names and vote totals. + |
+
+ False
+ |
+
src/votekit/graphs/ballot_graph.py267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 | |
fix_short_ballot(ballot, candidates)
+
+¶Adds missing candidates to a short ballot.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ballot |
+
+ list
+ |
+
+
+
+ A list of candidates on the ballot. + |
+ + required + | +
candidates |
+
+ list
+ |
+
+
+
+ A list of all candidates. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list
+ |
+
+
+
+ A new list with the missing candidates added to the end of the ballot. + |
+
src/votekit/graphs/ballot_graph.py190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 | |
from_profile(profile, fix_short=True)
+
+¶Updates existing graph based on cast ballots from a PreferenceProfile, +or creates graph based on PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile assigned to graph. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Graph
+ |
+
+
+
+ Graph based on PreferenceProfile, 'cast' node attribute indicates + ballots cast in PreferenceProfile. + |
+
src/votekit/graphs/ballot_graph.py143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 | |
label_cands(candidates, to_display=all_nodes)
+
+¶Assigns candidate labels to ballot graph for plotting.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
candidates |
+
+ list
+ |
+
+
+
+ A list of candidates. + |
+ + required + | +
to_display |
+
+ Callable
+ |
+
+
+
+ A Boolean callable that takes in a graph and node, + returns True if node should be displayed. + |
+
+ all_nodes
+ |
+
src/votekit/graphs/ballot_graph.py206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 | |
label_weights(to_display=all_nodes)
+
+¶Assigns weight labels to ballot graph for plotting. +Only shows weight if non-zero.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
to_display |
+
+ Callable
+ |
+
+
+
+ A Boolean callable that takes in a graph and node, + returns True if node should be displayed. + |
+
+ all_nodes
+ |
+
src/votekit/graphs/ballot_graph.py234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 | |
PairwiseComparisonGraph
+
+
+¶
+ Bases: Graph
Class to construct the pairwise comparison graph where nodes are candidates +and edges are pairwise preferences.
+Attributes
+profile
+: PreferenceProfile to construct graph from.
ballot_length
+: (optional) max length of ballot, defaults to longest possible ballot length.
Methods
+ +src/votekit/graphs/pairwise_comparison_graph.py12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 + 23 + 24 + 25 + 26 + 27 + 28 + 29 + 30 + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 | |
ballot_fill(profile, ballot_length)
+
+¶Fills incomplete ballots for pairwise comparison.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile to fill. + |
+ + required + | +
ballot_length |
+
+ int
+ |
+
+
+
+ How long a ballot is. + |
+ + required + | +
Returns:
+| Name | Type | +Description | +
|---|---|---|
PreferenceProfile |
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile with incomplete +ballots filled in. + |
+
src/votekit/graphs/pairwise_comparison_graph.py38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 | |
build_graph()
+
+¶Builds the networkx pairwise comparison graph.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ DiGraph
+ |
+
+
+
+ The networkx digraph representing the pairwise comparison graph. + |
+
src/votekit/graphs/pairwise_comparison_graph.py129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 | |
compute_pairwise_dict()
+
+¶Constructs dictionary where keys are tuples (cand_a, cand_b) containing +two candidates and values is the frequency cand_a is preferred to +cand_b.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ A dictionary with keys = (cand_a, cand_b) and values = frequency cand_a is preferred +to cand_b. + |
+
src/votekit/graphs/pairwise_comparison_graph.py97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 | |
dominating_tiers()
+
+
+ cached
+
+
+¶Finds dominating tiers within an election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ list[set]
+ |
+
+
+
+ A list of dominating tiers. + |
+
src/votekit/graphs/pairwise_comparison_graph.py209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 | |
draw(outfile=None)
+
+¶Draws pairwise comparison graph.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
outfile |
+
+ str
+ |
+
+
+
+ The filepath to save the graph. Defaults to not saving. + |
+
+ None
+ |
+
src/votekit/graphs/pairwise_comparison_graph.py142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 | |
get_condorcet_cycles()
+
+
+ cached
+
+
+¶Returns a list of condorcet cycles in the graph, which we define as any cycle of length + greater than 2.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ list
+ |
+
+
+
+ List of condorcet cycles sorted by length. + |
+
src/votekit/graphs/pairwise_comparison_graph.py251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 | |
get_condorcet_winner()
+
+¶Returns the condorcet winner. Raises a ValueError if no condorcet winner.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ str
+ |
+
+
+
+ The condorcet winner. + |
+
src/votekit/graphs/pairwise_comparison_graph.py195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 | |
has_condorcet_cycles()
+
+¶Checks if graph has any condorcet cycles, which we define as any cycle of length + greater than 2 in the graph.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ True if condorcet cycles exists, False otherwise. + |
+
src/votekit/graphs/pairwise_comparison_graph.py236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 | |
has_condorcet_winner()
+
+¶Checks if graph has a condorcet winner.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ True if condorcet winner exists, False otherwise. + |
+
src/votekit/graphs/pairwise_comparison_graph.py183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 | |
head2head_count(cand1, cand2)
+
+¶Counts head to head comparisons between two candidates. Note that the given order +of the candidates matters here.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
cand1 |
+
+ str
+ |
+
+
+
+ The first candidate to compare. + |
+ + required + | +
cand2 |
+
+ str
+ |
+
+
+
+ The second candidate to compare. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Fraction
+ |
+
+
+
+ A count of the number of times cand1 is preferred to cand2. + |
+
src/votekit/graphs/pairwise_comparison_graph.py73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 | |
load_csv(fpath, rank_cols=[], *, weight_col=None, delimiter=None, id_col=None)
+
+¶Given a file path, loads cast vote records (cvr) with ranks as columns and voters as rows. +Empty cells are treated as None.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
fpath |
+
+ str
+ |
+
+
+
+ Path to cvr file. + |
+ + required + | +
rank_cols |
+
+ list[int]
+ |
+
+
+
+ List of column indexes that contain rankings. Indexing starts from 0, + in order from top to bottom rank. + Default implies that all columns contain rankings. + |
+
+ []
+ |
+
weight_col |
+
+ Optional[int]
+ |
+
+
+
+ The column position for ballot weights. + |
+
+ None
+ |
+
delimiter |
+
+ Optional[str]
+ |
+
+
+
+ The character that breaks up rows. + |
+
+ None
+ |
+
id_col |
+
+ Optional[int]
+ |
+
+
+
+ Index for the column with voter ids. + |
+
+ None
+ |
+
Raises:
+| Type | +Description | +
|---|---|
+ FileNotFoundError
+ |
+
+
+
+ If fpath is invalid. + |
+
+ EmptyDataError
+ |
+
+
+
+ If dataset is empty. + |
+
+ ValueError
+ |
+
+
+
+ If the voter id column has missing values. + |
+
+ DataError
+ |
+
+
+
+ If the voter id column has duplicate values. + |
+
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile that represents all the ballots in the election. + |
+
src/votekit/cvr_loaders.py12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 | |
load_scottish(fpath)
+
+¶Given a file path, loads cvr from format used for Scottish election data.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
fpath |
+
+ str
+ |
+
+
+
+ Path to cvr file. + |
+ + required + | +
Raises:
+| Type | +Description | +
|---|---|
+ FileNotFoundError
+ |
+
+
+
+ If fpath is invalid. + |
+
+ EmptyDataError
+ |
+
+
+
+ If dataset is empty. + |
+
+ DataError
+ |
+
+
+
+ If there is missing or incorrect metadata or candidate data. + |
+
Returns:
+| Type | +Description | +
|---|---|
+ tuple
+ |
+
+
+
+ A tuple (PreferenceProfile, seats) representing the election and the + number of seats in the election. + |
+
src/votekit/cvr_loaders.py90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 | |
BallotGenerator
+
+
+¶Base class for ballot generation models that use the candidate simplex +(e.g. Plackett-Luce, Bradley-Terry, etc.).
+Attributes
+candidates
+: list of candidates in the election.
cohesion_parameters
+: dictionary of dictionaries mapping of bloc to cohesion parameters.
+ (ex. {bloc_1: {bloc_1: .7, bloc_2: .2, bloc_3:.1}})
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
bloc_voter_prop
+: dictionary mapping of bloc to voter proportions (ex. {bloc: voter proportion}).
pref_intervals_by_bloc and bloc_voter_prop.Methods
+ +src/votekit/ballot_generator.py77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 | |
ballot_pool_to_profile(ballot_pool, candidates)
+
+
+ staticmethod
+
+
+¶Given a list of ballots and candidates, convert them into a PreferenceProfile.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ballot_pool |
+
+ list of tuple
+ |
+
+
+
+ A list of ballots, where each ballot is a tuple + of candidates indicating their ranking from top to bottom. + |
+ + required + | +
candidates |
+
+ list
+ |
+
+
+
+ A list of candidates. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile representing the ballots in the election. + |
+
src/votekit/ballot_generator.py278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 | |
from_params(slate_to_candidates, bloc_voter_prop, cohesion_parameters, alphas, **data)
+
+
+ classmethod
+
+
+¶Initializes a BallotGenerator by constructing a preference interval +from parameters; the prior parameters (if inputted) will be overwritten.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
slate_to_candidates |
+
+ dict
+ |
+
+
+
+ A mapping of blocs to candidates +(ex. {bloc: [candidate]}) + |
+ + required + | +
bloc_voter_prop |
+
+ dict
+ |
+
+
+
+ A mapping of the percentage of total voters + per bloc (ex. {bloc: 0.7}) + |
+ + required + | +
cohesion_parameters |
+
+ dict
+ |
+
+
+
+ Cohension factors for each bloc (ex. {bloc_1: {bloc_1: .9, + bloc_2:.1}) + |
+ + required + | +
alphas |
+
+ dict
+ |
+
+
+
+ Alpha for the Dirichlet distribution of each bloc + (ex. {bloc: {bloc: 1, opposing_bloc: 1/2}}). + |
+ + required + | +
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If the voter proportion for blocs don't sum to 1. + |
+
+ ValueError
+ |
+
+
+
+ Blocs are not the same. + |
+
Returns:
+| Type | +Description | +
|---|---|
+ BallotGenerator
+ |
+
+
+
+ Initialized ballot generator. + |
+
src/votekit/ballot_generator.py170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 | |
generate_profile(number_of_ballots, by_bloc=False)
+
+
+ abstractmethod
+
+
+¶Generates a PreferenceProfile.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
number_of_ballots |
+
+ int
+ |
+
+
+
+ Number of ballots to generate. + |
+ + required + | +
by_bloc |
+
+ bool
+ |
+
+
+
+ True if you want a tuple (pp_by_bloc, pp), which is a dictionary of + PreferenceProfiles with keys = blocs and the aggregated profile. + False if you want the aggregated profile. Defaults to False. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A generated |
+
src/votekit/ballot_generator.py246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 | |
BallotSimplex
+
+
+¶
+ Bases: BallotGenerator
Base class for ballot generation models that use the ballot simplex +(e.g. ImpartialCulture, ImpartialAnonymousCulture).
+Attributes
+alpha
+: (float) alpha parameter for ballot simplex. Defaults to None.
point
+: dictionary representing a point in the ballot simplex with candidate as
+ keys and electoral support as values. Defaults to None.
Point or alpha arguments must be included to initialize.
+Methods
+ +src/votekit/ballot_generator.py308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 | |
from_alpha(alpha, **data)
+
+
+ classmethod
+
+
+¶Initializes a Ballot Simplex model from an alpha value for the Dirichlet +distribution.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
alpha |
+
+ float
+ |
+
+
+
+ An alpha parameter for the Dirichlet distribution. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ BallotSimplex
+ |
+
+
+
+ Initialized from alpha. + |
+
src/votekit/ballot_generator.py362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 | |
from_point(point, **data)
+
+
+ classmethod
+
+
+¶Initializes a Ballot Simplex model from a point in the Dirichlet distribution.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
point |
+
+ dict
+ |
+
+
+
+ A mapping of candidate to candidate support. + |
+ + required + | +
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If the candidate support does not sum to 1. + |
+
Returns:
+| Type | +Description | +
|---|---|
+ BallotSimplex
+ |
+
+
+
+ Initialized from point. + |
+
src/votekit/ballot_generator.py342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 | |
generate_profile(number_of_ballots, by_bloc=False)
+
+¶Generates a PreferenceProfile from the ballot simplex.
+ +src/votekit/ballot_generator.py377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 | |
slate_PlackettLuce
+
+
+¶
+ Bases: BallotGenerator
Class for generating ballots using a slate-PlackettLuce model. +This model first samples a ballot type by flipping a cohesion parameter weighted coin. +It then fills out the ballot type via sampling with out replacement from the interval.
+Can be initialized with an interval or can be
+constructed with the Dirichlet distribution using the from_params method in the
+BallotGenerator class.
Attributes
+slate_to_candidates
+: dictionary mapping of slate to candidates (ex. {bloc: [candidate]}).
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
bloc_voter_prop
+: dictionary mapping of bloc to voter proportions (ex. {bloc: proportion}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
Methods
+See BallotGenerator base class
src/votekit/ballot_generator.py1480 +1481 +1482 +1483 +1484 +1485 +1486 +1487 +1488 +1489 +1490 +1491 +1492 +1493 +1494 +1495 +1496 +1497 +1498 +1499 +1500 +1501 +1502 +1503 +1504 +1505 +1506 +1507 +1508 +1509 +1510 +1511 +1512 +1513 +1514 +1515 +1516 +1517 +1518 +1519 +1520 +1521 +1522 +1523 +1524 +1525 +1526 +1527 +1528 +1529 +1530 +1531 +1532 +1533 +1534 +1535 +1536 +1537 +1538 +1539 +1540 +1541 +1542 +1543 +1544 +1545 +1546 +1547 +1548 +1549 +1550 +1551 +1552 +1553 +1554 +1555 +1556 +1557 +1558 +1559 +1560 +1561 +1562 +1563 +1564 +1565 +1566 +1567 +1568 +1569 +1570 +1571 +1572 +1573 +1574 +1575 +1576 +1577 +1578 +1579 +1580 +1581 +1582 +1583 +1584 +1585 +1586 +1587 +1588 +1589 +1590 +1591 +1592 | |
generate_profile(number_of_ballots, by_bloc=False)
+
+¶Args:
+number_of_ballots: The number of ballots to generate.
by_bloc: True if you want to return a dictionary of PreferenceProfiles by bloc.
+ False if you want the full, aggregated PreferenceProfile.
src/votekit/ballot_generator.py1514 +1515 +1516 +1517 +1518 +1519 +1520 +1521 +1522 +1523 +1524 +1525 +1526 +1527 +1528 +1529 +1530 +1531 +1532 +1533 +1534 +1535 +1536 +1537 +1538 +1539 +1540 +1541 +1542 +1543 +1544 +1545 +1546 +1547 +1548 +1549 +1550 +1551 +1552 +1553 +1554 +1555 +1556 +1557 +1558 +1559 +1560 +1561 +1562 +1563 +1564 +1565 +1566 +1567 +1568 +1569 +1570 +1571 +1572 +1573 +1574 +1575 +1576 +1577 +1578 +1579 +1580 +1581 +1582 +1583 +1584 +1585 +1586 +1587 +1588 +1589 +1590 +1591 +1592 | |
name_PlackettLuce
+
+
+¶
+ Bases: short_name_PlackettLuce
Class for generating full ballots with name-PlackettLuce. This model samples without
+replacement from a preference interval. Can be initialized with an interval or can be
+constructed with the Dirichlet distribution using the from_params method in the
+BallotGenerator class.
Attributes
+candidates
+: a list of candidates.
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
bloc_voter_prop
+: dictionary mapping of bloc to voter proportions (ex. {bloc: proportion}).
Methods
+See BallotGenerator base class
src/votekit/ballot_generator.py619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 | |
slate_BradleyTerry
+
+
+¶
+ Bases: BallotGenerator
Class for generating ballots using a slate-BradleyTerry model. It +presamples ballot types by checking all pairwise comparisons, then fills out candidate +ordering by sampling without replacement from preference intervals.
+Only works with 2 blocs at the moment.
+Can be initialized with an interval or can be
+constructed with the Dirichlet distribution using the from_params method in the
+BallotGenerator class.
Attributes
+slate_to_candidates
+: dictionary mapping of slate to candidates (ex. {bloc: [candidate]}).
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
bloc_voter_prop
+: dictionary mapping of bloc to voter proportions (ex. {bloc: proportion}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
Methods
+See BallotGenerator base class
src/votekit/ballot_generator.py1595 +1596 +1597 +1598 +1599 +1600 +1601 +1602 +1603 +1604 +1605 +1606 +1607 +1608 +1609 +1610 +1611 +1612 +1613 +1614 +1615 +1616 +1617 +1618 +1619 +1620 +1621 +1622 +1623 +1624 +1625 +1626 +1627 +1628 +1629 +1630 +1631 +1632 +1633 +1634 +1635 +1636 +1637 +1638 +1639 +1640 +1641 +1642 +1643 +1644 +1645 +1646 +1647 +1648 +1649 +1650 +1651 +1652 +1653 +1654 +1655 +1656 +1657 +1658 +1659 +1660 +1661 +1662 +1663 +1664 +1665 +1666 +1667 +1668 +1669 +1670 +1671 +1672 +1673 +1674 +1675 +1676 +1677 +1678 +1679 +1680 +1681 +1682 +1683 +1684 +1685 +1686 +1687 +1688 +1689 +1690 +1691 +1692 +1693 +1694 +1695 +1696 +1697 +1698 +1699 +1700 +1701 +1702 +1703 +1704 +1705 +1706 +1707 +1708 +1709 +1710 +1711 +1712 +1713 +1714 +1715 +1716 +1717 +1718 +1719 +1720 +1721 +1722 +1723 +1724 +1725 +1726 +1727 +1728 +1729 +1730 +1731 +1732 +1733 +1734 +1735 +1736 +1737 +1738 +1739 +1740 +1741 +1742 +1743 +1744 +1745 +1746 +1747 +1748 +1749 +1750 +1751 +1752 +1753 +1754 +1755 +1756 +1757 +1758 +1759 +1760 +1761 +1762 +1763 +1764 +1765 +1766 +1767 +1768 +1769 +1770 +1771 +1772 +1773 +1774 +1775 +1776 +1777 +1778 +1779 +1780 +1781 +1782 +1783 +1784 +1785 +1786 +1787 +1788 +1789 +1790 +1791 +1792 +1793 +1794 +1795 +1796 +1797 +1798 +1799 +1800 +1801 +1802 +1803 +1804 +1805 +1806 +1807 +1808 +1809 +1810 +1811 +1812 +1813 +1814 +1815 +1816 +1817 +1818 +1819 +1820 +1821 +1822 +1823 +1824 +1825 +1826 +1827 +1828 +1829 +1830 +1831 +1832 +1833 +1834 +1835 +1836 +1837 | |
generate_profile(number_of_ballots, by_bloc=False, deterministic=True)
+
+¶Args:
+number_of_ballots: The number of ballots to generate.
by_bloc: True if you want to return a dictionary of PreferenceProfiles by bloc.
+ False if you want the full, aggregated PreferenceProfile.
deterministic: True if you want to use the computed pdf for the slate-BT model,
+ False if you want to use MCMC approximation. Defaults to True.
src/votekit/ballot_generator.py1750 +1751 +1752 +1753 +1754 +1755 +1756 +1757 +1758 +1759 +1760 +1761 +1762 +1763 +1764 +1765 +1766 +1767 +1768 +1769 +1770 +1771 +1772 +1773 +1774 +1775 +1776 +1777 +1778 +1779 +1780 +1781 +1782 +1783 +1784 +1785 +1786 +1787 +1788 +1789 +1790 +1791 +1792 +1793 +1794 +1795 +1796 +1797 +1798 +1799 +1800 +1801 +1802 +1803 +1804 +1805 +1806 +1807 +1808 +1809 +1810 +1811 +1812 +1813 +1814 +1815 +1816 +1817 +1818 +1819 +1820 +1821 +1822 +1823 +1824 +1825 +1826 +1827 +1828 +1829 +1830 +1831 +1832 +1833 +1834 +1835 +1836 +1837 | |
name_BradleyTerry
+
+
+¶
+ Bases: BallotGenerator
Class for generating ballots using a name-BradleyTerry model. The probability of sampling
+the ranking \(X>Y>Z\) is proportional to \(P(X>Y)*P(X>Z)*P(Y>Z)\).
+These individual probabilities are based on the preference interval: \(P(X>Y) = x/(x+y)\).
+Can be initialized with an interval or can be constructed with the Dirichlet distribution using
+the from_params method in the BallotGenerator class.
Attributes
+candidates
+: a list of candidates.
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals or dictionary of PIs.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
bloc_voter_prop
+: dictionary mapping of slate to voter proportions (ex. {race: voter proportion}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
Methods
+See BallotGenerator base class.
src/votekit/ballot_generator.py663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 | |
generate_profile_MCMC(number_of_ballots, verbose=False, by_bloc=False)
+
+¶Sample from the BT distribution using Markov Chain Monte Carlo. number_of_ballots should
+be sufficiently large to allow for convergence of the chain.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
number_of_ballots |
+
+ int
+ |
+
+
+
+ Number of ballots to generate. + |
+ + required + | +
verbose |
+
+ bool
+ |
+
+
+
+ If True, print the acceptance ratio of the chain. Default + is False. + |
+
+ False
+ |
+
by_bloc |
+
+ bool
+ |
+
+
+
+ True if you want a tuple (pp_by_bloc, pp), which is a + dictionary of PreferenceProfiles with keys = blocs and the + aggregated profile. False if you want the aggregated profile. + Defaults to False. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Union[PreferenceProfile, Tuple]
+ |
+
+
+
+ Generated ballots as a PreferenceProfile or tuple (dict, PreferenceProfile). + |
+
src/votekit/ballot_generator.py906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 | |
AlternatingCrossover
+
+
+¶
+ Bases: BallotGenerator
Class for Alternating Crossover style of generating ballots. +AC assumes that voters either rank all of their own blocs candidates above the other bloc, +or the voters "crossover" and rank a candidate from the other bloc first, then alternate +between candidates from their own bloc and the opposing. +Should only be used when there are two blocs.
+Can be initialized with an interval or can be
+constructed with the Dirichlet distribution using the from_params method in the
+BallotGenerator class.
Attributes
+pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
bloc_voter_prop
+: dictionary mapping of slate to voter proportions (ex. {bloc: voter proportion}).
slate_to_candidates
+: dictionary mapping of slate to candidates (ex. {bloc: [candidate1, candidate2]}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
Methods
+See BallotGenerator base class.
src/votekit/ballot_generator.py970 + 971 + 972 + 973 + 974 + 975 + 976 + 977 + 978 + 979 + 980 + 981 + 982 + 983 + 984 + 985 + 986 + 987 + 988 + 989 + 990 + 991 + 992 + 993 + 994 + 995 + 996 + 997 + 998 + 999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 +1023 +1024 +1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 +1067 +1068 +1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 | |
CambridgeSampler
+
+
+¶
+ Bases: BallotGenerator
Class for generating ballots based on historical RCV elections occurring +in Cambridge. Alternative election data can be used if specified. Assumes that there are two +blocs, a majority and a minority bloc, and determines this based on the bloc_voter_prop attr.
+Based on cohesion parameters, decides if a voter casts their top choice within their bloc +or in the opposing bloc. Then uses historical data; given their first choice, choose a +ballot type from the historical distribution.
+Attributes
+slate_to_candidates
+: dictionary mapping of slate to candidates (ex. {bloc: [candidate]}).
bloc_voter_prop
+: dictionary mapping of bloc to voter proportions (ex. {bloc: voter proportion}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
historical_majority
+: name of majority bloc in historical data, defaults to W for Cambridge.
historical_minority
+: name of minority bloc in historical data, defaults to C for Cambridge.
path
+: file path to an election data file to sample from. Defaults to Cambridge elections.
Methods
+See BallotGenerator base class.
src/votekit/ballot_generator.py1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 +1152 +1153 +1154 +1155 +1156 +1157 +1158 +1159 +1160 +1161 +1162 +1163 +1164 +1165 +1166 +1167 +1168 +1169 +1170 +1171 +1172 +1173 +1174 +1175 +1176 +1177 +1178 +1179 +1180 +1181 +1182 +1183 +1184 +1185 +1186 +1187 +1188 +1189 +1190 +1191 +1192 +1193 +1194 +1195 +1196 +1197 +1198 +1199 +1200 +1201 +1202 +1203 +1204 +1205 +1206 +1207 +1208 +1209 +1210 +1211 +1212 +1213 +1214 +1215 +1216 +1217 +1218 +1219 +1220 +1221 +1222 +1223 +1224 +1225 +1226 +1227 +1228 +1229 +1230 +1231 +1232 +1233 +1234 +1235 +1236 +1237 +1238 +1239 +1240 +1241 +1242 +1243 +1244 +1245 +1246 +1247 +1248 +1249 +1250 +1251 +1252 +1253 +1254 +1255 +1256 +1257 +1258 +1259 +1260 +1261 +1262 +1263 +1264 +1265 +1266 +1267 +1268 +1269 +1270 +1271 +1272 +1273 +1274 +1275 +1276 +1277 +1278 +1279 +1280 +1281 +1282 +1283 +1284 +1285 +1286 +1287 +1288 +1289 +1290 +1291 +1292 +1293 +1294 +1295 +1296 +1297 +1298 +1299 +1300 +1301 +1302 +1303 +1304 +1305 +1306 +1307 +1308 +1309 +1310 +1311 +1312 +1313 +1314 +1315 +1316 +1317 +1318 +1319 +1320 +1321 +1322 +1323 +1324 +1325 +1326 +1327 +1328 +1329 +1330 +1331 +1332 +1333 +1334 +1335 +1336 +1337 +1338 +1339 +1340 +1341 +1342 +1343 +1344 +1345 +1346 +1347 +1348 +1349 +1350 +1351 +1352 +1353 +1354 +1355 +1356 +1357 +1358 +1359 +1360 +1361 +1362 | |
OneDimSpatial
+
+
+¶
+ Bases: BallotGenerator
1-D spatial model for ballot generation. Assumes the candidates are normally distributed on +the real line. Then voters are also normally distributed, and vote based on Euclidean distance +to the candidates.
+Attributes
+candidates
+ : a list of candidates.
See BallotGenerator base class.
Methods
+See BallotGenerator base class.
src/votekit/ballot_generator.py1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 | |
ImpartialCulture
+
+
+¶
+ Bases: BallotSimplex
Impartial Culture model with an alpha value of 1e10 (should be infinity theoretically). +This model is uniform on all linear rankings.
+Attributes
+candidates
+: (list) a list of candidates
alpha
+: (float) alpha parameter for ballot simplex. Defaults to None.
point
+: dictionary representing a point in the ballot simplex with candidate as
+ keys and electoral support as values. Defaults to None.
Methods
+See BallotSimplex object.
Point or alpha arguments must be included to initialize. For details see
+BallotSimplex and BallotGenerator object.
src/votekit/ballot_generator.py416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 | |
ImpartialAnonymousCulture
+
+
+¶
+ Bases: BallotSimplex
Impartial Anonymous Culture model with an alpha value of 1. This model choose uniformly + from among all distributions on full linear rankings, and then draws according to the + chosen distribution.
+Attributes
+candidates
+: (list) a list of candidates
alpha
+: (float) alpha parameter for ballot simplex. Defaults to None.
point
+: dictionary representing a point in the ballot simplex with candidate as
+ keys and electoral support as values. Defaults to None.
Methods
+See BallotSimplex base class.
Point or alpha arguments must be included to initialize. For details see
+BallotSimplex and BallotGenerator object.
src/votekit/ballot_generator.py450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 | |
name_Cumulative
+
+
+¶
+ Bases: BallotGenerator
Class for generating cumulative ballots. This model samples with
+replacement from a combined preference interval and counts candidates with multiplicity.
+Can be initialized with an interval or can be constructed with the Dirichlet distribution
+using the from_params method in the BallotGenerator class.
Attributes
+candidates
+: a list of candidates.
pref_intervals_by_bloc
+: dictionary of dictionaries mapping of bloc to preference intervals.
+ (ex. {bloc_1: {bloc_1 : PI, bloc_2: PI}}).
cohesion_parameters
+: dictionary of dictionaries of cohesion parameters (ex. {bloc_1: {bloc_1:.7, bloc_2: .3}})
bloc_voter_prop
+: dictionary mapping of bloc to voter proportions (ex. {bloc: proportion}).
num_votes
+: the number of votes allowed per ballot.
Methods
+See BallotGenerator base class
src/votekit/ballot_generator.py1365 +1366 +1367 +1368 +1369 +1370 +1371 +1372 +1373 +1374 +1375 +1376 +1377 +1378 +1379 +1380 +1381 +1382 +1383 +1384 +1385 +1386 +1387 +1388 +1389 +1390 +1391 +1392 +1393 +1394 +1395 +1396 +1397 +1398 +1399 +1400 +1401 +1402 +1403 +1404 +1405 +1406 +1407 +1408 +1409 +1410 +1411 +1412 +1413 +1414 +1415 +1416 +1417 +1418 +1419 +1420 +1421 +1422 +1423 +1424 +1425 +1426 +1427 +1428 +1429 +1430 +1431 +1432 +1433 +1434 +1435 +1436 +1437 +1438 +1439 +1440 +1441 +1442 +1443 +1444 +1445 +1446 +1447 +1448 +1449 +1450 +1451 +1452 +1453 +1454 +1455 +1456 +1457 +1458 +1459 +1460 +1461 +1462 +1463 +1464 +1465 +1466 +1467 +1468 +1469 +1470 +1471 +1472 +1473 +1474 +1475 +1476 +1477 | |
generate_profile(number_of_ballots, by_bloc=False)
+
+¶Args:
+number_of_ballots: The number of ballots to generate.
by_bloc: True if you want to return a dictionary of PreferenceProfiles by bloc.
+ False if you want the full, aggregated PreferenceProfile.
src/votekit/ballot_generator.py1416 +1417 +1418 +1419 +1420 +1421 +1422 +1423 +1424 +1425 +1426 +1427 +1428 +1429 +1430 +1431 +1432 +1433 +1434 +1435 +1436 +1437 +1438 +1439 +1440 +1441 +1442 +1443 +1444 +1445 +1446 +1447 +1448 +1449 +1450 +1451 +1452 +1453 +1454 +1455 +1456 +1457 +1458 +1459 +1460 +1461 +1462 +1463 +1464 +1465 +1466 +1467 +1468 +1469 +1470 +1471 +1472 +1473 +1474 +1475 +1476 +1477 | |
Bloc
+
+
+¶
+ Bases: Election
Elects m candidates with the highest m-approval scores. The m-approval +score of a candidate is equal to the number of voters who rank this +candidate among their m top ranked candidates.
+Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 | |
run_election()
+
+
+ cached
+
+
+¶Runs complete Bloc election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object with results for a complete election. + |
+
src/votekit/elections/election_types.py397 +398 +399 +400 +401 +402 +403 +404 +405 +406 | |
run_step()
+
+¶Conducts a Limited election to elect m-candidates.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a Limited election. + |
+
src/votekit/elections/election_types.py380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 | |
Borda
+
+
+¶
+ Bases: Election
Positional voting system that assigns a decreasing number of points to
+candidates based on order and a score vector. The conventional score
+vector is \((n, n-1, \dots, 1)\), where \(n\) is the number of candidates.
+If a ballot is incomplete, the remaining points of the score vector
+are evenly distributed to the unlisted candidates (see borda_scores function in utils).
Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
score_vector
+: (optional) weights assigned to candidate ranking, should be a list of Fractions.
+ Defaults to \((n,n-1,\dots,1)\).
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py910 + 911 + 912 + 913 + 914 + 915 + 916 + 917 + 918 + 919 + 920 + 921 + 922 + 923 + 924 + 925 + 926 + 927 + 928 + 929 + 930 + 931 + 932 + 933 + 934 + 935 + 936 + 937 + 938 + 939 + 940 + 941 + 942 + 943 + 944 + 945 + 946 + 947 + 948 + 949 + 950 + 951 + 952 + 953 + 954 + 955 + 956 + 957 + 958 + 959 + 960 + 961 + 962 + 963 + 964 + 965 + 966 + 967 + 968 + 969 + 970 + 971 + 972 + 973 + 974 + 975 + 976 + 977 + 978 + 979 + 980 + 981 + 982 + 983 + 984 + 985 + 986 + 987 + 988 + 989 + 990 + 991 + 992 + 993 + 994 + 995 + 996 + 997 + 998 + 999 +1000 +1001 +1002 +1003 +1004 | |
run_election()
+
+
+ cached
+
+
+¶Simulates a complete Borda contest.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py995 + 996 + 997 + 998 + 999 +1000 +1001 +1002 +1003 +1004 | |
run_step()
+
+¶Simulates a complete Borda contest as Borda is not a round-by-round +system.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 | |
CondoBorda
+
+
+¶
+ Bases: Election
Elects candidates ordered by dominating set, but breaks ties +between candidates with Borda.
+Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 | |
run_election()
+
+
+ cached
+
+
+¶Simulates a complete Conda-Borda election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py808 +809 +810 +811 +812 +813 +814 +815 +816 +817 | |
run_step()
+
+¶Conducts a complete Conda-Borda election as it is not a round-by-round +system.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An |
+
src/votekit/elections/election_types.py772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 | |
Cumulative
+
+
+¶
+ Bases: HighestScore
Voting system where voters are allowed to vote for candidates with multiplicity. +Each ranking position should have one candidate, and every candidate ranked will receive +one point, i.e., the score vector is \((1,\dots,1)\). +Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py1154 +1155 +1156 +1157 +1158 +1159 +1160 +1161 +1162 +1163 +1164 +1165 +1166 +1167 +1168 +1169 +1170 +1171 +1172 +1173 +1174 +1175 +1176 +1177 +1178 +1179 +1180 +1181 +1182 +1183 +1184 +1185 +1186 +1187 +1188 +1189 +1190 +1191 +1192 +1193 +1194 +1195 +1196 +1197 +1198 +1199 +1200 +1201 | |
DominatingSets
+
+
+¶
+ Bases: Election
Finds tiers of candidates by dominating set, which is a set of candidates +such that every candidate in the set wins head to head comparisons against +candidates outside of it.
+Attributes
+profile
+: PreferenceProfile to run election on.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
Methods
+ +src/votekit/elections/election_types.py666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 | |
run_election()
+
+
+ cached
+
+
+¶Simulates a complete DominatingSets election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py721 +722 +723 +724 +725 +726 +727 +728 +729 +730 | |
run_step()
+
+¶Conducts a complete DominatingSets election as it is not a round-by-round +system.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 | |
HighestScore
+
+
+¶
+ Bases: Election
Conducts an election based on points from score vector. +Chooses the m candidates with highest scores. +Ties are broken by randomly permuting the tied candidates.
+Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected
score_vector
+: list of floats where ith entry denotes the number of points given to candidates
+ ranked in position i.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
ballot_ties (optional)
+: resolves ties in ballots. Should only be set to True if you want ballots
+ to have full linear rankings.
src/votekit/elections/election_types.py1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 +1101 +1102 +1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 +1136 +1137 +1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 | |
IRV
+
+
+¶
+ Bases: STV
A class for conducting IRV elections, which are mathematically equivalent to STV for one seat.
+Attributes
+profile
+: PreferenceProfile to run election on.
quota
+: formula to calculate quota (defaults to droop).
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
src/votekit/elections/election_types.py1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 | |
Limited
+
+
+¶
+ Bases: Election
Elects m candidates with the highest k-approval scores. +The k-approval score of a candidate is equal to the number of voters who +rank this candidate among their k top ranked candidates.
+Attributes
+profile
+: PreferenceProfile to run election on.
k
+: value of an approval score.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 | |
run_election()
+
+
+ cached
+
+
+¶Simulates a complete Limited election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object with results for a complete election. + |
+
src/votekit/elections/election_types.py328 +329 +330 +331 +332 +333 +334 +335 +336 +337 | |
run_step()
+
+¶Conducts Limited election in which m candidates are elected based +on approval scores.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a Limited election. + |
+
src/votekit/elections/election_types.py265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 | |
Plurality
+
+
+¶
+ Bases: SNTV
Simulates a single or multi-winner plurality election. Inherits
+methods from SNTV to run election.
src/votekit/elections/election_types.py1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 | |
SNTV
+
+
+¶
+ Bases: Election
Single nontransferable vote (SNTV): Elects k candidates with the highest +Plurality scores.
+Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 | |
run_election()
+
+
+ cached
+
+
+¶Runs complete SNTV election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object with results for a complete election. + |
+
src/votekit/elections/election_types.py462 +463 +464 +465 +466 +467 +468 +469 +470 +471 | |
run_step()
+
+¶Conducts an SNTV election to elect candidates.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a SNTV election. + |
+
src/votekit/elections/election_types.py448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 | |
SNTV_STV_Hybrid
+
+
+¶
+ Bases: Election
Election method that first runs SNTV to a cutoff, then runs STV to +pick a committee with a given number of seats.
+Attributes
+profile
+: PreferenceProfile to run election on.
transfer
+: transfer method (e.g. fractional transfer).
r1_cutoff
+: first-round cutoff value.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 | |
run_election()
+
+
+ cached
+
+
+¶Runs complete SNTV_STV election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object with results for a complete election. + |
+
src/votekit/elections/election_types.py586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 | |
run_step(stage)
+
+¶Simulates one round an SNTV_STV election.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
stage |
+
+ str
+ |
+
+
+
+ Stage of the hybrid election, can be SNTV or STV. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a given round. + |
+
src/votekit/elections/election_types.py524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 | |
STV
+
+
+¶
+ Bases: Election
Class for single-winner IRV and multi-winner STV elections.
+Attributes
+profile
+: PreferenceProfile to run election on.
transfer
+: transfer method (e.g. fractional transfer).
seats
+: number of seats to be elected.
quota
+: formula to calculate quota (defaults to droop).
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py26 + 27 + 28 + 29 + 30 + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 | |
get_threshold()
+
+¶Calculates threshold required for election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ int
+ |
+
+
+
+ Value of the threshold. + |
+
src/votekit/elections/election_types.py78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 | |
next_round()
+
+¶Determines if the number of seats has been met to call an election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ True if number of seats has not been met, False otherwise. + |
+
src/votekit/elections/election_types.py93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 | |
run_election()
+
+
+ cached
+
+
+¶Runs complete STV election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object with results for a complete election. + |
+
src/votekit/elections/election_types.py201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 | |
run_step()
+
+¶Simulates one round an STV election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a given round. + |
+
src/votekit/elections/election_types.py105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 | |
SequentialRCV
+
+
+¶
+ Bases: Election
Class to conduct Sequential RCV election, in which votes are not transferred +after a candidate has reached threshold, or been elected.
+Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 | |
run_election()
+
+
+ cached
+
+
+¶Simulates a complete sequential RCV contest.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 | |
run_step(old_profile)
+
+¶Simulates a single step of the sequential RCV contest or a full +IRV election run on the current set of candidates.
+Returns: + An ElectionState object for a given round.
+ +src/votekit/elections/election_types.py859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 | |
TopTwo
+
+
+¶
+ Bases: Election
Eliminates all but the top two plurality vote getters, and then +conducts a runoff between them, reallocating other ballots.
+Attributes
+profile
+: PreferenceProfile to run election on.
seats
+: number of seats to be elected.
ballot_ties
+: (optional) resolves input ballot ties if True, else assumes ballots have no ties.
+ Defaults to True.
tiebreak
+: (optional) resolves procedural and final ties by specified tiebreak.
+ Can either be a custom tiebreak function or a string. Supported strings are
+ given in tie_broken_ranking documentation. The custom function must take as
+ input two named parameters; ranking, a list-of-sets ranking of candidates and
+ profile, the original PreferenceProfile. It must return a list-of-sets
+ ranking of candidates with no ties. Defaults to random tiebreak.
Methods
+ +src/votekit/elections/election_types.py599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 | |
run_election()
+
+
+ cached
+
+
+¶Simulates a complete TopTwo election.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for a complete election. + |
+
src/votekit/elections/election_types.py654 +655 +656 +657 +658 +659 +660 +661 +662 +663 | |
run_step()
+
+¶Conducts a TopTwo election for one seat with a cutoff of 2 for the runoff.
+ + + +Returns:
+| Type | +Description | +
|---|---|
+ ElectionState
+ |
+
+
+
+ An ElectionState object for the TopTwo election. + |
+
src/votekit/elections/election_types.py636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 | |
clean_profile(pp, clean_ballot_func)
+
+¶Allows user-defined cleaning rules for PreferenceProfile. Input function +that applies modification or rule to a single ballot.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp |
+
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile to clean. + |
+ + required + | +
clean_ballot_func |
+
+ Callable[[Ballot], Ballot]
+ |
+
+
+
+ Function that +takes a list of ballots and cleans each ballot. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A cleaned PreferenceProfile. + |
+
src/votekit/cleaning.py38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 | |
deduplicate_profiles(pp)
+
+¶Given a PreferenceProfile, deduplicates its ballots.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp |
+
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile to clean. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A cleaned PreferenceProfile without duplicates. + |
+
src/votekit/cleaning.py87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 | |
merge_ballots(ballots)
+
+¶Takes a list of ballots with the same ranking and merge them into one ballot.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ballots |
+
+ list[Ballot]
+ |
+
+
+
+ A list of ballots to deduplicate. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Ballot
+ |
+
+
+
+ A ballot with the same ranking and aggregated weight and voters. + |
+
src/votekit/cleaning.py67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 | |
remove_empty_ballots(pp, keep_candidates=False)
+
+¶Removes empty ballots from a PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp |
+
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile to clean. + |
+ + required + | +
keep_candidates |
+
+ bool
+ |
+
+
+
+ If True, keep all of the candidates +from the original PreferenceProfile in the returned PreferenceProfile, even if +they got no votes. Defaults to False. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A cleaned PreferenceProfile. + |
+
src/votekit/cleaning.py11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 | |
remove_noncands(profile, non_cands)
+
+¶Removes user-assigned non-candidates from ballots, deletes ballots +that are empty as a result of the removal.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile to clean. + |
+ + required + | +
non_cands |
+
+ list[str]
+ |
+
+
+
+ A list of non-candidates to be removed. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ PreferenceProfile
+ |
+
+
+
+ A profile with non-candidates removed. + |
+
src/votekit/cleaning.py125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 | |
borda_scores(profile, ballot_length=None, score_vector=None)
+
+¶Calculates Borda scores for a PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ Inputed PreferenceProfile of ballots. + |
+ + required + | +
ballot_length |
+
+ Optional[int]
+ |
+
+
+
+ Length of a ballot, if None length of longest ballot is +used. + |
+
+ None
+ |
+
score_vector |
+
+ Optional[list]
+ |
+
+
+
+ Borda weights, if None, vector is assigned \((n,n-1,\dots,1)\). + |
+
+ None
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ Dictionary of candidates (keys) and Borda scores (values). + |
+
src/votekit/utils.py199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 | |
first_place_votes(profile, to_float=False)
+
+¶Calculates first-place votes for a PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ Inputed PreferenceProfile of ballots. + |
+ + required + | +
to_float |
+
+ bool
+ |
+
+
+
+ If True, compute first place votes as floats instead of Fractions. Defaults to + False. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ Dictionary of candidates (keys) and first place vote totals (values). + |
+
src/votekit/utils.py146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 | |
mentions(profile)
+
+¶Calculates total mentions for a PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ Inputed PreferenceProfile of ballots. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ Dictionary of candidates (keys) and mention totals (values). + |
+
src/votekit/utils.py171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 | |
earth_mover_dist(pp1, pp2)
+
+¶Computes the earth mover distance between two elections. +Assumes both elections share the same candidates.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp1 |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile for first election. + |
+ + required + | +
pp2 |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile for second election. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ int
+ |
+
+
+
+ Earth mover distance between inputted elections. + |
+
src/votekit/metrics/distances.py9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 | |
lp_dist(pp1, pp2, p_value=1)
+
+¶Computes the L_p distance between two election distributions. +Use 'inf' for infinity norm. +Assumes both elections share the same candidates.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp1 |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile for first election. + |
+ + required + | +
pp2 |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile for second election. + |
+ + required + | +
p_value |
+
+ Optional[Union[int, str]]
+ |
+
+
+
+ Distance parameter, 1 for Manhattan, 2 for Euclidean +or 'inf' for Chebyshev distance. + |
+
+ 1
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ int
+ |
+
+
+
+ Lp distance between two elections. + |
+
src/votekit/metrics/distances.py44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 | |
em_array(pp)
+
+¶Converts a PreferenceProfile into a distribution using ballot graphs.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile for a given election. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list
+ |
+
+
+
+ Distribution of ballots for an election. + |
+
src/votekit/metrics/distances.py123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 | |
fractional_transfer(winner, ballots, votes, threshold)
+
+¶Calculates fractional transfer from winner, then removes winner +from the list of ballots.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
winner |
+
+ str
+ |
+
+
+
+ Candidate to transfer votes from. + |
+ + required + | +
ballots |
+
+ list[Ballot]
+ |
+
+
+
+ List of Ballot objects. + |
+ + required + | +
votes |
+
+ dict
+ |
+
+
+
+ Contains candidates and their corresponding vote totals. + |
+ + required + | +
threshold |
+
+ int
+ |
+
+
+
+ Value required to be elected, used to calculate transfer value. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list[Ballot]
+ |
+
+
+
+ Modified ballots with transfered weights and the winning candidate removed. + |
+
src/votekit/elections/transfers.py8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 | |
seqRCV_transfer(winner, ballots, votes, threshold)
+
+¶Transfer method for Sequential RCV elections.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
winner |
+
+ str
+ |
+
+
+
+ Candidate to transfer votes from. + |
+ + required + | +
ballots |
+
+ list[Ballot]
+ |
+
+
+
+ List of Ballot objects. + |
+ + required + | +
votes |
+
+ dict
+ |
+
+
+
+ Contains candidates and their corresponding vote totals. + |
+ + required + | +
threshold |
+
+ int
+ |
+
+
+
+ Value required to be elected, used to calculate transfer value. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list[Ballot]
+ |
+
+
+
+ Original list of ballots as Sequential RCV does not transfer votes. + |
+
src/votekit/elections/transfers.py88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 | |
random_transfer(winner, ballots, votes, threshold)
+
+¶Cambridge-style transfer where transfer ballots are selected randomly.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
winner |
+
+ str
+ |
+
+
+
+ Candidate to transfer votes from. + |
+ + required + | +
ballots |
+
+ list[Ballot]
+ |
+
+
+
+ List of Ballot objects. + |
+ + required + | +
votes |
+
+ dict
+ |
+
+
+
+ Contains candidates and their corresponding vote totals. + |
+ + required + | +
threshold |
+
+ int
+ |
+
+
+
+ Value required to be elected, used to calculate transfer value. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list[Ballot]
+ |
+
+
+
+ Modified ballots with transferred weights and the winning candidate removed. + |
+
src/votekit/elections/transfers.py48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 | |
compute_MDS(data, distance, random_seed=47, *args, **kwargs)
+
+¶Computes the coordinates of an MDS plot. This is time intensive, so it is decoupled from
+plot_mds to allow users to flexibly use the coordinates.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ Dict[str, list[PreferenceProfile]]
+ |
+
+
+
+ Dictionary with key being a string label and value being list of + PreferenceProfiles. ex: {'PL with alpha = 4': list[PreferenceProfile]} + |
+ + required + | +
distance |
+
+ Callable[..., int]
+ |
+
+
+
+ Distance function. See distance.py. + |
+ + required + | +
random_seed |
+
+ int
+ |
+
+
+
+ an integer seed to allow for reproducible MDS plots. Defaults to 47. + |
+
+ 47
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
coord_dict |
+ dict
+ |
+
+
+
+ a dictionary whose keys match |
+
| + | +
+
+
+ numpy arrays (x_list, y_list) of coordinates for the MDS plot. + |
+
src/votekit/plots/mds.py34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 | |
distance_matrix(pp_arr, distance, *args, **kwargs)
+
+¶Creates pairwise distance matrix between PreferenceProfile. The \((i,j)\) entry is the pairwise +distance between \(i\)th and the \(j\)th PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
pp_arr |
+
+ list[PreferenceProfile]
+ |
+
+
+
+ List of PreferenceProfiles. + |
+ + required + | +
distance |
+
+ Callable[..., int]
+ |
+
+
+
+ Callable distance function type. See distances.py in the metrics module. + |
+ + required + | +
Returns:
+| Name | Type | +Description | +
|---|---|---|
dist_matrix |
+ ndarray
+ |
+
+
+
+ Distance matrix for an election. + |
+
src/votekit/plots/mds.py10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 | |
plot_MDS(coord_dict, plot_kwarg_dict=None, legend=True, title=True)
+
+¶Creates an MDS plot from the output of compute_MDS with legend labels matching the keys
+of coord_dict.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
coord_dict |
+
+ dict
+ |
+
+
+
+ Dictionary with key being a string label and value being tuple + |
+ + required + | +
plot_kwarg_dict |
+
+ Optional[dict]
+ |
+
+
+
+ Dictionary with keys matching coord_dict and values are kwarg dictionaries
+that will be passed to matplotlib |
+
+ None
+ |
+
legend |
+
+ bool
+ |
+
+
+
+ boolean for plotting the legend. Defaults to True. + |
+
+ True
+ |
+
title |
+
+ bool
+ |
+
+
+
+ boolean for plotting the title. Defaults to True. + |
+
+ True
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
fig | + | +
+
+
+ a matplotlib fig + |
+
src/votekit/plots/mds.py85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 | |
plot_summary_stats(profile, stat, multi_color=True, title='')
+
+¶Plots histogram of election summary statistics.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ A PreferenceProfile to visualize. + |
+ + required + | +
stat |
+
+ str
+ |
+
+
+
+ 'first place votes', 'mentions', or 'borda'. + |
+ + required + | +
multi_color |
+
+ bool
+ |
+
+
+
+ If the bars should be multicolored. Defaults to True. + |
+
+ True
+ |
+
title |
+
+ str
+ |
+
+
+
+ Title for the figure. Defaults to None. + |
+
+ ''
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Figure
+ |
+
+
+
+ A figure with the visualization. + |
+
src/votekit/plots/profile_plots.py7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 | |
compute_votes(candidates, ballots)
+
+¶Computes first place votes for all candidates in a PreferenceProfile.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
candidates |
+
+ list
+ |
+
+
+
+ List of all candidates in a PreferenceProfile. + |
+ + required + | +
ballots |
+
+ list[Ballot]
+ |
+
+
+
+ List of Ballot objects. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ tuple[list[CandidateVotes], dict]
+ |
+
+
+
+ A tuple (ordered, votes) where ordered is a list of tuples (cand, first place votes) +ordered by decreasing first place votes and votes is a dictionary whose keys are +candidates and values are first place votes. + |
+
src/votekit/utils.py57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 | |
remove_cand(removed, ballots)
+
+¶Removes specified candidate(s) from ballots.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
removed |
+
+ Union[str, Iterable]
+ |
+
+
+
+ Candidate or set of candidates to be removed. + |
+ + required + | +
ballots |
+
+ list[Ballot]
+ |
+
+
+
+ List of Ballots to remove candidate(s) from. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list[Ballot]
+ |
+
+
+
+ Updated list of ballots with candidate(s) removed. + |
+
src/votekit/utils.py93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 | |
fix_ties(ballot)
+
+¶Helper function for recursively_fix_ties. Resolves the first appearing +tied rank in the input ballot.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ballot |
+
+ Ballot
+ |
+
+
+
+ A Ballot. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ list
+ |
+
+
+
+ List of Ballots that are permutations of the tied ballot. + |
+
src/votekit/utils.py478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 | |
elect_cands_from_set_ranking(ranking, seats)
+
+¶Splits a ranking into elected and eliminated based on seats, +and if a tie set overlaps the desired number of seats raises a ValueError.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ranking |
+
+ list[set[str]]
+ |
+
+
+
+ A list-of-set ranking of candidates. + |
+ + required + | +
seats |
+
+ int
+ |
+
+
+
+ Number of seats to fill. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ tuple[list[set[str]], list[set[str]]]
+ |
+
+
+
+ A list-of-sets of elected candidates, a list-of-sets of eliminated candidates. + |
+
src/votekit/utils.py418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 | |
scores_into_set_list(score_dict, candidate_subset=None)
+
+¶Sorts candidates based on a scoring dictionary (i.e Borda, First-Place).
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
score_dict |
+
+ dict
+ |
+
+
+
+ Dictionary between candidates (key) and their score (value). + |
+ + required + | +
candidate_subset |
+
+ Union[list[str], set[str], None]
+ |
+
+
+
+ Relevant candidates to sort. + |
+
+ None
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[set[str]]
+ |
+
+
+
+ Candidate rankings in a list-of-sets form. + |
+
src/votekit/utils.py335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 | |
tie_broken_ranking(ranking, profile, tiebreak='none')
+
+¶Breaks ties in a list-of-sets ranking according to a given scheme.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ranking |
+
+ list[set[str]]
+ |
+
+
+
+ A list-of-set ranking of candidates. + |
+ + required + | +
profile |
+
+ PreferenceProfile
+ |
+
+
+
+ PreferenceProfile. + |
+ + required + | +
tiebreak |
+
+ str
+ |
+
+
+
+ Method of tiebreak, currently supports 'none', 'random', 'borda', 'firstplace'. + |
+
+ 'none'
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[set[str]]
+ |
+
+
+
+ A list-of-set ranking of candidates (tie broken down to one candidate sets unless +tiebreak = 'none'). + |
+
src/votekit/utils.py290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 | |
candidate_position_dict(ranking)
+
+¶Creates a dictionary with the integer ranking of candidates given a set ranking +i.e. A > B, C > D returns {A: 1, B: 2, C: 2, D: 4}.
+ + + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
ranking |
+
+ list[set[str]]
+ |
+
+
+
+ A list-of-sets ranking of candidates. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ dict
+ |
+
+
+
+ Dictionary of candidates (keys) and integer rankings (values). + |
+
src/votekit/utils.py268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 | |