The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Vote::Count::Matrix

VERSION 2.04

Win-Loss Matrix

Condorcet Pairwise Methods require a Win-Loss Matrix. This object takes an RCV BallotSet with an optional Active list and returns the Matrix as an object. The object is capable of Scoring itself, Calculating a Smith Set, and identifying Condorcet Winners and Losers.

SYNOPSIS

my $Matrix =
  Vote::Count::Matrix->new(
    'BallotSet' => $myVoteCount->BallotSet() );
  my $Scores = $Matrix->ScoreMatrix();
  my %DominantSet = $Matrix->SmithSet()->%*;
  my $CondorcetWinner = $Matrix->CondorcetWinner();

Tie Breakers

A tie breaker may be specified by setting the Tie::Breaker attribute, see the Tie::Breaker module for more information. If using Range Ballots 'none' and 'approval' are the only currently supported options.

new

Parameters:

BallotSet (required)

A Ballot Set reference as generated by ReadBallots, which can be retrieved from a Vote::Count object via the ->BallotSet() method.

Both Ranked Choice and Range BallotSets are supported.

Active (optional)

A hash reference with active choices as the keys. The default value is all of the choices defined in the BallotSet.

Logging (optional)

Has the logging methods of L.

Methods

MatrixTable

Returns a MarkDown formatted table with the wins losses and ties for each Active Choice as text.

PairingVotesTable

Returns a MarkDown formatted table with the votes for all of the pairings.

GetPairResult ( $A, $B )

Returns the results of the pairing of two choices as a hashref.

{
 'FUDGESWIRL' =>  6,
 'loser'      =>  "STRAWBERRY",
 'margin'     =>  2,
 'STRAWBERRY' =>  4,
 'tie'        =>  0,
 'winner'     =>  "FUDGESWIRL"
}

GetPairWinner ( $A, $B )

Returns the winner of the pairing of two choices. If there is no Winner it returns a false value (empty string).

ScoreMatrix

Returns a HashRef of the choices and their Matrix Scores. The scoring is 1 for each win, 0 for losses and ties. In the event a choice has ties but no wins their score will be .001. Where N is the number of choices, a Condorcet Winner will have a score of N-1, a Condorcet Loser will have a score of 0. Since a choice with at least one tie but no wins is not defeated by all other choices they are not a Condorcet Loser, and thus those cases are scored with a near to zero value instead of 0. Methods that wish to treat no wins but tie case as a Condorcet Loser may test for a score less than 1.

ScoreTable

Returns the ScoreMatrix as a markdown compatible table.

LeastWins

Returns an array of the choice or choices with the fewest wins.

CondorcetLoser

Eliminates all Condorcet Losers from the Matrix Object's Active list. Returns a hashref. Takes an optional true false argument (default is false) to include choices that have tied but not won in the elimination.

{
  verbose => 'verbose message',
  terse   => 'terse message',
  eliminated => [ eliminated choices ],
  eliminations => number of eliminated choices,
};

CondorcetWinner

Returns either the Condorcet Winner or an empty string if there is none.

SmithSet

Finds the innermost Smith Set (Dominant Set). [ assistance in finding proof of the algorithm used would be appreciated so it could be correctly referenced in this documentation ]. A Dominant Set is a set which defeats all choices outside of that set. The inner Smith Set is the smallest possible Dominant Set.

Returns a hashref with the keys as the choices of the Smith Set.

ResetActive

Reset Active list to the choices list of the BallotSet.

GreatestLoss

Returns the greatest loss for a choice $MyMatrix->GreatestLoss( $A ).

RankGreatestLoss

Returns a RankCount object of the Greatest Loss for each choice.

BUG TRACKER

https://github.com/brainbuz/Vote-Count/issues

AUTHOR

John Karr (BRAINBUZ) brainbuz@cpan.org

CONTRIBUTORS

Copyright 2019-2021 by John Karr (BRAINBUZ) brainbuz@cpan.org.

LICENSE

This module is released under the GNU Public License Version 3. See license file for details. For more information on this license visit http://fsf.org.

SUPPORT

This software is provided as is, per the terms of the GNU Public License. Professional support and customisation services are available from the author.