NAME
    Statistics::RankOrder - Algorithms for determining overall rankings from
    a panel of judges

SYNOPSIS
      use Statistics::RankOrder;

      my $r = Statistics::RankOrder->new();
  
      $r->add_judge( [qw( A B C )] );
      $r->add_judge( [qw( A C B )] );
      $r->add_judge( [qw( B A C )] );

      my %ranks = $r->mean_rank;
      my %ranks = $r->trimmed_mean_rank(1);
      my %ranks = $r->median_rank;
      my %ranks = $r->best_majority_rank;
  
DESCRIPTION
    This module offers algorithms for combining the rank-ordering of
    candidates by a panel of judges. For the purpose of this module, the
    term "candidates" means candidates in an election, brands in a
    taste-test, competitors in a sporting event, and so on. "Judges" means
    those rank-ordering the candidates, whether these are event judges,
    voters, etc. Unlike "voting" algorithms (e.g. majority-rule or
    single-transferable-vote), these algorithms require judges to rank-order
    all candidates. (Ties may be permissible for some algorithms).

    Algorithms included are:

    * Lowest-Mean
    * Trimmed-Lowest-Mean
    * Median-Rank
    * Best-of-Majority
    In this alpha version, there is minimal error checking. Future versions
    will have more robust error checking and may have additional ranking
    methods such as pair-ranking methods.

USAGE
  `new'

     $r = Statistics::RankOrder->new();

    Creates a new object with no judges on the panel (i.e. no data);

  `add_judge'

     $r->add_judge( [qw( A B C D E )] );

    Adds a judge to the panel. The single argument is an array-reference
    with the names of candidates ordered from best to worst.

  `best_majority_rank'

     my %ranks = $r->best_majority_rank;

    Ranks candidates according to the "Best-of-Majority" algorithm. The
    median rank is found for each candidate. If there are an even number of
    judges, the worst of the two median ranks is used. The idea behind this
    method is that the result for a candidate represents the worst rank such
    that a majority of judges support that rank or better. Ties in the
    median ranks are broken by the following comparisons, in order, until
    the tie is broken:

    * larger "Size of Majority" (SOM) -- number of judges ranking at median
    rank or better
    * lower "Total Ordinals of Majority" (TOM) -- sum of ordinal rankings of
    judges ranking at median rank or better
    * lower "Total Ordinals" (TO) -- sum of all ordinals from all judges
    If a tie still exists after these comparisons, then the tie stands. (In
    practice, this is generally rare.) When a tie occurs, the next rank
    assigned after the tie is calculated as if the tie had not occured.
    E.g., 1st, 2nd, 2nd, 4th, 5th.

    Returns a hash where the keys are the names of the candidates and the
    values are their rankings, with 1 being best and higher numbers worse.

  `candidates'

     my %candidates = $r->candidates;

    Returns a hash with keys being the names of candidates and the values
    being array references containing the rankings from all judges for each
    candidate.

  `judges'

     my @judges = $r->judges;

    Returns a list of array-references representing the rank-orderings of
    each judge.

  `mean_rank'

     my %ranks = $r->mean_rank;

    Ranks candidates according to the "Lowest Mean Rank" algorithm. The
    average rank is computed for each candidate. The candidate with the
    lowest mean rank is placed 1st, the second lowest mean rank is 2nd, and
    so on. If the mean ranks are the same, the candidates tie for that
    position. When a tie occurs, the next rank assigned after the tie is
    calculated as if the tie had not occured. E.g., 1st, 2nd, 2nd, 4th, 5th.

    Returns a hash where the keys are the names of the candidates and the
    values are their rankings, with 1 being best and higher numbers worse.

  `median_rank'

     my %ranks = $r->median_rank;

    Ranks candidates according to the "Median Rank" algorithm. The median
    rank is found for each candidate. If there are an even number of judges,
    the worst of the two median ranks is used. The idea behind this method
    is that the result for a candidate represents the lowest rank such that
    a majority of judges support that rank or better. The candidate with the
    lowest median rank is placed 1st, the second lowest median rank is 2nd,
    and so on. If the median ranks are the same, the candidates tie for that
    position. When a tie occurs, the next rank assigned after the tie is
    calculated as if the tie had not occured. E.g., 1st, 2nd, 2nd, 4th, 5th.

    Returns a hash where the keys are the names of the candidates and the
    values are their rankings, with 1 being best and higher numbers worse.

  `trimmed_mean_rank'

     my %ranks = $r->trimmed_mean_rank( N );

    Ranks candidates according to the "Trimmed Lowest Mean Rank" algorithm.
    The average rank is computed for each candidate after dropping the N
    lowest and N highest scores. E.g. `trimmed_mean_rank(2)' will drop the 2
    lowest and highest scores. The candidate with the lowest mean rank is
    placed 1st, the second lowest mean rank is 2nd, and so on. If the mean
    ranks are the same, the candidates tie for that position. When a tie
    occurs, the next rank assigned after the tie is calculated as if the tie
    had not occured. E.g., 1st, 2nd, 2nd, 4th, 5th.

    Returns a hash where the keys are the names of the candidates and the
    values are their rankings, with 1 being best and higher numbers worse.

SEE ALSO
    * Lingua::EN::Number::Ordinate -- for converting "1" to "1st", etc.
    For further details on various ranking methods, in particular, the "Best
    of Majority" method, see the following articles:

    * "Rating Skating", Gilbert W. Basset and Joseph Persky, Journal of the
    American Statistical Association, volume 89, Issue 427 (Sept 1994), pp.
    1075-1079
    * "The Canadians Should Have Won!?", Maureen T. Carroll, Elyn K. Rykken,
    and Jody M. Sorensen.
    http://mathcs.muhlenberg.edu/~rykken/skating-full.pdf
INSTALLATION
    The following commands will build, test, and install this module:

     perl Build.PL
     perl Build
     perl Build test
     perl Build install

BUGS
    Please report bugs using the CPAN Request Tracker at
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=Statistics-RankOrder

AUTHOR
    David A Golden (DAGOLDEN)

    dagolden@cpan.org

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2005 by David A Golden

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

