com.google.instrumentation.stats

Class Distribution

java.lang.Object

com.google.instrumentation.stats.Distribution

public final class Distribution
extends Object

A distribution contains summary statistics for a population of values and, optionally, a histogram representing the distribution of those values across a specified set of histogram buckets.

The bucket boundaries for that histogram are described by BucketBoundaries, which defines BucketBoundaries.getBoundaries().size() + 1 (= N) buckets. The boundaries for bucket index i are:

• [-infinity, bounds[i]) for i == 0
• [bounds[i-1], bounds[i]) for 0 < i < N-1
• [bounds[i-1], +infinity) for i == N-1

i.e. an underflow bucket (number 0), zero or more finite buckets (1 through N - 2, and an overflow bucket (N - 1), with inclusive lower bounds and exclusive upper bounds.

Note: If N = 1, there are no finite buckets and the single bucket is both the overflow and underflow bucket. TODO(songya): needs to determine whether N = 1 is valid. (Currently we don't allow N = 1.)

Although not forbidden, it is generally a bad idea to include non-finite values (infinities or NaNs) in the population of values, as this will render the mean meaningless.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Distribution.Range Describes a range of population values.

Method Summary

Modifier and Type	Method and Description
void	add(double value) Put a new value into the Distribution.
static Distribution	create() Constructs a new, empty Distribution.
static Distribution	create(BucketBoundaries bucketBoundaries) Constructs a new Distribution with specified bucketBoundaryList.
List<Long>	getBucketCounts() A Distribution may optionally contain a histogram of the values in the population.
long	getCount() The number of values in the population.
double	getMean() The arithmetic mean of the values in the population.
Distribution.Range	getRange() The range of the population values.
double	getSum() The sum of the values in the population.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static final Distribution create()

Constructs a new, empty Distribution.

Returns:

a new, empty Distribution.

create

public static final Distribution create(BucketBoundaries bucketBoundaries)

Constructs a new Distribution with specified bucketBoundaryList.

Parameters:

bucketBoundaries - the boundaries for the buckets in the underlying Distribution.

Returns:

a new, empty Distribution with the specified boundaries.

getCount

public long getCount()

The number of values in the population. Must be non-negative.

Returns:

The number of values in the population.

getMean

public double getMean()

The arithmetic mean of the values in the population. If getCount() is zero then this value will be NaN.

Returns:

The arithmetic mean of all values in the population.

getSum

public double getSum()

The sum of the values in the population. If getCount() is zero then this value must also be zero.

Returns:

The sum of values in the population.

getRange

public Distribution.Range getRange()

The range of the population values. If getCount() is zero then this returned range is implementation-dependent.

Returns:

The {code Range} representing the range of population values.

getBucketCounts

@Nullable
public List<Long> getBucketCounts()

A Distribution may optionally contain a histogram of the values in the population. The histogram is given in getBucketCounts() as counts of values that fall into one of a sequence of non-overlapping buckets, described by BucketBoundaries. The sum of the values in getBucketCounts() must equal the value in getCount().

Bucket counts are given in order under the numbering scheme described above (the underflow bucket has number 0; the finite buckets, if any, have numbers 1 through N-2; the overflow bucket has number N-1).

The size of getBucketCounts() must be no greater than N as defined in BucketBoundaries.

Any suffix of trailing buckets containing only zero may be omitted.

getBucketCounts() will return null iff the associated BucketBoundaries is null.

Returns:

The count of population values in each histogram bucket.

add

public void add(double value)

Put a new value into the Distribution.

Parameters:

value - new value to be added to population