#187

Build # #187

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/02f4b5e6af730d578bfb42d1c385a96a92f0505b">02f4b5e6a">&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/&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/02f4b5e6af730d578bfb42d1c385a96a92f0505b">02f4b5e6a</a><a href="https://github.com/apache/datasketches-java/commit/02f4b5e6af730d578bfb42d1c385a96a92f0505b">&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/&lt;/a&gt;&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/apache/datasketches-java/commit/02f4b5e6af730d578bfb42d1c385a96a92f0505b&quot;&gt;02f4b5e6a&lt;/a&gt;&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/02f4b5e6af730d578bfb42d1c385a96a92f0505b&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/02f4b5e6af730d578bfb42d1c385a96a92f0505b&amp;quot;&amp;gt;&amp;amp;quot;&amp;amp;gt;&am... (continued)

Run Details

1581 of 1581 new or added lines in 16 files covered. (100.0%)

19152 of 19502 relevant lines covered (98.21%)

0.98 hits per line

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

82.0

/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.DEFAULT_K;
import static org.apache.datasketches.kll.KllPreambleUtil.DEFAULT_M;
import static org.apache.datasketches.kll.KllSketch.ERRNO.ERR_SRC_IS_NOT_FLOAT;
import static org.apache.datasketches.kll.KllSketch.ERRNO.ERR_SRC_CANNOT_BE_DIRECT;
import static org.apache.datasketches.kll.KllSketch.ERRNO.ERR_MUST_NOT_CALL;

import org.apache.datasketches.SketchesArgumentException;
import org.apache.datasketches.memory.Memory;

/**
 * This class implements an on-heap floats KllSketch.
 *
 * <p>Please refer to the documentation in the package-info:<br>
 * {@link org.apache.datasketches.kll}</p>
 *
 * @author Lee Rhodes, Kevin Lang
 */
public final class KllFloatsSketch extends KllHeapSketch {
  private float[] floatItems_;
  private float minFloatValue_;
  private float maxFloatValue_;

  /**
   * Private heapify constructor.
   * @param mem Memory object that contains data serialized by this sketch.
   * @param memVal the MemoryCheck object
   */
  private KllFloatsSketch(final Memory mem, final KllMemoryValidate memVal) {
    super(memVal.k, memVal.m, SketchType.FLOATS_SKETCH);
    buildHeapKllSketchFromMemory(memVal);
  }

  /**
   * Heap constructor with the default <em>k = 200</em>, and DEFAULT_M of 8.
   * This will have a rank error of about 1.65%.
   */
  public KllFloatsSketch() {
    this(DEFAULT_K);
  }

  /**
   * Heap constructor 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).
   * This constructor assumes the DEFAULT_M, which is 8.
   * @param k parameter that controls size of the sketch and accuracy of estimates
   */
  public KllFloatsSketch(final int k) {
    this(k, DEFAULT_M);
  }

  /**
   * Heap constructor with a given parameter <em>k</em> and <em>m</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).
   * The DEFAULT_M, which is 8 is recommended for the given parameter <em>m</em>.
   * Other values of <em>m</em> should be considered experimental as they have not been
   * as well characterized.
   * @param k parameter that controls size of the sketch and accuracy of estimates
   * @param m parameter that controls the minimum level width.
   */
  KllFloatsSketch(final int k, final int m) {
    super(k, m, SketchType.FLOATS_SKETCH);
    floatItems_ = new float[k];
    minFloatValue_ = Float.NaN;
    maxFloatValue_ = Float.NaN;
  }

  /**
   * 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 mem 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 mem) {
    final KllMemoryValidate memVal = new KllMemoryValidate(mem);
    if (memVal.doublesSketch) {
      throw new SketchesArgumentException("Memory object is not a KllFloatsSketch.");
    }
    return new KllFloatsSketch(mem, 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.
   *
   * @return an array of m+1 double values on the interval [0.0, 1.0) exclusive,
   * 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) {
    return getFloatsPmfOrCdf(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 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.
   *
   * @return an array of m+1 doubles on the interval [0.0, 1.0) exclusive,
   * 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) {
    return getFloatsPmfOrCdf(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.
   *
   * <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.
   *
   * @return the approximation to the value at the given fraction
   */
  public float getQuantile(final double fraction) {
    return getFloatsQuantile(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 float getQuantileLowerBound(final double fraction) {
    return getQuantile(max(0, fraction - KllHelper.getNormalizedRankError(getDynamicMinK(), 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.
   *
   * @return array of approximations to the given fractions in the same order as given fractions
   * array.
   */
  public float[] getQuantiles(final double[] fractions) {
    return getFloatsQuantiles(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.
   *
   * <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.
   *
   * @return array of approximations to the given fractions in the same order as given fractions
   * array.
   */
  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(getDynamicMinK(), 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
   * @return an approximate rank of the given value
   */
  public double getRank(final float value) {
    return getFloatRank(value);
  }

  /**
   * @return the iterator for this class
   */
  public KllFloatsSketchIterator iterator() {
    return new KllFloatsSketchIterator(getFloatItemsArray(), getLevelsArray(), getNumLevels());
  }

  /**
   * Merges another sketch into this one.
   * @param other sketch to merge into this one
   */
  public void merge(final KllFloatsSketch other) {
    if (other.isDirect()) { kllSketchThrow(ERR_SRC_CANNOT_BE_DIRECT); }
    if (!other.isFloatsSketch()) { kllSketchThrow(ERR_SRC_IS_NOT_FLOAT); }
    mergeFloatImpl(other);
  }

  /**
   * 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) {
    updateFloat(value);
  }

  @Override //Dummy
  double[] getDoubleItemsArray() { kllSketchThrow(ERR_MUST_NOT_CALL); return null; }

  @Override //Dummy
  double getDoubleItemsArrayAt(final int index) { kllSketchThrow(ERR_MUST_NOT_CALL); return Double.NaN; }

  @Override //Used internally
  float[] getFloatItemsArray() { return floatItems_; }

  @Override //Used internally
  float getFloatItemsArrayAt(final int index) { return floatItems_[index]; }

  @Override //Dummy
  double getMaxDoubleValue() { kllSketchThrow(ERR_MUST_NOT_CALL); return maxFloatValue_; }

  @Override //Used internally
  float getMaxFloatValue() { return maxFloatValue_; }

  @Override //Dummy
  double getMinDoubleValue() { kllSketchThrow(ERR_MUST_NOT_CALL); return minFloatValue_; }

  @Override //Used internally
  float getMinFloatValue() { return minFloatValue_; }

  @Override //Dummy
  void setDoubleItemsArray(final double[] doubleItems) { kllSketchThrow(ERR_MUST_NOT_CALL); }

  @Override //Dummy
  void setDoubleItemsArrayAt(final int index, final double value) { kllSketchThrow(ERR_MUST_NOT_CALL); }

  @Override //Used internally
  void setFloatItemsArray(final float[] floatItems) { floatItems_ = floatItems; }

  @Override //Used internally
  void setFloatItemsArrayAt(final int index, final float value) { floatItems_[index] = value; }

  @Override //Dummy
  void setMaxDoubleValue(final double value) { kllSketchThrow(ERR_MUST_NOT_CALL); }

  @Override //Used internally
  void setMaxFloatValue(final float value) { maxFloatValue_ = value; }

  @Override //Dummy
  void setMinDoubleValue(final double value) { kllSketchThrow(ERR_MUST_NOT_CALL); }

  @Override //Used internally
  void setMinFloatValue(final float value) { minFloatValue_ = value; }

}

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.DEFAULT_K;
25	import static org.apache.datasketches.kll.KllPreambleUtil.DEFAULT_M;
26	import static org.apache.datasketches.kll.KllSketch.ERRNO.ERR_SRC_IS_NOT_FLOAT;
27	import static org.apache.datasketches.kll.KllSketch.ERRNO.ERR_SRC_CANNOT_BE_DIRECT;
28	import static org.apache.datasketches.kll.KllSketch.ERRNO.ERR_MUST_NOT_CALL;
29
30	import org.apache.datasketches.SketchesArgumentException;
31	import org.apache.datasketches.memory.Memory;
32
33	/**
34	* This class implements an on-heap floats KllSketch.
35	*
36	* <p>Please refer to the documentation in the package-info:<br>
37	* {@link org.apache.datasketches.kll}</p>
38	*
39	* @author Lee Rhodes, Kevin Lang
40	*/
41	public final class KllFloatsSketch extends KllHeapSketch {
42	private float[] floatItems_;
43	private float minFloatValue_;
44	private float maxFloatValue_;
45
46	/**
47	* Private heapify constructor.
48	* @param mem Memory object that contains data serialized by this sketch.
49	* @param memVal the MemoryCheck object
50	*/
51	private KllFloatsSketch(final Memory mem, final KllMemoryValidate memVal) {
52	super(memVal.k, memVal.m, SketchType.FLOATS_SKETCH);	1✔
53	buildHeapKllSketchFromMemory(memVal);	1✔
54	}	1✔
55
56	/**
57	* Heap constructor with the default <em>k = 200</em>, and DEFAULT_M of 8.
58	* This will have a rank error of about 1.65%.
59	*/
60	public KllFloatsSketch() {
61	this(DEFAULT_K);	1✔
62	}	1✔
63
64	/**
65	* Heap constructor with a given parameter <em>k</em>. <em>k</em> can be any value between DEFAULT_M and
66	* 65535, inclusive. The default <em>k</em> = 200 results in a normalized rank error of about
67	* 1.65%. Higher values of K will have smaller error but the sketch will be larger (and slower).
68	* This constructor assumes the DEFAULT_M, which is 8.
69	* @param k parameter that controls size of the sketch and accuracy of estimates
70	*/
71	public KllFloatsSketch(final int k) {
72	this(k, DEFAULT_M);	1✔
73	}	1✔
74
75	/**
76	* Heap constructor with a given parameter <em>k</em> and <em>m</em>.
77	* <em>k</em> can be any value between DEFAULT_M and 65535, inclusive.
78	* The default <em>k</em> = 200 results in a normalized rank error of about 1.65%.
79	* Higher values of K will have smaller error but the sketch will be larger (and slower).
80	* The DEFAULT_M, which is 8 is recommended for the given parameter <em>m</em>.
81	* Other values of <em>m</em> should be considered experimental as they have not been
82	* as well characterized.
83	* @param k parameter that controls size of the sketch and accuracy of estimates
84	* @param m parameter that controls the minimum level width.
85	*/
86	KllFloatsSketch(final int k, final int m) {
87	super(k, m, SketchType.FLOATS_SKETCH);	1✔
88	floatItems_ = new float[k];	1✔
89	minFloatValue_ = Float.NaN;	1✔
90	maxFloatValue_ = Float.NaN;	1✔
91	}	1✔
92
93	/**
94	* Factory heapify takes the sketch image in Memory and instantiates an on-heap sketch.
95	* The resulting sketch will not retain any link to the source Memory.
96	* @param mem a Memory image of a sketch serialized by this sketch.
97	* <a href="{@docRoot}/resources/dictionary.html#mem">See Memory</a>
98	* @return a heap-based sketch based on the given Memory.
99	*/
100	public static KllFloatsSketch heapify(final Memory mem) {
101	final KllMemoryValidate memVal = new KllMemoryValidate(mem);	1✔
102	if (memVal.doublesSketch) {	1✔
103	throw new SketchesArgumentException("Memory object is not a KllFloatsSketch.");	×
104	}
105	return new KllFloatsSketch(mem, memVal);	1✔
106	}
107
108	/**
109	* Returns an approximation to the Cumulative Distribution Function (CDF), which is the
110	* cumulative analog of the PMF, of the input stream given a set of splitPoint (values).
111	*
112	* <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
113	* getNormalizedRankError(false) function.
114	*
115	* <p>If the sketch is empty this returns null.</p>
116	*
117	* @param splitPoints an array of <i>m</i> unique, monotonically increasing float values
118	* that divide the real number line into <i>m+1</i> consecutive disjoint intervals.
119	* The definition of an "interval" is inclusive of the left splitPoint (or minimum value) and
120	* exclusive of the right splitPoint, with the exception that the last interval will include
121	* the maximum value.
122	* It is not necessary to include either the min or max values in these split points.
123	*
124	* @return an array of m+1 double values on the interval [0.0, 1.0) exclusive,
125	* which are a consecutive approximation to the CDF of the input stream given the splitPoints.
126	* The value at array position j of the returned CDF array is the sum of the returned values
127	* in positions 0 through j of the returned PMF array.
128	*/
129	public double[] getCDF(final float[] splitPoints) {
130	return getFloatsPmfOrCdf(splitPoints, true);	1✔
131	}
132
133	/**
134	* Returns the max value of the stream.
135	* If the sketch is empty this returns NaN.
136	*
137	* @return the max value of the stream
138	*/
139	public float getMaxValue() { return getMaxFloatValue(); }	1✔
140
141	/**
142	* Returns the min value of the stream.
143	* If the sketch is empty this returns NaN.
144	*
145	* @return the min value of the stream
146	*/
147	public float getMinValue() { return getMinFloatValue(); }	1✔
148
149	/**
150	* Returns an approximation to the Probability Mass Function (PMF) of the input stream
151	* given a set of splitPoints (values).
152	*
153	* <p>The resulting approximations have a probabilistic guarantee that can be obtained from the
154	* getNormalizedRankError(true) function.
155	*
156	* <p>If the sketch is empty this returns null.</p>
157	*
158	* @param splitPoints an array of <i>m</i> unique, monotonically increasing float values
159	* that divide the real number line into <i>m+1</i> consecutive disjoint intervals.
160	* The definition of an "interval" is inclusive of the left splitPoint (or minimum value) and
161	* exclusive of the right splitPoint, with the exception that the last interval will include
162	* the maximum value.
163	* It is not necessary to include either the min or max values in these split points.
164	*
165	* @return an array of m+1 doubles on the interval [0.0, 1.0) exclusive,
166	* each of which is an approximation to the fraction of the total input stream values
167	* (the mass) that fall into one of those intervals.
168	* The definition of an "interval" is inclusive of the left splitPoint and exclusive of the right
169	* splitPoint, with the exception that the last interval will include maximum value.
170	*/
171	public double[] getPMF(final float[] splitPoints) {
172	return getFloatsPmfOrCdf(splitPoints, false);	1✔
173	}
174
175	/**
176	* Returns an approximation to the value of the data item
177	* that would be preceded by the given fraction of a hypothetical sorted
178	* version of the input stream so far.
179	*
180	* <p>We note that this method has a fairly large overhead (microseconds instead of nanoseconds)
181	* so it should not be called multiple times to get different quantiles from the same
182	* sketch. Instead use getQuantiles(), which pays the overhead only once.
183	*
184	* <p>If the sketch is empty this returns NaN.
185	*
186	* @param fraction the specified fractional position in the hypothetical sorted stream.
187	* These are also called normalized ranks or fractional ranks.
188	* If fraction = 0.0, the true minimum value of the stream is returned.
189	* If fraction = 1.0, the true maximum value of the stream is returned.
190	*
191	* @return the approximation to the value at the given fraction
192	*/
193	public float getQuantile(final double fraction) {
194	return getFloatsQuantile(fraction);	1✔
195	}
196
197	/**
198	* Gets the lower bound of the value interval in which the true quantile of the given rank
199	* exists with a confidence of at least 99%.
200	* @param fraction the given normalized rank as a fraction
201	* @return the lower bound of the value interval in which the true quantile of the given rank
202	* exists with a confidence of at least 99%. Returns NaN if the sketch is empty.
203	*/
204	public float getQuantileLowerBound(final double fraction) {
205	return getQuantile(max(0, fraction - KllHelper.getNormalizedRankError(getDynamicMinK(), false)));	1✔
206	}
207
208	/**
209	* This is a more efficient multiple-query version of getQuantile().
210	*
211	* <p>This returns an array that could have been generated by using getQuantile() with many
212	* different fractional ranks, but would be very inefficient.
213	* This method incurs the internal set-up overhead once and obtains multiple quantile values in
214	* a single query. It is strongly recommend that this method be used instead of multiple calls
215	* to getQuantile().
216	*
217	* <p>If the sketch is empty this returns null.
218	*
219	* @param fractions given array of fractional positions in the hypothetical sorted stream.
220	* These are also called normalized ranks or fractional ranks.
221	* These fractions must be in the interval [0.0, 1.0], inclusive.
222	*
223	* @return array of approximations to the given fractions in the same order as given fractions
224	* array.
225	*/
226	public float[] getQuantiles(final double[] fractions) {
227	return getFloatsQuantiles(fractions);	1✔
228	}
229
230	/**
231	* This is also a more efficient multiple-query version of getQuantile() and allows the caller to
232	* specify the number of evenly spaced fractional ranks.
233	*
234	* <p>If the sketch is empty this returns null.
235	*
236	* @param numEvenlySpaced an integer that specifies the number of evenly spaced fractional ranks.
237	* This must be a positive integer greater than 0. A value of 1 will return the min value.
238	* A value of 2 will return the min and the max value. A value of 3 will return the min,
239	* the median and the max value, etc.
240	*
241	* @return array of approximations to the given fractions in the same order as given fractions
242	* array.
243	*/
244	public float[] getQuantiles(final int numEvenlySpaced) {
245	if (isEmpty()) { return null; }	1✔
246	return getQuantiles(org.apache.datasketches.Util.evenlySpaced(0.0, 1.0, numEvenlySpaced));	1✔
247	}
248
249	/**
250	* Gets the upper bound of the value interval in which the true quantile of the given rank
251	* exists with a confidence of at least 99%.
252	* @param fraction the given normalized rank as a fraction
253	* @return the upper bound of the value interval in which the true quantile of the given rank
254	* exists with a confidence of at least 99%. Returns NaN if the sketch is empty.
255	*/
256	public float getQuantileUpperBound(final double fraction) {
257	return getQuantile(min(1.0, fraction + KllHelper.getNormalizedRankError(getDynamicMinK(), false)));	1✔
258	}
259
260	/**
261	* Returns an approximation to the normalized (fractional) rank of the given value from 0 to 1,
262	* inclusive.
263	*
264	* <p>The resulting approximation has a probabilistic guarantee that can be obtained from the
265	* getNormalizedRankError(false) function.
266	*
267	* <p>If the sketch is empty this returns NaN.</p>
268	*
269	* @param value to be ranked
270	* @return an approximate rank of the given value
271	*/
272	public double getRank(final float value) {
273	return getFloatRank(value);	1✔
274	}
275
276	/**
277	* @return the iterator for this class
278	*/
279	public KllFloatsSketchIterator iterator() {
280	return new KllFloatsSketchIterator(getFloatItemsArray(), getLevelsArray(), getNumLevels());	1✔
281	}
282
283	/**
284	* Merges another sketch into this one.
285	* @param other sketch to merge into this one
286	*/
287	public void merge(final KllFloatsSketch other) {
288	if (other.isDirect()) { kllSketchThrow(ERR_SRC_CANNOT_BE_DIRECT); }	1✔
289	if (!other.isFloatsSketch()) { kllSketchThrow(ERR_SRC_IS_NOT_FLOAT); }	1✔
290	mergeFloatImpl(other);	1✔
291	}	1✔
292
293	/**
294	* Updates this sketch with the given data item.
295	*
296	* @param value an item from a stream of items. NaNs are ignored.
297	*/
298	public void update(final float value) {
299	updateFloat(value);	1✔
300	}	1✔
301
302	@Override //Dummy
303	double[] getDoubleItemsArray() { kllSketchThrow(ERR_MUST_NOT_CALL); return null; }	×
304
305	@Override //Dummy
306	double getDoubleItemsArrayAt(final int index) { kllSketchThrow(ERR_MUST_NOT_CALL); return Double.NaN; }	×
307
308	@Override //Used internally
309	float[] getFloatItemsArray() { return floatItems_; }	1✔
310
311	@Override //Used internally
312	float getFloatItemsArrayAt(final int index) { return floatItems_[index]; }	1✔
313
314	@Override //Dummy
315	double getMaxDoubleValue() { kllSketchThrow(ERR_MUST_NOT_CALL); return maxFloatValue_; }	×
316
317	@Override //Used internally
318	float getMaxFloatValue() { return maxFloatValue_; }	1✔
319
320	@Override //Dummy
321	double getMinDoubleValue() { kllSketchThrow(ERR_MUST_NOT_CALL); return minFloatValue_; }	×
322
323	@Override //Used internally
324	float getMinFloatValue() { return minFloatValue_; }	1✔
325
326	@Override //Dummy
327	void setDoubleItemsArray(final double[] doubleItems) { kllSketchThrow(ERR_MUST_NOT_CALL); }	×
328
329	@Override //Dummy
330	void setDoubleItemsArrayAt(final int index, final double value) { kllSketchThrow(ERR_MUST_NOT_CALL); }	×
331
332	@Override //Used internally
333	void setFloatItemsArray(final float[] floatItems) { floatItems_ = floatItems; }	1✔
334
335	@Override //Used internally
336	void setFloatItemsArrayAt(final int index, final float value) { floatItems_[index] = value; }	1✔
337
338	@Override //Dummy
339	void setMaxDoubleValue(final double value) { kllSketchThrow(ERR_MUST_NOT_CALL); }	×
340
341	@Override //Used internally
342	void setMaxFloatValue(final float value) { maxFloatValue_ = value; }	1✔
343
344	@Override //Dummy
345	void setMinDoubleValue(final double value) { kllSketchThrow(ERR_MUST_NOT_CALL); }	×
346
347	@Override //Used internally
348	void setMinFloatValue(final float value) { minFloatValue_ = value; }	1✔
349
350	}

apache / datasketches-java / #187

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