io.virtdata.libimpl.discrete

Class IntegerDistributions

java.lang.Object

io.virtdata.libimpl.discrete.IntegerDistributions

All Implemented Interfaces:

Named, VirtDataFunctionLibrary

@AutoService(value=io.virtdata.api.VirtDataFunctionLibrary.class)
public class IntegerDistributions
extends Object
implements VirtDataFunctionLibrary

This mapper provides inverse cumulative distribution sampling for integer-valued distributions. This works by mapping a long value between 0L and Long.MAX_VALUE to a double value in the unit interval [0.0,1.0], and then applying this to an inverse cumulative distribution function that is distribution specific.

Some distributions are realistic in their shape, but not practical in their computational overhead. For these, you can use an interpolated form, in which the function is sampled equidistantly over the unit interval at some resolution, and then all subsequent lookups are computed from simple linear interpolation. This offers the trade-off of a very slight degradation of accuracy (arguably dependent on the actual density curve in question), with the ability to make all statistical sampling perform in O(1) time, and possibly more importantly, the same time as all other statistical curves.

There are various ways to configure these distributions. For each, there are two choices to be made: mapping vs hashing, and computing vs interpolating.

Mapping vs Hashing

• mapto_ - When a specifier contains mapto_, direct ICDF mapping mode is used. This allows for selecting a value over the distribution by providing the unit sample value directly. Instead of "randomizing" the sample value selector, it simply accesses the ICDF value directly. In this way, it is mapping the unit interval to the ICDF curve.
• hashto_ (default) - When a specifier contains hashto_, then a "sampling" mode is used. This takes the input long value and applies a consistent hash to it, then scales it to a double value in the unit interval before drawing a sample from the curve.

Computing vs Interpolating

• interpolate_ (default) - When a specifier contains interpolate_, then the inverse cumulative density curve is pre-sampled at some resolution (1000 by default) over the unit interval. Any values read from the ICDF are then read instead from the interpolation table. This is done by default unless you specify compute_ as explained below.
• compute_ - When a specifier contains compute_, then every time you ask for a value from the function, the inverse cumulative density function is calculated for a given point on the unit interval. This can be expensive, as well as introduce variance in your generation times depending on the distribution.

It is valid to include mapto_ or hashto_ and interpolate_ or compute_ in your specifiers any order, so long as there are no conflicts.

Examples:

• zipf(10,5.0) - use interpolation and hashing to simulate sampling from the zipf distribution, with 10 elements and exponent of 5.0. Because no qualifiers were included as explained above, hashto_ and interpolate_ were implied.
• mapto_zipf(10,5.0) - Same distribution as above, but use ICDF mapping instead of hashing. Continue to use interpolation as implied
• compute_zipf(10,5.0) - Same distribution as above, but enforce non-interpolated mode. Since mapto_ and hashto_ weren't provided, hashto_ is implied.
• mapto_compute_zipf(10,5.0) - This will be very slow. This forces computation of a harmonic series over N elements for every single access. Interpolation is usually the better way.

Constructor Summary

Constructors

Constructor and Description
IntegerDistributions()

Method Summary

Modifier and Type	Method and Description
static LongUnaryOperator	forSpec(String spec)
List<String>	getDataMapperNames()
String	getName()
List<ResolvedFunction>	resolveFunctions(Class<?> returnClass, Class<?> inputClass, String funcName, Object... parameters)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.virtdata.api.VirtDataFunctionLibrary

getDataMapper, getDataMappers, resolveFunctions

Constructor Detail

IntegerDistributions

public IntegerDistributions()

Method Detail

forSpec

public static LongUnaryOperator forSpec(String spec)

resolveFunctions

public List<ResolvedFunction> resolveFunctions(Class<?> returnClass,
                                               Class<?> inputClass,
                                               String funcName,
                                               Object... parameters)

Specified by:

resolveFunctions in interface VirtDataFunctionLibrary

getName

public String getName()

Specified by:

getName in interface Named

getDataMapperNames

public List<String> getDataMapperNames()

Specified by:

getDataMapperNames in interface VirtDataFunctionLibrary