Class NaturalRanking
- All Implemented Interfaces:
Function<double[],
,double[]> UnaryOperator<double[]>
,RankingAlgorithm
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 generator of random values in [0, x)
can be supplied as a IntUnaryOperator
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:
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 ClassesModifier and TypeClassDescriptionprivate static class
Represents the position of adouble
value in a data array.private static class
An expandable list of int values. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final DoubleUnaryOperator
Raise an exception for values.private static final DoubleUnaryOperator
Map values to negative infinity.private static final DoubleUnaryOperator
Map values to positive infinity.private static final NaNStrategy
Default NaN strategy.private static final TiesStrategy
Default ties strategy.private final NaNStrategy
NaN strategy.private static final String
Message for a null user-suppliedNaNStrategy
.private static final String
Message for a null user-supplied source of randomness.private static final String
Message for a null user-suppliedTiesStrategy
.private IntUnaryOperator
Source of randomness when ties strategy is RANDOM.private final TiesStrategy
Ties strategy. -
Constructor Summary
ConstructorsModifierConstructorDescriptionCreates an instance withNaNStrategy.FAILED
andTiesStrategy.AVERAGE
.NaturalRanking
(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, 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, IntUnaryOperator randomIntFunction) NaturalRanking
(TiesStrategy tiesStrategy) Creates an instance withNaNStrategy.FAILED
and the specified @tiesStrategy
. -
Method Summary
Modifier and TypeMethodDescriptiondouble[]
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, DoubleUnaryOperator nanAction) Creates the rank data.private 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
.Return theNaNStrategy
.private IntUnaryOperator
Gets the function to map positivex
randomly to[0, x)
.Return theTiesStrategy
.private void
resolveTie
(double[] ranks, NaturalRanking.IntList tiesTrace, int finalIndex) Resolve a sequence of ties, using the configuredTiesStrategy
.
-
Field Details
-
NULL_NAN_STRATEGY
Message for a null user-suppliedNaNStrategy
.- See Also:
-
NULL_TIES_STRATEGY
Message for a null user-suppliedTiesStrategy
.- See Also:
-
NULL_RANDOM_SOURCE
Message for a null user-supplied source of randomness.- See Also:
-
DEFAULT_NAN_STRATEGY
Default NaN strategy. -
DEFAULT_TIES_STRATEGY
Default ties strategy. -
ACTION_POS_INF
Map values to positive infinity. -
ACTION_NEG_INF
Map values to negative infinity. -
ACTION_ERROR
Raise an exception for values. -
nanStrategy
NaN strategy. -
tiesStrategy
Ties strategy. -
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 Details
-
NaturalRanking
public NaturalRanking()Creates an instance withNaNStrategy.FAILED
andTiesStrategy.AVERAGE
. -
NaturalRanking
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:
NullPointerException
- if the strategy isnull
-
NaturalRanking
Creates an instance with the specified @nanStrategy
andTiesStrategy.AVERAGE
.- Parameters:
nanStrategy
- NaNStrategy to use.- Throws:
NullPointerException
- if the strategy isnull
-
NaturalRanking
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:
NullPointerException
- if any strategy isnull
-
NaturalRanking
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:
NullPointerException
- if the source of randomness isnull
-
NaturalRanking
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:
NullPointerException
- if the strategy or source of randomness arenull
-
NaturalRanking
private NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy, IntUnaryOperator randomIntFunction) - Parameters:
nanStrategy
- NaNStrategy to use.tiesStrategy
- TiesStrategy to use.randomIntFunction
- Source of random index data.
-
-
Method Details
-
getNanStrategy
Return theNaNStrategy
.- Returns:
- the strategy for handling NaN
-
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 interfaceFunction<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:
IllegalArgumentException
- if the selectedNaNStrategy
isFAILED
and aDouble.NaN
is encountered in the input data.
-
createRankData
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:
IllegalArgumentException
- if the data contains NaN values when usingNaNStrategy.FAILED
.
-
createNaNAction
Creates the NaN action.- Parameters:
nanCount
- Output counter for NaN values.- Returns:
- the operator applied to NaN values
-
createNonNaNRankData
Creates the rank data with NaNs removed.- Parameters:
data
- Source data.- Returns:
- the rank data
-
createMappedRankData
private static NaturalRanking.DataPosition[] createMappedRankData(double[] data, DoubleUnaryOperator nanAction) Creates the rank data.- Parameters:
data
- Source data.nanAction
- Mapping operator applied to NaN values.- Returns:
- the rank data
-
resolveTie
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
Setsdata[i] = value
for each i intiesTrace
.- Parameters:
data
- Array to modify.tiesTrace
- List of index values to set.value
- Value to set.
-
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
-