#193

Build # #193

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/864d1c2832b9eaf404041c79843b8e3ee5623ee9">864d1c283<a href="https://github.com/apache/datasketches-java/commit/864d1c2832b9eaf404041c79843b8e3ee5623ee9">&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/864d1c2832b9eaf404041c79843b8e3ee5623ee9&quot;&gt;864d1c283&lt;/a&gt;&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/864d1c2832b9eaf404041c79843b8e3ee5623ee9&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/864d1c2832b9eaf404041c79843b8e3e&lt;/a&gt;e5623ee9&quot;>&quot;&gt;Merge &lt;/a&gt;&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/apache/datasketches-java/commit/<a class="double-link" href="https://github.com/apache/datasketches-java/commit/091635be25188068eced3ccbaf030c254c447710">091635be2</a><a href="https://github.com/apache/datasketches-java/commit/864d1c2832b9eaf404041c79843b8e3ee5623ee9">&amp;quot;&amp;gt;091635be2&amp;lt;/a&amp;gt;&amp;quot;&amp;gt;091635be2&amp;lt;/a&amp;gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/864d1c2832b9eaf404041c79843b8e3ee5623&lt;/a&gt;ee9&quot;&gt; into &lt;/a&gt;&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/apache/datasketches-java/commit/<a class="double-link" href="https://github.com/apache/datasketches-java/commit/53cbfa964">53cbfa964">53cbfa964</a>

Run Details

1558 of 1558 new or added lines in 19 files covered. (100.0%)

19107 of 19474 relevant lines covered (98.12%)

0.98 hits per line

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

85.0

/src/main/java/org/apache/datasketches/kll/KllDoublesSketch.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.KllSketch.Error.SRC_IS_NOT_DOUBLE;
import static org.apache.datasketches.kll.KllSketch.Error.SRC_CANNOT_BE_DIRECT;
import static org.apache.datasketches.kll.KllSketch.Error.MUST_NOT_CALL;
import static org.apache.datasketches.kll.KllSketch.Error.kllSketchThrow;

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

/**
 * This class implements an on-heap doubles 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 KllDoublesSketch extends KllHeapSketch {
  private double[] doubleItems_;
  private double minDoubleValue_;
  private double maxDoubleValue_;

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

  /**
   * Heap constructor with the default <em>k = 200</em>.
   * This will have a rank error of about 1.65%.
   */
  public KllDoublesSketch() {
    this(KllSketch.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).
   * @param k parameter that controls size of the sketch and accuracy of estimates
   */
  public KllDoublesSketch(final int k) {
    this(k, KllSketch.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 in items.
   */
  KllDoublesSketch(final int k, final int m) {
    super(k, m, SketchType.DOUBLES_SKETCH);
    doubleItems_ = new double[k];
    minDoubleValue_ = Double.NaN;
    maxDoubleValue_ = Double.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 KllDoublesSketch heapify(final Memory mem) {
    final KllMemoryValidate memChk = new KllMemoryValidate(mem);
    if (!memChk.doublesSketch) {
      throw new SketchesArgumentException("Memory object is not a KllDoublesSketch.");
    }
    return new KllDoublesSketch(mem, memChk);
  }

  /**
   * 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 double 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),
   * 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 getDoublesPmfOrCdf(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).
   *
   * <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 double 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),
   * 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 getDoublesPmfOrCdf(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 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(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.
   *
   * @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.
   *
   * <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 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.
   *
   * <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 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(SRC_CANNOT_BE_DIRECT); }
    if (!other.isDoublesSketch()) { kllSketchThrow(SRC_IS_NOT_DOUBLE); }
    mergeDoubleImpl(other);
  }

  @Override
  public void reset() {
    final int k = getK();
    setN(0);
    setMinK(k);
    setNumLevels(1);
    setLevelsArray(new int[] {k, k});
    setLevelZeroSorted(false);
    doubleItems_ = new double[k];
    minDoubleValue_ = Double.NaN;
    maxDoubleValue_ = Double.NaN;
  }

  /**
   * 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);
  }

  @Override //Used internally
  double[] getDoubleItemsArray() { return doubleItems_; }

  @Override
  double getDoubleItemsArrayAt(final int index) { return doubleItems_[index]; }

  @Override //Dummy
  float[] getFloatItemsArray() { kllSketchThrow(MUST_NOT_CALL); return null; }

  @Override //Dummy
  float getFloatItemsArrayAt(final int index) { kllSketchThrow(MUST_NOT_CALL); return Float.NaN; }

  @Override //Used internally
  double getMaxDoubleValue() { return maxDoubleValue_; }

  @Override //Dummy
  float getMaxFloatValue() { kllSketchThrow(MUST_NOT_CALL); return (float) maxDoubleValue_; }

  @Override //Used internally
  double getMinDoubleValue() { return minDoubleValue_; }

  @Override //Dummy
  float getMinFloatValue() { kllSketchThrow(MUST_NOT_CALL); return (float) minDoubleValue_; }

  @Override //Used internally
  void setDoubleItemsArray(final double[] doubleItems) { doubleItems_ = doubleItems; }

  @Override //Used internally
  void setDoubleItemsArrayAt(final int index, final double value) { doubleItems_[index] = value; }

  @Override //Dummy
  void setFloatItemsArray(final float[] floatItems) { kllSketchThrow(MUST_NOT_CALL); }

  @Override //Dummy
  void setFloatItemsArrayAt(final int index, final float value) { kllSketchThrow(MUST_NOT_CALL); }

  @Override //Used internally
  void setMaxDoubleValue(final double value) { maxDoubleValue_ = value; }

  @Override //Dummy
  void setMaxFloatValue(final float value) { kllSketchThrow(MUST_NOT_CALL); }

  @Override //Used internally
  void setMinDoubleValue(final double value) { minDoubleValue_ = value; }

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

apache / datasketches-java / #193

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