org.apache.commons.math3.stat.ranking

## Class NaturalRanking

- java.lang.Object
- - org.apache.commons.math3.stat.ranking.NaturalRanking

- All Implemented Interfaces:
    RankingAlgorithm

      public class NaturalRanking
      extends 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)
  NaNStrategy | TiesStrategy | `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
  Version:
    $Id: NaturalRanking.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `NaturalRanking.IntDoublePair` Represents the position of a double value in an ordering.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static NaNStrategy` | `DEFAULT_NAN_STRATEGY` default NaN strategy
    `static TiesStrategy` | `DEFAULT_TIES_STRATEGY` default ties strategy
    `private NaNStrategy` | `nanStrategy` NaN strategy - defaults to NaNs maximal
    `private RandomData` | `randomData` Source of random data - used only when ties strategy is RANDOM
    `private TiesStrategy` | `tiesStrategy` Ties strategy - defaults to ties averaged

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NaturalRanking()` Create a NaturalRanking with default strategies for handling ties and NaNs.
    `NaturalRanking(NaNStrategy nanStrategy)` Create a NaturalRanking with the given NaNStrategy.
    `NaturalRanking(NaNStrategy nanStrategy, RandomGenerator randomGenerator)` Create a NaturalRanking with the given NaNStrategy, TiesStrategy.RANDOM and the given source of random data.
    `NaturalRanking(NaNStrategy nanStrategy, TiesStrategy tiesStrategy)` Create a NaturalRanking with the given NaNStrategy and TiesStrategy.
    `NaturalRanking(RandomGenerator randomGenerator)` Create a NaturalRanking with TiesStrategy.RANDOM and the given RandomGenerator as the source of random data.
    `NaturalRanking(TiesStrategy tiesStrategy)` Create a NaturalRanking with the given TiesStrategy.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private boolean` | `containsNaNs(NaturalRanking.IntDoublePair[] ranks)` Checks for presence of NaNs in `ranks.`
    `private void` | `fill(double[] data, List<Integer> tiesTrace, double value)` Sets`data[i] = value` for each i in `tiesTrace.`
    `private List<Integer>` | `getNanPositions(NaturalRanking.IntDoublePair[] ranks)` Returns a list of indexes where `ranks` is `NaN.`
    `NaNStrategy` | `getNanStrategy()` Return the NaNStrategy
    `TiesStrategy` | `getTiesStrategy()` Return the TiesStrategy
    `double[]` | `rank(double[] data)` Rank `data` using the natural ordering on Doubles, with NaN values handled according to `nanStrategy` and ties resolved using `tiesStrategy.`
    `private void` | `recodeNaNs(NaturalRanking.IntDoublePair[] ranks, double value)` Recodes NaN values to the given value.
    `private NaturalRanking.IntDoublePair[]` | `removeNaNs(NaturalRanking.IntDoublePair[] ranks)` Returns an array that is a copy of the input array with IntDoublePairs having NaN values removed.
    `private void` | `resolveTie(double[] ranks, List<Integer> tiesTrace)` Resolve a sequence of ties, using the configured `TiesStrategy`.
    `private void` | `restoreNaNs(double[] ranks, List<Integer> nanPositions)` Set `ranks[i] = Double.NaN` for each i in `nanPositions.`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 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 RandomData 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,
                        List<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,
                  List<Integer> 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

    - #### restoreNaNs

          private void restoreNaNs(double[] ranks,
                         List<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 List<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`

Copyright (c) 2003-2013 Apache Software Foundation