org.apache.datasketches.quantilescommon

## Class ItemsSketchSortedView<T>

- java.lang.Object
- - org.apache.datasketches.quantilescommon.ItemsSketchSortedView<T>

Type Parameters:
  `T` - The sketch data type

All Implemented Interfaces:
  GenericSortedView<T>, PartitioningFeature<T>, SketchPartitionLimits, SortedView

    public class ItemsSketchSortedView<T>
    extends Object
    implements GenericSortedView<T>

The SortedView for the KllItemsSketch and the classic ItemsSketch.

Author:
  Alexander Saydakov, Lee Rhodes

### Constructor Summary

Constructors
Constructor and Description
`ItemsSketchSortedView(T[] quantiles, long[] cumWeights, QuantilesGenericAPI<T> sk)` Constructor.

### Method Summary

All Methods Instance Methods Concrete Methods
`Comparator<? super T>` `getComparator()` Gets the Comparator for this generic type.
`long[]` `getCumulativeWeights()` Returns the array of cumulative weights from the sketch.
`T` `getMaxItem()` Returns the maximum item of the stream.
`int` `getMaxPartitions()` Gets the maximum number of partitions this sketch will support based on the configured size K and the number of retained values of this sketch.
`T` `getMinItem()` Returns the minimum item of the stream.
`long` `getN()` Gets the length of the input stream offered to the sketch..
`int` `getNumRetained()` Gets the number of quantiles retained by this sorted view.
`GenericPartitionBoundaries<T>` `getPartitionBoundariesFromNumParts(int numEquallySizedParts, QuantileSearchCriteria searchCrit)` This method returns an instance of `GenericPartitionBoundaries` which provides sufficient information for the user to create the given number of equally sized partitions, where "equally sized" refers to an approximately equal number of items per partition.
`GenericPartitionBoundaries<T>` `getPartitionBoundariesFromPartSize(long nominalPartitionSize, QuantileSearchCriteria searchCrit)` This method returns an instance of `GenericPartitionBoundaries` which provides sufficient information for the user to create the given number of equally sized partitions, where "equally sized" refers to an approximately equal number of items per partition.
`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.
`T[]` `getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit)` Gets an array of quantiles corresponding to the given array of ranks.
`double` `getRank(T quantile, QuantileSearchCriteria searchCrit)` Gets the normalized rank corresponding to the given a quantile.
`boolean` `isEmpty()` Returns true if this sorted view is empty.
`GenericSortedViewIterator<T>` `iterator()` Returns an iterator for this Sorted View.

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

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

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

`getCDF, getPMF, validateItems`

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

`getPartitionBoundariesFromNumParts, getPartitionBoundariesFromPartSize`

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

`getMinPartitionSizeItems`

### Constructor Detail

#### ItemsSketchSortedView

    public ItemsSketchSortedView(T[] quantiles,
                                 long[] cumWeights,
                                 QuantilesGenericAPI<T> sk)

Constructor.

Parameters:
  `quantiles` - the given array of quantiles, which must be ordered.
  `cumWeights` - the given array of cumulative weights, which must be ordered, start with the value one, and the last value must be equal to N, the total number of items updated to the sketch.
  `sk` - the underlying quantile sketch.

### Method Detail

#### getComparator

    public Comparator<? super T> getComparator()

Description copied from interface: `GenericSortedView`
Gets the Comparator for this generic type.

Specified by:
  `getComparator` in interface `GenericSortedView<T>`
Returns:
  the Comparator for this generic type.

#### getCumulativeWeights

    public long[] getCumulativeWeights()

Description copied from interface: `SortedView`
Returns the array of cumulative weights from the sketch. Also known as the natural ranks, which are the Natural Numbers on the interval [1, N].

Specified by:
  `getCumulativeWeights` in interface `SortedView`
Returns:
  the array of cumulative weights (or natural ranks).

#### getMaxItem

    public T getMaxItem()

Description copied from interface: `GenericSortedView`
Returns the maximum item of the stream. This may be distinct from the largest item retained by the sketch algorithm.

Specified by:
  `getMaxItem` in interface `GenericSortedView<T>`
Returns:
  the maximum item of the stream

#### getMinItem

    public T getMinItem()

Description copied from interface: `GenericSortedView`
Returns the minimum item of the stream. This may be distinct from the smallest item retained by the sketch algorithm.

Specified by:
  `getMinItem` in interface `GenericSortedView<T>`
Returns:
  the minimum item of the stream

#### getN

    public long getN()

Description copied from interface: `SketchPartitionLimits`
Gets the length of the input stream offered to the sketch..

Specified by:
  `getN` in interface `SketchPartitionLimits`
Specified by:
  `getN` in interface `SortedView`
Returns:
  the length of the input stream offered to the sketch.

#### getNumRetained

    public int getNumRetained()

Description copied from interface: `SortedView`
Gets the number of quantiles retained by this sorted view. This may be slightly different from the function with the same name when called from the originating sketch.

Specified by:
  `getNumRetained` in interface `SortedView`
Returns:
  the number of quantiles retained by this sorted view

#### getMaxPartitions

    public int getMaxPartitions()

Description copied from interface: `SketchPartitionLimits`
Gets the maximum number of partitions this sketch will support based on the configured size K and the number of retained values of this sketch.

Specified by:
  `getMaxPartitions` in interface `SketchPartitionLimits`
Returns:
  the maximum number of partitions this sketch will support.

#### getPartitionBoundariesFromPartSize

    public GenericPartitionBoundaries<T> getPartitionBoundariesFromPartSize(long nominalPartitionSize,
                                                                            QuantileSearchCriteria searchCrit)

Description copied from interface: `PartitioningFeature`
This method returns an instance of `GenericPartitionBoundaries` which provides sufficient information for the user to create the given number of equally sized partitions, where "equally sized" refers to an approximately equal number of items per partition.

The sketch must not be empty.

Specified by:
  `getPartitionBoundariesFromPartSize` in interface `PartitioningFeature<T>`
Parameters:
  `nominalPartitionSize` - an integer that specifies the nominal size, in items, of each target partition. This must be a positive integer greater than `getMinPartitionSizeItems()`.
  `searchCrit` - If INCLUSIVE, all the returned quantiles are the upper boundaries of the equally sized partitions with the exception of the lowest returned quantile, which is the lowest boundary of the lowest ranked partition. If EXCLUSIVE, all the returned quantiles are the lower boundaries of the equally sized partitions with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition.
Returns:
  an instance of `GenericPartitionBoundaries`.

#### getPartitionBoundariesFromNumParts

    public GenericPartitionBoundaries<T> getPartitionBoundariesFromNumParts(int numEquallySizedParts,
                                                                            QuantileSearchCriteria searchCrit)

Description copied from interface: `PartitioningFeature`
This method returns an instance of `GenericPartitionBoundaries` which provides sufficient information for the user to create the given number of equally sized partitions, where "equally sized" refers to an approximately equal number of items per partition.

The sketch must not be empty.

Specified by:
  `getPartitionBoundariesFromNumParts` in interface `PartitioningFeature<T>`
Parameters:
  `numEquallySizedParts` - an integer that specifies the number of equally sized partitions between `getMinItem()` and `getMaxItem()`. This must be a positive integer less than `getMaxPartitions()`
  - A 1 will return: minItem, maxItem.
  - A 2 will return: minItem, median quantile, maxItem.
  - Etc.
  `searchCrit` - If INCLUSIVE, all the returned quantiles are the upper boundaries of the equally sized partitions with the exception of the lowest returned quantile, which is the lowest boundary of the lowest ranked partition. If EXCLUSIVE, all the returned quantiles are the lower boundaries of the equally sized partitions with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition.
Returns:
  an instance of `GenericPartitionBoundaries`.

#### getQuantile

    public T getQuantile(double rank,
                         QuantileSearchCriteria searchCrit)

Description copied from interface: `GenericSortedView`
Gets the approximate quantile of the given normalized rank and the given search criterion.

Specified by:
  `getQuantile` in interface `GenericSortedView<T>`
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.
See Also:
  `QuantileSearchCriteria`

#### getQuantiles

    public T[] getQuantiles(double[] ranks,
                            QuantileSearchCriteria searchCrit)

Gets an array of quantiles corresponding to the given array of ranks.

Parameters:
  `ranks` - the given array of normalized ranks
  `searchCrit` - The search criterion: either INCLUSIVE or EXCLUSIVE.
Returns:
  an array of quantiles corresponding to the given array of ranks.

#### getQuantiles

    public T[] getQuantiles()

Description copied from interface: `GenericSortedView`
Returns the full array of quantiles.

Specified by:
  `getQuantiles` in interface `GenericSortedView<T>`
Returns:
  the full array of quantiles.

#### getRank

    public double getRank(T quantile,
                          QuantileSearchCriteria searchCrit)

Description copied from interface: `GenericSortedView`
Gets the normalized rank corresponding to the given a quantile.

Specified by:
  `getRank` in interface `GenericSortedView<T>`
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.
See Also:
  `QuantileSearchCriteria`

#### isEmpty

    public boolean isEmpty()

Description copied from interface: `SortedView`
Returns true if this sorted view is empty.

Specified by:
  `isEmpty` in interface `SortedView`
Returns:
  true if this sorted view is empty.

#### iterator

    public GenericSortedViewIterator<T> iterator()

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

Specified by:
  `iterator` in interface `GenericSortedView<T>`
Specified by:
  `iterator` in interface `SortedView`
Returns:
  an iterator for this Sorted View.