+
+Package org.apache.datasketches.kll
+Class KllLongsSketch
+
+
+-
+
- java.lang.Object +
-
+
-
+
- org.apache.datasketches.kll.KllSketch +
-
+
-
+
- org.apache.datasketches.kll.KllLongsSketch +
+
+
+
+-
+
-
+
-
+
- All Implemented Interfaces: +
QuantilesAPI,QuantilesLongsAPI
+
+public abstract class KllLongsSketch +extends KllSketch +implements QuantilesLongsAPI
+This variation of the KllSketch implements primitive longs.+-
+
- See Also: +
KllSketch
+
+
+
+-
+
-
+
+
+ + +-
+
-
+
+
+
Nested Class Summary
+-
+
-
+
+
+
Nested classes/interfaces inherited from class org.apache.datasketches.kll.KllSketch
+KllSketch.SketchStructure, KllSketch.SketchType
+
+ -
+
+
+
+ + +-
+
-
+
+
+
Field Summary
+ +-
+
-
+
+
+
Fields inherited from interface org.apache.datasketches.quantilescommon.QuantilesAPI
+EMPTY_MSG, MEM_REQ_SVR_NULL_MSG, NOT_SINGLE_ITEM_MSG, SELF_MERGE_MSG, TGT_IS_READ_ONLY_MSG, UNSUPPORTED_MSG
+
+ -
+
+
+
+ +-
+
-
+
+
+
Method Summary
++
+All Methods Static Methods Instance Methods Concrete Methods ++ +Modifier and Type +Method +Description ++ +double[]getCDF(long[] splitPoints, + QuantileSearchCriteria searchCrit)+ +Returns an approximation to the Cumulative Distribution Function (CDF) of the input stream + as a monotonically increasing array of double ranks (or cumulative probabilities) on the interval [0.0, 1.0], + given a set of splitPoints.++ +double[]getPMF(long[] splitPoints, + QuantileSearchCriteria searchCrit)+ +Returns an approximation to the Probability Mass Function (PMF) of the input stream + as an array of probability masses as doubles on the interval [0.0, 1.0], + given a set of splitPoints.++ +longgetQuantile(double rank, + QuantileSearchCriteria searchCrit)+ +Gets the approximate quantile of the given normalized rank and the given search criterion.++ +longgetQuantileLowerBound(double rank)+ +Gets the lower bound of the quantile confidence interval in which the quantile of the + given rank exists.++ +long[]getQuantiles(double[] ranks, + QuantileSearchCriteria searchCrit)+ +Gets an array of quantiles from the given array of normalized ranks.++ +longgetQuantileUpperBound(double rank)+ +Gets the upper bound of the quantile confidence interval in which the true quantile of the + given rank exists.++ +doublegetRank(long quantile, + QuantileSearchCriteria searchCrit)+ +Gets the normalized rank corresponding to the given a quantile.++ +doublegetRankLowerBound(double rank)+ +Gets the lower bound of the rank confidence interval in which the true rank of the + given rank exists.++ +double[]getRanks(long[] quantiles, + QuantileSearchCriteria searchCrit)+ +Gets an array of normalized ranks corresponding to the given array of quantiles and the given + search criterion.++ +doublegetRankUpperBound(double rank)+ +Gets the upper bound of the rank confidence interval in which the true rank of the + given rank exists.++ +LongsSketchSortedViewgetSortedView()+ +Gets the sorted view of this sketch++ +static KllLongsSketchheapify(org.apache.datasketches.memory.Memory srcMem)+ +Factory heapify takes a compact sketch image in Memory and instantiates an on-heap sketch.++ +QuantilesLongsSketchIteratoriterator()+ +Gets the iterator for this sketch, which is not sorted.++ +voidmerge(KllSketch other)+ +Merges another sketch into this one.++ +static KllLongsSketchnewDirectInstance(int k, + org.apache.datasketches.memory.WritableMemory dstMem, + org.apache.datasketches.memory.MemoryRequestServer memReqSvr)+ +Create a new direct updatable instance of this sketch with a given k.++ +static KllLongsSketchnewDirectInstance(org.apache.datasketches.memory.WritableMemory dstMem, + org.apache.datasketches.memory.MemoryRequestServer memReqSvr)+ +Create a new direct updatable instance of this sketch with the default k.++ +static KllLongsSketchnewHeapInstance()+ +Create a new heap instance of this sketch with the default k = 200.++ +static KllLongsSketchnewHeapInstance(int k)+ +Create a new heap instance of this sketch with a given parameter k.++ +voidreset()+ +Resets this sketch to the empty state.++ +byte[]toByteArray()+ +Returns a byte array representation of this sketch.++ +StringtoString(boolean withLevels, + boolean withLevelsAndItems)+ +Returns human readable summary information about this sketch.++ +voidupdate(long item)+ +Updates this sketch with the given item.++ +voidupdate(long[] items, + int offset, + int length)+ +Vector update.++ +voidupdate(long item, + long weight)+ +Weighted update.++ +static KllLongsSketchwrap(org.apache.datasketches.memory.Memory srcMem)+ +Wrap a sketch around the given read only compact source Memory containing sketch data + that originated from this sketch.++ +static KllLongsSketchwritableWrap(org.apache.datasketches.memory.WritableMemory srcMem, + org.apache.datasketches.memory.MemoryRequestServer memReqSvr)+ +Wrap a sketch around the given source Writable Memory containing sketch data + that originated from this sketch.+-
+
-
+
+
+
Methods inherited from class org.apache.datasketches.kll.KllSketch
+getKFromEpsilon, getMaxSerializedSizeBytes, getNormalizedRankError, getNormalizedRankError, getNumRetained, getSerializedSizeBytes, hasMemory, isCompactMemoryFormat, isDirect, isEmpty, isEstimationMode, isMemoryUpdatableFormat, isReadOnly, isSameResource, toString
+
-
+
-
+
+
+
Methods inherited from class java.lang.Object
+clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
+
-
+
-
+
+
+
Methods inherited from interface org.apache.datasketches.quantilescommon.QuantilesAPI
+getK, getN, getNormalizedRankError, getNumRetained, hasMemory, isDirect, isEmpty, isEstimationMode, isReadOnly, toString
+
-
+
-
+
+
+
Methods inherited from interface org.apache.datasketches.quantilescommon.QuantilesLongsAPI
+getCDF, getMaxItem, getMinItem, getPMF, getQuantile, getQuantiles, getRank, getRanks, getSerializedSizeBytes
+
+ -
+
+
+
+ -
+
+
+
+
+-
+
-
+
+
+ +-
+
-
+
+
+
Method Detail
+ + + +-
+
-
+
newHeapInstance
+public static KllLongsSketch newHeapInstance()
+Create a new heap instance of this sketch with the default k = 200. + The default k = 200 results in a normalized rank error of about + 1.65%. Larger K will have smaller error but the sketch will be larger (and slower).+-
+
- Returns: +
- new KllLongsSketch on the Java heap. +
+
-
+
-
+
newHeapInstance
+public static KllLongsSketch newHeapInstance(int k)
+Create a new heap instance of this sketch with a given parameter k. + k can be between 8, inclusive, and 65535, inclusive. + The default k = 200 results in a normalized rank error of about + 1.65%. Larger K will have smaller error but the sketch will be larger (and slower).+-
+
- Parameters: +
k- parameter that controls size of the sketch and accuracy of estimates.
+- Returns: +
- new KllLongsSketch on the Java heap. +
+
-
+
-
+
newDirectInstance
+public static KllLongsSketch newDirectInstance(org.apache.datasketches.memory.WritableMemory dstMem, + org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
+Create a new direct updatable instance of this sketch with the default k. + The default k = 200 results in a normalized rank error of about + 1.65%. Larger k will have smaller error but the sketch will be larger (and slower).+-
+
- Parameters: +
dstMem- the given destination WritableMemory object for use by the sketch
+memReqSvr- the given MemoryRequestServer to request a larger WritableMemory
+- Returns: +
- a new direct instance of this sketch +
+
-
+
-
+
newDirectInstance
+public static KllLongsSketch newDirectInstance(int k, + org.apache.datasketches.memory.WritableMemory dstMem, + org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
+Create a new direct updatable instance of this sketch with a given k.+-
+
- Parameters: +
k- parameter that controls size of the sketch and accuracy of estimates.
+dstMem- the given destination WritableMemory object for use by the sketch
+memReqSvr- the given MemoryRequestServer to request a larger WritableMemory
+- Returns: +
- a new direct instance of this sketch +
+
-
+
-
+
heapify
+public static KllLongsSketch heapify(org.apache.datasketches.memory.Memory srcMem)
+Factory heapify takes a compact sketch image in Memory and instantiates an on-heap sketch. + The resulting sketch will not retain any link to the source Memory.+-
+
- Parameters: +
srcMem- a compact Memory image of a sketch serialized by this sketch. + See Memory
+- Returns: +
- a heap-based sketch based on the given Memory. +
+
-
+
-
+
wrap
+public static KllLongsSketch wrap(org.apache.datasketches.memory.Memory srcMem)
+Wrap a sketch around the given read only compact source Memory containing sketch data + that originated from this sketch.+-
+
- Parameters: +
srcMem- the read only source Memory
+- Returns: +
- instance of this sketch +
+
-
+
-
+
writableWrap
+public static KllLongsSketch writableWrap(org.apache.datasketches.memory.WritableMemory srcMem, + org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
+Wrap a sketch around the given source Writable Memory containing sketch data + that originated from this sketch.+-
+
- Parameters: +
srcMem- a WritableMemory that contains data.
+memReqSvr- the given MemoryRequestServer to request a larger WritableMemory
+- Returns: +
- instance of this sketch +
+
-
+
-
+
getCDF
+public double[] getCDF(long[] splitPoints, + QuantileSearchCriteria searchCrit)
+Description copied from interface:+QuantilesLongsAPIReturns an approximation to the Cumulative Distribution Function (CDF) of the input stream + as a monotonically increasing array of double ranks (or cumulative probabilities) on the interval [0.0, 1.0], + given a set of splitPoints. + ++The resulting approximations have a probabilistic guarantee that can be obtained from the + getNormalizedRankError(false) function.
-
+
- Specified by: +
getCDFin interfaceQuantilesLongsAPI
+- Parameters: +
splitPoints- an array of m unique, monotonically increasing items + (of the same type as the input items) + that divide the item input domain into m+1 overlapping intervals. + +The start of each interval is below the lowest item retained by the sketch + corresponding to a zero rank or zero probability, and the end of the interval + is the rank or cumulative probability corresponding to the split point.
+ +The (m+1)th interval represents 100% of the distribution represented by the sketch + and consistent with the definition of a cumulative probability distribution, thus the (m+1)th + rank or probability in the returned array is always 1.0.
+ +If a split point exactly equals a retained item of the sketch and the search criterion is:
+ +-
+
- INCLUSIVE, the resulting cumulative probability will include that item. +
- EXCLUSIVE, the resulting cumulative probability will not include the weight of that split point. +
It is not recommended to include either the minimum or maximum items of the input stream.
+searchCrit- the desired search criteria.
+- Returns: +
- a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. +
+
-
+
-
+
getPMF
+public double[] getPMF(long[] splitPoints, + QuantileSearchCriteria searchCrit)
+Description copied from interface:+QuantilesLongsAPIReturns an approximation to the Probability Mass Function (PMF) of the input stream + as an array of probability masses as doubles on the interval [0.0, 1.0], + given a set of splitPoints. + ++The resulting approximations have a probabilistic guarantee that can be obtained from the + getNormalizedRankError(true) function.
-
+
- Specified by: +
getPMFin interfaceQuantilesLongsAPI
+- Parameters: +
splitPoints- an array of m unique, monotonically increasing items + (of the same type as the input items) + that divide the item input domain into m+1 consecutive, non-overlapping intervals. + +Each interval except for the end intervals starts with a split point and ends with the next split + point in sequence.
+ +The first interval starts below the lowest item retained by the sketch + corresponding to a zero rank or zero probability, and ends with the first split point
+ +The last (m+1)th interval starts with the last split point and ends after the last + item retained by the sketch corresponding to a rank or probability of 1.0.
+ +The sum of the probability masses of all (m+1) intervals is 1.0.
+ +If the search criterion is:
+ +-
+
- INCLUSIVE, and the upper split point of an interval equals an item retained by the sketch, the interval + will include that item. If the lower split point equals an item retained by the sketch, the interval will exclude + that item. +
- EXCLUSIVE, and the upper split point of an interval equals an item retained by the sketch, the interval + will exclude that item. If the lower split point equals an item retained by the sketch, the interval will include + that item. +
It is not recommended to include either the minimum or maximum items of the input stream.
+searchCrit- the desired search criteria.
+- Returns: +
- a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. +
+
-
+
-
+
getQuantile
+public long getQuantile(double rank, + QuantileSearchCriteria searchCrit)
+Description copied from interface:+QuantilesLongsAPIGets the approximate quantile of the given normalized rank and the given search criterion.+-
+
- Specified by: +
getQuantilein interfaceQuantilesLongsAPI
+- Parameters: +
rank- the given normalized rank, a double in the range [0.0, 1.0].
+searchCrit- If INCLUSIVE, the given rank includes all quantiles ≤ + the quantile directly corresponding to the given rank. + If EXCLUSIVE, he given rank includes all quantiles < + the quantile directly corresponding to the given rank.
+- Returns: +
- the approximate quantile given the normalized rank. +
- See Also: +
QuantileSearchCriteria
+
+
-
+
-
+
getQuantiles
+public long[] getQuantiles(double[] ranks, + QuantileSearchCriteria searchCrit)
+Description copied from interface:+QuantilesLongsAPIGets an array of quantiles from the given array of normalized ranks.+-
+
- Specified by: +
getQuantilesin interfaceQuantilesLongsAPI
+- Parameters: +
ranks- the given array of normalized ranks, each of which must be + in the interval [0.0,1.0].
+searchCrit- if INCLUSIVE, the given ranks include all quantiles ≤ + the quantile directly corresponding to each rank.
+- Returns: +
- an array of quantiles corresponding to the given array of normalized ranks. +
- See Also: +
QuantileSearchCriteria
+
+
-
+
-
+
getQuantileLowerBound
+public long getQuantileLowerBound(double rank)
+Gets the lower bound of the quantile confidence interval in which the quantile of the + given rank exists. + ++Although it is possible to estimate the probability that the true quantile + exists within the quantile confidence interval specified by the upper and lower quantile bounds, + it is not possible to guarantee the width of the quantile confidence interval + as an additive or multiplicative percent of the true quantile.
+ The approximate probability that the true quantile is within the confidence interval + specified by the upper and lower quantile bounds for this sketch is 0.99.-
+
- Specified by: +
getQuantileLowerBoundin interfaceQuantilesLongsAPI
+- Parameters: +
rank- the given normalized rank
+- Returns: +
- the lower bound of the quantile confidence interval in which the quantile of the + given rank exists. +
+
-
+
-
+
getQuantileUpperBound
+public long getQuantileUpperBound(double rank)
+Gets the upper bound of the quantile confidence interval in which the true quantile of the + given rank exists. + ++Although it is possible to estimate the probability that the true quantile + exists within the quantile confidence interval specified by the upper and lower quantile bounds, + it is not possible to guarantee the width of the quantile interval + as an additive or multiplicative percent of the true quantile.
+ The approximate probability that the true quantile is within the confidence interval + specified by the upper and lower quantile bounds for this sketch is 0.99.-
+
- Specified by: +
getQuantileUpperBoundin interfaceQuantilesLongsAPI
+- Parameters: +
rank- the given normalized rank
+- Returns: +
- the upper bound of the quantile confidence interval in which the true quantile of the + given rank exists. +
+
-
+
-
+
getRank
+public double getRank(long quantile, + QuantileSearchCriteria searchCrit)
+Description copied from interface:+QuantilesLongsAPIGets the normalized rank corresponding to the given a quantile.+-
+
- Specified by: +
getRankin interfaceQuantilesLongsAPI
+- Parameters: +
quantile- the given quantile
+searchCrit- if INCLUSIVE the given quantile is included into the rank.
+- Returns: +
- the normalized rank corresponding to the given quantile +
- See Also: +
QuantileSearchCriteria
+
+
-
+
-
+
getRankLowerBound
+public double getRankLowerBound(double rank)
+Gets the lower bound of the rank confidence interval in which the true rank of the + given rank exists. + The approximate probability that the true rank is within the confidence interval + specified by the upper and lower rank bounds for this sketch is 0.99.+-
+
- Specified by: +
getRankLowerBoundin interfaceQuantilesAPI
+- Parameters: +
rank- the given normalized rank.
+- Returns: +
- the lower bound of the rank confidence interval in which the true rank of the + given rank exists. +
+
-
+
-
+
getRankUpperBound
+public double getRankUpperBound(double rank)
+Gets the upper bound of the rank confidence interval in which the true rank of the + given rank exists. + The approximate probability that the true rank is within the confidence interval + specified by the upper and lower rank bounds for this sketch is 0.99.+-
+
- Specified by: +
getRankUpperBoundin interfaceQuantilesAPI
+- Parameters: +
rank- the given normalized rank.
+- Returns: +
- the upper bound of the rank confidence interval in which the true rank of the + given rank exists. +
+
-
+
-
+
getRanks
+public double[] getRanks(long[] quantiles, + QuantileSearchCriteria searchCrit)
+Description copied from interface:+QuantilesLongsAPIGets an array of normalized ranks corresponding to the given array of quantiles and the given + search criterion.+-
+
- Specified by: +
getRanksin interfaceQuantilesLongsAPI
+- Parameters: +
quantiles- the given array of quantiles
+searchCrit- if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile.
+- Returns: +
- an array of normalized ranks corresponding to the given array of quantiles. +
- See Also: +
QuantileSearchCriteria
+
+
-
+
-
+
iterator
+public QuantilesLongsSketchIterator iterator()
+Description copied from interface:+QuantilesLongsAPIGets the iterator for this sketch, which is not sorted.+-
+
- Specified by: +
iteratorin interfaceQuantilesLongsAPI
+- Returns: +
- the iterator for this sketch +
+
-
+
-
+
merge
+public final void merge(KllSketch other)
+Description copied from class:+KllSketchMerges another sketch into this one. + Attempting to merge a sketch of the wrong type will throw an exception.+ +
+
-
+
-
+
reset
+public final void reset()
+Resets this sketch to the empty state. + If the sketch is read only this does nothing. + ++The parameter k will not change.
+The parameter k will not change.
-
+
- Specified by: +
resetin interfaceQuantilesAPI
+
+
-
+
-
+
toByteArray
+public byte[] toByteArray()
+Description copied from interface:+QuantilesLongsAPIReturns a byte array representation of this sketch.+-
+
- Specified by: +
toByteArrayin interfaceQuantilesLongsAPI
+- Returns: +
- a byte array representation of this sketch. +
+
-
+
-
+
toString
+public String toString(boolean withLevels, + boolean withLevelsAndItems)
+Description copied from class:+KllSketchReturns human readable summary information about this sketch. + Used for debugging.+ +
+
-
+
-
+
update
+public void update(long item)
+Description copied from interface:+QuantilesLongsAPIUpdates this sketch with the given item.+-
+
- Specified by: +
updatein interfaceQuantilesLongsAPI
+- Parameters: +
item- from a stream of items. NaNs are ignored.
+
+
-
+
-
+
update
+public void update(long item, + long weight)
+Weighted update. Updates this sketch with the given item the number of times specified by the given integer weight.+-
+
- Parameters: +
item- the item to be repeated. NaNs are ignored.
+weight- the number of times the update of item is to be repeated. It must be ≥ one.
+
+
-
+
-
+
update
+public void update(long[] items, + int offset, + int length)
+Vector update. Updates this sketch with the given array (vector) of items, starting at the items + offset for a length number of items. This is not supported for direct sketches.+-
+
- Parameters: +
items- the vector of items
+offset- the starting index of the items[] array
+length- the number of items
+
+
-
+
-
+
getSortedView
+public LongsSketchSortedView getSortedView()
+Description copied from interface:+QuantilesLongsAPIGets the sorted view of this sketch+-
+
- Specified by: +
getSortedViewin interfaceQuantilesLongsAPI
+- Returns: +
- the sorted view of this sketch +
+
+ -
+
+ -
+
+
+