Class NaturalRanking

java.lang.Object
org.apache.commons.statistics.ranking.NaturalRanking
All Implemented Interfaces:
Function<double[],double[]>, UnaryOperator<double[]>, RankingAlgorithm
public class NaturalRanking extends Object implements RankingAlgorithm
Ranking based on the natural ordering on floating-point values.

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:

Examples
Input data: [20, 17, 30, 42.3, 17, 50, Double.NaN, Double.NEGATIVE_INFINITY, 17]
NaNStrategyTiesStrategy 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

  • Field Details

    • NULL_NAN_STRATEGY

      private static final String NULL_NAN_STRATEGY
      Message for a null user-supplied NaNStrategy.
      See Also:

    • NULL_TIES_STRATEGY

      private static final String NULL_TIES_STRATEGY
      Message for a null user-supplied TiesStrategy.
      See Also:

    • NULL_RANDOM_SOURCE

      private static final String NULL_RANDOM_SOURCE
      Message for a null user-supplied source of randomness.
      See Also:

    • 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 DoubleUnaryOperator ACTION_POS_INF
      Map values to positive infinity.

    • ACTION_NEG_INF

      private static final DoubleUnaryOperator ACTION_NEG_INF
      Map values to negative infinity.

    • ACTION_ERROR

      private static final DoubleUnaryOperator ACTION_ERROR
      Raise an exception for values.

    • nanStrategy

      private final NaNStrategy nanStrategy
      NaN strategy.

    • tiesStrategy

      private final TiesStrategy tiesStrategy
      Ties strategy.

    • randomIntFunction

      private 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 Details

    • NaturalRanking

      public NaturalRanking()
      Creates an instance with NaNStrategy.FAILED and TiesStrategy.AVERAGE.

    • NaturalRanking

      public NaturalRanking(TiesStrategy tiesStrategy)
      Creates an instance with NaNStrategy.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 is null

    • NaturalRanking

      public NaturalRanking(NaNStrategy nanStrategy)
      Creates an instance with the specified @nanStrategy and TiesStrategy.AVERAGE.
      Parameters:
      nanStrategy - NaNStrategy to use.
      Throws:
      NullPointerException - if the strategy is null

    • 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:
      NullPointerException - if any strategy is null

    • NaturalRanking

      public NaturalRanking(IntUnaryOperator randomIntFunction)
      Creates an instance with NaNStrategy.FAILED, TiesStrategy.RANDOM and the given the source of random index data.
      Parameters:
      randomIntFunction - Source of random index data. Function maps positive x randomly to [0, x)
      Throws:
      NullPointerException - if the source of randomness is null

    • NaturalRanking

      public NaturalRanking(NaNStrategy nanStrategy, 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 positive x randomly to [0, x)
      Throws:
      NullPointerException - if the strategy or source of randomness are null

    • 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

      public NaNStrategy getNanStrategy()
      Return the NaNStrategy.
      Returns:
      the strategy for handling NaN

    • getTiesStrategy

      public TiesStrategy getTiesStrategy()
      Return the TiesStrategy.
      Returns:
      the strategy for handling ties

    • apply

      public double[] apply(double[] data)
      Rank data using the natural ordering on floating-point values, with NaN values handled according to nanStrategy and ties resolved using tiesStrategy.
      Specified by:
      apply in interface Function<double[],double[]>
      Specified by:
      apply in interface RankingAlgorithm
      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 selected NaNStrategy is FAILED and a Double.NaN is encountered in the input data.

    • createRankData

      private NaturalRanking.DataPosition[] createRankData(double[] data, int[] nanCount)
      Creates the rank data. If using NaNStrategy.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 using NaNStrategy.FAILED.

    • createNaNAction

      private 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, 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 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].

      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 where ranks is constant, that is, for any i and j in tiesTrace: 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)
      Sets data[i] = value for each i in tiesTrace.
      Parameters:
      data - Array to modify.
      tiesTrace - List of index values to set.
      value - Value to set.

    • getRandomIntFunction

      private IntUnaryOperator getRandomIntFunction()
      Gets the function to map positive x randomly to [0, x). Defaults to a system provided generator if the constructor source of randomness is null.
      Returns:
      the RNG