Please refer to the documentation in the package-info:

* {@link org.apache.datasketches.kll}

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

If the sketch is empty this returns null.

* * @param splitPoints an array ofThe resulting approximations have a probabilistic guarantee that can be obtained from the * getNormalizedRankError(true) function. * *

If the sketch is empty this returns null.

* * @param splitPoints an array ofWe note that this method has a fairly large overhead (microseconds instead of nanoseconds) * so it should not be called multiple times to get different quantiles from the same * sketch. Instead use getQuantiles(), which pays the overhead only once. * *

If the sketch is empty this returns NaN. * * @param fraction the specified fractional position in the hypothetical sorted stream. * These are also called normalized ranks or fractional ranks. * If fraction = 0.0, the true minimum value of the stream is returned. * If fraction = 1.0, the true maximum value of the stream is returned. * * @return the approximation to the value at the given fraction */ public double getQuantile(final double fraction) { return getDoublesQuantile(fraction); } /** * Gets the lower bound of the value interval in which the true quantile of the given rank * exists with a confidence of at least 99%. * @param fraction the given normalized rank as a fraction * @return the lower bound of the value interval in which the true quantile of the given rank * exists with a confidence of at least 99%. Returns NaN if the sketch is empty. */ public double getQuantileLowerBound(final double fraction) { return getQuantile(max(0, fraction - KllHelper.getNormalizedRankError(getDyMinK(), false))); } /** * This is a more efficient multiple-query version of getQuantile(). * *

This returns an array that could have been generated by using getQuantile() with many * different fractional ranks, but would be very inefficient. * This method incurs the internal set-up overhead once and obtains multiple quantile values in * a single query. It is strongly recommend that this method be used instead of multiple calls * to getQuantile(). * *

If the sketch is empty this returns null. * * @param fractions given array of fractional positions in the hypothetical sorted stream. * These are also called normalized ranks or fractional ranks. * These fractions must be in the interval [0.0, 1.0], inclusive. * * @return array of approximations to the given fractions in the same order as given fractions * array. */ public double[] getQuantiles(final double[] fractions) { return getDoublesQuantiles(fractions); } /** * This is also a more efficient multiple-query version of getQuantile() and allows the caller to * specify the number of evenly spaced fractional ranks. * *

If the sketch is empty this returns null. * * @param numEvenlySpaced an integer that specifies the number of evenly spaced fractional ranks. * This must be a positive integer greater than 0. A value of 1 will return the min value. * A value of 2 will return the min and the max value. A value of 3 will return the min, * the median and the max value, etc. * * @return array of approximations to the given fractions in the same order as given fractions * array. */ public double[] getQuantiles(final int numEvenlySpaced) { if (isEmpty()) { return null; } return getQuantiles(org.apache.datasketches.Util.evenlySpaced(0.0, 1.0, numEvenlySpaced)); } /** * Gets the upper bound of the value interval in which the true quantile of the given rank * exists with a confidence of at least 99%. * @param fraction the given normalized rank as a fraction * @return the upper bound of the value interval in which the true quantile of the given rank * exists with a confidence of at least 99%. Returns NaN if the sketch is empty. */ public double getQuantileUpperBound(final double fraction) { return getQuantile(min(1.0, fraction + KllHelper.getNormalizedRankError(getDyMinK(), false))); } /** * Returns an approximation to the normalized (fractional) rank of the given value from 0 to 1, * inclusive. * *

The resulting approximation has a probabilistic guarantee that can be obtained from the * getNormalizedRankError(false) function. * *

If the sketch is empty this returns NaN.

* * @param value to be ranked * @return an approximate rank of the given value */ public double getRank(final double value) { return getDoubleRank(value); } /** * @return the iterator for this class */ public KllDoublesSketchIterator iterator() { return new KllDoublesSketchIterator(getDoubleItemsArray(), getLevelsArray(), getNumLevels()); } /** * Merges another sketch into this one. * @param other sketch to merge into this one */ public void merge(final KllSketch other) { if (!other.isDirect()) { kllSketchThrow(32); } if (!other.isDoublesSketch()) { kllSketchThrow(33); } mergeDoubleImpl(other); } @Override public byte[] toByteArray() { return toCompactByteArrayImpl(); } @Override public String toString(final boolean withLevels, final boolean withData) { return toStringImpl(withLevels, withData); } /** * Updates this sketch with the given data item. * * @param value an item from a stream of items. NaNs are ignored. */ public void update(final double value) { updateDouble(value); } }