org.bolson.vote
Class VotingSystem

java.lang.Object
  org.bolson.vote.VotingSystem

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Approval, DistributiveVSWrapper, EmptyVotingSystem, Histogram, RankedVotingSystem, RatedVotingSystem, SynchronizedVSWrapper

public abstract class VotingSystem
extends java.lang.Object
implements java.io.Serializable

Top level abstract class for ranked or rated voting systems. Most implementations will subclass either RankedVotingSystem or RatedVotingSystem.

See Also:

RankedVotingSystem, RatedVotingSystem, Serialized Form

Field Summary

boolean	debug Debug info collecting flag.
static int	NO_VOTE This value represents that the voter made no action on some choice.
protected int	numc number of candidates

Constructor Summary

VotingSystem(int numCandidates)
In addition to interfaced methods, there shall be a constructor taking the integer number N of choices to be voted on.

Method Summary

boolean	checkRatedVote(int[] rating, int min, int max) squash (sum of absolute value of vote) to (max - min)
java.lang.String	getDebugHTML(java.lang.String[] names) Return HTML representation of debug data.
java.lang.String	getDebugText(java.lang.String[] names) Return textual representation of debug data.
int	getNumberOfCandidates() accessor to read only variable
abstract int[]	getWinners() Do processing if necessary, return winners.
int[]	getWinners(int numSeats) Do processing if necessary, return winners.
int[]	getWinners(java.io.PrintWriter out) Deprecated. use getWinners(), debug, and getDebugText() or getDebugHTML()
int[]	getWinners(java.io.PrintWriter out, int numSeats) Deprecated. use getWinners(int), debug, and getDebugText() or getDebugHTML()
abstract java.lang.String	htmlSummary(java.lang.String[] names) A fancy html representation.
VotingSystem	init(java.lang.String[] argv) Arguments to modify behavior of VotingSystem
boolean	isValidRankedVote(int[] ranking) Checks that ranking is valid.
boolean	isValidRatedVote(int[] rating, int min, int max) Checks that rating is valid.
java.lang.String	name() Return name of this voting system.
static void	normalize(double[] ratings) Divide values by their average
static void	normalize(double[] dest, double[] src) Divide values by their average
static void	normalize(double[] dest, int[] src) Divide values by their average
static void	normalize(float[] ratings) Divide values by their average
static void	normalize(float[] dest, float[] src)
static void	normalizeL2(double[] ratings) Calculate "L2" norm.
static void	normalizeL2(double[] dest, double[] src) Calculate "L2" norm.
static void	normalizeL2(double[] dest, int[] src) Calculate "L2" norm.
static void	normalizeL2(float[] ratings) Calculate "L2" norm.
static void	normalizeL2(float[] dest, float[] src) Calculate "L2" norm.
static void	stretch(double[] vote, float tmin, float tmax) Maximize a vote between bounds.
abstract java.lang.String	toString(java.lang.String[] names) A more interesting representation.
abstract int	voteRanking(int[] ranking)
abstract int	voteRating(double[] rating)
abstract int	voteRating(float[] rating)
abstract int	voteRating(int[] rating)
int	voteRating(java.lang.Object rating)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

numc

protected int numc

number of candidates

debug

public boolean debug

Debug info collecting flag. If true, then an implementation should collect data that can be retreived by getDebugText() and getDebugHTML()

See Also:

getDebugText(String[]), getDebugHTML(String[])

NO_VOTE

public static final int NO_VOTE

This value represents that the voter made no action on some choice. This is the default value. On a YES/NO or HOW MUCH the answer was no answer. For float and double votes NaN is the NO_VOTE value.

See Also:

Constant Field Values

Constructor Detail

VotingSystem

public VotingSystem(int numCandidates)

In addition to interfaced methods, there shall be a constructor taking the integer number N of choices to be voted on.

Method Detail

getDebugText

public java.lang.String getDebugText(java.lang.String[] names)

Return textual representation of debug data. Default implementation returns null.

Parameters:

names - Symbolic names for the choices makes human debugging easier. May be null.

Returns:

debug text (default=null)

See Also:

debug

getDebugHTML

public java.lang.String getDebugHTML(java.lang.String[] names)

Return HTML representation of debug data. Default implementation is: "<PRE>"+getDebugText()+"</PRE>" (except that this method returns null or the empty string if getDebugText() returns null or the empty string).

Parameters:

names - Symbolic names for the choices makes human debugging easier. May be null.

Returns:

debug HTML

See Also:

debug

init

public VotingSystem init(java.lang.String[] argv)

Arguments to modify behavior of VotingSystem

Returns:

this so that you can do

vs = (new VS(numc)).init( new String[]{"blah", "grunt"} );

getNumberOfCandidates

public int getNumberOfCandidates()

accessor to read only variable

Returns:

numc

voteRating

public abstract int voteRating(int[] rating)

Parameters:

rating - An array int[numc]. rating[i] is the rating of choice i. A rating can be any int value. Higher means more preferred. NO_VOTE for unrated.

Returns:

0 on success

voteRating

public abstract int voteRating(float[] rating)

Parameters:

rating - An array int[N]. rating[i] is the rating of choice i. A rating can be any int value. Higher means more preferred. NO_VOTE for unrated.

Returns:

0 on success

voteRating

public abstract int voteRating(double[] rating)

Parameters:

rating - An array int[N]. rating[i] is the rating of choice i. A rating can be any int value. Higher means more preferred. NO_VOTE for unrated.

Returns:

0 on success

voteRating

public int voteRating(java.lang.Object rating)
               throws java.lang.ClassCastException

Parameters:

rating - An array of int, float or double

Returns:

0 on success

Throws:

java.lang.ClassCastException

See Also:

voteRating(int[]), voteRating(float[]), voteRating(double[])

voteRanking

public abstract int voteRanking(int[] ranking)

Parameters:

ranking - An array int[N]. ranking[i] is the ranking of choice i. rankings are 1 (most preferred) through N (least). INT_MAX, N, or NO_VOTE for unspecified.

Returns:

0 on success

checkRatedVote

public boolean checkRatedVote(int[] rating,
                              int min,
                              int max)

squash (sum of absolute value of vote) to (max - min)

Parameters:

rating - vote to check

min - minimum (inclusive) value allowed for rating

max - maximum (inclusive) value allowed for rating

Returns:

true if rating.length == numc AND all values in rating are >= min and <= max

normalize

public static void normalize(double[] ratings)

Divide values by their average

Parameters:

ratings - take average, then devide each element by the average

normalize

public static void normalize(double[] dest,
                             double[] src)

Divide values by their average

Parameters:

src - values to normalize

dest - receives normalized version of src

normalize

public static void normalize(float[] ratings)

Divide values by their average

Parameters:

ratings - take average, then devide each element by the average

normalize

public static void normalize(float[] dest,
                             float[] src)

normalize

public static void normalize(double[] dest,
                             int[] src)

Divide values by their average

Parameters:

src - values to normalize

dest - receives normalized version of src

normalizeL2

public static void normalizeL2(double[] ratings)

Calculate "L2" norm. Divide values by sqrt( sum of squares ).

Parameters:

ratings - take sqrt of the sum of squares, then devide each element by the that

normalizeL2

public static void normalizeL2(double[] dest,
                               double[] src)

Calculate "L2" norm. Divide values by sqrt( sum of squares ).

Parameters:

src - values to normalize

dest - receives normalized version of src

normalizeL2

public static void normalizeL2(float[] ratings)

Calculate "L2" norm. Divide values by sqrt( sum of squares ).

Parameters:

ratings - take sqrt of the sum of squares, then devide each element by the that

normalizeL2

public static void normalizeL2(float[] dest,
                               float[] src)

Calculate "L2" norm. Divide values by sqrt( sum of squares ).

Parameters:

src - values to normalize

dest - receives normalized version of src

normalizeL2

public static void normalizeL2(double[] dest,
                               int[] src)

Calculate "L2" norm. Divide values by sqrt( sum of squares ).

Parameters:

src - values to normalize

dest - receives normalized version of src

isValidRatedVote

public boolean isValidRatedVote(int[] rating,
                                int min,
                                int max)

Checks that rating is valid.

Parameters:

rating - vote to check

min - minimum (inclusive) value allowed for rating

max - maximum (inclusive) value allowed for rating

Returns:

true if rating.length == numc AND all values in rating are >= min and <= max

isValidRankedVote

public boolean isValidRankedVote(int[] ranking)

Checks that ranking is valid.

Parameters:

ranking - vote to check

Returns:

true if rating.length == numc AND all values in rating are >= 1 and <= numc

stretch

public static void stretch(double[] vote,
                           float tmin,
                           float tmax)

Maximize a vote between bounds. Multiply and shift so that the lowest rating becomes equal to tmin and the highest rating becomes equal to tmax.

Parameters:

vote - ratings

tmin - target minimum value

tmax - target maximum value

getWinners

public abstract int[] getWinners()

Do processing if necessary, return winners.

It is recommended to cache the return value in such a way that calling this function again does not do complex recalculation. That cache should be cleared if voteRating or voteRanking is called.

Returns:

indecies of winners (hopefully 1 of them)

getWinners

public int[] getWinners(java.io.PrintWriter out)

Deprecated. use getWinners(), debug, and getDebugText() or getDebugHTML()

Print verbose explaination of internal process as it happens. By default, do no printing and return result of getWinners() .

Parameters:

out - where to print

Returns:

indecies of winners, hopefully 1 of them but in case of ties there may be more. Check .length to be sure.

See Also:

getWinners(), debug, getDebugText(String[]), getDebugHTML(String[])

getWinners

public int[] getWinners(java.io.PrintWriter out,
                        int numSeats)

Deprecated. use getWinners(int), debug, and getDebugText() or getDebugHTML()

Do processing if necessary, return winners. Default implementation returns null so that not all systems have to be multi-seat systems.

Parameters:

out - where to print news and diagnostics

numSeats - the number of seats available.

Returns:

indecies of winners, hopefully numSeats of them but in case of ties there may be more and in case of some internal schism there may be fewer. Check .length to be sure.

See Also:

getWinners(int), debug, getDebugText(String[]), getDebugHTML(String[])

getWinners

public int[] getWinners(int numSeats)

Do processing if necessary, return winners. Default implementation returns null so that not all systems have to be multi-seat systems.

It is recommended to cache the return value in such a way that calling this function again does not do complex recalculation. That cache should be cleared if voteRating or voteRanking is called.

Parameters:

numSeats - the number of seats available.

Returns:

indecies of winners, hopefully numSeats of them but in case of ties there may be more and in case of some internal schism there may be fewer. Check .length to be sure.

toString

public abstract java.lang.String toString(java.lang.String[] names)

A more interesting representation. Include the names of the choices voted upon in the representation.

Parameters:

names - The names of the choices.

Returns:

state, with names!

htmlSummary

public abstract java.lang.String htmlSummary(java.lang.String[] names)

A fancy html representation. Include the names of the choices voted upon in the representation.

Parameters:

names - The names of the choices. May be null.

Returns:

state, with names!

name

public java.lang.String name()

Return name of this voting system. This is a function so that it can potentially construct a detailed name based on options set in init().

Returns:

a descriptive name