#246

Build # #246

Build Type

push

Committed by

Commit Message

<a href="https://github.com/apache/datasketches-java/commit/<a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa7ce3fcea">fd9888dfa">&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/</a><a class="double-link" href="https://github.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa7ce3fcea">fd9888dfa</a><a href="https://github.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa7ce3fcea">&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa7ce3fcea&quot;&gt;&amp;quot;&amp;gt;&amp;amp;lt;a href=&amp;amp;quot;https://github.com/apache/datasketches-java/commit/&amp;lt;/a&amp;gt;&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/apache/datasketches-java/commit/&amp;amp;lt;a class=&amp;amp;quot;double-link&amp;amp;quot; href=&amp;amp;quot;https://git&amp;quot;&amp;gt;&amp;amp;lt;a class=&amp;lt;/a&amp;gt;hub.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa7ce3fcea&amp;quot;&amp;gt;fd9888dfa&amp;lt;/a&amp;gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa7ce3fcea&amp;quot;&amp;gt;&amp;amp;lt;a href=&amp;amp;quot;https://github.com/apache/datasketches-java/commit/fd9888dfaf8b81d0ed5492a0e30254fa&amp;lt;/a&amp;gt;7ce3fcea&amp;quo</a>t;&gt;&amp;quot;&amp;gt;Merge &amp;lt;/a&amp;gt;&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://github.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; hre... (continued)

Run Details

46 of 46 new or added lines in 8 files covered. (100.0%)

19278 of 19602 relevant lines covered (98.35%)

0.98 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

83.64

/src/main/java/org/apache/datasketches/kll/KllFloatsSketch.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

package org.apache.datasketches.kll;

import static java.lang.Math.max;
import static java.lang.Math.min;
import static org.apache.datasketches.kll.KllPreambleUtil.getMemoryUpdatableFormatFlag;
import static org.apache.datasketches.kll.KllSketch.Error.MUST_NOT_BE_UPDATABLE_FORMAT;
import static org.apache.datasketches.kll.KllSketch.Error.MUST_NOT_CALL;
import static org.apache.datasketches.kll.KllSketch.Error.TGT_IS_READ_ONLY;
import static org.apache.datasketches.kll.KllSketch.Error.kllSketchThrow;

import java.util.Objects;

import org.apache.datasketches.memory.Memory;
import org.apache.datasketches.memory.MemoryRequestServer;
import org.apache.datasketches.memory.WritableMemory;

public abstract class KllFloatsSketch extends KllSketch {

  KllFloatsSketch(final WritableMemory wmem, final MemoryRequestServer memReqSvr) {
    super(SketchType.FLOATS_SKETCH, wmem, memReqSvr);
  }

  /**
   * Returns upper bound on the serialized size of a KllFloatsSketch given the following parameters.
   * @param k parameter that controls size of the sketch and accuracy of estimates
   * @param n stream length
   * @param updatableMemoryFormat true if updatable Memory format, otherwise the standard compact format.
   * @return upper bound on the serialized size of a KllSketch.
   */
  public static int getMaxSerializedSizeBytes(final int k, final long n, final boolean updatableMemoryFormat) {
    return getMaxSerializedSizeBytes(k, n, SketchType.FLOATS_SKETCH, updatableMemoryFormat);
  }

  /**
   * Factory heapify takes the sketch image in Memory and instantiates an on-heap sketch.
   * The resulting sketch will not retain any link to the source Memory.
   * @param srcMem a Memory image of a sketch serialized by this sketch.
   * <a href="{@docRoot}/resources/dictionary.html#mem">See Memory</a>
   * @return a heap-based sketch based on the given Memory.
   */
  public static KllFloatsSketch heapify(final Memory srcMem) {
    Objects.requireNonNull(srcMem, "Parameter 'srcMem' must not be null");
    if (getMemoryUpdatableFormatFlag(srcMem)) { Error.kllSketchThrow(MUST_NOT_BE_UPDATABLE_FORMAT); }
    return KllHeapFloatsSketch.heapifyImpl(srcMem);
  }

  /**
   * Create a new direct instance of this sketch with a given <em>k</em>.
   * @param k parameter that controls size of the sketch and accuracy of estimates.
   * @param dstMem the given destination WritableMemory object for use by the sketch
   * @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
   * @return a new direct instance of this sketch
   */
  public static KllFloatsSketch newDirectInstance(
      final int k,
      final WritableMemory dstMem,
      final MemoryRequestServer memReqSvr) {
    Objects.requireNonNull(dstMem, "Parameter 'dstMem' must not be null");
    Objects.requireNonNull(memReqSvr, "Parameter 'memReqSvr' must not be null");
    return KllDirectFloatsSketch.newDirectInstance(k, DEFAULT_M, dstMem, memReqSvr);
  }

  /**
   * Create a new direct instance of this sketch with the default <em>k</em>.
   * The default <em>k</em> = 200 results in a normalized rank error of about
   * 1.65%. Higher values of <em>k</em> will have smaller error but the sketch will be larger (and slower).
   * @param dstMem the given destination WritableMemory object for use by the sketch
   * @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
   * @return a new direct instance of this sketch
   */
  public static KllFloatsSketch newDirectInstance(
      final WritableMemory dstMem,
      final MemoryRequestServer memReqSvr) {
    Objects.requireNonNull(dstMem, "Parameter 'dstMem' must not be null");
    Objects.requireNonNull(memReqSvr, "Parameter 'memReqSvr' must not be null");
    return KllDirectFloatsSketch.newDirectInstance(DEFAULT_K, DEFAULT_M, dstMem, memReqSvr);
  }

  /**
   * Create a new heap instance of this sketch with the default <em>k = 200</em>.
   * The default <em>k</em> = 200 results in a normalized rank error of about
   * 1.65%. Higher values of K will have smaller error but the sketch will be larger (and slower).
   * This will have a rank error of about 1.65%.
   * @return new KllFloatsSketch on the heap.
   */
  public static KllFloatsSketch  newHeapInstance() {
    return new KllHeapFloatsSketch(DEFAULT_K, DEFAULT_M);
  }

  /**
   * Create a new heap instance of this sketch with a given parameter <em>k</em>.
   * <em>k</em> can be any value between DEFAULT_M and 65535, inclusive.
   * The default <em>k</em> = 200 results in a normalized rank error of about
   * 1.65%. Higher values of K will have smaller error but the sketch will be larger (and slower).
   * @param k parameter that controls size of the sketch and accuracy of estimates.
   * @return new KllFloatsSketch on the heap.
   */
  public static KllFloatsSketch newHeapInstance(final int k) {
    return new KllHeapFloatsSketch(k, DEFAULT_M);
  }

  /**
   * Wrap a sketch around the given read only source Memory containing sketch data
   * that originated from this sketch.
   * @param srcMem the read only source Memory
   * @return instance of this sketch
   */
  public static KllFloatsSketch wrap(final Memory srcMem) {
    Objects.requireNonNull(srcMem, "Parameter 'srcMem' must not be null");
    final KllMemoryValidate memVal = new KllMemoryValidate(srcMem);
    if (memVal.updatableMemFormat) {
      return new KllDirectFloatsSketch((WritableMemory) srcMem, null, memVal);
    } else {
      return new KllDirectCompactFloatsSketch(srcMem, memVal);
    }
  }

  /**
   * Wrap a sketch around the given source Writable Memory containing sketch data
   * that originated from this sketch.
   * @param srcMem a WritableMemory that contains data.
   * @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
   * @return instance of this sketch
   */
  public static KllFloatsSketch writableWrap(
      final WritableMemory srcMem,
      final MemoryRequestServer memReqSvr) {
    Objects.requireNonNull(srcMem, "Parameter 'srcMem' must not be null");
    final KllMemoryValidate memVal = new KllMemoryValidate(srcMem);
    if (memVal.updatableMemFormat) {
      if (!memVal.readOnly) {
        Objects.requireNonNull(memReqSvr, "Parameter 'memReqSvr' must not be null");
      }
      return new KllDirectFloatsSketch(srcMem, memReqSvr, memVal);
    } else {
      return new KllDirectCompactFloatsSketch(srcMem, memVal);
    }
  }

  /**
   * Returns an approximation to the Cumulative Distribution Function (CDF), which is the
   * cumulative analog of the PMF, of the input stream given a set of splitPoint (values).
   *
   * <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
   * getNormalizedRankError(false) function.
   *
   * <p>If the sketch is empty this returns null.</p>
   *
   * @param splitPoints an array of <i>m</i> unique, monotonically increasing float values
   * that divide the real number line into <i>m+1</i> 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.
   *
   * @param inclusive if true the weight of the given value is included into the rank.
   * Otherwise the rank equals the sum of the weights of all values that are less than the given value
   *
   * @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 float[] splitPoints, final boolean inclusive) {
    return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, true, inclusive);
  }

  /**
   * Same as {@link #getCDF(float[], boolean) getCDF(float[] splitPoints, false)}
   * @param splitPoints splitPoints
   * @return CDF
   */
  public double[] getCDF(final float[] splitPoints) {
    return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, true, false);
  }

  /**
   * Returns the max value of the stream.
   * If the sketch is empty this returns NaN.
   *
   * @return the max value of the stream
   */
  public float getMaxValue() { return getMaxFloatValue(); }

  /**
   * Returns the min value of the stream.
   * If the sketch is empty this returns NaN.
   *
   * @return the min value of the stream
   */
  public float getMinValue() { return getMinFloatValue(); }

  /**
   * Returns an approximation to the Probability Mass Function (PMF) of the input stream
   * given a set of splitPoints (values).
   *
   * <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
   * getNormalizedRankError(true) function.
   *
   * <p>If the sketch is empty this returns null.</p>
   *
   * @param splitPoints an array of <i>m</i> unique, monotonically increasing float values
   * that divide the real number line into <i>m+1</i> 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.
   *
   * @param inclusive if true the weight of the given value is included into the rank.
   * Otherwise the rank equals the sum of the weights of all values that are less than the given value
   *
   * @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 float[] splitPoints, final boolean inclusive) {
    return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, false, inclusive);
  }

  /**
   * Same as {@link #getPMF(float[], boolean) getPMF(float[] splitPoints, false)}
   * @param splitPoints splitPoints
   * @return PMF
   */
  public double[] getPMF(final float[] splitPoints) {
    return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, false, 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.
   *
   * <p>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.
   *
   * <p>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.
   *
   * @param inclusive if true, the given fraction (rank) is considered inclusive
   * @return the approximation to the value at the given fraction
   */
  public float getQuantile(final double fraction, final boolean inclusive) {
    return KllFloatsHelper.getFloatsQuantile(this, fraction, inclusive);
  }

  /**
   * Same as {@link #getQuantile(double, boolean) getQuantile(double fraction, false)}
   * @param fraction fractional rank
   * @return quantile
   */
  public float getQuantile(final double fraction) {
    return KllFloatsHelper.getFloatsQuantile(this, fraction, false);
  }

  /**
   * 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 float getQuantileLowerBound(final double fraction) {
    return getQuantile(max(0, fraction - KllHelper.getNormalizedRankError(getMinK(), false)));
  }

  /**
   * This is a more efficient multiple-query version of getQuantile().
   *
   * <p>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().
   *
   * <p>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.
   *
   * @param inclusive if true, the given fractions (ranks) are considered inclusive
   * @return array of approximations to the given fractions in the same order as given fractions
   * array.
   */
  public float[] getQuantiles(final double[] fractions, final boolean inclusive) {
    return KllFloatsHelper.getFloatsQuantiles(this, fractions, inclusive);
  }

  /**
   * Same as {@link #getQuantiles(double[], boolean) getQuantiles(double[] fractions, false)}
   * @param fractions fractional ranks
   * @return quantiles
   */
  public float[] getQuantiles(final double[] fractions) {
    return KllFloatsHelper.getFloatsQuantiles(this, fractions, false);
  }

  /**
   * This is also a more efficient multiple-query version of getQuantile() and allows the caller to
   * specify the number of evenly spaced fractional ranks.
   *
   * <p>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.
   *
   * @param inclusive if true, the fractional ranks are considered inclusive
   * @return array of approximations to the given fractions in the same order as given fractions
   * array.
   */
  public float[] getQuantiles(final int numEvenlySpaced, final boolean inclusive) {
    if (isEmpty()) { return null; }
    return getQuantiles(org.apache.datasketches.Util.evenlySpaced(0.0, 1.0, numEvenlySpaced), inclusive);
  }

  /**
   * Same as {@link #getQuantiles(int, boolean) getQuantiles(int numEvenlySpaced, false)}
   * @param numEvenlySpaced number of evenly spaced fractional ranks
   * @return quantiles
   */
  public float[] 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 float 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.
   *
   * <p>The resulting approximation has a probabilistic guarantee that can be obtained from the
   * getNormalizedRankError(false) function.
   *
   * <p>If the sketch is empty this returns NaN.</p>
   *
   * @param value to be ranked
   * @param inclusive if true the weight of the given value is included into the rank.
   * Otherwise the rank equals the sum of the weights of all values that are less than the given value
   * @return an approximate rank of the given value
   */
  public double getRank(final float value, final boolean inclusive) {
    return KllFloatsHelper.getFloatRank(this, value, inclusive);
  }

  /**
   * Same as {@link #getRank(float, boolean) getRank(float value, false)}
   * @param value value to be ranked
   * @return fractional rank
   */
  public double getRank(final float value) {
    return KllFloatsHelper.getFloatRank(this, value, false);
  }

  /**
   * @return the iterator for this class
   */
  public KllFloatsSketchIterator iterator() {
    return new KllFloatsSketchIterator(getFloatItemsArray(), 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 float value) {
    if (readOnly) { kllSketchThrow(TGT_IS_READ_ONLY); }
    KllFloatsHelper.updateFloat(this, value);
  }

  @Override //Artifact of inheritance
  double[] getDoubleItemsArray() { kllSketchThrow(MUST_NOT_CALL); return null; }

  @Override //Artifact of inheritance
  double getMaxDoubleValue() { kllSketchThrow(MUST_NOT_CALL); return Double.NaN; }

  @Override //Artifact of inheritance
  double getMinDoubleValue() { kllSketchThrow(MUST_NOT_CALL); return Double.NaN; }

  @Override //Artifact of inheritance
  void setDoubleItemsArray(final double[] doubleItems) { kllSketchThrow(MUST_NOT_CALL); }

  @Override //Artifact of inheritance
  void setDoubleItemsArrayAt(final int index, final double value) { kllSketchThrow(MUST_NOT_CALL); }

  @Override //Artifact of inheritance
  void setMaxDoubleValue(final double value) { kllSketchThrow(MUST_NOT_CALL); }

  @Override //Artifact of inheritance
  void setMinDoubleValue(final double value) { kllSketchThrow(MUST_NOT_CALL); }

}

1	/*
2	* Licensed to the Apache Software Foundation (ASF) under one
3	* or more contributor license agreements. See the NOTICE file
4	* distributed with this work for additional information
5	* regarding copyright ownership. The ASF licenses this file
6	* to you under the Apache License, Version 2.0 (the
7	* "License"); you may not use this file except in compliance
8	* with the License. You may obtain a copy of the License at
9	*
10	* http://www.apache.org/licenses/LICENSE-2.0
11	*
12	* Unless required by applicable law or agreed to in writing,
13	* software distributed under the License is distributed on an
14	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15	* KIND, either express or implied. See the License for the
16	* specific language governing permissions and limitations
17	* under the License.
18	*/
19
20	package org.apache.datasketches.kll;
21
22	import static java.lang.Math.max;
23	import static java.lang.Math.min;
24	import static org.apache.datasketches.kll.KllPreambleUtil.getMemoryUpdatableFormatFlag;
25	import static org.apache.datasketches.kll.KllSketch.Error.MUST_NOT_BE_UPDATABLE_FORMAT;
26	import static org.apache.datasketches.kll.KllSketch.Error.MUST_NOT_CALL;
27	import static org.apache.datasketches.kll.KllSketch.Error.TGT_IS_READ_ONLY;
28	import static org.apache.datasketches.kll.KllSketch.Error.kllSketchThrow;
29
30	import java.util.Objects;
31
32	import org.apache.datasketches.memory.Memory;
33	import org.apache.datasketches.memory.MemoryRequestServer;
34	import org.apache.datasketches.memory.WritableMemory;
35
36	public abstract class KllFloatsSketch extends KllSketch {
37
38	KllFloatsSketch(final WritableMemory wmem, final MemoryRequestServer memReqSvr) {
39	super(SketchType.FLOATS_SKETCH, wmem, memReqSvr);	1✔
40	}	1✔
41
42	/**
43	* Returns upper bound on the serialized size of a KllFloatsSketch given the following parameters.
44	* @param k parameter that controls size of the sketch and accuracy of estimates
45	* @param n stream length
46	* @param updatableMemoryFormat true if updatable Memory format, otherwise the standard compact format.
47	* @return upper bound on the serialized size of a KllSketch.
48	*/
49	public static int getMaxSerializedSizeBytes(final int k, final long n, final boolean updatableMemoryFormat) {
50	return getMaxSerializedSizeBytes(k, n, SketchType.FLOATS_SKETCH, updatableMemoryFormat);	1✔
51	}
52
53	/**
54	* Factory heapify takes the sketch image in Memory and instantiates an on-heap sketch.
55	* The resulting sketch will not retain any link to the source Memory.
56	* @param srcMem a Memory image of a sketch serialized by this sketch.
57	* <a href="{@docRoot}/resources/dictionary.html#mem">See Memory</a>
58	* @return a heap-based sketch based on the given Memory.
59	*/
60	public static KllFloatsSketch heapify(final Memory srcMem) {
61	Objects.requireNonNull(srcMem, "Parameter 'srcMem' must not be null");	1✔
62	if (getMemoryUpdatableFormatFlag(srcMem)) { Error.kllSketchThrow(MUST_NOT_BE_UPDATABLE_FORMAT); }	1✔
63	return KllHeapFloatsSketch.heapifyImpl(srcMem);	1✔
64	}
65
66	/**
67	* Create a new direct instance of this sketch with a given <em>k</em>.
68	* @param k parameter that controls size of the sketch and accuracy of estimates.
69	* @param dstMem the given destination WritableMemory object for use by the sketch
70	* @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
71	* @return a new direct instance of this sketch
72	*/
73	public static KllFloatsSketch newDirectInstance(
74	final int k,
75	final WritableMemory dstMem,
76	final MemoryRequestServer memReqSvr) {
77	Objects.requireNonNull(dstMem, "Parameter 'dstMem' must not be null");	1✔
78	Objects.requireNonNull(memReqSvr, "Parameter 'memReqSvr' must not be null");	1✔
79	return KllDirectFloatsSketch.newDirectInstance(k, DEFAULT_M, dstMem, memReqSvr);	1✔
80	}
81
82	/**
83	* Create a new direct instance of this sketch with the default <em>k</em>.
84	* The default <em>k</em> = 200 results in a normalized rank error of about
85	* 1.65%. Higher values of <em>k</em> will have smaller error but the sketch will be larger (and slower).
86	* @param dstMem the given destination WritableMemory object for use by the sketch
87	* @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
88	* @return a new direct instance of this sketch
89	*/
90	public static KllFloatsSketch newDirectInstance(
91	final WritableMemory dstMem,
92	final MemoryRequestServer memReqSvr) {
93	Objects.requireNonNull(dstMem, "Parameter 'dstMem' must not be null");	1✔
94	Objects.requireNonNull(memReqSvr, "Parameter 'memReqSvr' must not be null");	1✔
95	return KllDirectFloatsSketch.newDirectInstance(DEFAULT_K, DEFAULT_M, dstMem, memReqSvr);	1✔
96	}
97
98	/**
99	* Create a new heap instance of this sketch with the default <em>k = 200</em>.
100	* The default <em>k</em> = 200 results in a normalized rank error of about
101	* 1.65%. Higher values of K will have smaller error but the sketch will be larger (and slower).
102	* This will have a rank error of about 1.65%.
103	* @return new KllFloatsSketch on the heap.
104	*/
105	public static KllFloatsSketch newHeapInstance() {
106	return new KllHeapFloatsSketch(DEFAULT_K, DEFAULT_M);	1✔
107	}
108
109	/**
110	* Create a new heap instance of this sketch with a given parameter <em>k</em>.
111	* <em>k</em> can be any value between DEFAULT_M and 65535, inclusive.
112	* The default <em>k</em> = 200 results in a normalized rank error of about
113	* 1.65%. Higher values of K will have smaller error but the sketch will be larger (and slower).
114	* @param k parameter that controls size of the sketch and accuracy of estimates.
115	* @return new KllFloatsSketch on the heap.
116	*/
117	public static KllFloatsSketch newHeapInstance(final int k) {
118	return new KllHeapFloatsSketch(k, DEFAULT_M);	1✔
119	}
120
121	/**
122	* Wrap a sketch around the given read only source Memory containing sketch data
123	* that originated from this sketch.
124	* @param srcMem the read only source Memory
125	* @return instance of this sketch
126	*/
127	public static KllFloatsSketch wrap(final Memory srcMem) {
128	Objects.requireNonNull(srcMem, "Parameter 'srcMem' must not be null");	1✔
129	final KllMemoryValidate memVal = new KllMemoryValidate(srcMem);	1✔
130	if (memVal.updatableMemFormat) {	1✔
131	return new KllDirectFloatsSketch((WritableMemory) srcMem, null, memVal);	1✔
132	} else {
133	return new KllDirectCompactFloatsSketch(srcMem, memVal);	1✔
134	}
135	}
136
137	/**
138	* Wrap a sketch around the given source Writable Memory containing sketch data
139	* that originated from this sketch.
140	* @param srcMem a WritableMemory that contains data.
141	* @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
142	* @return instance of this sketch
143	*/
144	public static KllFloatsSketch writableWrap(
145	final WritableMemory srcMem,
146	final MemoryRequestServer memReqSvr) {
147	Objects.requireNonNull(srcMem, "Parameter 'srcMem' must not be null");	1✔
148	final KllMemoryValidate memVal = new KllMemoryValidate(srcMem);	1✔
149	if (memVal.updatableMemFormat) {	1✔
150	if (!memVal.readOnly) {	1✔
151	Objects.requireNonNull(memReqSvr, "Parameter 'memReqSvr' must not be null");	1✔
152	}
153	return new KllDirectFloatsSketch(srcMem, memReqSvr, memVal);	1✔
154	} else {
155	return new KllDirectCompactFloatsSketch(srcMem, memVal);	1✔
156	}
157	}
158
159	/**
160	* Returns an approximation to the Cumulative Distribution Function (CDF), which is the
161	* cumulative analog of the PMF, of the input stream given a set of splitPoint (values).
162	*
163	* <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
164	* getNormalizedRankError(false) function.
165	*
166	* <p>If the sketch is empty this returns null.</p>
167	*
168	* @param splitPoints an array of <i>m</i> unique, monotonically increasing float values
169	* that divide the real number line into <i>m+1</i> consecutive disjoint intervals.
170	* The definition of an "interval" is inclusive of the left splitPoint (or minimum value) and
171	* exclusive of the right splitPoint, with the exception that the last interval will include
172	* the maximum value.
173	* It is not necessary to include either the min or max values in these split points.
174	*
175	* @param inclusive if true the weight of the given value is included into the rank.
176	* Otherwise the rank equals the sum of the weights of all values that are less than the given value
177	*
178	* @return an array of m+1 double values on the interval [0.0, 1.0),
179	* which are a consecutive approximation to the CDF of the input stream given the splitPoints.
180	* The value at array position j of the returned CDF array is the sum of the returned values
181	* in positions 0 through j of the returned PMF array.
182	*/
183	public double[] getCDF(final float[] splitPoints, final boolean inclusive) {
184	return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, true, inclusive);	1✔
185	}
186
187	/**
188	* Same as {@link #getCDF(float[], boolean) getCDF(float[] splitPoints, false)}
189	* @param splitPoints splitPoints
190	* @return CDF
191	*/
192	public double[] getCDF(final float[] splitPoints) {
193	return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, true, false);	1✔
194	}
195
196	/**
197	* Returns the max value of the stream.
198	* If the sketch is empty this returns NaN.
199	*
200	* @return the max value of the stream
201	*/
202	public float getMaxValue() { return getMaxFloatValue(); }	1✔
203
204	/**
205	* Returns the min value of the stream.
206	* If the sketch is empty this returns NaN.
207	*
208	* @return the min value of the stream
209	*/
210	public float getMinValue() { return getMinFloatValue(); }	1✔
211
212	/**
213	* Returns an approximation to the Probability Mass Function (PMF) of the input stream
214	* given a set of splitPoints (values).
215	*
216	* <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
217	* getNormalizedRankError(true) function.
218	*
219	* <p>If the sketch is empty this returns null.</p>
220	*
221	* @param splitPoints an array of <i>m</i> unique, monotonically increasing float values
222	* that divide the real number line into <i>m+1</i> consecutive disjoint intervals.
223	* The definition of an "interval" is inclusive of the left splitPoint (or minimum value) and
224	* exclusive of the right splitPoint, with the exception that the last interval will include
225	* the maximum value.
226	* It is not necessary to include either the min or max values in these split points.
227	*
228	* @param inclusive if true the weight of the given value is included into the rank.
229	* Otherwise the rank equals the sum of the weights of all values that are less than the given value
230	*
231	* @return an array of m+1 doubles on the interval [0.0, 1.0),
232	* each of which is an approximation to the fraction of the total input stream values
233	* (the mass) that fall into one of those intervals.
234	* The definition of an "interval" is inclusive of the left splitPoint and exclusive of the right
235	* splitPoint, with the exception that the last interval will include maximum value.
236	*/
237	public double[] getPMF(final float[] splitPoints, final boolean inclusive) {
238	return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, false, inclusive);	1✔
239	}
240
241	/**
242	* Same as {@link #getPMF(float[], boolean) getPMF(float[] splitPoints, false)}
243	* @param splitPoints splitPoints
244	* @return PMF
245	*/
246	public double[] getPMF(final float[] splitPoints) {
247	return KllFloatsHelper.getFloatsPmfOrCdf(this, splitPoints, false, false);	1✔
248	}
249
250	/**
251	* Returns an approximation to the value of the data item
252	* that would be preceded by the given fraction of a hypothetical sorted
253	* version of the input stream so far.
254	*
255	* <p>We note that this method has a fairly large overhead (microseconds instead of nanoseconds)
256	* so it should not be called multiple times to get different quantiles from the same
257	* sketch. Instead use getQuantiles(), which pays the overhead only once.
258	*
259	* <p>If the sketch is empty this returns NaN.
260	*
261	* @param fraction the specified fractional position in the hypothetical sorted stream.
262	* These are also called normalized ranks or fractional ranks.
263	* If fraction = 0.0, the true minimum value of the stream is returned.
264	* If fraction = 1.0, the true maximum value of the stream is returned.
265	*
266	* @param inclusive if true, the given fraction (rank) is considered inclusive
267	* @return the approximation to the value at the given fraction
268	*/
269	public float getQuantile(final double fraction, final boolean inclusive) {
270	return KllFloatsHelper.getFloatsQuantile(this, fraction, inclusive);	1✔
271	}
272
273	/**
274	* Same as {@link #getQuantile(double, boolean) getQuantile(double fraction, false)}
275	* @param fraction fractional rank
276	* @return quantile
277	*/
278	public float getQuantile(final double fraction) {
279	return KllFloatsHelper.getFloatsQuantile(this, fraction, false);	1✔
280	}
281
282	/**
283	* Gets the lower bound of the value interval in which the true quantile of the given rank
284	* exists with a confidence of at least 99%.
285	* @param fraction the given normalized rank as a fraction
286	* @return the lower bound of the value interval in which the true quantile of the given rank
287	* exists with a confidence of at least 99%. Returns NaN if the sketch is empty.
288	*/
289	public float getQuantileLowerBound(final double fraction) {
290	return getQuantile(max(0, fraction - KllHelper.getNormalizedRankError(getMinK(), false)));	1✔
291	}
292
293	/**
294	* This is a more efficient multiple-query version of getQuantile().
295	*
296	* <p>This returns an array that could have been generated by using getQuantile() with many
297	* different fractional ranks, but would be very inefficient.
298	* This method incurs the internal set-up overhead once and obtains multiple quantile values in
299	* a single query. It is strongly recommend that this method be used instead of multiple calls
300	* to getQuantile().
301	*
302	* <p>If the sketch is empty this returns null.
303	*
304	* @param fractions given array of fractional positions in the hypothetical sorted stream.
305	* These are also called normalized ranks or fractional ranks.
306	* These fractions must be in the interval [0.0, 1.0], inclusive.
307	*
308	* @param inclusive if true, the given fractions (ranks) are considered inclusive
309	* @return array of approximations to the given fractions in the same order as given fractions
310	* array.
311	*/
312	public float[] getQuantiles(final double[] fractions, final boolean inclusive) {
313	return KllFloatsHelper.getFloatsQuantiles(this, fractions, inclusive);	1✔
314	}
315
316	/**
317	* Same as {@link #getQuantiles(double[], boolean) getQuantiles(double[] fractions, false)}
318	* @param fractions fractional ranks
319	* @return quantiles
320	*/
321	public float[] getQuantiles(final double[] fractions) {
322	return KllFloatsHelper.getFloatsQuantiles(this, fractions, false);	1✔
323	}
324
325	/**
326	* This is also a more efficient multiple-query version of getQuantile() and allows the caller to
327	* specify the number of evenly spaced fractional ranks.
328	*
329	* <p>If the sketch is empty this returns null.
330	*
331	* @param numEvenlySpaced an integer that specifies the number of evenly spaced fractional ranks.
332	* This must be a positive integer greater than 0. A value of 1 will return the min value.
333	* A value of 2 will return the min and the max value. A value of 3 will return the min,
334	* the median and the max value, etc.
335	*
336	* @param inclusive if true, the fractional ranks are considered inclusive
337	* @return array of approximations to the given fractions in the same order as given fractions
338	* array.
339	*/
340	public float[] getQuantiles(final int numEvenlySpaced, final boolean inclusive) {
341	if (isEmpty()) { return null; }	×
342	return getQuantiles(org.apache.datasketches.Util.evenlySpaced(0.0, 1.0, numEvenlySpaced), inclusive);	×
343	}
344
345	/**
346	* Same as {@link #getQuantiles(int, boolean) getQuantiles(int numEvenlySpaced, false)}
347	* @param numEvenlySpaced number of evenly spaced fractional ranks
348	* @return quantiles
349	*/
350	public float[] getQuantiles(final int numEvenlySpaced) {
351	if (isEmpty()) { return null; }	1✔
352	return getQuantiles(org.apache.datasketches.Util.evenlySpaced(0.0, 1.0, numEvenlySpaced));	1✔
353	}
354
355	/**
356	* Gets the upper bound of the value interval in which the true quantile of the given rank
357	* exists with a confidence of at least 99%.
358	* @param fraction the given normalized rank as a fraction
359	* @return the upper bound of the value interval in which the true quantile of the given rank
360	* exists with a confidence of at least 99%. Returns NaN if the sketch is empty.
361	*/
362	public float getQuantileUpperBound(final double fraction) {
363	return getQuantile(min(1.0, fraction + KllHelper.getNormalizedRankError(getMinK(), false)));	1✔
364	}
365
366	/**
367	* Returns an approximation to the normalized (fractional) rank of the given value from 0 to 1,
368	* inclusive.
369	*
370	* <p>The resulting approximation has a probabilistic guarantee that can be obtained from the
371	* getNormalizedRankError(false) function.
372	*
373	* <p>If the sketch is empty this returns NaN.</p>
374	*
375	* @param value to be ranked
376	* @param inclusive if true the weight of the given value is included into the rank.
377	* Otherwise the rank equals the sum of the weights of all values that are less than the given value
378	* @return an approximate rank of the given value
379	*/
380	public double getRank(final float value, final boolean inclusive) {
381	return KllFloatsHelper.getFloatRank(this, value, inclusive);	1✔
382	}
383
384	/**
385	* Same as {@link #getRank(float, boolean) getRank(float value, false)}
386	* @param value value to be ranked
387	* @return fractional rank
388	*/
389	public double getRank(final float value) {
390	return KllFloatsHelper.getFloatRank(this, value, false);	1✔
391	}
392
393	/**
394	* @return the iterator for this class
395	*/
396	public KllFloatsSketchIterator iterator() {
397	return new KllFloatsSketchIterator(getFloatItemsArray(), getLevelsArray(), getNumLevels());	1✔
398	}
399
400	/**
401	* Updates this sketch with the given data item.
402	*
403	* @param value an item from a stream of items. NaNs are ignored.
404	*/
405	public void update(final float value) {
406	if (readOnly) { kllSketchThrow(TGT_IS_READ_ONLY); }	1✔
407	KllFloatsHelper.updateFloat(this, value);	1✔
408	}	1✔
409
410	@Override //Artifact of inheritance
411	double[] getDoubleItemsArray() { kllSketchThrow(MUST_NOT_CALL); return null; }	×
412
413	@Override //Artifact of inheritance
414	double getMaxDoubleValue() { kllSketchThrow(MUST_NOT_CALL); return Double.NaN; }	×
415
416	@Override //Artifact of inheritance
417	double getMinDoubleValue() { kllSketchThrow(MUST_NOT_CALL); return Double.NaN; }	×
418
419	@Override //Artifact of inheritance
420	void setDoubleItemsArray(final double[] doubleItems) { kllSketchThrow(MUST_NOT_CALL); }	×
421
422	@Override //Artifact of inheritance
423	void setDoubleItemsArrayAt(final int index, final double value) { kllSketchThrow(MUST_NOT_CALL); }	×
424
425	@Override //Artifact of inheritance
426	void setMaxDoubleValue(final double value) { kllSketchThrow(MUST_NOT_CALL); }	×
427
428	@Override //Artifact of inheritance
429	void setMinDoubleValue(final double value) { kllSketchThrow(MUST_NOT_CALL); }	×
430
431	}

apache / datasketches-java / #246

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous