org.apache.datasketches.quantilescommon

## Interface GenericSortedView<T>

Type Parameters:
  `T` - The generic quantile type.

All Superinterfaces:
  PartitioningFeature<T>, SketchPartitionLimits, SortedView

All Known Implementing Classes:
  ItemsSketchSortedView

    public interface GenericSortedView<T>
    extends PartitioningFeature<T>, SketchPartitionLimits, SortedView

The Sorted View for quantiles of generic type.

Author:
  Alexander Saydakov, Lee Rhodes
See Also:
  `SortedView`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`default double[]` `getCDF(T[] splitPoints, QuantileSearchCriteria searchCrit)` Returns an approximation to the Cumulative Distribution Function (CDF) of the input stream as a monotonically increasing array of double ranks (or cumulative probabilities) on the interval [0.0, 1.0], given a set of splitPoints.
`Comparator<? super T>` `getComparator()` Gets the Comparator for this generic type.
`T` `getMaxItem()` Returns the maximum item of the stream.
`T` `getMinItem()` Returns the minimum item of the stream.
`default double[]` `getPMF(T[] splitPoints, QuantileSearchCriteria searchCrit)` Returns an approximation to the Probability Mass Function (PMF) of the input stream as an array of probability masses as doubles on the interval [0.0, 1.0], given a set of splitPoints.
`T` `getQuantile(double rank, QuantileSearchCriteria searchCrit)` Gets the approximate quantile of the given normalized rank and the given search criterion.
`T[]` `getQuantiles()` Returns the full array of quantiles.
`double` `getRank(T quantile, QuantileSearchCriteria searchCrit)` Gets the normalized rank corresponding to the given a quantile.
`GenericSortedViewIterator<T>` `iterator()` Returns an iterator for this Sorted View.
`static <T> void` `validateItems(T[] items, Comparator<? super T> comparator)` Checks the sequential validity of the given array of generic items.

### Methods inherited from interface org.apache.datasketches.quantilescommon.PartitioningFeature

`getPartitionBoundariesFromNumParts, getPartitionBoundariesFromNumParts, getPartitionBoundariesFromPartSize, getPartitionBoundariesFromPartSize`

### Methods inherited from interface org.apache.datasketches.quantilescommon.SketchPartitionLimits

`getMaxPartitions, getMinPartitionSizeItems, getN`

### Methods inherited from interface org.apache.datasketches.quantilescommon.SortedView

`getCumulativeWeights, getN, getNumRetained, isEmpty`

### Method Detail

#### getCDF

    default double[] getCDF(T[] splitPoints,
                            QuantileSearchCriteria searchCrit)

Returns an approximation to the Cumulative Distribution Function (CDF) of the input stream as a monotonically increasing array of double ranks (or cumulative probabilities) on the interval [0.0, 1.0], given a set of splitPoints.

If the sketch is empty this returns null.

The resulting approximations have a probabilistic guarantee that can be obtained from the getNormalizedRankError(false) function.

Parameters:
  `splitPoints` - an array of m unique, monotonically increasing items (of the same type as the input items) that divide the item input domain into m+1 overlapping intervals.

  > The start of each interval is below the lowest item retained by the sketch corresponding to a zero rank or zero probability, and the end of the interval is the rank or cumulative probability corresponding to the split point.

  > The (m+1)th interval represents 100% of the distribution represented by the sketch and consistent with the definition of a cumulative probability distribution, thus the (m+1)th rank or probability in the returned array is always 1.0.

  > If a split point exactly equals a retained item of the sketch and the search criterion is:

  > - INCLUSIVE, the resulting cumulative probability will include that item.
  > - EXCLUSIVE, the resulting cumulative probability will not include the weight of that split point.

  > It is not recommended to include either the minimum or maximum items of the input stream.

  `searchCrit` - the desired search criteria.
Returns:
  a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0].
Throws:
  `IllegalArgumentException` - if sketch is empty.

#### getComparator

    Comparator<? super T> getComparator()

Gets the Comparator for this generic type.

Returns:
  the Comparator for this generic type.

#### getMaxItem

    T getMaxItem()

Returns the maximum item of the stream. This may be distinct from the largest item retained by the sketch algorithm.

Returns:
  the maximum item of the stream
Throws:
  `IllegalArgumentException` - if sketch is empty.

#### getMinItem

    T getMinItem()

Returns the minimum item of the stream. This may be distinct from the smallest item retained by the sketch algorithm.

Returns:
  the minimum item of the stream
Throws:
  `IllegalArgumentException` - if sketch is empty.

#### getPMF

    default double[] getPMF(T[] splitPoints,
                            QuantileSearchCriteria searchCrit)

Returns an approximation to the Probability Mass Function (PMF) of the input stream as an array of probability masses as doubles on the interval [0.0, 1.0], given a set of splitPoints.

The resulting approximations have a probabilistic guarantee that can be obtained from the getNormalizedRankError(true) function.

Parameters:
  `splitPoints` - an array of m unique, monotonically increasing items (of the same type as the input items) that divide the item input domain into m+1 consecutive, non-overlapping intervals.

  > Each interval except for the end intervals starts with a split point and ends with the next split point in sequence.

  > The first interval starts below the lowest item retained by the sketch corresponding to a zero rank or zero probability, and ends with the first split point

  > The last (m+1)th interval starts with the last split point and ends after the last item retained by the sketch corresponding to a rank or probability of 1.0.

  > The sum of the probability masses of all (m+1) intervals is 1.0.

  > If the search criterion is:

  > - INCLUSIVE, and the upper split point of an interval equals an item retained by the sketch, the interval will include that item. If the lower split point equals an item retained by the sketch, the interval will exclude that item.
  > - EXCLUSIVE, and the upper split point of an interval equals an item retained by the sketch, the interval will exclude that item. If the lower split point equals an item retained by the sketch, the interval will include that item.

  > It is not recommended to include either the minimum or maximum items of the input stream.

  `searchCrit` - the desired search criteria.
Returns:
  a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0].
Throws:
  `IllegalArgumentException` - if sketch is empty.

#### getQuantile

    T getQuantile(double rank,
                  QuantileSearchCriteria searchCrit)

Gets the approximate quantile of the given normalized rank and the given search criterion.

Parameters:
  `rank` - the given normalized rank, a double in the range [0.0, 1.0].
  `searchCrit` - If INCLUSIVE, the given rank includes all quantiles ≤ the quantile directly corresponding to the given rank. If EXCLUSIVE, he given rank includes all quantiles < the quantile directly corresponding to the given rank.
Returns:
  the approximate quantile given the normalized rank.
Throws:
  `IllegalArgumentException` - if sketch is empty.
See Also:
  `QuantileSearchCriteria`

#### getQuantiles

    T[] getQuantiles()

Returns the full array of quantiles.

Returns:
  the full array of quantiles.

#### getRank

    double getRank(T quantile,
                   QuantileSearchCriteria searchCrit)

Gets the normalized rank corresponding to the given a quantile.

Parameters:
  `quantile` - the given quantile
  `searchCrit` - if INCLUSIVE the given quantile is included into the rank.
Returns:
  the normalized rank corresponding to the given quantile.
Throws:
  `IllegalArgumentException` - if sketch is empty.
See Also:
  `QuantileSearchCriteria`

#### iterator

    GenericSortedViewIterator<T> iterator()

Description copied from interface: `SortedView`
Returns an iterator for this Sorted View.

Specified by:
  `iterator` in interface `SortedView`
Returns:
  an iterator for this Sorted View.

#### validateItems

    static <T> void validateItems(T[] items,
                                  Comparator<? super T> comparator)

Checks the sequential validity of the given array of generic items. They must be unique, monotonically increasing and not null.

Type Parameters:
  `T` - the data type
Parameters:
  `items` - given array of generic items
  `comparator` - the comparator for generic item data type T