Package org.apache.commons.statistics.ranking

Class 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 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 Detail

      • 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​(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:
        java.lang.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:
        java.lang.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:
        java.lang.NullPointerException - if any strategy is null

      • NaturalRanking

        public NaturalRanking​(java.util.function.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:
        java.lang.NullPointerException - if the source of randomness is null

      • 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 positive x randomly to [0, x)
        Throws:
        java.lang.NullPointerException - if the strategy or source of randomness are null

      • 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 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 java.util.function.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if the data contains NaN values when using NaNStrategy.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 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 java.util.function.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