bcds.tools.stat
Class Series

java.lang.Object
  bcds.tools.stat.CollectorBase
      bcds.tools.stat.Series

All Implemented Interfaces:

Collector

public class Series
extends CollectorBase

Implements a collector whose items correspond to a series, for example, a temporal series. Each "item" in the series is another collector of type Average. Conceptually, this collector can be thought of as a map, in which the key is the identifier (the position on the x-axis) and the item is the corresponding value on the y-axis.

Keys are always numeric and their range can be defined within -INF..+INF (assuming the double data type). One instance of this class must specify the number of "decimal places" its key is going to have. Keys are rounded to that precision and kept internally as a java.math.BigDecimal object. The roundimg mode is ROUND_DOWN (see BigDecimal's documentation for details).

The reason for requiring a given precision and for performing the rounding of key values is for reducing the possibility that two independently computed keys which are "similar" from a human point of view (for example when printed), are in fact treated as different keys. Consider for instance the values 1.00000000001 and 1.00000000002). In any case, keys are asumed to be integer (precision digits = 0) by default.

Keys are kept ordered in a tree map. Thus, when iterating over the keys, they will appear sorted in ascending order.

Note that this collector cannot use the one-parameter collect(double) method. The proper way to add observations to the series is by calling collect(double, double).

Author:

Juan Segovia S.

Constructor Summary

Series()
Default constructor.

Series(java.lang.String name, java.lang.String desc)
Creates a new collector of with the given name and description, and with key precision set to 0, that is, integer keys.

Series(java.lang.String name, java.lang.String desc, int key_prec)
Creates a new collector with the given name, description, and key precision.

Method Summary

void	collect(double value) This method is disabled (throws an exception).
void	collect(double at, double value) Register a new observation at the point identified by at.
Average	get(java.math.BigDecimal at) Returns the value (the collector object), for the key at.
Average	get(double at) Returns the value (the collector object), for the key at, which is first "converted" by calling makeIndex(at).
java.lang.String[]	getAxisLabels() Returns the axis labels in a 2-element array.
int	getKeyPrecision() Returns the precision (number of decimal places) of keys in this series.
double[]	getKeyRange() Returns the values that define the key range of this series as elements of an array of length 2.
double[]	getResults() Returns null.
java.lang.String[]	getResultsLabels() Returns a zero-length array, as required by the Collector interface when the results are not simple values.
java.util.Set<java.math.BigDecimal>	keySet() Returns an unmodifiable view of the keys in this series, sorted in ascending order.
java.math.BigDecimal	makeIndex(double at) Converts a key expressed as an arbitrary double value to a fixed-precision BigDecimal object.
java.lang.String	report() Returns the series' name and the number of items it contains.
void	setAxisLabels(java.lang.String xlabel, java.lang.String ylabel) Sets the labels of the axis.
void	setKeyPrecision(int key_prec) Sets the precision (number of decimal places) of keys in this series.
void	setKeyRange(java.lang.Double min, java.lang.Double max) Sets the key range within which observartions will be accepted in this series.
void	setup(java.lang.String name, java.lang.String desc) Resets this collector.
java.util.Collection<Average>	values() Returns an unmodifiable view of the values in this series.

Methods inherited from class bcds.tools.stat.CollectorBase

equals, getDescription, getName, hashCode, report, report, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Series

public Series()

Default constructor. Without a call to setup(java.lang.String, java.lang.String), this instance is practically unusable.

Series

public Series(java.lang.String name,
              java.lang.String desc)

Creates a new collector of with the given name and description, and with key precision set to 0, that is, integer keys.

Series

public Series(java.lang.String name,
              java.lang.String desc,
              int key_prec)

Creates a new collector with the given name, description, and key precision.

Method Detail

setup

public void setup(java.lang.String name,
                  java.lang.String desc)

Resets this collector. The key range is left open.

Specified by:

setup in interface Collector

Overrides:

setup in class CollectorBase

collect

public void collect(double value)

This method is disabled (throws an exception).

Throws:

UnsupportedOperationException, - as the method collect(double, double) must be used instead.

report

public java.lang.String report()

Returns the series' name and the number of items it contains.

Specified by:

report in interface Collector

Overrides:

report in class CollectorBase

getResults

public double[] getResults()

Returns null. This collector does not produce simple results.

getResultsLabels

public java.lang.String[] getResultsLabels()

Returns a zero-length array, as required by the Collector interface when the results are not simple values.

collect

public void collect(double at,
                    double value)

Register a new observation at the point identified by at. If no entry exists yet for that point, one is created by instantiating an Average with name "@t", where t=makeIndex(at). If t is outside the range of this series, the method simply returns without adding the observation.

setKeyRange

public void setKeyRange(java.lang.Double min,
                        java.lang.Double max)

Sets the key range within which observartions will be accepted in this series. A null value for min and max means the corresponding range limit is "open". Minimum and maximum values are, respectively, Double.NEGATIVE_INFINITY and Double.POSITIVE_INFINITY. No check is performed to make sure that the range makes sense (so, [10, 3] is acceptable but will make all observations to be ignored).

Throws:

java.lang.RuntimeException - if this series is not empty.

getKeyRange

public double[] getKeyRange()

Returns the values that define the key range of this series as elements of an array of length 2. One or both values may be null.

setKeyPrecision

public void setKeyPrecision(int key_prec)

Sets the precision (number of decimal places) of keys in this series.

Throws:

java.lang.RuntimeException - if this series is not empty.

getKeyPrecision

public int getKeyPrecision()

Returns the precision (number of decimal places) of keys in this series.

setAxisLabels

public void setAxisLabels(java.lang.String xlabel,
                          java.lang.String ylabel)

Sets the labels of the axis. These labels may be useful when plotting the series.

getAxisLabels

public java.lang.String[] getAxisLabels()

Returns the axis labels in a 2-element array. The first elements is the "x" axis, and the second for the "y" axis.

makeIndex

public java.math.BigDecimal makeIndex(double at)

Converts a key expressed as an arbitrary double value to a fixed-precision BigDecimal object. Rounding is applied with rounding mode set to BigDecimal.ROUND_DOWN.

keySet

public java.util.Set<java.math.BigDecimal> keySet()

Returns an unmodifiable view of the keys in this series, sorted in ascending order.

values

public java.util.Collection<Average> values()

Returns an unmodifiable view of the values in this series.

get

public Average get(double at)

Returns the value (the collector object), for the key at, which is first "converted" by calling makeIndex(at). May return null if the key does not exist or, due to precision loss, the BigDecimal-based key cannot be found.

get

public Average get(java.math.BigDecimal at)

Returns the value (the collector object), for the key at. May return null if the key does not exist or, due to precision loss, the appropiate it cannot be found.