net.sourceforge.chart2d
Class Dataset

java.lang.Object
  |
  +--net.sourceforge.chart2d.Dataset

public final class Dataset

extends java.lang.Object

The container for the data values to chart. A dataset is like a third order array (ex. float[][][]). The first order is the "sets" order. A set contains data divided by category. The "sets" refer to the objects described by the legend labels, if a legend exists. The second order is the "cats" or categories order. Data within a set can be divided by category. A category can have multiple data items. If using a graph chart, the categories are described by the labels-axis labels. For pie charts, there is only one category. The third order is the "items" order. The "items" order are the values for a particular category and set.
For example, if we had data for the years 1999 and 2000 of how many units were sold on each day during that time, then one way to chart this would be using a graph chart and making the years correspond to the "sets" order, "months", correspond to the "cats" order, and the number of units sold per day correspond to the "items" order.
There are two important rules to mention about this. For each set, the number of cats must be the same. For each cat, the number of items must be the same. In our example, we would probably want to choose the number of items per category to be 30, corresponding the average number of days per month. For months with less than thirty days, we would populate the unfilled days with the average of the filled days or simply carry the last value of the filled days into the unfilled days. For months with more than thirty days, we would average the last two days, and use that value as the value of the last day.
If passing to a PieChart2DProperties, the value used for each pie sector is the sum of the values in each set of data. Pass this to any number of PieChart2D or GraphChart2D objects.

Constructor Summary

Dataset()
Creates a dataset with 0 sets, 0 categories, and 0 items.

Dataset(net.sourceforge.chart2d.Dataset dataset)
Creates a dataset that is a copy of another dataset.

Dataset(int sets, int cats, int items)
Creates a dataset with the specified number of sets, categories per set, and items per set and per category.

Method Summary

void	add(int set, int cat, int item, float value) Adds a value to the dataset increasing its internal data structure if necessary.
void	addMovingAverage(net.sourceforge.chart2d.Dataset dataset, int scope) Analyzes the (input) dataset and adds moving average trend data to this dataset.
void	doConvertToStacked() Converts the dataset for use in "stacked" charts.
void	doShiftLower(float[] values) Shifts all the data items one place, from the higher order to the lower order, replacing the highest order items with the specified items.
float	get(int set, int cat, int item) Gets the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category.
float	getAverage(int set, int cat, int item) Gets the average of some set of numbers.
float	getGreatest() Gets the greatest value of all the data in the datset.
float	getLeast() Gets the least value of all the data in the datset.
int	getNumCats() Gets the number of categories per set of data in this dataset.
int	getNumItems() Gets the number of items per category of data in this dataset.
int	getNumSets() Gets the number of sets of data in this dataset.
void	remove(int set, int cat, int item) Removes values from the dataset.
void	set(net.sourceforge.chart2d.Dataset dataset) Sets all the values of this dataset from another Dataset.
void	set(int set, int cat, int item, float value) Sets the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category.
void	setDatasetToDefaults() Sets the dataset to its default state.
void	setMovingAverage(int set, net.sourceforge.chart2d.Dataset dataset, int scope) Analyzes the (input) dataset and sets moving average trend data to this dataset.
void	setSize(int sets, int cats, int items) Resets the size of the dataset.

Methods inherited from class java.lang.Object

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

Constructor Detail

Dataset

public Dataset()

Creates a dataset with 0 sets, 0 categories, and 0 items. Use the add (int, int, int, float) method to add data items.

Dataset

public Dataset(int sets,
               int cats,
               int items)

Creates a dataset with the specified number of sets, categories per set, and items per set and per category. All internal objects are created at once. Use the set (int, int, int, float) method to add data items.

Parameters:

sets - The number of sets.

cats - The number of categories per set.

items - The number of items per category and per set.

Dataset

public Dataset(net.sourceforge.chart2d.Dataset dataset)

Creates a dataset that is a copy of another dataset. Copying is a deep copy.

Parameters:

dataset - The dataset to copy.

Method Detail

setDatasetToDefaults

public final void setDatasetToDefaults()

Sets the dataset to its default state. It's default state is a dataset with no sets, no cats, and no items.

set

public final void set(int set,
                      int cat,
                      int item,
                      float value)

Sets the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category. If internal resources have not yet been allocated for this item, a null pointer will occurr.

Parameters:

set - The specified set of the variable.

cat - The specified cat of the variable.

item - The specified item of the variable.

value - The specified value of the variable.

set

public final void set(net.sourceforge.chart2d.Dataset dataset)

Sets all the values of this dataset from another Dataset. The values are copied using a deep copy.

Parameters:

dataset - The Dataset to copy.

setSize

public final void setSize(int sets,
                          int cats,
                          int items)

Resets the size of the dataset. Similar to the constructor Dataset (sets, cats, items). If current size is smaller, then fills with zeroes.

Parameters:

sets - The number of sets.

cats - The number of categories per set.

items - The number of items per category and per set.

get

public final float get(int set,
                       int cat,
                       int item)

Gets the value for the variable in the set specified by set, the category specified by cat within the set, and the item specified by item within the category. If internal resources have not yet been allocated to contain such a variable a null pointer error may occurr.

Parameters:

set - The specified set of the variable.

cat - The specified cat of the variable.

item - The specified item of the variable.

Returns:

float The value of this variable.

getNumSets

public final int getNumSets()

Gets the number of sets of data in this dataset.

Returns:

int The number of sets of this dataset.

getNumCats

public final int getNumCats()

Gets the number of categories per set of data in this dataset. This method requires that the dataset be valid according to the method validate(). If not, then a null pointer error may occurr.

Returns:

int The number of cats per set of this dataset.

getNumItems

public final int getNumItems()

Gets the number of items per category of data in this dataset. This method requires that the dataset be valid according to the method validate(). If not, then a null pointer error may occurr.

Returns:

int The number of items per category of this dataset.

getGreatest

public final float getGreatest()

Gets the greatest value of all the data in the datset. If the dataset is invalid or empty, then returns Float.MIN_VALUE;

Returns:

float The greatest value in the dataset.

getLeast

public final float getLeast()

Gets the least value of all the data in the datset. If the dataset is invalid or empty, then returns Float.MAX_VALUE;

Returns:

float The least value in the dataset.

getAverage

public final float getAverage(int set,
                              int cat,
                              int item)

Gets the average of some set of numbers. There are three possibilities. If you want the average of all data items in a particular set and cat, then pass -1 for item. If you want the average of all data items in a particular set and item, then pass -1 for cat. If you want the average of all data items in a particular cat and item, then pass -1 for set. Note, only one -1 may be passed in over all three parameters.

Parameters:

set - Which particular set or -1 for all.

cat - Which particular cat or -1 for all.

item - Which particular item or -1 for all.

add

public final void add(int set,
                      int cat,
                      int item,
                      float value)

Adds a value to the dataset increasing its internal data structure if necessary.

Parameters:

set - The specified set of the variable.

cat - The specified cat of the variable.

item - The specified item of the variable.

value - The specified value of the variable.

addMovingAverage

public final void addMovingAverage(net.sourceforge.chart2d.Dataset dataset,
                                   int scope)

Analyzes the (input) dataset and adds moving average trend data to this dataset. Moving averages are computed by taking some odd number of adjacent items, computing their average and doing that from left to right for each item. How many adjacent items are used in computing the moving average is specified in the scope parameter.

Parameters:

dataset - The dataset to analyze.

scope - The number of data points to compute over.

setMovingAverage

public final void setMovingAverage(int set,
                                   net.sourceforge.chart2d.Dataset dataset,
                                   int scope)

Analyzes the (input) dataset and sets moving average trend data to this dataset. Moving averages are computed by taking some odd number of adjacent items, computing their average and doing that from left to right for each item. How many adjacent items are used in computing the moving average is specified in the scope parameter. Assumes this dataset already has the same number of cats and items, and that the set exists.

Parameters:

set - The set into this dataset to put the moving average.

dataset - The dataset to analyze.

scope - The number of data points to compute over.

remove

public final void remove(int set,
                         int cat,
                         int item)

Removes values from the dataset. Depending on the values of the paramters, eight different operations may result. The simplest is to remove a particular item from a particular set and a particular category. But one can also perform more complex operations. For example, one can remove every set of data. The key to modifying the behavior is passing in a negative one or -1 value for a parameter. A -1 value specifies that whatever is to be removed, will be removed for all such things (ie sets, cats, or items) corresponding to that parameter. So if one wanted to remove every set of data, one could pass -1 to set, to cat, and to item. This would be specify to remove all items, for all cats, for all sets. If one wanted to remove only a single item from a particular set and a particular category, then one would pass a non -1 value for each of the parameters. Below is a listing of the options and a short description. The letters "a", "b", "c" indicates a non -1 value.
set= -1, cat= -1, item= -1 Removes every set of data.
set= a, cat= -1, item= -1 Removes a particular set of data.
set= -1, cat= a, item= -1 Removes a particular category of data for every set.
set= a, cat= b, item= -1 Removes a particular category of data for a particular set.
set= -1, cat= -1, item= a Removes a particular item for every set and every category.
set= -1, cat= a, item= b Removes a particular item of a particular category in every set.
set= a, cat= -1, item= b Removes a particular item of a particular set in every category.
set= a, cat= b, item= c Removes a particular item of a particular category of a particular set.

Parameters:

set - The set of data within which data is to be removed.

cat - The cat of data within which data is to be removed.

item - The item of data that is to be removed.

doShiftLower

public final void doShiftLower(float[] values)

Shifts all the data items one place, from the higher order to the lower order, replacing the highest order items with the specified items. This method is designed to be used with graph charts where the data is dynamically updated and graphed over time categories. For example, if you picture a normal line chart with say three sets of data, that charts the amount of memory being used by various programs on your computer and is updated every second. The number of lines would correspond to the number of programs being charted. The number of x axis labels would refer to the number of seconds of data is being charted (ex 10 seconds). Every second, we could call shiftLower and this would shift left all the old data in the chart, and shift in to the right of the chart, some new data. There would have to be a new data value for each line in the chart. The the number of lines corresponds to the number of programs, and the number of programs, corresponds to the number of legend labels, etc, the number of data values shifted in must be equal to the number of sets in the dataset.

Parameters:

values - An array of values of length getNumSets() to shift in.

doConvertToStacked

public final void doConvertToStacked()

Converts the dataset for use in "stacked" charts. This is a convenience method. Stacked charts are those where each set of data is to be stacked on top of the previous set. So if you have multiple sets of data and you want the graph components corresponding to each set to be stacked on top of the previous set but you don't want to have to adjust your data yourself to get this ***affect*** then use this method. Multiple calls to this method will change your dataset each time. You will only want to call it once. Unless you repopulate your whole dataset with virgin (i.e. never before stacked) values again.