com.orsoncharts.data

## Class DataUtils

- java.lang.Object
- - com.orsoncharts.data.DataUtils

-     public class DataUtils
      extends java.lang.Object

  Some utility methods for working with the various datasets and data structures available in Orson Charts.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <S extends java.lang.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 java.lang.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 java.lang.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset<S>` | `extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends java.lang.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset<S>` | `extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends java.lang.Number> source, C xColKey, C yColKey, C zColKey, NullConversion nullConversion, java.util.List<KeyedValues3DItemKey> exceptions)` Creates an `XYZDataset` by extracting values from specified columns in a `KeyedValues3D` instance.
    `static <S extends java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset` | `extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends java.lang.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset` | `extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends java.lang.Number> source, R xRowKey, R yRowKey, R zRowKey, NullConversion nullConversion, java.util.List<KeyedValues3DItemKey> exceptions)` Creates an `XYZDataset` by extracting values from specified rows in a `KeyedValues3D` instance.
    `static Range` | `findStackedValueRange(Values3D<? extends java.lang.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 java.lang.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 java.lang.Number> data)` Returns the range of values in the specified data structure (a three dimensional cube).
    `static Range` | `findValueRange(Values3D<? extends java.lang.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 java.lang.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 java.lang.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 java.lang.Comparable<S>> double` | `total(KeyedValues3D<S,?,?,? extends java.lang.Number> data, S seriesKey)` Returns the total of the non-`null` values in the dataset for the specified series.
    `static double` | `total(Values<java.lang.Number> values)` Returns the total of the values in the list.
    `static <S extends java.lang.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 java.lang.Comparable<C>> double` | `totalForColumn(KeyedValues3D<?,?,C,? extends java.lang.Number> data, C columnKey)` Returns the total of the non-`null` entries in the dataset for the specified column (all series).
    `static <R extends java.lang.Comparable<R>> double` | `totalForRow(KeyedValues3D<?,R,?,? extends java.lang.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 Detail

    - #### total

          public static double total(Values<java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Comparable<S>> double total(KeyedValues3D<S,?,?,? extends java.lang.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 java.lang.Comparable<R>> double totalForRow(KeyedValues3D<?,R,?,? extends java.lang.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 java.lang.Comparable<C>> double totalForColumn(KeyedValues3D<?,?,C,? extends java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends java.lang.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset extractXYZDatasetFromRows(KeyedValues3D<S,R,C,? extends java.lang.Number> source,
                                                                                                                                                                     R xRowKey,
                                                                                                                                                                     R yRowKey,
                                                                                                                                                                     R zRowKey,
                                                                                                                                                                     NullConversion nullConversion,
                                                                                                                                                                     java.util.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset<S> extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends java.lang.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 java.lang.Comparable<S>,R extends java.lang.Comparable<R>,C extends java.lang.Comparable<C>> XYZDataset<S> extractXYZDatasetFromColumns(KeyedValues3D<S,R,C,? extends java.lang.Number> source,
                                                                                                                                                                           C xColKey,
                                                                                                                                                                           C yColKey,
                                                                                                                                                                           C zColKey,
                                                                                                                                                                           NullConversion nullConversion,
                                                                                                                                                                           java.util.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