public abstract class KllLongsSketch extends KllSketch implements QuantilesLongsAPI
KllSketch
KllSketch.SketchStructure, KllSketch.SketchType
EMPTY_MSG, MEM_REQ_SVR_NULL_MSG, NOT_SINGLE_ITEM_MSG, SELF_MERGE_MSG, TGT_IS_READ_ONLY_MSG, UNSUPPORTED_MSG
Modifier and Type | Method and 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.
|
long |
getQuantile(double rank,
QuantileSearchCriteria searchCrit)
Gets the approximate quantile of the given normalized rank and the given search criterion.
|
long |
getQuantileLowerBound(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.
|
long |
getQuantileUpperBound(double rank)
Gets the upper bound of the quantile confidence interval in which the true quantile of the
given rank exists.
|
double |
getRank(long quantile,
QuantileSearchCriteria searchCrit)
Gets the normalized rank corresponding to the given a quantile.
|
double |
getRankLowerBound(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.
|
double |
getRankUpperBound(double rank)
Gets the upper bound of the rank confidence interval in which the true rank of the
given rank exists.
|
LongsSketchSortedView |
getSortedView()
Gets the sorted view of this sketch
|
static KllLongsSketch |
heapify(org.apache.datasketches.memory.Memory srcMem)
Factory heapify takes a compact sketch image in Memory and instantiates an on-heap sketch.
|
QuantilesLongsSketchIterator |
iterator()
Gets the iterator for this sketch, which is not sorted.
|
void |
merge(KllSketch other)
Merges another sketch into this one.
|
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.
|
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.
|
static KllLongsSketch |
newHeapInstance()
Create a new heap instance of this sketch with the default k = 200.
|
static KllLongsSketch |
newHeapInstance(int k)
Create a new heap instance of this sketch with a given parameter k.
|
void |
reset()
Resets this sketch to the empty state.
|
byte[] |
toByteArray()
Returns a byte array representation of this sketch.
|
String |
toString(boolean withLevels,
boolean withLevelsAndItems)
Returns human readable summary information about this sketch.
|
void |
update(long item)
Updates this sketch with the given item.
|
void |
update(long[] items,
int offset,
int length)
Vector update.
|
void |
update(long item,
long weight)
Weighted update.
|
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.
|
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.
|
getKFromEpsilon, getMaxSerializedSizeBytes, getNormalizedRankError, getNormalizedRankError, getNumRetained, getSerializedSizeBytes, hasMemory, isCompactMemoryFormat, isDirect, isEmpty, isEstimationMode, isMemoryUpdatableFormat, isReadOnly, isSameResource, toString
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getCDF, getMaxItem, getMinItem, getPMF, getQuantile, getQuantiles, getRank, getRanks, getSerializedSizeBytes
getK, getN, getNormalizedRankError, getNumRetained, hasMemory, isDirect, isEmpty, isEstimationMode, isReadOnly, toString
public static KllLongsSketch newHeapInstance()
public static KllLongsSketch newHeapInstance(int k)
k
- parameter that controls size of the sketch and accuracy of estimates.public static KllLongsSketch newDirectInstance(org.apache.datasketches.memory.WritableMemory dstMem, org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
dstMem
- the given destination WritableMemory object for use by the sketchmemReqSvr
- the given MemoryRequestServer to request a larger WritableMemorypublic static KllLongsSketch newDirectInstance(int k, org.apache.datasketches.memory.WritableMemory dstMem, org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
k
- parameter that controls size of the sketch and accuracy of estimates.dstMem
- the given destination WritableMemory object for use by the sketchmemReqSvr
- the given MemoryRequestServer to request a larger WritableMemorypublic static KllLongsSketch heapify(org.apache.datasketches.memory.Memory srcMem)
srcMem
- a compact Memory image of a sketch serialized by this sketch.
See Memorypublic static KllLongsSketch wrap(org.apache.datasketches.memory.Memory srcMem)
srcMem
- the read only source Memorypublic static KllLongsSketch writableWrap(org.apache.datasketches.memory.WritableMemory srcMem, org.apache.datasketches.memory.MemoryRequestServer memReqSvr)
srcMem
- a WritableMemory that contains data.memReqSvr
- the given MemoryRequestServer to request a larger WritableMemorypublic double[] getCDF(long[] splitPoints, QuantileSearchCriteria searchCrit)
QuantilesLongsAPI
The resulting approximations have a probabilistic guarantee that can be obtained from the getNormalizedRankError(false) function.
getCDF
in interface QuantilesLongsAPI
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:
It is not recommended to include either the minimum or maximum items of the input stream.
searchCrit
- the desired search criteria.public double[] getPMF(long[] splitPoints, QuantileSearchCriteria searchCrit)
QuantilesLongsAPI
The resulting approximations have a probabilistic guarantee that can be obtained from the getNormalizedRankError(true) function.
getPMF
in interface QuantilesLongsAPI
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:
It is not recommended to include either the minimum or maximum items of the input stream.
searchCrit
- the desired search criteria.public long getQuantile(double rank, QuantileSearchCriteria searchCrit)
QuantilesLongsAPI
getQuantile
in interface QuantilesLongsAPI
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.QuantileSearchCriteria
public long[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit)
QuantilesLongsAPI
getQuantiles
in interface QuantilesLongsAPI
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.QuantileSearchCriteria
public long getQuantileLowerBound(double rank)
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.getQuantileLowerBound
in interface QuantilesLongsAPI
rank
- the given normalized rankpublic long getQuantileUpperBound(double rank)
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.getQuantileUpperBound
in interface QuantilesLongsAPI
rank
- the given normalized rankpublic double getRank(long quantile, QuantileSearchCriteria searchCrit)
QuantilesLongsAPI
getRank
in interface QuantilesLongsAPI
quantile
- the given quantilesearchCrit
- if INCLUSIVE the given quantile is included into the rank.QuantileSearchCriteria
public double getRankLowerBound(double rank)
getRankLowerBound
in interface QuantilesAPI
rank
- the given normalized rank.public double getRankUpperBound(double rank)
getRankUpperBound
in interface QuantilesAPI
rank
- the given normalized rank.public double[] getRanks(long[] quantiles, QuantileSearchCriteria searchCrit)
QuantilesLongsAPI
getRanks
in interface QuantilesLongsAPI
quantiles
- the given array of quantilessearchCrit
- if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile.QuantileSearchCriteria
public QuantilesLongsSketchIterator iterator()
QuantilesLongsAPI
iterator
in interface QuantilesLongsAPI
public final void merge(KllSketch other)
KllSketch
public final void reset()
The parameter k will not change.
The parameter k will not change.
reset
in interface QuantilesAPI
public byte[] toByteArray()
QuantilesLongsAPI
toByteArray
in interface QuantilesLongsAPI
public String toString(boolean withLevels, boolean withLevelsAndItems)
KllSketch
public void update(long item)
QuantilesLongsAPI
update
in interface QuantilesLongsAPI
item
- from a stream of items. NaNs are ignored.public void update(long item, long weight)
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.public void update(long[] items, int offset, int length)
items
- the vector of itemsoffset
- the starting index of the items[] arraylength
- the number of itemspublic LongsSketchSortedView getSortedView()
QuantilesLongsAPI
getSortedView
in interface QuantilesLongsAPI
Copyright © 2015–2024 The Apache Software Foundation. All rights reserved.