Package org.apache.commons.math3.stat.ranking

Class 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

    • 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 RandomDataGenerator 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