Class NaturalRanking
- java.lang.Object
-
- org.apache.commons.statistics.ranking.NaturalRanking
-
- All Implemented Interfaces:
java.util.function.Function<double[],double[]>
,java.util.function.UnaryOperator<double[]>
,RankingAlgorithm
public class NaturalRanking extends java.lang.Object implements RankingAlgorithm
Ranking based on the natural ordering on floating-point values.NaNs
are treated according to the configuredNaNStrategy
and ties are handled using the selectedTiesStrategy
. Configuration settings are supplied in optional constructor arguments. Defaults areNaNStrategy.FAILED
andTiesStrategy.AVERAGE
, respectively.When using
TiesStrategy.RANDOM
, a generator of random values in[0, x)
can be supplied as aIntUnaryOperator
argument; otherwise a default is created on-demand. The source of randomness can be supplied using a method reference. The following example creates a ranking with NaN values with the highest ranking and ties resolved randomly:NaturalRanking ranking = new NaturalRanking(NaNStrategy.MAXIMAL, new SplittableRandom()::nextInt);
Note: Using
TiesStrategy.RANDOM
is not thread-safe due to the mutable generator of randomness. Instances not using random resolution of ties are thread-safe.Examples:
Examples Input data: [20, 17, 30, 42.3, 17, 50, Double.NaN, Double.NEGATIVE_INFINITY, 17] NaNStrategy TiesStrategy rank(data)
MAXIMAL default (ties averaged) [5, 3, 6, 7, 3, 8, 9, 1, 3] 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] MINIMAL MAXIMUM [6, 5, 7, 8, 5, 9, 2, 2, 5] - Since:
- 1.1
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
NaturalRanking.DataPosition
Represents the position of adouble
value in a data array.private static class
NaturalRanking.IntList
An expandable list of int values.
-
Field Summary
Fields Modifier and Type Field Description private static java.util.function.DoubleUnaryOperator
ACTION_ERROR
Raise an exception for values.private static java.util.function.DoubleUnaryOperator
ACTION_NEG_INF
Map values to negative infinity.private static java.util.function.DoubleUnaryOperator
ACTION_POS_INF
Map values to positive infinity.private static NaNStrategy
DEFAULT_NAN_STRATEGY
Default NaN strategy.private static TiesStrategy
DEFAULT_TIES_STRATEGY
Default ties strategy.private NaNStrategy
nanStrategy
NaN strategy.private static java.lang.String
NULL_NAN_STRATEGY
Message for a null user-suppliedNaNStrategy
.private static java.lang.String
NULL_RANDOM_SOURCE
Message for a null user-supplied source of randomness.private static java.lang.String
NULL_TIES_STRATEGY
Message for a null user-suppliedTiesStrategy
.private java.util.function.IntUnaryOperator
randomIntFunction
Source of randomness when ties strategy is RANDOM.private TiesStrategy
tiesStrategy
Ties strategy.
-
Constructor Summary
Constructors Modifier Constructor Description NaturalRanking()
Creates an instance withNaNStrategy.FAILED
andTiesStrategy.AVERAGE
.NaturalRanking(java.util.function.IntUnaryOperator randomIntFunction)
Creates an instance withNaNStrategy.FAILED
,TiesStrategy.RANDOM
and the given the source of random index data.NaturalRanking(NaNStrategy nanStrategy)
Creates an instance with the specified @nanStrategy
andTiesStrategy.AVERAGE
.NaturalRanking(NaNStrategy nanStrategy, java.util.function.IntUnaryOperator randomIntFunction)
Creates an instance with the specified @nanStrategy
,TiesStrategy.RANDOM
and the given the source of random index data.NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy)
Creates an instance with the specified @nanStrategy
and the specified @tiesStrategy
.private
NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy, java.util.function.IntUnaryOperator randomIntFunction)
NaturalRanking(TiesStrategy tiesStrategy)
Creates an instance withNaNStrategy.FAILED
and the specified @tiesStrategy
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description double[]
apply(double[] data)
Rankdata
using the natural ordering on floating-point values, with NaN values handled according tonanStrategy
and ties resolved usingtiesStrategy
.private static NaturalRanking.DataPosition[]
createMappedRankData(double[] data, java.util.function.DoubleUnaryOperator nanAction)
Creates the rank data.private java.util.function.DoubleUnaryOperator
createNaNAction(int[] nanCount)
Creates the NaN action.private static NaturalRanking.DataPosition[]
createNonNaNRankData(double[] data)
Creates the rank data with NaNs removed.private NaturalRanking.DataPosition[]
createRankData(double[] data, int[] nanCount)
Creates the rank data.private static void
fill(double[] data, NaturalRanking.IntList tiesTrace, double value)
Setsdata[i] = value
for each i intiesTrace
.NaNStrategy
getNanStrategy()
Return theNaNStrategy
.private java.util.function.IntUnaryOperator
getRandomIntFunction()
Gets the function to map positivex
randomly to[0, x)
.TiesStrategy
getTiesStrategy()
Return theTiesStrategy
.private void
resolveTie(double[] ranks, NaturalRanking.IntList tiesTrace, int finalIndex)
Resolve a sequence of ties, using the configuredTiesStrategy
.
-
-
-
Field Detail
-
NULL_NAN_STRATEGY
private static final java.lang.String NULL_NAN_STRATEGY
Message for a null user-suppliedNaNStrategy
.- See Also:
- Constant Field Values
-
NULL_TIES_STRATEGY
private static final java.lang.String NULL_TIES_STRATEGY
Message for a null user-suppliedTiesStrategy
.- See Also:
- Constant Field Values
-
NULL_RANDOM_SOURCE
private static final java.lang.String NULL_RANDOM_SOURCE
Message for a null user-supplied source of randomness.- See Also:
- Constant Field Values
-
DEFAULT_NAN_STRATEGY
private static final NaNStrategy DEFAULT_NAN_STRATEGY
Default NaN strategy.
-
DEFAULT_TIES_STRATEGY
private static final TiesStrategy DEFAULT_TIES_STRATEGY
Default ties strategy.
-
ACTION_POS_INF
private static final java.util.function.DoubleUnaryOperator ACTION_POS_INF
Map values to positive infinity.
-
ACTION_NEG_INF
private static final java.util.function.DoubleUnaryOperator ACTION_NEG_INF
Map values to negative infinity.
-
ACTION_ERROR
private static final java.util.function.DoubleUnaryOperator ACTION_ERROR
Raise an exception for values.
-
nanStrategy
private final NaNStrategy nanStrategy
NaN strategy.
-
tiesStrategy
private final TiesStrategy tiesStrategy
Ties strategy.
-
randomIntFunction
private java.util.function.IntUnaryOperator randomIntFunction
Source of randomness when ties strategy is RANDOM. Function maps positive x to[0, x)
. Can be null to default to a JDK implementation.
-
-
Constructor Detail
-
NaturalRanking
public NaturalRanking()
Creates an instance withNaNStrategy.FAILED
andTiesStrategy.AVERAGE
.
-
NaturalRanking
public NaturalRanking(TiesStrategy tiesStrategy)
Creates an instance withNaNStrategy.FAILED
and the specified @tiesStrategy
.If the ties strategy is
RANDOM
a default source of randomness is used to resolve ties.- Parameters:
tiesStrategy
- TiesStrategy to use.- Throws:
java.lang.NullPointerException
- if the strategy isnull
-
NaturalRanking
public NaturalRanking(NaNStrategy nanStrategy)
Creates an instance with the specified @nanStrategy
andTiesStrategy.AVERAGE
.- Parameters:
nanStrategy
- NaNStrategy to use.- Throws:
java.lang.NullPointerException
- if the strategy isnull
-
NaturalRanking
public NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy)
Creates an instance with the specified @nanStrategy
and the specified @tiesStrategy
.If the ties strategy is
RANDOM
a default source of randomness is used to resolve ties.- Parameters:
nanStrategy
- NaNStrategy to use.tiesStrategy
- TiesStrategy to use.- Throws:
java.lang.NullPointerException
- if any strategy isnull
-
NaturalRanking
public NaturalRanking(java.util.function.IntUnaryOperator randomIntFunction)
Creates an instance withNaNStrategy.FAILED
,TiesStrategy.RANDOM
and the given the source of random index data.- Parameters:
randomIntFunction
- Source of random index data. Function maps positivex
randomly to[0, x)
- Throws:
java.lang.NullPointerException
- if the source of randomness isnull
-
NaturalRanking
public NaturalRanking(NaNStrategy nanStrategy, java.util.function.IntUnaryOperator randomIntFunction)
Creates an instance with the specified @nanStrategy
,TiesStrategy.RANDOM
and the given the source of random index data.- Parameters:
nanStrategy
- NaNStrategy to use.randomIntFunction
- Source of random index data. Function maps positivex
randomly to[0, x)
- Throws:
java.lang.NullPointerException
- if the strategy or source of randomness arenull
-
NaturalRanking
private NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy, java.util.function.IntUnaryOperator randomIntFunction)
- Parameters:
nanStrategy
- NaNStrategy to use.tiesStrategy
- TiesStrategy to use.randomIntFunction
- Source of random index data.
-
-
Method Detail
-
getNanStrategy
public NaNStrategy getNanStrategy()
Return theNaNStrategy
.- Returns:
- the strategy for handling NaN
-
getTiesStrategy
public TiesStrategy getTiesStrategy()
Return theTiesStrategy
.- Returns:
- the strategy for handling ties
-
apply
public double[] apply(double[] data)
Rankdata
using the natural ordering on floating-point values, with NaN values handled according tonanStrategy
and ties resolved usingtiesStrategy
.- Specified by:
apply
in interfacejava.util.function.Function<double[],double[]>
- Specified by:
apply
in interfaceRankingAlgorithm
- Parameters:
data
- Array of data to be ranked.- Returns:
- an array of ranks corresponding to the elements of the input array
- Throws:
java.lang.IllegalArgumentException
- if the selectedNaNStrategy
isFAILED
and aDouble.NaN
is encountered in the input data.
-
createRankData
private NaturalRanking.DataPosition[] createRankData(double[] data, int[] nanCount)
Creates the rank data. If usingNaNStrategy.REMOVED
then NaNs are filtered. Otherwise NaNs may be mapped to an infinite value, counted to allow subsequent processing, or cause an exception to be thrown.- Parameters:
data
- Source data.nanCount
- Output counter for NaN values.- Returns:
- the rank data
- Throws:
java.lang.IllegalArgumentException
- if the data contains NaN values when usingNaNStrategy.FAILED
.
-
createNaNAction
private java.util.function.DoubleUnaryOperator createNaNAction(int[] nanCount)
Creates the NaN action.- Parameters:
nanCount
- Output counter for NaN values.- Returns:
- the operator applied to NaN values
-
createNonNaNRankData
private static NaturalRanking.DataPosition[] createNonNaNRankData(double[] data)
Creates the rank data with NaNs removed.- Parameters:
data
- Source data.- Returns:
- the rank data
-
createMappedRankData
private static NaturalRanking.DataPosition[] createMappedRankData(double[] data, java.util.function.DoubleUnaryOperator nanAction)
Creates the rank data.- Parameters:
data
- Source data.nanAction
- Mapping operator applied to NaN values.- Returns:
- the rank data
-
resolveTie
private void resolveTie(double[] ranks, NaturalRanking.IntList tiesTrace, int finalIndex)
Resolve a sequence of ties, using the configuredTiesStrategy
. The inputranks
array is expected to take the same value for all indices intiesTrace
. 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].Note: For convenience the final index of the trace is passed as an argument; it is assumed the list is already non-empty. At the end of the method the list of indices is cleared.
- Parameters:
ranks
- Array of ranks.tiesTrace
- List of indices whereranks
is constant, that is, for any i and j intiesTrace
:ranks[i] == ranks[j]
.finalIndex
- The final index to add to the sequence of ties.
-
fill
private static void fill(double[] data, NaturalRanking.IntList tiesTrace, double value)
Setsdata[i] = value
for each i intiesTrace
.- Parameters:
data
- Array to modify.tiesTrace
- List of index values to set.value
- Value to set.
-
getRandomIntFunction
private java.util.function.IntUnaryOperator getRandomIntFunction()
Gets the function to map positivex
randomly to[0, x)
. Defaults to a system provided generator if the constructor source of randomness is null.- Returns:
- the RNG
-
-