NAME
Voting::VoteFairRanking - Calculates VoteFair Ranking results
VERSION
Version 4.90
SYNOPSIS
VoteFair Ranking is described at www.VoteFair.org and in the book "Ending The Hidden Unfairness In U.S. Elections" by Richard Fobes. The components of VoteFair Ranking that are implemented here are briefly described below in the ABOUT section.
The following sample code executes this module.
use Voting::VoteFairRanking;
&Voting::VoteFairRanking::votefair_read_calculate_write( );This usage assumes that you supply via STDIN (standard input) a file that contains the appropriately formatted election/survey/poll data, and that you direct the output via STDOUT (standard output) to a file. These input and output files can be handled most easily by using Vote-Info-Split-Join (VISJ) files, which are available on GitHub in the CPSolver account. The VISJ framework uses the Language::Dashrep module.
Alternatively, this module can be accessed from any Perl software by directly using these subroutines:
votefair_put_next_vote_info_number
votefair_do_calculations_all_questions
votefair_get_next_result_info_number
(c) Copyright 1991 through 2011 Richard Fobes at www.VoteFair.org. You can redistribute and/or modify this VoteFairRanking library module under the Perl Artistic license version 2.0 (a copy of which is included in the LICENSE file). As required by the license this full copyright notice must be included in all copies of this software.
Conversion of this code into another programming language is also covered by the above license terms.
The mathematical algorithms of VoteFair Ranking are in the public domain.
ABOUT
This module calculates VoteFair Ranking results. The portions of VoteFair Ranking implemented here are:
VoteFair popularity ranking. This voting method calculates the full popularity ranking of all candidates (or choices in the case of a survey) from most popular and second-most popular down to least popular. It uses the preference information collected on 1-2-3 ballots (or any equivalent way of expressing "ranked" preferences). When a single position is being filled, the most popular candidate is declared the winner. This calculation method is mathematically equivalent to the Condorcet-Kemeny election method.
VoteFair representation ranking. This voting method is used to elect a second candidate who represents the voters who are not well-represented by the most-popular candidate, or to fill multiple board-of-director positions, or to choose a second simultaneous activity in addition to the most popular activity. This method reduces the influence of the voters who are already well-represented by the most popular candidate (or choice), and it does so in a way that protects against strategic voting. If instead the second-most popular candidate as identified by VoteFair popularity ranking were chosen, the same voters who prefer the first winner also can determine the second winner, and this can leave large numbers of other voters unrepresented. Additional levels of representation ranking can be used to fill additional seats, although VoteFair partial-proportional ranking should be used instead if "proportional representation" is important.
VoteFair party ranking. This voting method ranks political parties according to a different kind of "popularity". The results can be used in high-stakes elections to limit the number of candidates allowed by each party. In such cases the two or three political parties that are ranked highest can be limited to offering just two candidates from each party, and lower-ranked parties can be allowed to offer one candidate each, and any additional parties can be prohibited from offering any candidate (because those parties are too unpopular and too unrepresentative). Such limits have not been needed in the past because the fear of vote splitting has limited each political party to offering just one candidate in each contest.
For detailed descriptions of VoteFair Ranking, see www.VoteFair.org or the book "Ending The Hidden Unfairness In U.S. Elections" by Richard Fobes.
In addition to being useful for elections, VoteFair Ranking also is useful for calculating results for surveys and polls, ranking the popularity of songs and movies, and much more.
In mathematical terms, VoteFair Ranking is useful for doing "combinatorial optimization" and may be useful for solving the "linear ordering problem". See Wikipedia for details about these terms.
EXPORT
The following subroutines are exported:
votefair_read_calculate_write
votefair_put_next_vote_info_number
votefair_do_calculations_all_questions
votefair_get_next_result_info_number
votefair_put_input_string
votefair_get_output_string
votefair_always_do_rep_and_party_ranking
votefair_start_new_cases
FUNCTIONS
votefair_read_calculate_write
Reads numbers from the standard input file, does all the requested calculations, and writes requested results to the standard output file. In most election situations this is the only subroutine that needs to be used.
votefair_put_next_vote_info_number
Adds the next input vote-info number to the list that stores the input data. The meaning of the negative numbers are explained in an output file that this module creates.
votefair_get_next_result_info_number
Gets the next result-info number from the list that stores the result information.
votefair_put_input_string
Interprets an input text string that contains vote-info data (for all cases). Unlike the votefair_put_next_vote_info_number subroutine, this string can contain easy-to-type codes instead of numeric-only codes. These codes are useful for testing this module, and for supplying a hypothetical voting scenario that is typed rather than collected through ballots.
votefair_get_output_string
Creates a text string that contains all the results in a person-readable code. It is useful for testing this module, and to allow a person to directly (although cryptically) read the results.
votefair_do_calculations_all_questions
Does the requested calculations for all the questions (although other subroutines do the actual calculations).
votefair_start_new_cases
Does initialization again so that another batch of cases of data can be processed. Normally this subroutine is not needed because all the cases (each with independent questions and preferences) are done in one batch.
votefair_always_do_rep_and_party_ranking
Requests that VoteFair representation ranking and VoteFair party ranking always be done -- except when only plurality votes are requested (because in those cases 1-2-3 ballots have not been used).
calc_votefair_popularity_rank
(Not exported, for internal use only.)
Handles the overhead actions for calculating VoteFair popularity ranking results, as described in the book "Ending The Hidden Unfairness In U.S. Elections", and as described in Wikipedia as the "Condorcet-Kemeny method" (which redirects to the "Kemeny-Young method" article). See VoteFair.org for details.
These results are used in situations where a single seat is being filled (and there is only one such seat), or to determine the full ranking of choices, or to correctly identify the least-popular choice (where that choice is a contestant who is eliminated before the next round of the contest).
calc_votefair_representation_rank
(Not exported, for internal use only.)
Calculates VoteFair representation ranking results, as described in the book "Ending The Hidden Unfairness In U.S. Elections." These results are used in situations where more than one choice is selected, such as when there is more than one seat being filled, or when there is more than one activity (for participation) being offered at the same time (and attendance at both activities is not possible). The first-most representative choice is the most popular based on VoteFair popularity ranking, which is calculated before arriving here. Therefore, this subroutine identifies the VoteFair-based second-most representative, third-most representative, etc. choices in an election.
calc_votefair_party_rank
(Not exported, for internal use only.)
Calculates VoteFair party ranking results, as described in the book "Ending The Hidden Unfairness In U.S. Elections." These results are used to determine the maximum number of candidates each political party is allowed to offer in one election. The number of allowed candidates will vary according to the election type, with less-important elections not having any limits, and very important elections, such as for U.S. President, allowing two candidates each from the first-ranked and second-ranked parties, one candidate each from the next three or four parties, and no candidates from any other parties.
calc_all_sequence_scores
(Not exported, for internal use only.)
Calculates VoteFair popularity ranking results by calculating every sequence score to find the highest score, and regarding the sequence (ranking) with the highest score to be the overall ranking. For details, see www.VoteFair.org or Wikipedia's "Condorcet-Kemeny method" article (which currently redirects to the "Kemeny-Young method" article) or the book titled "Ending The Hidden Unfairness In U.S. Elections".
If multiple sequences have the same highest score, calculate the average sequence position for each choice (but only for the sequences that have the highest score), and then normalize (remove gaps from) those rankings.
do_full_initialization
(Not exported, for internal use only.)
Initializes all the global values and constants. It is always done at the beginning of executing this module. It is also executed if a new (second or later) set of cases is calculated.
write_numeric_code_definitions
(Not exported, for internal use only.)
Write to an output file Dashrep definitions that associate negative code numbers -- that are used for input data and output results -- with text-based names for those values.
check_vote_info_numbers
(Not exported, for internal use only.)
Checks the validity of the numbers in the vote-info list, and requests skipping any cases or questions that contain invalid data. Also, counts the number of questions in each case, and counts the choices in each question.
calculate_results_for_one_question
(Not exported, for internal use only.)
Calculates voting results for one question (contest) in an election/poll/survey.
set_all_choices_as_used
(Not exported, for internal use only.)
Specifies that all the choices (for the current question) are used (non-ignored).
reset_ballot_info_and_tally_table
(Not exported, for internal use only.)
Restarts the counting of ballot information at the first ballot (in the current case). Also sets up the adjusted (alias) choice numbers and pair counters to exclude the choices being ignored. Also creates and initializes the tally table.
get_numbers_based_on_one_ballot
(Not exported, for internal use only.)
Gets the preference information from the next ballot. This information may include an optional multiple-ballot count that indicates how many ballots have the same specified preferences.
add_preferences_to_tally_table
(Not exported, for internal use only.)
Adds to the tally table the just-acquired preference numbers (from the current ballot).
normalize_ranking
(Not exported, for internal use only.)
Normalizes ranking levels so that ranking levels are sequential integer numbers (with no numbers skipped).
put_next_result_info_number
(Not exported, for internal use only.)
Puts the next result-info number into the array that stores the result information.
output_plurality_counts
(Not exported, for internal use only.)
Puts into the output results the plurality counts.
output_tally_table_numbers
(Not exported, for internal use only.)
Puts the pairwise counts from the tally table into the output list.
output_ranking_results
(Not exported, for internal use only.)
Outputs the results of the requested VoteFair Ranking results. These results are supplied in two forms: in their sequence order, and in order of their choice number.
AUTHOR
Richard Fobes, <fobes at CPAN.org>
BUGS
Please report any bugs or feature requests on GitHub, at the CPSolver account, in the VoteFairRanking project area. Thank you!
SUPPORT
You can find documentation for this module on GitHub, in the CPSolver account, in the VoteFairRanking project area.
You can find details about VoteFair Ranking at: www.VoteFair.org
ACKNOWLEDGEMENTS
Richard Fobes designed VoteFair Ranking and developed the original version of this code over a period of many years. Richard Fobes is the author of the books titled "The Creative Problem Solver's Toolbox" and "Ending The Hidden Unfairness In U.S. Elections."
COPYRIGHT & LICENSE
(c) Copyright 1991 through 2011 Richard Fobes at www.VoteFair.org. You can redistribute and/or modify this VoteFairRanking library module under the Perl Artistic license version 2.0 (a copy of which is included in the LICENSE file). As required by the license this full copyright notice must be included in all copies of this software.
Conversion of this code into another programming language is also covered by the above license terms.
The mathematical algorithms of VoteFair Ranking are in the public domain.