diff --git a/packages/preview/comitia/0.1.0/LICENSE b/packages/preview/comitia/0.1.0/LICENSE new file mode 100644 index 0000000000..556c3c4786 --- /dev/null +++ b/packages/preview/comitia/0.1.0/LICENSE @@ -0,0 +1,7 @@ +Copyright (c) 2025 Tobias Heidler + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/packages/preview/comitia/0.1.0/README.md b/packages/preview/comitia/0.1.0/README.md new file mode 100644 index 0000000000..06c369afad --- /dev/null +++ b/packages/preview/comitia/0.1.0/README.md @@ -0,0 +1,56 @@ +# comitia + +Use different voting mechanisms in your document. Powered by Rust WASM. + +You can analyze a vote turnout by calling `vote(ballots, method, ties_method)` which returns the raw JSON results +of your ballots or `vote-report(ballots, method, ties_method)` for a more detailled report on the vote. + +## Example + +First you must import the library and define an *input* for our vote method. This input must be a list +with each element of the list containing the ranked choice(s) for an individual: + +```typst +#import "@preview/comitia:0.1.0": * +#let input = ( + ("Alice", "Charlie"), + ("Bob", "Charlie", "Alice"), + ("Charlie", "Alice", "Bob"), + ("Alice", "Charlie", "Bob"), + ("Bob", "Alice", "Charlie"), + ("Tim",) +) +``` + +In our example the first person prefered Alice over Charlie and the last person +only voted for Tim. Please note that an Element that contains only one element +must end with a comma, as shown in `#("Tim",)`. + +Then you can either analyze the raw output using the function: + +```typst +#vote(input, method: "STV", ties_method: "Random") +``` + +Or you can have a more sophisticated report on each step performed: + +```typst +#vote-report(input, method: "STV", ties_method: "Random") +``` + +## Implemented + +### Methods + +- Plurality +- STV (Single Transferable Vote - for one candidate: Instant-Runoff Voting) + +### Tie Breakers + +- All +- Random +- Count + +### Minimum Number of Candidates + +Currently only single (or tie bound multiple) candidates are returned. Multiple voting rounds for more than one candidate are to be implemented in the future. diff --git a/packages/preview/comitia/0.1.0/comitia.wasm b/packages/preview/comitia/0.1.0/comitia.wasm new file mode 100755 index 0000000000..2ea9e7af29 Binary files /dev/null and b/packages/preview/comitia/0.1.0/comitia.wasm differ diff --git a/packages/preview/comitia/0.1.0/examples/example.pdf b/packages/preview/comitia/0.1.0/examples/example.pdf new file mode 100644 index 0000000000..48defbd6d2 Binary files /dev/null and b/packages/preview/comitia/0.1.0/examples/example.pdf differ diff --git a/packages/preview/comitia/0.1.0/examples/example.typ b/packages/preview/comitia/0.1.0/examples/example.typ new file mode 100644 index 0000000000..a4151106eb --- /dev/null +++ b/packages/preview/comitia/0.1.0/examples/example.typ @@ -0,0 +1,176 @@ +#import "@preview/comitia:0.1.0" : vote-report, vote + +#set heading(numbering: "1.1") + +#show heading.where(level: 4): it =>[ + #block(it.body) +] +#show heading.where(level: 5): it =>[ + #block(it.body) +] +#show heading.where(level: 6): it =>[ + #block(it.body) +] +#set par(justify: true) + +#outline(depth: 3) + += Define an Input + +First you must define an input for our vote method. This input must be a list +with each element of the list containing the ranked choices for an individual: + +```typst +#let input = ( + ("Alice", "Charlie"), + ("Bob", "Charlie", "Alice"), + ("Charlie", "Alice", "Bob"), + ("Alice", "Charlie", "Bob"), + ("Bob", "Alice", "Charlie"), + ("Tim",) +) +``` + +#let input = ( + ("Alice", "Charlie"), + ("Bob", "Charlie", "Alice"), + ("Charlie", "Alice", "Bob"), + ("Alice", "Charlie", "Bob"), + ("Bob", "Alice", "Charlie"), + ("Tim",) +) + +In our example the first person prefered Alice over Charlie and the last person +only voted for Tim. Please note that an Element that contains only one element +must end with a comma, as shown in #("Tim",). + += Retrieve raw results (`#vote`) + +To retrieve the raw results simply call + +```typst + #vote(input) +``` + +The results is JSON and is shown here: + +#vote(input) + +By default vote operates on Plurality (See @Plurality) vote mode and for ties +all candidates are retained (and/or eliminated). For other methods of solving +votes see @Methods and for other tie breaker modes see @Ties. + + += Retrieve a detailed result report (`#vote-report`) + +To retrieve a report of the raw results simply call + +```typst +#vote-report(input) +``` + +This method takes in the same parameters as `#vote`. For reference see @RAW. + +The results are shown in the examples (see @Example-Plurality and @Example-SVT). + + += Methods + +== Plurality + +Each ballot selects one candidate. The candidate with the highest number of votes wins. The candidate with the fewest votes is eliminated. + +== STV + +Single Transferable Vote is used when multiple seats are to be filled. A quota of votes is calculated. Candidates who reach the quota are elected, and any surplus votes they receive are transferred to remaining candidates according to voter preferences. If no one meets the quota, the candidate with the fewest votes is eliminated and their ballots transferred. The process repeats until all seats are filled. + +With only one seat to fill, STV works like Instant-Runoff Voting: voters rank candidates, the least-voted candidate is eliminated each round, and their ballots are transferred to the next preference, until one candidate remains and wins (> 50% of votes). + += Tie Breakers + +== All + +If multiple candidates tie for winning or elimination, all tied candidates share the outcome (all win or all are eliminated). + +== Random + +If multiple candidates tie, a random selection among the tied candidates determines who wins or is eliminated. + +== Count + +If multiple candidates tie, the total number of ballots that contain this candidate is summed up. This sum +is used to break the tie. + += Example Reports for Plurality-Voting + +== Tie Method: All + +```typst +//Call: +#vote-report(input) +``` + +#vote-report(input) +#pagebreak() + +== Tie Method: Random + +```typst +//Call: +#vote-report(input, tie-method: "Random") +``` + +#vote-report(input, tie-method: "Random") +#pagebreak() + +== Tie Method: Count + +```typst +//Call: +#vote-report(input, tie-method: "Count") +``` + +#vote-report(input, tie-method: "Count") +#pagebreak() + += Examples Reports for STV-Voting + +== Tie Method: All + +```typst +//Call: +#vote-report(input, method: "STV", tie-method: "All") +``` + +#vote-report(input, method: "STV", tie-method: "All") +#pagebreak() + +== Tie Method: Random + +```typst +//Call: +#vote-report(input, method: "STV", tie-method: "Random") +``` + +#vote-report(input, method: "STV", tie-method: "Random") +#pagebreak() + +== Tie Method: Count + +```typst +//Call: +#vote-report(input, method: "STV", tie-method: "Count") +``` + +#vote-report(input, method: "STV", tie-method: "Count") + +== Change Header Level + +Changes the top header of the report to level 3: + +```typst +//Call: +#vote-report(input, method: "STV", tie-method: "All", level-start: 3) +``` + +#vote-report(input, method: "STV", tie-method: "All", level-start: 3) \ No newline at end of file diff --git a/packages/preview/comitia/0.1.0/lib.typ b/packages/preview/comitia/0.1.0/lib.typ new file mode 100644 index 0000000000..c5a5a6fd43 --- /dev/null +++ b/packages/preview/comitia/0.1.0/lib.typ @@ -0,0 +1,160 @@ +#let p = plugin("./comitia.wasm") + +// Generates ordinal indicators from numbers +#let xth(n) = { + let x = if n == 1 { + [st] + } else if n == 2 { + [nd] + } else if n == 3 { + [rd] + } else { + [th] + } + [*#n#super[#x]*] +} + +// Adds a link to the current used method +#let method-link(method) = { + if method == "Plurality" { + link("https://en.wikipedia.org/wiki/Plurality_voting")[*Plurality*] + } else if method == "STV" { + link("https://en.wikipedia.org/wiki/Single_transferable_vote")[*STV*] + } else { + [*#method*] + } +} + +// Displays JSON data as a table +// Source: https://www.reddit.com/r/typst/comments/164v4pe/creating_tables_from_json_file/ +// Credit goes to: a5sk6n +#let table-json(data) = { + let keys = data.at(0).keys() + table( + columns: keys.len(), + ..keys, + ..data.map( + row => keys.map( + key => [#row.at(key, default: [n/a])] + ) + ).flatten() + ) +} + +// Adapted table-json(data) for displaying detailed voting results tables +#let details-table-json(data) = { + let keys = data.at(0).keys() + table( + columns: keys.len(), + [Run], [Candidate], [ID], [Votes], [Total Votes], [Percentage], [Winner], [Winner Candidate], [Eliminated], [Elem. Candidate], + ..data.map( + row => keys.map( + key => { + let value = row.at(key, default: [n/a]) + if key == "percentage" { + value = calc.round(value*10)/10 + } + [#value] + } + ) + ).flatten() + ) +} + +// Returns the results for each iteration of voting +#let vote(ballots, method: "Plurality", tie-method : "All" ) = { + let ballots = json.encode(ballots) + let args = "{ + \"ballots\": "+ballots+", + \"vote_method\": \""+method+"\", + \"tie_method\": \""+tie-method+"\" + }" + + json(p.vote(bytes(args))) +} + +// Displays a detailled voting report for each step +#let vote-report(ballots, method: "Plurality", tie-method : "All", level-start : 4) = { + let vote_results = vote(ballots, method : method, tie-method : tie-method) + + [ + #heading(level: level-start)[Report] + + #heading(level: level-start+1)[Method] + + We performed a *#method-link(method)* vote with *#tie-method* tie-breaking. + + ] + + let max_rounds = calc.max(..vote_results.map(r => r.run)) + let winners = vote_results.filter(r => r.is_winner) + + [ + #heading(level: level-start+1)[Results] + + The vote finished after *#max_rounds* rounds. + + The winner(s) is/are: + #winners.map(w => [- *#w.candidate*]).join() + + #heading(level: level-start+2)[Details] + ] + + for i in range(1, max_rounds + 1) { + let round_results = vote_results.filter(r => r.run == i) + let winner_candidates = round_results.filter(r => r.is_winner_candidate).map(r => r.candidate) + let winners = round_results.filter(r => r.is_winner) + let elimination_candidates = round_results.filter(r => r.is_elimination_candidate).map(r => r.candidate) + let eliminated = round_results.filter(r => r.is_eliminated) + + let block_winner = [ We have not determined a winner yet. ] + + + [ + + #heading(level: level-start+3)[Round #i] + + We performed the #xth(i) round of the vote: + + #details-table-json(round_results) + ] + + if winner_candidates.len() == 0 { + [ We have no winner candidates in this round. + + ] + } + if winner_candidates.len() == 1 { + [ + We have found a winner: *#winner_candidates.first()*. + + ] + } + if winner_candidates.len() > 1 { + [ We have multiple winner candidates: #winner_candidates.map(c => [*#c*]).join([, ]) + + We need to break the tie. The tie-breaking method is *#tie-method*. The final winner(s) is/are: #winners.map(w => [*#w.candidate*]).join([, ]) + + ] + } + + if elimination_candidates.len() == 0 { + [ + We have no elimination candidates in this round. + ] + } + if elimination_candidates.len() == 1 { + [ + We have found an elimination candidate: *#elimination_candidates.first()*. + + ] + } + if elimination_candidates.len() > 1 { + [ We have multiple elimination candidates: #elimination_candidates.map(c => [*#c*]).join(", ") + + We need to break the tie. The tie-breaking method is *#tie-method*. The final eliminated candidate(s) is/are: #eliminated.map(e => [*#e.candidate*]).join([, ]) + + ] + } + } +} \ No newline at end of file diff --git a/packages/preview/comitia/0.1.0/typst.toml b/packages/preview/comitia/0.1.0/typst.toml new file mode 100644 index 0000000000..6d19e59e5a --- /dev/null +++ b/packages/preview/comitia/0.1.0/typst.toml @@ -0,0 +1,18 @@ +[package] +name = "comitia" +version = "0.1.0" +entrypoint = "lib.typ" +authors = ["Tobias Heidler"] +license = "MIT" +description = "Explore voting mechanisms and produce clear results." + +repository = "https://github.com/pteridin/typst-comitia" +keywords = [ + "voting", + "election", + "stv", + "plurality", + "democracy" +] +exclude = ["examples", "example.typ"] +categories = ["utility","fun"]