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 of m unique, monotonically increasing double values * that divide the real number line into m+1 consecutive disjoint intervals. * The definition of an "interval" is inclusive of the left splitPoint (or minimum value) and * exclusive of the right splitPoint, with the exception that the last interval will include * the maximum value. * It is not necessary to include either the min or max values in these split points. * * @return an array of m+1 double values on the interval [0.0, 1.0), * which are a consecutive approximation to the CDF of the input stream given the splitPoints. * The value at array position j of the returned CDF array is the sum of the returned values * in positions 0 through j of the returned PMF array. */ public double[] getCDF(final double[] splitPoints) { return KllDoublesHelper.getDoublesPmfOrCdf(this, splitPoints, true); } /** * Returns the max value of the stream. * If the sketch is empty this returns NaN. * * @return the max value of the stream */ public double getMaxValue() { return getMaxDoubleValue(); } /** * Returns the min value of the stream. * If the sketch is empty this returns NaN. * * @return the min value of the stream */ public double getMinValue() { return getMinDoubleValue(); } /** * Returns an approximation to the Probability Mass Function (PMF) of the input stream * given a set of splitPoints (values). * *

The 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 of m unique, monotonically increasing double values * that divide the real number line into m+1 consecutive disjoint intervals. * The definition of an "interval" is inclusive of the left splitPoint (or minimum value) and * exclusive of the right splitPoint, with the exception that the last interval will include * the maximum value. * It is not necessary to include either the min or max values in these split points. * * @return an array of m+1 doubles on the interval [0.0, 1.0), * each of which is an approximation to the fraction of the total input stream values * (the mass) that fall into one of those intervals. * The definition of an "interval" is inclusive of the left splitPoint and exclusive of the right * splitPoint, with the exception that the last interval will include maximum value. */ public double[] getPMF(final double[] splitPoints) { return KllDoublesHelper.getDoublesPmfOrCdf(this, splitPoints, false); } /** * Returns an approximation to the value of the data item * that would be preceded by the given fraction of a hypothetical sorted * version of the input stream so far. * *

We 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 KllDoublesHelper.getDoublesQuantile(this, 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(getMinK(), 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 KllDoublesHelper.getDoublesQuantiles(this, 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(getMinK(), 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 KllDoublesHelper.getDoubleRank(this, value); } /** * @return the iterator for this class */ public KllDoublesSketchIterator iterator() { return new KllDoublesSketchIterator(getDoubleItemsArray(), getLevelsArray(), getNumLevels()); } /** * 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) { if (readOnly) { kllSketchThrow(TGT_IS_READ_ONLY); } KllDoublesHelper.updateDouble(this, value); } @Override //Artifact of inheritance float[] getFloatItemsArray() { kllSketchThrow(MUST_NOT_CALL); return null; } @Override //Artifact of inheritance float getFloatItemsArrayAt(final int index) { kllSketchThrow(MUST_NOT_CALL); return Float.NaN; } @Override //Artifact of inheritance float getMaxFloatValue() { kllSketchThrow(MUST_NOT_CALL); return Float.NaN; } @Override //Artifact of inheritance float getMinFloatValue() { kllSketchThrow(MUST_NOT_CALL); return Float.NaN; } @Override //Artifact of inheritance void setFloatItemsArray(final float[] floatItems) { kllSketchThrow(MUST_NOT_CALL); } @Override //Artifact of inheritance void setFloatItemsArrayAt(final int index, final float value) { kllSketchThrow(MUST_NOT_CALL); } @Override //Artifact of inheritance void setMaxFloatValue(final float value) { kllSketchThrow(MUST_NOT_CALL); } @Override //Artifact of inheritance void setMinFloatValue(final float value) { kllSketchThrow(MUST_NOT_CALL); } }