Sketch (com.yahoo.datasketches:sketches-core 0.9.0 API)

java.lang.Object
- com.yahoo.sketches.theta.Sketch

Direct Known Subclasses:

CompactSketch, UpdateSketch
```
public abstract class Sketch
extends Object
```
The top-level class for all sketches. This class is never constructed directly. Use the UpdateSketch.builder() methods to create UpdateSketches.

Author:

Lee Rhodes

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`getCountLessThanTheta(double theta)` Gets the number of hash values less than the given theta.
`int`	`getCurrentBytes(boolean compact)` Returns the number of storage bytes required for this Sketch in its current state.
`double`	`getEstimate()` Gets the unique count estimate.
`abstract Family`	`getFamily()` Returns the Family that this sketch belongs to
`double`	`getLowerBound(int numStdDev)` Gets the approximate lower error bound given the specified number of Standard Deviations.
`static int`	`getMaxCompactSketchBytes(int numberOfEntries)` Returns the maximum number of storage bytes required for a CompactSketch with the given number of actual entries.
`static int`	`getMaxUpdateSketchBytes(int nomEntries)` Returns the maximum number of storage bytes required for an UpdateSketch with the given number of nominal entries (power of 2).
`int`	`getRetainedEntries()` Returns the number of valid entries that have been retained by the sketch.
`abstract int`	`getRetainedEntries(boolean valid)` Returns the number of entries that have been retained by the sketch.
`static int`	`getSerializationVersion(Memory mem)` Returns the serialization version from the given Memory
`double`	`getTheta()` Gets the value of theta as a double with a value between zero and one
`double`	`getUpperBound(int numStdDev)` Gets the approximate upper error bound given the specified number of Standard Deviations.
`static Sketch`	`heapify(Memory srcMem)` Heapify takes the sketch image in Memory and instantiates an on-heap Sketch using the Default Update Seed.
`static Sketch`	`heapify(Memory srcMem, long seed)` Heapify takes the sketch image in Memory and instantiates an on-heap Sketch using the given seed.
`abstract boolean`	`isCompact()` Returns true if this sketch is in compact form.
`abstract boolean`	`isDirect()` Returns true if this sketch accesses its internal data using the Memory package
`abstract boolean`	`isEmpty()` See Empty
`boolean`	`isEstimationMode()` Returns true if the sketch is Estimation Mode (as opposed to Exact Mode).
`abstract boolean`	`isOrdered()` Returns true if internal cache is ordered
`abstract byte[]`	`toByteArray()` Serialize this sketch to a byte array form.
`String`	`toString()` Returns a human readable summary of the sketch.
`String`	`toString(boolean sketchSummary, boolean dataDetail, int width, boolean hexMode)` Gets a human readable listing of contents and summary of the given sketch.
`static Sketch`	`wrap(Memory srcMem)` Wrap takes the sketch image in Memory and refers to it directly.
`static Sketch`	`wrap(Memory srcMem, long seed)` Wrap takes the sketch image in Memory and refers to it directly.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getEstimate
```
public double getEstimate()
```
    Gets the unique count estimate.
    
    Returns:
    
    the sketch's best estimate of the cardinality of the input stream.
  - getLowerBound
```
public double getLowerBound(int numStdDev)
```
    Gets the approximate lower error bound given the specified number of Standard Deviations. This will return getEstimate() if isEmpty() is true.
    
    Parameters:
    
    numStdDev - See Number of Standard Deviations
    
    Returns:
    
    the lower bound.
  - getRetainedEntries
```
public int getRetainedEntries()
```
    Returns the number of valid entries that have been retained by the sketch.
    
    Returns:
    
    the number of valid retained entries
  - getRetainedEntries
```
public abstract int getRetainedEntries(boolean valid)
```
    Returns the number of entries that have been retained by the sketch.
    
    Parameters:
    
    valid - if true, returns the number of valid entries, which are less than theta and used for estimation. Otherwise, return the number of all entries, valid or not, that are currently in the internal sketch cache.
    
    Returns:
    
    the number of retained entries
  - getTheta
```
public double getTheta()
```
    Gets the value of theta as a double with a value between zero and one
    
    Returns:
    
    the value of theta as a double
  - getCountLessThanTheta
```
public int getCountLessThanTheta(double theta)
```
    Gets the number of hash values less than the given theta.
    
    Parameters:
    
    theta - the given theta as a double between zero and one.
    
    Returns:
    
    the number of hash values less than the given theta.
  - getUpperBound
```
public double getUpperBound(int numStdDev)
```
    Gets the approximate upper error bound given the specified number of Standard Deviations. This will return getEstimate() if isEmpty() is true.
    
    Parameters:
    
    numStdDev - See Number of Standard Deviations
    
    Returns:
    
    the upper bound.
  - isEmpty
```
public abstract boolean isEmpty()
```
    See Empty
    
    Returns:
    
    true if empty.
  - isEstimationMode
```
public boolean isEstimationMode()
```
    Returns true if the sketch is Estimation Mode (as opposed to Exact Mode). This is true if theta < 1.0 AND isEmpty() is false.
    
    Returns:
    
    true if the sketch is in estimation mode.
  - toByteArray
```
public abstract byte[] toByteArray()
```
    Serialize this sketch to a byte array form.
    
    Returns:
    
    byte array of this sketch
  - getFamily
```
public abstract Family getFamily()
```
    Returns the Family that this sketch belongs to
    
    Returns:
    
    the Family that this sketch belongs to
  - toString
```
public String toString()
```
    Returns a human readable summary of the sketch. This method is equivalent to the parameterized call:
    Sketch.toString(sketch, true, false, 8, true);
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    summary
  - toString
```
public String toString(boolean sketchSummary,
                       boolean dataDetail,
                       int width,
                       boolean hexMode)
```
    Gets a human readable listing of contents and summary of the given sketch. This can be a very long string. If this sketch is in a "dirty" state there may be values in the dataDetail view that are ≥ theta.
    
    Parameters:
    
    sketchSummary - If true the sketch summary will be output at the end.
    
    dataDetail - If true, includes all valid hash values in the sketch.
    
    width - The number of columns of hash values. Default is 8.
    
    hexMode - If true, hashes will be output in hex.
    
    Returns:
    
    The result string, which can be very long.
  - heapify
```
public static Sketch heapify(Memory srcMem)
```
    Heapify takes the sketch image in Memory and instantiates an on-heap Sketch using the Default Update Seed. The resulting sketch will not retain any link to the source Memory.
    
    Parameters:
    
    srcMem - an image of a Sketch where the image seed hash matches the default seed hash. See Memory
    
    Returns:
    
    a Heap-based Sketch from the given Memory
  - heapify
```
public static Sketch heapify(Memory srcMem,
                             long seed)
```
    Heapify takes the sketch image in Memory and instantiates an on-heap Sketch using the given seed. The resulting sketch will not retain any link to the source Memory.
    
    Parameters:
    
    srcMem - an image of a Sketch where the image seed hash matches the given seed hash. See Memory
    
    seed - See Update Hash Seed. Compact sketches store a 16-bit hash of the seed, but not the seed itself.
    
    Returns:
    
    a Heap-based Sketch from the given Memory
  - wrap
```
public static Sketch wrap(Memory srcMem)
```
    Wrap takes the sketch image in Memory and refers to it directly. There is no data copying onto the java heap. Only "Direct" Serialization Version 3 (i.e, OpenSource) sketches that have been explicity stored as direct objects can be wrapped. This method assumes the Util.DEFAULT_UPDATE_SEED. Default Update Seed.
    
    Parameters:
    
    srcMem - an image of a Sketch where the image seed hash matches the default seed hash. See Memory
    
    Returns:
    
    a Sketch backed by the given Memory
  - wrap
```
public static Sketch wrap(Memory srcMem,
                          long seed)
```
    Wrap takes the sketch image in Memory and refers to it directly. There is no data copying onto the java heap. Only "Direct" Serialization Version 3 (i.e, OpenSource) sketches that have been explicity stored as direct objects can be wrapped. An attempt to "wrap" earlier version sketches will result in a "heapified", normal Java Heap version of the sketch where all data will be copied to the heap.
    
    Parameters:
    
    srcMem - an image of a Sketch where the image seed hash matches the given seed hash. See Memory
    
    seed - See Update Hash Seed. Compact sketches store a 16-bit hash of the seed, but not the seed itself.
    
    Returns:
    
    a UpdateSketch backed by the given Memory
  - getCurrentBytes
```
public int getCurrentBytes(boolean compact)
```
    Returns the number of storage bytes required for this Sketch in its current state.
    
    Parameters:
    
    compact - if true, returns the bytes required for compact form. If this sketch is already in compact form this parameter is ignored.
    
    Returns:
    
    the number of storage bytes required for this sketch
  - getMaxCompactSketchBytes
```
public static int getMaxCompactSketchBytes(int numberOfEntries)
```
    Returns the maximum number of storage bytes required for a CompactSketch with the given number of actual entries.
    
    Parameters:
    
    numberOfEntries - the actual number of entries stored with the CompactSketch.
    
    Returns:
    
    the maximum number of storage bytes required for a CompactSketch with the given number of entries.
  - getMaxUpdateSketchBytes
```
public static int getMaxUpdateSketchBytes(int nomEntries)
```
    Returns the maximum number of storage bytes required for an UpdateSketch with the given number of nominal entries (power of 2).
    
    Parameters:
    
    nomEntries - Nominal Entres This will become the ceiling power of 2 if it is not.
    
    Returns:
    
    the maximum number of storage bytes required for a UpdateSketch with the given nomEntries
  - getSerializationVersion
```
public static int getSerializationVersion(Memory mem)
```
    Returns the serialization version from the given Memory
    
    Parameters:
    
    mem - the sketch Memory
    
    Returns:
    
    the serialization version from the Memory
  - isCompact
```
public abstract boolean isCompact()
```
    Returns true if this sketch is in compact form.
    
    Returns:
    
    true if this sketch is in compact form.
  - isOrdered
```
public abstract boolean isOrdered()
```
    Returns true if internal cache is ordered
    
    Returns:
    
    true if internal cache is ordered
  - isDirect
```
public abstract boolean isDirect()
```
    Returns true if this sketch accesses its internal data using the Memory package
    
    Returns:
    
    true if this sektch accesses its internal data using the Memory package

Class Sketch

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getEstimate

getLowerBound

getRetainedEntries

getRetainedEntries

getTheta

getCountLessThanTheta

getUpperBound

isEmpty

isEstimationMode

toByteArray

getFamily

toString

toString

heapify

heapify

wrap

wrap

getCurrentBytes

getMaxCompactSketchBytes

getMaxUpdateSketchBytes

getSerializationVersion

isCompact

isOrdered

isDirect