org.apache.datasketches.quantilescommon

Interface QuantilesDoublesAPI

All Superinterfaces:

QuantilesAPI

All Known Implementing Classes:

CompactDoublesSketch, DoublesSketch, KllDoublesSketch, UpdateDoublesSketch

public interface QuantilesDoublesAPI
extends QuantilesAPI

The Quantiles API for item type double.

Author:

Lee Rhodes

See Also:

QuantilesAPI

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	QuantilesDoublesAPI.DoublesPartitionBoundaries This encapsulates the essential information needed to construct actual partitions and is returned from the getPartitionBoundaries(int, QuantileSearchCritera) method.

Method Summary

Modifier and Type	Method and Description
default double[]	getCDF(double[] splitPoints) This is equivalent to getCDF(splitPoints, INCLUSIVE)
double[]	getCDF(double[] 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.
double	getMaxItem() Returns the maximum item of the stream.
double	getMinItem() Returns the minimum item of the stream.
default QuantilesDoublesAPI.DoublesPartitionBoundaries	getPartitionBoundaries(int numEquallyWeighted) This method returns an instance of DoublesPartitionBoundaries which provides sufficient information for the user to create the given number of equally weighted partitions.
QuantilesDoublesAPI.DoublesPartitionBoundaries	getPartitionBoundaries(int numEquallyWeighted, QuantileSearchCriteria searchCrit) This method returns an instance of DoublesPartitionBoundaries which provides sufficient information for the user to create the given number of equally weighted partitions.
default double[]	getPMF(double[] splitPoints) This is equivalent to getPMF(splitPoints, INCLUSIVE)
double[]	getPMF(double[] 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.
default double	getQuantile(double rank) This is equivalent to getQuantile(rank, INCLUSIVE)
double	getQuantile(double rank, QuantileSearchCriteria searchCrit) Gets the approximate quantile of the given normalized rank and the given search criterion.
double	getQuantileLowerBound(double rank) Gets the lower bound of the quantile confidence interval in which the quantile of the given rank exists.
default double[]	getQuantiles(double[] ranks) This is equivalent to getQuantiles(ranks, INCLUSIVE)
double[]	getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit) Gets an array of quantiles from the given array of normalized ranks.
double	getQuantileUpperBound(double rank) Gets the upper bound of the quantile confidence interval in which the true quantile of the given rank exists.
default double	getRank(double quantile) This is equivalent to getRank(quantile, INCLUSIVE)
double	getRank(double quantile, QuantileSearchCriteria searchCrit) Gets the normalized rank corresponding to the given a quantile.
default double[]	getRanks(double[] quantiles) This is equivalent to getRanks(quantiles, INCLUSIVE)
double[]	getRanks(double[] quantiles, QuantileSearchCriteria searchCrit) Gets an array of normalized ranks corresponding to the given array of quantiles and the given search criterion.
int	getSerializedSizeBytes() Returns the current number of bytes this Sketch would require if serialized.
DoublesSortedView	getSortedView() Gets the sorted view of this sketch
QuantilesDoublesSketchIterator	iterator() Gets the iterator for this sketch, which is not sorted.
byte[]	toByteArray() Returns a byte array representation of this sketch.
void	update(double item) Updates this sketch with the given item.

Methods inherited from interface org.apache.datasketches.quantilescommon.QuantilesAPI

getK, getN, getNumRetained, getRankLowerBound, getRankUpperBound, hasMemory, isDirect, isEmpty, isEstimationMode, isReadOnly, reset, toString

Method Detail

getCDF

default double[] getCDF(double[] splitPoints)

This is equivalent to getCDF(splitPoints, INCLUSIVE)

Parameters:

splitPoints - an array of m unique, monotonically increasing items.

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.

getCDF

double[] getCDF(double[] 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.

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.

getMaxItem

double getMaxItem()

Returns the maximum item of the stream. This is provided for convenience, but may be different from the largest item retained by the sketch algorithm.

Returns:

the maximum item of the stream

Throws:

IllegalArgumentException - if sketch is empty.

getMinItem

double getMinItem()

Returns the minimum item of the stream. This is provided for convenience, but is distinct from the smallest item retained by the sketch algorithm.

Returns:

the minimum item of the stream

Throws:

IllegalArgumentException - if sketch is empty.

getPartitionBoundaries

default QuantilesDoublesAPI.DoublesPartitionBoundaries getPartitionBoundaries(int numEquallyWeighted)

This method returns an instance of DoublesPartitionBoundaries which provides sufficient information for the user to create the given number of equally weighted partitions.

This method is equivalent to getPartitionBoundaries(numEquallyWeighted, INCLUSIVE).

Parameters:

numEquallyWeighted - an integer that specifies the number of equally weighted partitions between getMinItem() and getMaxItem(). This must be a positive integer greater than zero.

• A 1 will return: minItem, maxItem.
• A 2 will return: minItem, median quantile, maxItem.
• Etc.

Returns:

an instance of DoublesPartitionBoundaries.

Throws:

IllegalArgumentException - if sketch is empty.

IllegalArgumentException - if numEquallyWeighted is less than 1.

getPartitionBoundaries

QuantilesDoublesAPI.DoublesPartitionBoundaries getPartitionBoundaries(int numEquallyWeighted,
                                                                      QuantileSearchCriteria searchCrit)

This method returns an instance of DoublesPartitionBoundaries which provides sufficient information for the user to create the given number of equally weighted partitions.

Parameters:

numEquallyWeighted - an integer that specifies the number of equally weighted partitions between getMinItem() and getMaxItem(). This must be a positive integer greater than zero.

• 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 weighted 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 weighted partitions with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition.

Returns:

an instance of DoublesPartitionBoundaries.

Throws:

IllegalArgumentException - if sketch is empty.

IllegalArgumentException - if numEquallyWeighted is less than 1.

getPMF

default double[] getPMF(double[] splitPoints)

This is equivalent to getPMF(splitPoints, INCLUSIVE)

Parameters:

splitPoints - an array of m unique, monotonically increasing items.

Returns:

a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0].

Throws:

IllegalArgumentException - if sketch is empty.

getPMF

double[] getPMF(double[] 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

default double getQuantile(double rank)

This is equivalent to getQuantile(rank, INCLUSIVE)

Parameters:

rank - the given normalized rank, a double in the range [0.0, 1.0].

Returns:

the approximate quantile given the normalized rank.

Throws:

IllegalArgumentException - if sketch is empty.

getQuantile

double 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

getQuantileLowerBound

double getQuantileLowerBound(double rank)

Gets the lower bound of the quantile confidence interval in which the quantile of the given rank exists.

Although it is possible to estimate the probability that the true quantile exists within the quantile confidence interval specified by the upper and lower quantile bounds, it is not possible to guarantee the width of the quantile confidence interval as an additive or multiplicative percent of the true quantile.

Parameters:

rank - the given normalized rank

Returns:

the lower bound of the quantile confidence interval in which the quantile of the given rank exists.

Throws:

IllegalArgumentException - if sketch is empty.

getQuantileUpperBound

double getQuantileUpperBound(double rank)

Gets the upper bound of the quantile confidence interval in which the true quantile of the given rank exists.

Although it is possible to estimate the probability that the true quantile exists within the quantile confidence interval specified by the upper and lower quantile bounds, it is not possible to guarantee the width of the quantile interval as an additive or multiplicative percent of the true quantile.

Parameters:

rank - the given normalized rank

Returns:

the upper bound of the quantile confidence interval in which the true quantile of the given rank exists.

Throws:

IllegalArgumentException - if sketch is empty.

getQuantiles

default double[] getQuantiles(double[] ranks)

This is equivalent to getQuantiles(ranks, INCLUSIVE)

Parameters:

ranks - the given array of normalized ranks, each of which must be in the interval [0.0,1.0].

Returns:

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

Throws:

IllegalArgumentException - if sketch is empty.

getQuantiles

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

Gets an array of quantiles from the given array of normalized ranks.

Parameters:

ranks - the given array of normalized ranks, each of which must be in the interval [0.0,1.0].

searchCrit - if INCLUSIVE, the given ranks include all quantiles ≤ the quantile directly corresponding to each rank.

Returns:

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

Throws:

IllegalArgumentException - if sketch is empty.

See Also:

QuantileSearchCriteria

getRank

default double getRank(double quantile)

This is equivalent to getRank(quantile, INCLUSIVE)

Parameters:

quantile - the given quantile

Returns:

the normalized rank corresponding to the given quantile

Throws:

IllegalArgumentException - if sketch is empty.

getRank

double getRank(double 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

getRanks

default double[] getRanks(double[] quantiles)

This is equivalent to getRanks(quantiles, INCLUSIVE)

Parameters:

quantiles - the given array of quantiles

Returns:

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

Throws:

IllegalArgumentException - if sketch is empty.

getRanks

double[] getRanks(double[] quantiles,
                  QuantileSearchCriteria searchCrit)

Gets an array of normalized ranks corresponding to the given array of quantiles and the given search criterion.

Parameters:

quantiles - the given array of quantiles

searchCrit - if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile.

Returns:

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

Throws:

IllegalArgumentException - if sketch is empty.

See Also:

QuantileSearchCriteria

getSerializedSizeBytes

int getSerializedSizeBytes()

Returns the current number of bytes this Sketch would require if serialized.

Returns:

the number of bytes this sketch would require if serialized.

getSortedView

DoublesSortedView getSortedView()

Gets the sorted view of this sketch

Returns:

the sorted view of this sketch

iterator

QuantilesDoublesSketchIterator iterator()

Gets the iterator for this sketch, which is not sorted.

Returns:

the iterator for this sketch

toByteArray

byte[] toByteArray()

Returns a byte array representation of this sketch.

Returns:

a byte array representation of this sketch.

update

void update(double item)

Updates this sketch with the given item.

Parameters:

item - from a stream of quantiles. NaNs are ignored.