cern.jet.stat.quantile

Class QuantileFinderFactory

java.lang.Object

cern.jet.stat.quantile.QuantileFinderFactory

public class QuantileFinderFactory
extends Object

Factory constructing exact and approximate quantile finders for both known and unknown N. Also see hep.aida.bin.QuantileBin1D, demonstrating how this package can be used. The approx. algorithms compute approximate quantiles of large data sequences in a single pass. The approximation guarantees are explicit, and apply for arbitrary value distributions and arrival distributions of the data sequence. The main memory requirements are smaller than for any other known technique by an order of magnitude.

The approx. algorithms are primarily intended to help applications scale. When faced with a large data sequences, traditional methods either need very large memories or time consuming disk based sorting. In constrast, the approx. algorithms can deal with > 10^10 values without disk based sorting.

All classes can be seen from various angles, for example as

1. Algorithm to compute quantiles.

2. 1-dim-equi-depth histogram.

3. 1-dim-histogram arbitrarily rebinnable in real-time.

4. A space efficient MultiSet data structure using lossy compression.

5. A space efficient value preserving bin of a 2-dim or d-dim histogram.

(All subject to an accuracy specified by the user.)

Use methods newXXX(...) to get new instances of one of the following quantile finders.

1. Exact quantile finding algorithm for known and unknown N requiring large main memory.

The folkore algorithm: Keeps all elements in main memory, sorts the list, then picks the quantiles.

2. Approximate quantile finding algorithm for known N requiring only one pass and little main memory.

Needs as input the following parameters:

1. N - the number of values of the data sequence over which quantiles are to be determined.

2. quantiles - the number of quantiles to be computed. If unknown in advance, set this number large, e.g. quantiles >= 10000.

3. epsilon - the allowed approximation error on quantiles. The approximation guarantee of this algorithm is explicit.

It is also possible to couple the approximation algorithm with random sampling to further reduce memory requirements. With sampling, the approximation guarantees are explicit but probabilistic, i.e. they apply with respect to a (user controlled) confidence parameter "delta".

4. delta - the probability allowed that the approximation error fails to be smaller than epsilon. Set delta to zero for explicit non probabilistic guarantees.

After Gurmeet Singh Manku, Sridhar Rajagopalan and Bruce G. Lindsay, Approximate Medians and other Quantiles in One Pass and with Limited Memory, Proc. of the 1998 ACM SIGMOD Int. Conf. on Management of Data, Paper available here.

3. Approximate quantile finding algorithm for unknown N requiring only one pass and little main memory.

This algorithm requires at most two times the memory of a corresponding approx. quantile finder knowing N.

Needs as input the following parameters:

2. quantiles - the number of quantiles to be computed. If unknown in advance, set this number large, e.g. quantiles >= 1000.

2. epsilon - the allowed approximation error on quantiles. The approximation guarantee of this algorithm is explicit.

It is also possible to couple the approximation algorithm with random sampling to further reduce memory requirements. With sampling, the approximation guarantees are explicit but probabilistic, i.e. they apply with respect to a (user controlled) confidence parameter "delta".

3. delta - the probability allowed that the approximation error fails to be smaller than epsilon. Set delta to zero for explicit non probabilistic guarantees.

After Gurmeet Singh Manku, Sridhar Rajagopalan and Bruce G. Lindsay, Random Sampling Techniques for Space Efficient Online Computation of Order Statistics of Large Datasets. Proc. of the 1999 ACM SIGMOD Int. Conf. on Management of Data, Paper available here.

Example usage:

 _TODO_

Version:

1.0, 09/24/99

Author:

wolfgang.hoschek@cern.ch

See Also:

KnownDoubleQuantileEstimator, UnknownDoubleQuantileEstimator

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	QuantileFinderFactory() Make this class non instantiable.

Method Summary

Methods

Modifier and Type	Method and Description
protected static long[]	known_N_compute_B_and_K_quick(long N, double epsilon) Computes the number of buffers and number of values per buffer such that quantiles can be determined with a guaranteed approximation error no more than epsilon.
protected static long[]	known_N_compute_B_and_K_slow(long N, double epsilon, double delta, int quantiles, double[] returnSamplingRate) Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability.
static long[]	known_N_compute_B_and_K(long N, double epsilon, double delta, int quantiles, double[] returnSamplingRate) Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability.
static DoubleQuantileFinder	newDoubleQuantileFinder(boolean known_N, long N, double epsilon, double delta, int quantiles, RandomEngine generator) Returns a quantile finder that minimizes the amount of memory needed under the user provided constraints.
static DoubleArrayList	newEquiDepthPhis(int quantiles) Convenience method that computes phi's for equi-depth histograms.
protected static long[]	unknown_N_compute_B_and_K_raw(double epsilon, double delta, int quantiles) Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability.
static long[]	unknown_N_compute_B_and_K(double epsilon, double delta, int quantiles) Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability.

Methods inherited from class java.lang.Object

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

Constructor Detail

QuantileFinderFactory

protected QuantileFinderFactory()

Make this class non instantiable. Let still allow others to inherit.

Method Detail

known_N_compute_B_and_K

public static long[] known_N_compute_B_and_K(long N,
                             double epsilon,
                             double delta,
                             int quantiles,
                             double[] returnSamplingRate)

Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability. Assumes that quantiles are to be computed over N values. The required sampling rate is computed and stored in the first element of the provided returnSamplingRate array, which, therefore must be at least of length 1.

Parameters:

N - the number of values over which quantiles shall be computed (e.g 10^6).

epsilon - the approximation error which is guaranteed not to be exceeded (e.g. 0.001) (0 <= epsilon <= 1). To get exact result, set epsilon=0.0;

delta - the probability that the approximation error is more than than epsilon (e.g. 0.0001) (0 <= delta <= 1). To avoid probabilistic answers, set delta=0.0.

quantiles - the number of quantiles to be computed (e.g. 100) (quantiles >= 1). If unknown in advance, set this number large, e.g. quantiles >= 10000.

samplingRate - output parameter, a double[1] where the sampling rate is to be filled in.

Returns:

long[2] - long[0]=the number of buffers, long[1]=the number of elements per buffer, returnSamplingRate[0]=the required sampling rate.

known_N_compute_B_and_K_quick

protected static long[] known_N_compute_B_and_K_quick(long N,
                                   double epsilon)

Computes the number of buffers and number of values per buffer such that quantiles can be determined with a guaranteed approximation error no more than epsilon. Assumes that quantiles are to be computed over N values.

Parameters:

N - the anticipated number of values over which quantiles shall be determined.

epsilon - the approximation error which is guaranteed not to be exceeded (e.g. 0.001) (0 <= epsilon <= 1). To get exact result, set epsilon=0.0;

Returns:

long[2] - long[0]=the number of buffers, long[1]=the number of elements per buffer.

known_N_compute_B_and_K_slow

protected static long[] known_N_compute_B_and_K_slow(long N,
                                  double epsilon,
                                  double delta,
                                  int quantiles,
                                  double[] returnSamplingRate)

Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability. Assumes that quantiles are to be computed over N values. The required sampling rate is computed and stored in the first element of the provided returnSamplingRate array, which, therefore must be at least of length 1.

Parameters:

N - the anticipated number of values over which quantiles shall be computed (e.g 10^6).

epsilon - the approximation error which is guaranteed not to be exceeded (e.g. 0.001) (0 <= epsilon <= 1). To get exact result, set epsilon=0.0;

delta - the probability that the approximation error is more than than epsilon (e.g. 0.0001) (0 <= delta <= 1). To avoid probabilistic answers, set delta=0.0.

quantiles - the number of quantiles to be computed (e.g. 100) (quantiles >= 1). If unknown in advance, set this number large, e.g. quantiles >= 10000.

samplingRate - a double[1] where the sampling rate is to be filled in.

Returns:

long[2] - long[0]=the number of buffers, long[1]=the number of elements per buffer, returnSamplingRate[0]=the required sampling rate.

newDoubleQuantileFinder

public static DoubleQuantileFinder newDoubleQuantileFinder(boolean known_N,
                                           long N,
                                           double epsilon,
                                           double delta,
                                           int quantiles,
                                           RandomEngine generator)

Returns a quantile finder that minimizes the amount of memory needed under the user provided constraints. Many applications don't know in advance over how many elements quantiles are to be computed. However, some of them can give an upper limit, which will assist the factory in choosing quantile finders with minimal memory requirements. For example if you select values from a database and fill them into histograms, then you probably don't know how many values you will fill, but you probably do know that you will fill at most S elements, the size of your database.

Parameters:

known_N - specifies whether the number of elements over which quantiles are to be computed is known or not.

N - if known_N==true, the number of elements over which quantiles are to be computed. if known_N==false, the upper limit on the number of elements over which quantiles are to be computed. If such an upper limit is a-priori unknown, then set N = Long.MAX_VALUE.

epsilon - the approximation error which is guaranteed not to be exceeded (e.g. 0.001) (0 <= epsilon <= 1). To get exact result, set epsilon=0.0;

delta - the probability that the approximation error is more than than epsilon (e.g. 0.0001) (0 <= delta <= 1). To avoid probabilistic answers, set delta=0.0.

quantiles - the number of quantiles to be computed (e.g. 100) (quantiles >= 1). If unknown in advance, set this number large, e.g. quantiles >= 10000.

generator - a uniform random number generator. Set this parameter to null to use a default generator.

Returns:

the quantile finder minimizing memory requirements under the given constraints.

newEquiDepthPhis

public static DoubleArrayList newEquiDepthPhis(int quantiles)

Convenience method that computes phi's for equi-depth histograms. This is simply a list of numbers with i / (double)quantiles for i={1,2,...,quantiles-1}.

Returns:

the equi-depth phi's

unknown_N_compute_B_and_K

public static long[] unknown_N_compute_B_and_K(double epsilon,
                               double delta,
                               int quantiles)

Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability.

Parameters:

epsilon - the approximation error which is guaranteed not to be exceeded (e.g. 0.001) (0 <= epsilon <= 1). To get exact results, set epsilon=0.0;

delta - the probability that the approximation error is more than than epsilon (e.g. 0.0001) (0 <= delta <= 1). To get exact results, set delta=0.0.

quantiles - the number of quantiles to be computed (e.g. 100) (quantiles >= 1). If unknown in advance, set this number large, e.g. quantiles >= 10000.

Returns:

long[4] - long[0]=the number of buffers, long[1]=the number of elements per buffer, long[2]=the tree height where sampling shall start, long[3]==1 if precomputing is better, otherwise 0;

unknown_N_compute_B_and_K_raw

protected static long[] unknown_N_compute_B_and_K_raw(double epsilon,
                                   double delta,
                                   int quantiles)

Computes the number of buffers and number of values per buffer such that quantiles can be determined with an approximation error no more than epsilon with a certain probability. You never need to call this method. It is only for curious users wanting to gain some insight into the workings of the algorithms.

Parameters:

epsilon - the approximation error which is guaranteed not to be exceeded (e.g. 0.001) (0 <= epsilon <= 1). To get exact result, set epsilon=0.0;

delta - the probability that the approximation error is more than than epsilon (e.g. 0.0001) (0 <= delta <= 1). To get exact results, set delta=0.0.

quantiles - the number of quantiles to be computed (e.g. 100) (quantiles >= 1). If unknown in advance, set this number large, e.g. quantiles >= 10000.

Returns:

long[4] - long[0]=the number of buffers, long[1]=the number of elements per buffer, long[2]=the tree height where sampling shall start, long[3]==1 if precomputing is better, otherwise 0;