org.apache.commons.math3.stat.ranking
Class NaturalRanking

java.lang.Object
  extended by org.apache.commons.math3.stat.ranking.NaturalRanking
All Implemented Interfaces:
RankingAlgorithm

public class NaturalRanking
extends java.lang.Object
implements RankingAlgorithm

Ranking based on the natural ordering on doubles.

NaNs are treated according to the configured NaNStrategy and ties are handled using the selected TiesStrategy. Configuration settings are supplied in optional constructor arguments. Defaults are NaNStrategy.FAILED and TiesStrategy.AVERAGE, respectively. When using TiesStrategy.RANDOM, a RandomGenerator may be supplied as a constructor argument.

Examples:

Input data: (20, 17, 30, 42.3, 17, 50, Double.NaN, Double.NEGATIVE_INFINITY, 17)
NaNStrategyTiesStrategy rank(data)
default (NaNs maximal) default (ties averaged) (5, 3, 6, 7, 3, 8, 9, 1, 3)
default (NaNs maximal) MINIMUM (5, 2, 6, 7, 2, 8, 9, 1, 2)
MINIMAL default (ties averaged) (6, 4, 7, 8, 4, 9, 1.5, 1.5, 4)
REMOVED SEQUENTIAL (5, 2, 6, 7, 3, 8, 1, 4)
MINIMAL MAXIMUM (6, 5, 7, 8, 5, 9, 2, 2, 5)

Since:
2.0
Version:
$Id: NaturalRanking.java 1416643 2012-12-03 19:37:14Z tn $

Nested Class Summary
private static class NaturalRanking.IntDoublePair
          Represents the position of a double value in an ordering.
 
Field Summary
static NaNStrategy DEFAULT_NAN_STRATEGY
          default NaN strategy
static TiesStrategy DEFAULT_TIES_STRATEGY
          default ties strategy
private  NaNStrategy nanStrategy
          NaN strategy - defaults to NaNs maximal
private  RandomData randomData
          Source of random data - used only when ties strategy is RANDOM
private  TiesStrategy tiesStrategy
          Ties strategy - defaults to ties averaged
 
Constructor Summary
NaturalRanking()
          Create a NaturalRanking with default strategies for handling ties and NaNs.
NaturalRanking(NaNStrategy nanStrategy)
          Create a NaturalRanking with the given NaNStrategy.
NaturalRanking(NaNStrategy nanStrategy, RandomGenerator randomGenerator)
          Create a NaturalRanking with the given NaNStrategy, TiesStrategy.RANDOM and the given source of random data.
NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy)
          Create a NaturalRanking with the given NaNStrategy and TiesStrategy.
NaturalRanking(RandomGenerator randomGenerator)
          Create a NaturalRanking with TiesStrategy.RANDOM and the given RandomGenerator as the source of random data.
NaturalRanking(TiesStrategy tiesStrategy)
          Create a NaturalRanking with the given TiesStrategy.
 
Method Summary
private  boolean containsNaNs(NaturalRanking.IntDoublePair[] ranks)
          Checks for presence of NaNs in ranks.
private  void fill(double[] data, java.util.List<java.lang.Integer> tiesTrace, double value)
          Setsdata[i] = value for each i in tiesTrace.
private  java.util.List<java.lang.Integer> getNanPositions(NaturalRanking.IntDoublePair[] ranks)
          Returns a list of indexes where ranks is NaN.
 NaNStrategy getNanStrategy()
          Return the NaNStrategy
 TiesStrategy getTiesStrategy()
          Return the TiesStrategy
 double[] rank(double[] data)
          Rank data using the natural ordering on Doubles, with NaN values handled according to nanStrategy and ties resolved using tiesStrategy.
private  void recodeNaNs(NaturalRanking.IntDoublePair[] ranks, double value)
          Recodes NaN values to the given value.
private  NaturalRanking.IntDoublePair[] removeNaNs(NaturalRanking.IntDoublePair[] ranks)
          Returns an array that is a copy of the input array with IntDoublePairs having NaN values removed.
private  void resolveTie(double[] ranks, java.util.List<java.lang.Integer> tiesTrace)
          Resolve a sequence of ties, using the configured TiesStrategy.
private  void restoreNaNs(double[] ranks, java.util.List<java.lang.Integer> nanPositions)
          Set ranks[i] = Double.NaN for each i in nanPositions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_NAN_STRATEGY

public static final NaNStrategy DEFAULT_NAN_STRATEGY
default NaN strategy


DEFAULT_TIES_STRATEGY

public static final TiesStrategy DEFAULT_TIES_STRATEGY
default ties strategy


nanStrategy

private final NaNStrategy nanStrategy
NaN strategy - defaults to NaNs maximal


tiesStrategy

private final TiesStrategy tiesStrategy
Ties strategy - defaults to ties averaged


randomData

private final RandomData randomData
Source of random data - used only when ties strategy is RANDOM

Constructor Detail

NaturalRanking

public NaturalRanking()
Create a NaturalRanking with default strategies for handling ties and NaNs.


NaturalRanking

public NaturalRanking(TiesStrategy tiesStrategy)
Create a NaturalRanking with the given TiesStrategy.

Parameters:
tiesStrategy - the TiesStrategy to use

NaturalRanking

public NaturalRanking(NaNStrategy nanStrategy)
Create a NaturalRanking with the given NaNStrategy.

Parameters:
nanStrategy - the NaNStrategy to use

NaturalRanking

public NaturalRanking(NaNStrategy nanStrategy,
                      TiesStrategy tiesStrategy)
Create a NaturalRanking with the given NaNStrategy and TiesStrategy.

Parameters:
nanStrategy - NaNStrategy to use
tiesStrategy - TiesStrategy to use

NaturalRanking

public NaturalRanking(RandomGenerator randomGenerator)
Create a NaturalRanking with TiesStrategy.RANDOM and the given RandomGenerator as the source of random data.

Parameters:
randomGenerator - source of random data

NaturalRanking

public NaturalRanking(NaNStrategy nanStrategy,
                      RandomGenerator randomGenerator)
Create a NaturalRanking with the given NaNStrategy, TiesStrategy.RANDOM and the given source of random data.

Parameters:
nanStrategy - NaNStrategy to use
randomGenerator - source of random data
Method Detail

getNanStrategy

public NaNStrategy getNanStrategy()
Return the NaNStrategy

Returns:
returns the NaNStrategy

getTiesStrategy

public TiesStrategy getTiesStrategy()
Return the TiesStrategy

Returns:
the TiesStrategy

rank

public double[] rank(double[] data)
Rank data using the natural ordering on Doubles, with NaN values handled according to nanStrategy and ties resolved using tiesStrategy.

Specified by:
rank in interface RankingAlgorithm
Parameters:
data - array to be ranked
Returns:
array of ranks
Throws:
NotANumberException - if the selected NaNStrategy is FAILED and a Double.NaN is encountered in the input data

removeNaNs

private NaturalRanking.IntDoublePair[] removeNaNs(NaturalRanking.IntDoublePair[] ranks)
Returns an array that is a copy of the input array with IntDoublePairs having NaN values removed.

Parameters:
ranks - input array
Returns:
array with NaN-valued entries removed

recodeNaNs

private void recodeNaNs(NaturalRanking.IntDoublePair[] ranks,
                        double value)
Recodes NaN values to the given value.

Parameters:
ranks - array to recode
value - the value to replace NaNs with

containsNaNs

private boolean containsNaNs(NaturalRanking.IntDoublePair[] ranks)
Checks for presence of NaNs in ranks.

Parameters:
ranks - array to be searched for NaNs
Returns:
true iff ranks contains one or more NaNs

resolveTie

private void resolveTie(double[] ranks,
                        java.util.List<java.lang.Integer> tiesTrace)
Resolve a sequence of ties, using the configured TiesStrategy. The input ranks array is expected to take the same value for all indices in tiesTrace. The common value is recoded according to the tiesStrategy. For example, if ranks = <5,8,2,6,2,7,1,2>, tiesTrace = <2,4,7> and tiesStrategy is MINIMUM, ranks will be unchanged. The same array and trace with tiesStrategy AVERAGE will come out <5,8,3,6,3,7,1,3>.

Parameters:
ranks - array of ranks
tiesTrace - list of indices where ranks is constant -- that is, for any i and j in TiesTrace, ranks[i] == ranks[j]

fill

private void fill(double[] data,
                  java.util.List<java.lang.Integer> tiesTrace,
                  double value)
Setsdata[i] = value for each i in tiesTrace.

Parameters:
data - array to modify
tiesTrace - list of index values to set
value - value to set

restoreNaNs

private void restoreNaNs(double[] ranks,
                         java.util.List<java.lang.Integer> nanPositions)
Set ranks[i] = Double.NaN for each i in nanPositions.

Parameters:
ranks - array to modify
nanPositions - list of index values to set to Double.NaN

getNanPositions

private java.util.List<java.lang.Integer> getNanPositions(NaturalRanking.IntDoublePair[] ranks)
Returns a list of indexes where ranks is NaN.

Parameters:
ranks - array to search for NaNs
Returns:
list of indexes i such that ranks[i] = NaN


Copyright (c) 2003-2013 Apache Software Foundation