Module org.jfree.chart3d
Package org.jfree.chart3d.data

# Class DataUtils

java.lang.Object
org.jfree.chart3d.data.DataUtils

public class DataUtils extends Object
Some utility methods for working with the various datasets and data structures available in Orson Charts.

## Method Summary

Modifier and Type
Method
Description
`static <S extends Comparable<S>>
int`
`count(KeyedValues3D<S,?,?,?> data, S seriesKey)`
Returns the count of the non-`null` entries in the dataset for the specified series.
`static <C extends Comparable<C>>
int`
`countForColumn(KeyedValues3D<?,?,C,?> data, C columnKey)`
Returns the count of the non-`null` entries in the dataset for the specified column (all series).
`static <R extends Comparable<R>>
int`
`countForRow(KeyedValues3D<?,R,?,?> data, R rowKey)`
Returns the count of the non-`null` entries in the dataset for the specified row (all series).
`static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>>
XYZDataset<S>`
`extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends Number> source, C xColKey, C yColKey, C zColKey)`
Creates an `XYZDataset` by extracting values from specified columns in a `KeyedValues3D` instance, across all the available rows (items where any of the x, y or z values is `null` are skipped).
`static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>>
XYZDataset<S>`
`extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends Number> source, C xColKey, C yColKey, C zColKey, NullConversion nullConversion, List<KeyedValues3DItemKey> exceptions)`
Creates an `XYZDataset` by extracting values from specified columns in a `KeyedValues3D` instance.
`static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>>
XYZDataset`
`extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends Number> source, R xRowKey, R yRowKey, R zRowKey)`
Creates an `XYZDataset` by extracting values from specified rows in a `KeyedValues3D` instance, across all the available columns (items where any of the x, y or z values is `null` are skipped).
`static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>>
XYZDataset`
`extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends Number> source, R xRowKey, R yRowKey, R zRowKey, NullConversion nullConversion, List<KeyedValues3DItemKey> exceptions)`
Creates an `XYZDataset` by extracting values from specified rows in a `KeyedValues3D` instance.
`static Range`
`findStackedValueRange(Values3D<? extends Number> data)`
Finds the range of values in the dataset considering that each series is stacked on top of the other.
`static Range`
`findStackedValueRange(Values3D<? extends Number> data, double base)`
Finds the range of values in the dataset considering that each series is stacked on top of the others, starting at the base value.
`static Range`
`findValueRange(Values3D<? extends Number> data)`
Returns the range of values in the specified data structure (a three dimensional cube).
`static Range`
`findValueRange(Values3D<? extends Number> data, double base)`
Returns the range of values in the specified data cube, or `null` if there is no data.
`static Range`
`findValueRange(Values3D<? extends Number> data, double base, boolean finite)`
/** Returns the range of values in the specified data cube, or `null` if there is no data.
`static Range`
`findXRange(XYZDataset dataset)`
Returns the range of x-values in the dataset by iterating over all values (and ignoring `Double.NaN` and infinite values).
`static Range`
`findXRange(XYZDataset dataset, double inc)`
Returns the range of x-values in the dataset by iterating over all values (and ignoring `Double.NaN` values).
`static Range`
`findXRange(XYZDataset dataset, double inc, boolean finite)`
Returns the range of x-values in the dataset by iterating over all values (and ignoring `Double.NaN` values).
`static Range`
`findYRange(XYZDataset dataset)`
Returns the range of y-values in the dataset by iterating over all values (and ignoring `Double.NaN` and infinite values).
`static Range`
`findYRange(XYZDataset dataset, double inc)`
Returns the range of y-values in the dataset by iterating over all values (and ignoring `Double.NaN` values).
`static Range`
`findYRange(XYZDataset dataset, double inc, boolean finite)`
Returns the range of y-values in the dataset by iterating over all values (and ignoring `Double.NaN` values).
`static Range`
`findZRange(XYZDataset dataset)`
Returns the range of z-values in the dataset by iterating over all values (and ignoring `Double.NaN` and infinite values).
`static Range`
`findZRange(XYZDataset dataset, double inc)`
Returns the range of z-values in the dataset by iterating over all values (and ignoring `Double.NaN` values).
`static Range`
`findZRange(XYZDataset dataset, double inc, boolean finite)`
Returns the range of z-values in the dataset by iterating over all values (and ignoring `Double.NaN` values).
`static double[]`
`stackSubTotal(Values3D<? extends Number> data, double base, int series, int row, int column)`
Returns the positive and negative subtotals of the values for all the series preceding the specified series.
`static <S extends Comparable<S>>
double`
`total(KeyedValues3D<S,?,?,? extends Number> data, S seriesKey)`
Returns the total of the non-`null` values in the dataset for the specified series.
`static double`
`total(Values<Number> values)`
Returns the total of the values in the list.
`static <S extends Comparable<S>>
double`
`total(XYZDataset<S> data, S seriesKey)`
Returns the total of the non-`NaN` entries in the dataset for the specified series.
`static <C extends Comparable<C>>
double`
`totalForColumn(KeyedValues3D<?,?,C,? extends Number> data, C columnKey)`
Returns the total of the non-`null` entries in the dataset for the specified column (all series).
`static <R extends Comparable<R>>
double`
`totalForRow(KeyedValues3D<?,R,?,? extends Number> data, R rowKey)`
Returns the total of the non-`null` entries in the dataset for the specified row (all series).

### Methods inherited from class java.lang.Object

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

## Method Details

### total

public static double total(Values<Number> values)
Returns the total of the values in the list. Any `null` values are ignored.

Parameters:
  `values` - the values (`null` not permitted).
Returns:
  The total of the values in the list.

### count

public static <S extends Comparable<S>> int count(KeyedValues3D<S,?,?,?> data, S seriesKey)
Returns the count of the non-`null` entries in the dataset for the specified series. An `IllegalArgumentException` is thrown if the `seriesKey` is not present in the data.

Type Parameters:
  `S` - the series key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `seriesKey` - the series key (`null` not permitted).
Returns:
  The count.
Since:
  1.2

### countForRow

public static <R extends Comparable<R>> int countForRow(KeyedValues3D<?,R,?,?> data, R rowKey)
Returns the count of the non-`null` entries in the dataset for the specified row (all series).

Type Parameters:
  `R` - the row key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `rowKey` - the row key (`null` not permitted).
Returns:
  The count.
Since:
  1.2

### countForColumn

public static <C extends Comparable<C>> int countForColumn(KeyedValues3D<?,?,C,?> data, C columnKey)
Returns the count of the non-`null` entries in the dataset for the specified column (all series).

Type Parameters:
  `C` - the column key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `columnKey` - the column key (`null` not permitted).
Returns:
  The count.
Since:
  1.2

### total

public static <S extends Comparable<S>> double total(KeyedValues3D<S,?,?,? extends Number> data, S seriesKey)
Returns the total of the non-`null` values in the dataset for the specified series. If there is no series with the specified key, this method will throw an `IllegalArgumentException`.

Type Parameters:
  `S` - the series key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `seriesKey` - the series key (`null` not permitted).
Returns:
  The total.
Since:
  1.2

### totalForRow

public static <R extends Comparable<R>> double totalForRow(KeyedValues3D<?,R,?,? extends Number> data, R rowKey)
Returns the total of the non-`null` entries in the dataset for the specified row (all series).

Type Parameters:
  `R` - the row key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `rowKey` - the row key (`null` not permitted).
Returns:
  The total.
Since:
  1.2

### totalForColumn

public static <C extends Comparable<C>> double totalForColumn(KeyedValues3D<?,?,C,? extends Number> data, C columnKey)
Returns the total of the non-`null` entries in the dataset for the specified column (all series).

Type Parameters:
  `C` - the column key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `columnKey` - the row key (`null` not permitted).
Returns:
  The total.
Since:
  1.2

### findValueRange

public static Range findValueRange(Values3D<? extends Number> data)
Returns the range of values in the specified data structure (a three dimensional cube). If there is no data, this method returns `null`.

Parameters:
  `data` - the data (`null` not permitted).
Returns:
  The range of data values (possibly `null`).

### findValueRange

public static Range findValueRange(Values3D<? extends Number> data, double base)
Returns the range of values in the specified data cube, or `null` if there is no data. The range will be expanded, if required, to include the `base` value (unless it is `Double.NaN` in which case it is ignored).

Parameters:
  `data` - the data (`null` not permitted).
  `base` - a value that must be included in the range (often 0). This argument is ignored if it is `Double.NaN`.
Returns:
  The range (possibly `null`).

### findValueRange

public static Range findValueRange(Values3D<? extends Number> data, double base, boolean finite)
/** Returns the range of values in the specified data cube, or `null` if there is no data. The range will be expanded, if required, to include the `base` value (unless it is `Double.NaN` in which case it is ignored).

Parameters:
  `data` - the data (`null` not permitted).
  `base` - a value that must be included in the range (often 0). This argument is ignored if it is `Double.NaN`.
  `finite` - if `true` infinite values will be ignored.
Returns:
  The range (possibly `null`).
Since:
  1.4

### findStackedValueRange

public static Range findStackedValueRange(Values3D<? extends Number> data)
Finds the range of values in the dataset considering that each series is stacked on top of the other.

Parameters:
  `data` - the data (`null` not permitted).
Returns:
  The range.

### findStackedValueRange

public static Range findStackedValueRange(Values3D<? extends Number> data, double base)
Finds the range of values in the dataset considering that each series is stacked on top of the others, starting at the base value.

Parameters:
  `data` - the data values (`null` not permitted).
  `base` - the base value.
Returns:
  The range.

### stackSubTotal

public static double[] stackSubTotal(Values3D<? extends Number> data, double base, int series, int row, int column)
Returns the positive and negative subtotals of the values for all the series preceding the specified series.
One application for this method is to compute the base values for individual bars in a stacked bar chart.

Parameters:
  `data` - the data (`null` not permitted).
  `base` - the initial base value (normally `0.0`, but the values can be stacked from a different starting point).
  `series` - the index of the current series (series with lower indices are included in the sub-totals).
  `row` - the row index of the required item.
  `column` - the column index of the required item.
Returns:
  The subtotals, where `result[0]` is the subtotal of the negative data items, and `result[1]` is the subtotal of the positive data items.

### total

public static <S extends Comparable<S>> double total(XYZDataset<S> data, S seriesKey)
Returns the total of the non-`NaN` entries in the dataset for the specified series.

Type Parameters:
  `S` - the series key (must implement Comparable).
Parameters:
  `data` - the dataset (`null` not permitted).
  `seriesKey` - the series key (`null` not permitted).
Returns:
  The count.
Since:
  1.2

### findXRange

public static Range findXRange(XYZDataset dataset)
Returns the range of x-values in the dataset by iterating over all values (and ignoring `Double.NaN` and infinite values). If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
Returns:
  The range (possibly `null`).

### findXRange

public static Range findXRange(XYZDataset dataset, double inc)
Returns the range of x-values in the dataset by iterating over all values (and ignoring `Double.NaN` values). The range will be extended if necessary to include `inc` (unless it is `Double.NaN` in which case it is ignored). Infinite values in the dataset will be ignored. If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `inc` - an additional x-value to include.
Returns:
  The range (possibly `null`).

### findXRange

public static Range findXRange(XYZDataset dataset, double inc, boolean finite)
Returns the range of x-values in the dataset by iterating over all values (and ignoring `Double.NaN` values). The range will be extended if necessary to include `inc` (unless it is `Double.NaN` in which case it is ignored). If the `finite` flag is set, infinite values in the dataset will be ignored. If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `inc` - an additional x-value to include.
  `finite` - a flag indicating whether to exclude infinite values.
Returns:
  The range (possibly `null`).
Since:
  1.4

### findYRange

public static Range findYRange(XYZDataset dataset)
Returns the range of y-values in the dataset by iterating over all values (and ignoring `Double.NaN` and infinite values). If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
Returns:
  The range.

### findYRange

public static Range findYRange(XYZDataset dataset, double inc)
Returns the range of y-values in the dataset by iterating over all values (and ignoring `Double.NaN` values). The range will be extended if necessary to include `inc` (unless it is `Double.NaN` in which case it is ignored). Infinite values in the dataset will be ignored. If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `inc` - an additional x-value to include.
Returns:
  The range.

### findYRange

public static Range findYRange(XYZDataset dataset, double inc, boolean finite)
Returns the range of y-values in the dataset by iterating over all values (and ignoring `Double.NaN` values). The range will be extended if necessary to include `inc` (unless it is `Double.NaN` in which case it is ignored). If the `finite` flag is set, infinite values in the dataset will be ignored. If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `inc` - an additional y-value to include.
  `finite` - a flag indicating whether to exclude infinite values.
Returns:
  The range (possibly `null`).
Since:
  1.4

### findZRange

public static Range findZRange(XYZDataset dataset)
Returns the range of z-values in the dataset by iterating over all values (and ignoring `Double.NaN` and infinite values). If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
Returns:
  The range (possibly `null`).

### findZRange

public static Range findZRange(XYZDataset dataset, double inc)
Returns the range of z-values in the dataset by iterating over all values (and ignoring `Double.NaN` values). The range will be extended if necessary to include `inc` (unless it is `Double.NaN` in which case it is ignored). Infinite values in the dataset will be ignored. If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `inc` - an additional x-value to include.
Returns:
  The range (possibly `null`).

### findZRange

public static Range findZRange(XYZDataset dataset, double inc, boolean finite)
Returns the range of z-values in the dataset by iterating over all values (and ignoring `Double.NaN` values). The range will be extended if necessary to include `inc` (unless it is `Double.NaN` in which case it is ignored). If the `finite` flag is set, infinite values in the dataset will be ignored. If there are no values eligible for inclusion in the range, this method returns `null`.

Parameters:
  `dataset` - the dataset (`null` not permitted).
  `inc` - an additional z-value to include.
  `finite` - a flag indicating whether to exclude infinite values.
Returns:
  The range (possibly `null`).
Since:
  1.4

### extractXYZDatasetFromRows

public static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>> XYZDataset extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends Number> source, R xRowKey, R yRowKey, R zRowKey)
Creates an `XYZDataset` by extracting values from specified rows in a `KeyedValues3D` instance, across all the available columns (items where any of the x, y or z values is `null` are skipped). The new dataset contains a copy of the data and is completely independent of the `source` dataset.
Note that `CategoryDataset3D` is an extension of `KeyedValues3D` so you can use this method for any implementation of the `CategoryDataset3D` interface.

Type Parameters:
  `S` - the series key (must implement Comparable).
  `R` - the row key (must implement Comparable).
  `C` - the column key (must implement Comparable).
Parameters:
  `source` - the source data (`null` not permitted).
  `xRowKey` - the row key for x-values (`null` not permitted).
  `yRowKey` - the row key for y-values (`null` not permitted).
  `zRowKey` - the row key for z-values (`null` not permitted).
Returns:
  A new dataset.
Since:
  1.3

### extractXYZDatasetFromRows

public static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>> XYZDataset extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends Number> source, R xRowKey, R yRowKey, R zRowKey, NullConversion nullConversion, List<KeyedValues3DItemKey> exceptions)
Creates an `XYZDataset` by extracting values from specified rows in a `KeyedValues3D` instance. The new dataset contains a copy of the data and is completely independent of the `source` dataset. Note that `CategoryDataset3D` is an extension of `KeyedValues3D`.
Special handling is provided for items that contain `null` values. The caller may pass in an `exceptions` list ( normally empty) that will be populated with the keys of the items that receive special handling, if any.

Type Parameters:
  `S` - the series key (must implement Comparable).
  `R` - the row key (must implement Comparable).
  `C` - the column key (must implement Comparable).
Parameters:
  `source` - the source data (`null` not permitted).
  `xRowKey` - the row key for x-values (`null` not permitted).
  `yRowKey` - the row key for y-values (`null` not permitted).
  `zRowKey` - the row key for z-values (`null` not permitted).
  `nullConversion` - specifies the treatment for `null` values in the dataset (`null` not permitted).
  `exceptions` - a list that, if not null, will be populated with keys for the items in the source dataset that contain `null` values (`null` permitted).
Returns:
  A new dataset.
Since:
  1.3

### extractXYZDatasetFromColumns

public static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>> XYZDataset<S> extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends Number> source, C xColKey, C yColKey, C zColKey)
Creates an `XYZDataset` by extracting values from specified columns in a `KeyedValues3D` instance, across all the available rows (items where any of the x, y or z values is `null` are skipped). The new dataset contains a copy of the data and is completely independent of the `source` dataset.
Note that `CategoryDataset3D` is an extension of `KeyedValues3D` so you can use this method for any implementation of the `CategoryDataset3D` interface.

Type Parameters:
  `S` - the series key (must implement Comparable).
  `R` - the row key (must implement Comparable).
  `C` - the column key (must implement Comparable).
Parameters:
  `source` - the source data (`null` not permitted).
  `xColKey` - the column key for x-values (`null` not permitted).
  `yColKey` - the column key for y-values (`null` not permitted).
  `zColKey` - the column key for z-values (`null` not permitted).
Returns:
  A new dataset.
Since:
  1.3

### extractXYZDatasetFromColumns

public static <S extends Comparable<S>, R extends Comparable<R>, C extends Comparable<C>> XYZDataset<S> extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends Number> source, C xColKey, C yColKey, C zColKey, NullConversion nullConversion, List<KeyedValues3DItemKey> exceptions)
Creates an `XYZDataset` by extracting values from specified columns in a `KeyedValues3D` instance. The new dataset contains a copy of the data and is completely independent of the `source` dataset. Note that `CategoryDataset3D` is an extension of `KeyedValues3D`.
Special handling is provided for items that contain `null` values. The caller may pass in an `exceptions` list ( normally empty) that will be populated with the keys of the items that receive special handling, if any.

Type Parameters:
  `S` - the series key (must implement Comparable).
  `R` - the row key (must implement Comparable).
  `C` - the column key (must implement Comparable).
Parameters:
  `source` - the source data (`null` not permitted).
  `xColKey` - the column key for x-values (`null` not permitted).
  `yColKey` - the column key for y-values (`null` not permitted).
  `zColKey` - the column key for z-values (`null` not permitted).
  `nullConversion` - specifies the treatment for `null` values in the dataset (`null` not permitted).
  `exceptions` - a list that, if not null, will be populated with keys for the items in the source dataset that contain `null` values (`null` permitted).
Returns:
  A new dataset.
Since:
  1.3