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
`private static class` `NaturalRanking.IntDoublePair` Represents the position of a double value in an ordering.

### Field Summary

Fields
`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
`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`