Skip to content

Commit

Permalink
update docs and tutorials
Browse files Browse the repository at this point in the history
  • Loading branch information
@cdonnay
cdonnay committed Jul 11, 2024
1 parent 71b2f81 commit 9fa6d2e
Show file tree
Hide file tree
Showing 23 changed files with 288 additions and 297 deletions.
1 change: 1 addition & 0 deletions docs/requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Jinja2==3.1.4
joblib==1.4.2
jsonschema==4.22.0
jsonschema-specifications==2023.12.1
jupyter==1.0.0
kiwisolver==1.4.5
MarkupSafe==2.1.5
matplotlib==3.9.0
Expand Down
2 changes: 1 addition & 1 deletion docs/social_choice_docs/scr.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -492,7 +492,7 @@ Plurality scores. Equivalent to Limited with :math:`k=1` and SNTV.
HighestScore
------------
Conducts an election based on points from a score vector.
A score vector is a vector whose :math:`i`th entry denotes the number of points given
A score vector is a vector whose :math:`i` th entry denotes the number of points given
to a candidate in position :math:`i`. Normally a score vector is non-negative and
decreasing. A HighestScore election chooses the :math:`m` candidates with highest scores.
Ties are broken by randomly permuting the tied candidates.
Expand Down
90 changes: 45 additions & 45 deletions docs/user/tutorial/1_intro.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -371,7 +371,7 @@ candidate will appear at the bottom of the ballot.
.. figure:: ../../_static/assets/preference_interval.png
:alt: png


png

One of the generative models is called the **slate-Plackett-Luce
model**, or s-PL. In s-PL, voters fill in their ballot from the top
Expand All @@ -396,7 +396,7 @@ but bear with us.
# the preference interval (80,15,5)
pref_intervals_by_bloc = {"all_voters":
{"all_voters": PreferenceInterval({"A": .80, "B":.15, "C":.05})}
{"all_voters": PreferenceInterval({"A": .80, "B": .15, "C": .05})}
}
# the sPL model needs an estimate of cohesion between blocs,
Expand All @@ -415,11 +415,11 @@ but bear with us.
.. parsed-literal::
Ballots Weight
(A, B, C) 61
(A, C, B) 17
(B, A, C) 17
(C, A, B) 4
(B, C, A) 1
(A, B, C) 56
(A, C, B) 23
(B, A, C) 12
(C, A, B) 7
(C, B, A) 2
Re-run the above block several times to see that the elections will come
Expand Down Expand Up @@ -461,11 +461,11 @@ their bloc.
# note that we include candidates with 0 support,
# and that our preference intervals will automatically rescale to sum to 1
pref_intervals_by_bloc = {"Alpha": {"Alpha": PreferenceInterval({"A": .8, "B":.2}),
"Xenon": PreferenceInterval({"X":0, "Y": 1})},
pref_intervals_by_bloc = {"Alpha": {"Alpha": PreferenceInterval({"A": .8, "B": .2}),
"Xenon": PreferenceInterval({"X": 0, "Y": 1})},
"Xenon": {"Alpha": PreferenceInterval({"A": .5, "B":.5}),
"Xenon": PreferenceInterval({"X":.5, "Y": .5})}}
"Xenon": {"Alpha": PreferenceInterval({"A": .5, "B": .5}),
"Xenon": PreferenceInterval({"X": .5, "Y": .5})}}
bloc_voter_prop = {"Alpha": .8, "Xenon": .2}
Expand Down Expand Up @@ -493,48 +493,48 @@ their bloc.
The ballots from Alpha voters
Ballots Weight
(A, B, Y, X) 5527
(B, A, Y, X) 967
(Y, A, B, X) 673
(A, Y, B, X) 605
(Y, B, A, X) 123
(B, Y, A, X) 105
(A, B, Y, X) 5184
(B, A, Y, X) 1283
(Y, A, B, X) 659
(A, Y, B, X) 580
(Y, B, A, X) 154
(B, Y, A, X) 140
The ballots from Xenon voters
PreferenceProfile too long, only showing 15 out of 24 rows.
Ballots Weight
(Y, X, A, B) 415
(X, Y, B, A) 405
(Y, X, B, A) 401
(X, Y, A, B) 397
(Y, X, A, B) 420
(X, Y, A, B) 412
(X, Y, B, A) 397
(Y, X, B, A) 378
(B, Y, X, A) 50
(A, X, Y, B) 45
(B, X, Y, A) 44
(Y, B, X, A) 41
(X, A, Y, B) 40
(Y, A, X, B) 36
(X, B, Y, A) 35
(A, Y, X, B) 33
(A, B, X, Y) 9
(B, Y, A, X) 9
(A, X, B, Y) 7
(X, A, Y, B) 48
(B, X, Y, A) 47
(A, X, Y, B) 44
(A, Y, X, B) 41
(Y, B, X, A) 37
(Y, A, X, B) 37
(X, B, Y, A) 34
(A, B, X, Y) 8
(B, A, Y, X) 7
(X, B, A, Y) 6
Aggregated ballots
PreferenceProfile too long, only showing 15 out of 30 rows.
Ballots Weight
(A, B, Y, X) 5527
(B, A, Y, X) 967
(Y, A, B, X) 673
(A, Y, B, X) 605
(Y, X, A, B) 415
(X, Y, B, A) 405
(Y, X, B, A) 401
(X, Y, A, B) 397
(Y, B, A, X) 123
(B, Y, A, X) 105
(A, B, Y, X) 5184
(B, A, Y, X) 1283
(Y, A, B, X) 659
(A, Y, B, X) 580
(Y, X, A, B) 420
(X, Y, A, B) 412
(X, Y, B, A) 397
(Y, X, B, A) 378
(Y, B, A, X) 154
(B, Y, A, X) 140
(B, Y, X, A) 50
(A, X, Y, B) 45
(B, X, Y, A) 44
(Y, B, X, A) 41
(X, A, Y, B) 40
(X, A, Y, B) 48
(B, X, Y, A) 47
(A, X, Y, B) 44
(A, Y, X, B) 41
Scan this to be sure it is reasonable, recalling that our intervals say
Expand Down
155 changes: 73 additions & 82 deletions docs/user/tutorial/3_viz.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,21 +47,21 @@ case.
IC profile:
Ballots Weight
(B, C, A) 175
(B, A, C) 175
(B, A, C) 173
(C, B, A) 172
(A, C, B) 170
(C, B, A) 169
(C, A, B) 163
(A, B, C) 148
(B, C, A) 170
(C, A, B) 162
(A, B, C) 153
IAC profile:
Ballots Weight
(B, C, A) 218
(B, A, C) 192
(A, C, B) 180
(C, B, A) 176
(C, A, B) 129
(A, B, C) 105
(B, C, A) 388
(B, A, C) 254
(A, B, C) 135
(A, C, B) 103
(C, A, B) 62
(C, B, A) 58
Now we’ll plot some summary statistics for the generated elections.
Expand Down Expand Up @@ -143,23 +143,23 @@ times :math:`B` is preferred to :math:`A`.
.. parsed-literal::
PreferenceProfile too long, only showing 15 out of 101 rows.
PreferenceProfile too long, only showing 15 out of 97 rows.
Ballots Weight
(W2, W1, C2, C1) 78
(W2, W1) 61
(W1, W2) 46
(W1, W2, C2, C1) 44
(W2, W1, C2) 42
(W1, C2, W2, C1) 38
(W1, W2, C2) 36
(W2,) 36
(W2, C2, C1, W1) 36
(W1,) 33
(W2, C2, W1, C1) 32
(W2, W1, C1, C2) 26
(W2, C2, W1) 23
(W1, W2, C1, C2) 22
(W1, C2, C1, W2) 22
(W1, W2, C2, C1) 73
(W1, W2) 70
(W1, W2, C1, C2) 62
(W1,) 58
(W1, W2, C2) 44
(W1, C2, W2, C1) 40
(W1, C2, C1, W2) 34
(W2, W1) 32
(W1, C2, W2) 26
(W1, W2, C1) 25
(W2, W1, C2, C1) 23
(C2, W2, W1, C1) 23
(W2, W1, C1, C2) 22
(W1, C1, C2, W2) 21
(W2, W1, C1) 21
Expand Down Expand Up @@ -189,8 +189,8 @@ that beats every lower-tier candidate in a head-to-head comparison.
.. parsed-literal::
tiers: [{'W2'}, {'W1'}, {'C2'}, {'C1'}]
The Condorcet candidate is: W2
tiers: [{'W1'}, {'W2'}, {'C2'}, {'C1'}]
The Condorcet candidate is: W1
MDS Plots
Expand Down Expand Up @@ -428,12 +428,12 @@ Now let’s generate a ballot graph from election data.
.. parsed-literal::
Ballots Weight
(B, C, A) 395
(C, B, A) 315
(A, B, C) 165
(B, A, C) 61
(A, C, B) 41
(C, A, B) 23
(C, B, A) 772
(C, A, B) 121
(B, C, A) 48
(A, C, B) 47
(A, B, C) 8
(B, A, C) 4
Expand All @@ -443,14 +443,14 @@ Now let’s generate a ballot graph from election data.
.. parsed-literal::
(1,) {'weight': 0, 'cast': False}
(1, 2, 3) {'weight': Fraction(165, 1), 'cast': True}
(1, 3, 2) {'weight': Fraction(41, 1), 'cast': True}
(1, 2, 3) {'weight': Fraction(4, 1), 'cast': True}
(1, 3, 2) {'weight': Fraction(48, 1), 'cast': True}
(2,) {'weight': 0, 'cast': False}
(2, 3, 1) {'weight': Fraction(395, 1), 'cast': True}
(2, 1, 3) {'weight': Fraction(61, 1), 'cast': True}
(2, 3, 1) {'weight': Fraction(47, 1), 'cast': True}
(2, 1, 3) {'weight': Fraction(8, 1), 'cast': True}
(3,) {'weight': 0, 'cast': False}
(3, 1, 2) {'weight': Fraction(23, 1), 'cast': True}
(3, 2, 1) {'weight': Fraction(315, 1), 'cast': True}
(3, 1, 2) {'weight': Fraction(772, 1), 'cast': True}
(3, 2, 1) {'weight': Fraction(121, 1), 'cast': True}
Check that this is reasonable: only ballots that were in the
Expand Down Expand Up @@ -524,44 +524,47 @@ and place it in your working directory (the same folder as your code).
from votekit.cvr_loaders import load_scottish
from votekit.graphs import BallotGraph
# the load_scottish function returns a tuple, the first element is the preference
# profile and the second is the number of seats in the election
scottish_profile, num_seats = load_scottish("eilean_siar_2012_ward3.csv")
# the load_scottish function returns a tuple of information:
# the first element is the profile itself, the second is the number of seats in the election
# the third is a list of candidates, the fourth a dictionary mapping candidatess to parties,
# and the fourth the ward name
scottish_profile, seats, cand_list, cand_to_party, ward = load_scottish("eilean_siar_2012_ward3.csv")
# we don't want to alter any ballots so we'll turn off "fix_short"
ballot_graph = BallotGraph(scottish_profile, fix_short = False)
print(scottish_profile)
# only show us the ballots cast
ballot_graph.draw(show_cast = False,labels = False, scale=3)
.. parsed-literal::
PreferenceProfile too long, only showing 15 out of 57 rows.
Ballots Weight
(('Catherine', 'MACDONALD', 'Ind'),) 155
(('Catherine', 'MACDONALD', 'Ind'), ('Philip Robert', 'MCLEAN', 'SNP'), ('David Cameron', 'WILSON', 'SNP')) 74
(('Catherine', 'MACDONALD', 'Ind'), ('Philip Robert', 'MCLEAN', 'SNP')) 63
(('Catherine', 'MACDONALD', 'Ind'), ('D J', 'MACRAE', 'Lab')) 52
(('Philip Robert', 'MCLEAN', 'SNP'), ('David Cameron', 'WILSON', 'SNP')) 48
(('Philip Robert', 'MCLEAN', 'SNP'), ('Catherine', 'MACDONALD', 'Ind')) 36
(('Philip Robert', 'MCLEAN', 'SNP'), ('David Cameron', 'WILSON', 'SNP'), ('Catherine', 'MACDONALD', 'Ind')) 31
(('Catherine', 'MACDONALD', 'Ind'), ('D J', 'MACRAE', 'Lab'), ('Philip Robert', 'MCLEAN', 'SNP')) 29
(('Catherine', 'MACDONALD', 'Ind'), ('Philip Robert', 'MCLEAN', 'SNP'), ('D J', 'MACRAE', 'Lab')) 27
(('Philip Robert', 'MCLEAN', 'SNP'),) 24
(('Catherine', 'MACDONALD', 'Ind'), ('Philip Robert', 'MCLEAN', 'SNP'), ('David Cameron', 'WILSON', 'SNP'), ('D J', 'MACRAE', 'Lab')) 22
(('D J', 'MACRAE', 'Lab'), ('Catherine', 'MACDONALD', 'Ind')) 18
(('Catherine', 'MACDONALD', 'Ind'), ('D J', 'MACRAE', 'Lab'), ('Philip Robert', 'MCLEAN', 'SNP'), ('David Cameron', 'WILSON', 'SNP')) 17
(('Philip Robert', 'MCLEAN', 'SNP'), ('Catherine', 'MACDONALD', 'Ind'), ('David Cameron', 'WILSON', 'SNP')) 17
(('Catherine', 'MACDONALD', 'Ind'), ('D J', 'MACRAE', 'Lab'), ('David Cameron', 'WILSON', 'SNP')) 15
Ballots Weight
(Catherine Macdonald,) 155
(Catherine Macdonald, Philip Robert Mclean, David Cameron Wilson) 74
(Catherine Macdonald, Philip Robert Mclean) 63
(Catherine Macdonald, D J Macrae) 52
(Philip Robert Mclean, David Cameron Wilson) 48
(Philip Robert Mclean, Catherine Macdonald) 36
(Philip Robert Mclean, David Cameron Wilson, Catherine Macdonald) 31
(Catherine Macdonald, D J Macrae, Philip Robert Mclean) 29
(Catherine Macdonald, Philip Robert Mclean, D J Macrae) 27
(Philip Robert Mclean,) 24
(Catherine Macdonald, Philip Robert Mclean, David Cameron Wilson, D J Macrae) 22
(D J Macrae, Catherine Macdonald) 18
(Catherine Macdonald, D J Macrae, Philip Robert Mclean, David Cameron Wilson) 17
(Philip Robert Mclean, Catherine Macdonald, David Cameron Wilson) 17
(Catherine Macdonald, D J Macrae, David Cameron Wilson) 15
The candidates are labeled as follows.
1 ('D J', 'MACRAE', 'Lab')
2 ('David Cameron', 'WILSON', 'SNP')
3 ('Philip Robert', 'MCLEAN', 'SNP')
4 ('Catherine', 'MACDONALD', 'Ind')
1 David Cameron Wilson
2 Catherine Macdonald
3 D J Macrae
4 Philip Robert Mclean
Expand All @@ -577,36 +580,24 @@ you want to display the node.

.. code:: ipython3
scottish_dictionary = ballot_graph._number_cands(cands =
tuple(scottish_profile.get_candidates()))
for key,value in scottish_dictionary.items():
print(value,key)
print()
print("Missing ballots:")
def show_zero(graph, node):
# display nodes with no votes
if graph.nodes[node]["weight"] == 0:
return True
return False
print("Displaying missing ballots:")
ballot_graph.draw(labels=False, to_display=show_zero)
.. parsed-literal::
1 ('D J', 'MACRAE', 'Lab')
2 ('David Cameron', 'WILSON', 'SNP')
3 ('Philip Robert', 'MCLEAN', 'SNP')
4 ('Catherine', 'MACDONALD', 'Ind')
Missing ballots:
Displaying missing ballots:
The candidates are labeled as follows.
1 ('D J', 'MACRAE', 'Lab')
2 ('David Cameron', 'WILSON', 'SNP')
3 ('Philip Robert', 'MCLEAN', 'SNP')
4 ('Catherine', 'MACDONALD', 'Ind')
1 David Cameron Wilson
2 Catherine Macdonald
3 D J Macrae
4 Philip Robert Mclean
Expand Down
Binary file modified docs/user/tutorial/3_viz_files/3_viz_13_0.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_16_0.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_16_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_22_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_25_0.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_25_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_28_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_30_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_4_0.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_4_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/user/tutorial/3_viz_files/3_viz_7_1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 9fa6d2e

Please sign in to comment.