#191

Build # #191

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/e355801c5b87c2ef5c1cf99ac942f7e8d92e7533">e355801c5<a href="https://github.com/apache/datasketches-java/commit/e355801c5b87c2ef5c1cf99ac942f7e8d92e7533">&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/e355801c5b87c2ef5c1cf99ac942f7e8d92e7533&quot;&gt;e355801c5&lt;/a&gt;&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/e355801c5b87c2ef5c1cf99ac942f7e8d92e7533&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/e355801c5b87c2ef5c1cf99ac942f7e8&lt;/a&gt;d92e7533&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/0e5dde14f336f3970ec38a356f48461b4435a2e8">0e5dde14f</a><a href="https://github.com/apache/datasketches-java/commit/e355801c5b87c2ef5c1cf99ac942f7e8d92e7533">&amp;quot;&amp;gt;0e5dde14f&amp;lt;/a&amp;gt;&amp;quot;&amp;gt;0e5dde14f&amp;lt;/a&amp;gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/e355801c5b87c2ef5c1cf99ac942f7e8d92e7&lt;/a&gt;533&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

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

19181 of 19549 relevant lines covered (98.12%)

0.98 hits per line

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

87.3

/src/main/java/org/apache/datasketches/kll/KllDirectDoublesSketch.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.DATA_START_ADR_DOUBLE;
import static org.apache.datasketches.kll.KllPreambleUtil.DOUBLES_SKETCH_BIT_MASK;
import static org.apache.datasketches.kll.KllPreambleUtil.PREAMBLE_INTS_DOUBLE;
import static org.apache.datasketches.kll.KllPreambleUtil.SERIAL_VERSION_UPDATABLE;
import static org.apache.datasketches.kll.KllPreambleUtil.UPDATABLE_BIT_MASK;
import static org.apache.datasketches.kll.KllPreambleUtil.insertMinK;
import static org.apache.datasketches.kll.KllPreambleUtil.insertFamilyID;
import static org.apache.datasketches.kll.KllPreambleUtil.insertFlags;
import static org.apache.datasketches.kll.KllPreambleUtil.insertK;
import static org.apache.datasketches.kll.KllPreambleUtil.insertM;
import static org.apache.datasketches.kll.KllPreambleUtil.insertN;
import static org.apache.datasketches.kll.KllPreambleUtil.insertNumLevels;
import static org.apache.datasketches.kll.KllPreambleUtil.insertPreInts;
import static org.apache.datasketches.kll.KllPreambleUtil.insertSerVer;
import static org.apache.datasketches.kll.KllSketch.Error.MUST_NOT_CALL;
import static org.apache.datasketches.kll.KllSketch.Error.SRC_IS_NOT_DIRECT;
import static org.apache.datasketches.kll.KllSketch.Error.SRC_IS_NOT_DOUBLE;
import static org.apache.datasketches.kll.KllSketch.Error.TGT_IS_IMMUTABLE;

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

/**
 * This class implements an off-heap doubles KllSketch via a WritableMemory instance of the sketch.
 *
 * <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 KllDirectDoublesSketch extends KllDirectSketch {

  /**
   * The actual constructor.
   * @param wmem the current WritableMemory
   * @param memReqSvr the given MemoryRequestServer to request a larger WritableMemory
   * @param memVal the MemoryValadate object
   */
  private KllDirectDoublesSketch(final WritableMemory wmem, final MemoryRequestServer memReqSvr,
      final KllMemoryValidate memVal) {
    super(SketchType.DOUBLES_SKETCH, wmem, memReqSvr, memVal);
  }

  /**
   * Wrap a sketch around the given source 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 KllDirectDoublesSketch writableWrap(final WritableMemory srcMem, final MemoryRequestServer memReqSvr) {
    final KllMemoryValidate memVal = new KllMemoryValidate(srcMem);
    return new KllDirectDoublesSketch(srcMem, memReqSvr, memVal);
  }

  /**
   * Create a new instance of this sketch using the default <i>m</i> of 8.
   * @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 instance of this sketch
   */
  public static KllDirectDoublesSketch newInstance(final int k, final WritableMemory dstMem,
      final MemoryRequestServer memReqSvr) {
    return newInstance(k, KllSketch.DEFAULT_M, dstMem, memReqSvr);
  }

  /**
   * Create a new instance of this sketch.
   * @param k parameter that controls size of the sketch and accuracy of estimates
   * @param m parameter that controls the minimum level width.
   * @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 instance of this sketch
   */
  static KllDirectDoublesSketch newInstance(final int k, final int m, final WritableMemory dstMem,
      final MemoryRequestServer memReqSvr) {
    insertPreInts(dstMem, PREAMBLE_INTS_DOUBLE);
    insertSerVer(dstMem, SERIAL_VERSION_UPDATABLE);
    insertFamilyID(dstMem, Family.KLL.getID());
    insertFlags(dstMem, DOUBLES_SKETCH_BIT_MASK | UPDATABLE_BIT_MASK);
    insertK(dstMem, k);
    insertM(dstMem, m);
    insertN(dstMem, 0);
    insertMinK(dstMem, k);
    insertNumLevels(dstMem, 1);
    int offset = DATA_START_ADR_DOUBLE;
    dstMem.putIntArray(offset, new int[] {k, k}, 0, 2);
    offset += 2 * Integer.BYTES;
    dstMem.putDoubleArray(offset, new double[] {Double.NaN, Double.NaN}, 0, 2);
    offset += 2 * Double.BYTES;
    dstMem.putDoubleArray(offset, new double[k], 0, k);
    final KllMemoryValidate memVal = new KllMemoryValidate(dstMem);
    return new KllDirectDoublesSketch(dstMem, memReqSvr, 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 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_IS_NOT_DIRECT); }
    if (!other.isDoublesSketch()) { kllSketchThrow(SRC_IS_NOT_DOUBLE); }
    mergeDoubleImpl(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 double value) {
    updateDouble(value);
  }

  @Override
  double[] getDoubleItemsArray() {
    final int items = getItemsArrLengthItems();
    final double[] itemsArr = new double[items];
    itemsArrUpdatable.getDoubleArray(0, itemsArr, 0, items);
    return itemsArr;
  }

  @Override
  double getDoubleItemsArrayAt(final int index) {
    return itemsArrUpdatable.getDouble((long)index * Double.BYTES);
  }

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

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

  @Override
  double getMaxDoubleValue() {
    return minMaxArrUpdatable.getDouble(Double.BYTES);
  }

  @Override
  float getMaxFloatValue() { kllSketchThrow(MUST_NOT_CALL); return Float.NaN; }

  @Override
  double getMinDoubleValue() {
    return minMaxArrUpdatable.getDouble(0);
  }

  @Override
  float getMinFloatValue() { kllSketchThrow(MUST_NOT_CALL); return Float.NaN; }

  @Override
  void setDoubleItemsArray(final double[] doubleItems) {
    if (!updatable) { kllSketchThrow(TGT_IS_IMMUTABLE); }
    itemsArrUpdatable.putDoubleArray(0, doubleItems, 0, doubleItems.length);
  }

  @Override
  void setDoubleItemsArrayAt(final int index, final double value) {
    itemsArrUpdatable.putDouble((long)index * Double.BYTES, value);
  }

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

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

  @Override
  void setMaxDoubleValue(final double value) {
    if (!updatable) { kllSketchThrow(TGT_IS_IMMUTABLE); }
    minMaxArrUpdatable.putDouble(Double.BYTES, value);
  }

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

  @Override
  void setMinDoubleValue(final double value) {
    if (!updatable) { kllSketchThrow(TGT_IS_IMMUTABLE); }
    minMaxArrUpdatable.putDouble(0, value);
  }

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

apache / datasketches-java / #191

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