com.threerings.parlor.rating.util
Class Percentiler

java.lang.Object
  com.threerings.parlor.rating.util.Percentiler

public class Percentiler
extends Object

Used to keep track of the percentile distribution of positive values (generally puzzle scores).

Field Summary

protected int[]	_counts A histogram of all values recorded to this percentiler.
protected boolean	_fixedRange If this Percentiler was created with a fixed range.
protected int	_max The maximum value seen by this percentiler.
protected int	_min The minimum value seen by this percentiler.
protected int	_nextRecomp Counts down to our next recalculation.
protected byte[]	_percentile The percentile associated with each bucket.
protected byte[]	_reverse The bucket associated with each percentile.
protected long	_snapTotal The value of _total at creation time or as of a call to clearModified().
protected long	_total The total number of data points seen by this percentiler.
protected static int	BUCKET_COUNT The number of divisions between zero and our maximum value, which defines the granularity of our histogram.
protected static int	INT_SIZE Number of bytes in an int; makes code clearer.

Constructor Summary

Percentiler()
Creates an empty percentiler.

Percentiler(byte[] data)
Creates a percentiler from its serialized representation.

Percentiler(int min, int max)
Creates a percentiler that expects values to fall within the given range.

Method Summary

void	clearModified() Clears this percentiler's "is modified" state.
void	dump(PrintWriter out) Dumps a text representation of this percentiler to the supplied print stream.
void	dumpGnuPlot(PrintWriter out) Dumps out our data in a format that can be used to generate a gnuplot.
int[]	getCounts() Returns the counts for each bucket.
int	getMaxScore() Returns the largest score seen by this percentiler.
int	getMinScore() Returns the smallest score seen by this percentiler.
int	getPercentile(float value) Returns the percent of all numbers seen that are lower than the specified value.
long	getRecordedCount() Returns the total number of values ever recorded to this percentiler.
float	getRequiredScore(int percentile) Returns the score necessary to attain the specified percentile.
float[]	getRequiredScores() Returns the scores required to obtain a percentile rating from 0 to 99.
boolean	isModified() Returns true if thsi percentiler has been modified since it was created or since the last call to clearModified().
void	recomputePercentiles() Recomputes the percentile cutoffs based on the values recorded since the last percentile computation.
void	recordValue(float value) Records a value, updating the histogram but not the percentiles (a call to recomputePercentiles() is required for that and is sufficiently expensive that it shouldn't be done every time a value is added).
void	recordValue(float value, boolean logNewMax) See recordValue(float).
protected String	spaces(int count)
protected int	toBucketIndex(float value) Returns the histogram bucket to which this value is assigned.
byte[]	toBytes() Converts this percentiler to a byte array so that it may be stored into a database.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

_fixedRange

protected boolean _fixedRange

If this Percentiler was created with a fixed range.

_total

protected long _total

The total number of data points seen by this percentiler.

_snapTotal

protected long _snapTotal

The value of _total at creation time or as of a call to clearModified().

_min

protected int _min

The minimum value seen by this percentiler.

_max

protected int _max

The maximum value seen by this percentiler.

_nextRecomp

protected int _nextRecomp

Counts down to our next recalculation.

_counts

protected int[] _counts

A histogram of all values recorded to this percentiler.

_percentile

protected byte[] _percentile

The percentile associated with each bucket.

_reverse

protected byte[] _reverse

The bucket associated with each percentile.

BUCKET_COUNT

protected static final int BUCKET_COUNT

The number of divisions between zero and our maximum value, which defines the granularity of our histogram.

See Also:

Constant Field Values

INT_SIZE

protected static final int INT_SIZE

Number of bytes in an int; makes code clearer.

See Also:

Constant Field Values

Constructor Detail

Percentiler

public Percentiler()

Creates an empty percentiler.

Percentiler

public Percentiler(int min,
                   int max)

Creates a percentiler that expects values to fall within the given range.

Percentiler

public Percentiler(byte[] data)

Creates a percentiler from its serialized representation.

Method Detail

recordValue

public void recordValue(float value)

Records a value, updating the histogram but not the percentiles (a call to recomputePercentiles() is required for that and is sufficiently expensive that it shouldn't be done every time a value is added).

recordValue

public void recordValue(float value,
                        boolean logNewMax)

See recordValue(float).

getRecordedCount

public long getRecordedCount()

Returns the total number of values ever recorded to this percentiler.

isModified

public boolean isModified()

Returns true if thsi percentiler has been modified since it was created or since the last call to clearModified().

clearModified

public void clearModified()

Clears this percentiler's "is modified" state.

getPercentile

public int getPercentile(float value)

Returns the percent of all numbers seen that are lower than the specified value. This value can range from zero to 100 (100 in the case where this is the highest value ever seen by this percentiler). This value reflects the percentiles computed as of the most recent call to recomputePercentiles().

getRequiredScore

public float getRequiredScore(int percentile)

Returns the score necessary to attain the specified percentile. This value reflects the percentiles computed as of the most recent call to recomputePercentiles().

Parameters:

percentile - the desired percentile (from 0 to 99 inclusive).

getMaxScore

public int getMaxScore()

Returns the largest score seen by this percentiler.

getMinScore

public int getMinScore()

Returns the smallest score seen by this percentiler.

getRequiredScores

public float[] getRequiredScores()

Returns the scores required to obtain a percentile rating from 0 to 99.

getCounts

public int[] getCounts()

Returns the counts for each bucket.

recomputePercentiles

public void recomputePercentiles()

Recomputes the percentile cutoffs based on the values recorded since the last percentile computation.

toBytes

public byte[] toBytes()

Converts this percentiler to a byte array so that it may be stored into a database.

toString

public String toString()

Overrides:

toString in class Object

dumpGnuPlot

public void dumpGnuPlot(PrintWriter out)

Dumps out our data in a format that can be used to generate a gnuplot.

dump

public void dump(PrintWriter out)

Dumps a text representation of this percentiler to the supplied print stream.

spaces

protected final String spaces(int count)

toBucketIndex

protected final int toBucketIndex(float value)

Returns the histogram bucket to which this value is assigned.