org.jfree.data.general

## Class DatasetUtilities

- java.lang.Object
- - org.jfree.data.general.DatasetUtilities

-     public final class DatasetUtilities
      extends java.lang.Object

  A collection of useful static methods relating to datasets.

- - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static double` | `calculateStackTotal(TableXYDataset dataset, int item)` Calculates the total for the y-values in all series for a given item index.
    `static Range` | `findDomainBounds(XYDataset dataset)` Returns the range of values in the domain (x-values) of a dataset.
    `static Range` | `findDomainBounds(XYDataset dataset, boolean includeInterval)` Returns the range of values in the domain (x-values) of a dataset.
    `static Range` | `findDomainBounds(XYDataset dataset, java.util.List visibleSeriesKeys, boolean includeInterval)` Returns the bounds of the x-values in the specified `dataset` taking into account only the visible series and including any x-interval if requested.
    `static int[]` | `findItemIndicesForX(XYDataset dataset, int series, double x)` Finds the indices of the the items in the dataset that span the specified x-value.
    `static java.lang.Number` | `findMaximumDomainValue(XYDataset dataset)` Returns the maximum domain value for the specified dataset.
    `static java.lang.Number` | `findMaximumRangeValue(XYDataset dataset)` Returns the maximum range value for the specified dataset.
    `static java.lang.Number` | `findMinimumDomainValue(XYDataset dataset)` Finds the minimum domain (or X) value for the specified dataset.
    `static java.lang.Number` | `findMinimumRangeValue(XYDataset dataset)` Returns the minimum range value for the specified dataset.
    `static Range` | `findRangeBounds(XYDataset dataset)` Returns the range of values in the range for the dataset.
    `static Range` | `findRangeBounds(XYDataset dataset, boolean includeInterval)` Returns the range of values in the range for the dataset.
    `static Range` | `findRangeBounds(XYDataset dataset, java.util.List visibleSeriesKeys, Range xRange, boolean includeInterval)` Finds the bounds of the y-values in the specified dataset, including only those series that are listed in visibleSeriesKeys, and those items whose x-values fall within the specified range.
    `static Range` | `findStackedRangeBounds(TableXYDataset dataset)` Returns the minimum and maximum values for the dataset's range, assuming that the series are stacked.
    `static Range` | `findStackedRangeBounds(TableXYDataset dataset, double base)` Returns the minimum and maximum values for the dataset's range, assuming that the series are stacked, using the specified base value.
    `static double` | `findYValue(XYDataset dataset, int series, double x)` Returns the interpolated value of y that corresponds to the specified x-value in the given series.
    `static Range` | `findZBounds(XYZDataset dataset)` Returns the range of values in the z-dimension for the dataset.
    `static Range` | `findZBounds(XYZDataset dataset, boolean includeInterval)` Returns the range of values in the z-dimension for the dataset.
    `static Range` | `findZBounds(XYZDataset dataset, java.util.List visibleSeriesKeys, Range xRange, boolean includeInterval)` Finds the bounds of the z-values in the specified dataset, including only those series that are listed in visibleSeriesKeys, and those items whose x-values fall within the specified range.
    `static boolean` | `isEmptyOrNull(XYDataset dataset)` Returns `true` if the dataset is empty (or `null`), and `false` otherwise.
    `static Range` | `iterateDomainBounds(XYDataset dataset)` Iterates over the items in an `XYDataset` to find the range of x-values.
    `static Range` | `iterateDomainBounds(XYDataset dataset, boolean includeInterval)` Iterates over the items in an `XYDataset` to find the range of x-values.
    `static Range` | `iterateRangeBounds(XYDataset dataset)` Iterates over the data item of the xy dataset to find the range bounds.
    `static Range` | `iterateRangeBounds(XYDataset dataset, boolean includeInterval)` Iterates over the data items of the xy dataset to find the range bounds.
    `static Range` | `iterateToFindDomainBounds(XYDataset dataset, java.util.List visibleSeriesKeys, boolean includeInterval)` Returns the range of x-values in the specified dataset for the data items belonging to the visible series.
    `static Range` | `iterateToFindRangeBounds(XYDataset dataset, java.util.List visibleSeriesKeys, Range xRange, boolean includeInterval)` Returns the range of y-values in the specified dataset for the data items belonging to the visible series and with x-values in the given range.
    `static Range` | `iterateToFindZBounds(XYZDataset dataset, java.util.List visibleSeriesKeys, Range xRange, boolean includeInterval)` Returns the range of z-values in the specified dataset for the data items belonging to the visible series and with x-values in the given range.
    `static Range` | `iterateXYRangeBounds(XYDataset dataset)` Deprecated. As of 1.0.10, use `iterateRangeBounds(XYDataset)`.
    `static Range` | `iterateZBounds(XYZDataset dataset)` Iterates over the data item of the xyz dataset to find the z-dimension bounds.
    `static Range` | `iterateZBounds(XYZDataset dataset, boolean includeInterval)` Iterates over the data items of the xyz dataset to find the z-dimension bounds.
    `static XYDataset` | `sampleFunction2D(Function2D f, double start, double end, int samples, java.lang.Comparable seriesKey)` Creates an `XYDataset` by sampling the specified function over a fixed range.
    `static XYSeries` | `sampleFunction2DToSeries(Function2D f, double start, double end, int samples, java.lang.Comparable seriesKey)` Creates an `XYSeries` by sampling the specified function over a fixed range.

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

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

- - ### Method Detail

    - #### sampleFunction2D

          public static XYDataset sampleFunction2D(Function2D f,
                                                   double start,
                                                   double end,
                                                   int samples,
                                                   java.lang.Comparable seriesKey)

      Creates an `XYDataset` by sampling the specified function over a fixed range.
      Parameters:
        `f` - the function (`null` not permitted).
        `start` - the start value for the range.
        `end` - the end value for the range.
        `samples` - the number of sample points (must be > 1).
        `seriesKey` - the key to give the resulting series (`null` not permitted).
      Returns:
        A dataset.

    - #### sampleFunction2DToSeries

          public static XYSeries sampleFunction2DToSeries(Function2D f,
                                                          double start,
                                                          double end,
                                                          int samples,
                                                          java.lang.Comparable seriesKey)

      Creates an `XYSeries` by sampling the specified function over a fixed range.
      Parameters:
        `f` - the function (`null` not permitted).
        `start` - the start value for the range.
        `end` - the end value for the range.
        `samples` - the number of sample points (must be > 1).
        `seriesKey` - the key to give the resulting series (`null` not permitted).
      Returns:
        A series.
      Since:
        1.0.13

    - #### isEmptyOrNull

          public static boolean isEmptyOrNull(XYDataset dataset)

      Returns `true` if the dataset is empty (or `null`), and `false` otherwise.
      Parameters:
        `dataset` - the dataset (`null` permitted).
      Returns:
        A boolean.

    - #### findDomainBounds

          public static Range findDomainBounds(XYDataset dataset)

      Returns the range of values in the domain (x-values) of a dataset.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range of values (possibly `null`).

    - #### findDomainBounds

          public static Range findDomainBounds(XYDataset dataset,
                                               boolean includeInterval)

      Returns the range of values in the domain (x-values) of a dataset.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `includeInterval` - determines whether or not the x-interval is taken into account (only applies if the dataset is an `IntervalXYDataset`).
      Returns:
        The range of values (possibly `null`).

    - #### findDomainBounds

          public static Range findDomainBounds(XYDataset dataset,
                                               java.util.List visibleSeriesKeys,
                                               boolean includeInterval)

      Returns the bounds of the x-values in the specified `dataset` taking into account only the visible series and including any x-interval if requested.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `visibleSeriesKeys` - the visible series keys (`null` not permitted).
        `includeInterval` - include the x-interval (if any)?
      Returns:
        The bounds (or `null` if the dataset contains no values.
      Since:
        1.0.13

    - #### iterateDomainBounds

          public static Range iterateDomainBounds(XYDataset dataset)

      Iterates over the items in an `XYDataset` to find the range of x-values. If the dataset is an instance of `IntervalXYDataset`, the starting and ending x-values will be used for the bounds calculation.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range (possibly `null`).

    - #### iterateDomainBounds

          public static Range iterateDomainBounds(XYDataset dataset,
                                                  boolean includeInterval)

      Iterates over the items in an `XYDataset` to find the range of x-values.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `includeInterval` - a flag that determines, for an `IntervalXYDataset`, whether the x-interval or just the x-value is used to determine the overall range.
      Returns:
        The range (possibly `null`).

    - #### findRangeBounds

          public static Range findRangeBounds(XYDataset dataset)

      Returns the range of values in the range for the dataset. This method is the partner for the `findDomainBounds(XYDataset)` method.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range (possibly `null`).

    - #### findRangeBounds

          public static Range findRangeBounds(XYDataset dataset,
                                              boolean includeInterval)

      Returns the range of values in the range for the dataset. This method is the partner for the `findDomainBounds(XYDataset, boolean)` method.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `includeInterval` - a flag that determines whether or not the y-interval is taken into account.
      Returns:
        The range (possibly `null`).

    - #### findRangeBounds

          public static Range findRangeBounds(XYDataset dataset,
                                              java.util.List visibleSeriesKeys,
                                              Range xRange,
                                              boolean includeInterval)

      Finds the bounds of the y-values in the specified dataset, including only those series that are listed in visibleSeriesKeys, and those items whose x-values fall within the specified range.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `visibleSeriesKeys` - the keys for the visible series (`null` not permitted).
        `xRange` - the x-range (`null` not permitted).
        `includeInterval` - include the y-interval (if the dataset has a y-interval).
      Returns:
        The data bounds.
      Since:
        1.0.13

    - #### iterateXYRangeBounds

          public static Range iterateXYRangeBounds(XYDataset dataset)

      Deprecated. As of 1.0.10, use `iterateRangeBounds(XYDataset)`.
      Iterates over the data item of the xy dataset to find the range bounds.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range (possibly `null`).

    - #### iterateRangeBounds

          public static Range iterateRangeBounds(XYDataset dataset)

      Iterates over the data item of the xy dataset to find the range bounds.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range (possibly `null`).
      Since:
        1.0.10

    - #### iterateRangeBounds

          public static Range iterateRangeBounds(XYDataset dataset,
                                                 boolean includeInterval)

      Iterates over the data items of the xy dataset to find the range bounds.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `includeInterval` - a flag that determines, for an `IntervalXYDataset`, whether the y-interval or just the y-value is used to determine the overall range.
      Returns:
        The range (possibly `null`).
      Since:
        1.0.10

    - #### findZBounds

          public static Range findZBounds(XYZDataset dataset)

      Returns the range of values in the z-dimension for the dataset. This method is the partner for the `findRangeBounds(XYDataset)` and `findDomainBounds(XYDataset)` methods.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range (possibly `null`).

    - #### findZBounds

          public static Range findZBounds(XYZDataset dataset,
                                          boolean includeInterval)

      Returns the range of values in the z-dimension for the dataset. This method is the partner for the `findRangeBounds(XYDataset, boolean)` and `findDomainBounds(XYDataset, boolean)` methods.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `includeInterval` - a flag that determines whether or not the z-interval is taken into account.
      Returns:
        The range (possibly `null`).

    - #### findZBounds

          public static Range findZBounds(XYZDataset dataset,
                                          java.util.List visibleSeriesKeys,
                                          Range xRange,
                                          boolean includeInterval)

      Finds the bounds of the z-values in the specified dataset, including only those series that are listed in visibleSeriesKeys, and those items whose x-values fall within the specified range.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `visibleSeriesKeys` - the keys for the visible series (`null` not permitted).
        `xRange` - the x-range (`null` not permitted).
        `includeInterval` - include the z-interval (if the dataset has a z-interval).
      Returns:
        The data bounds.

    - #### iterateZBounds

          public static Range iterateZBounds(XYZDataset dataset)

      Iterates over the data item of the xyz dataset to find the z-dimension bounds.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range (possibly `null`).

    - #### iterateZBounds

          public static Range iterateZBounds(XYZDataset dataset,
                                             boolean includeInterval)

      Iterates over the data items of the xyz dataset to find the z-dimension bounds.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `includeInterval` - include the z-interval (if the dataset has a z-interval.
      Returns:
        The range (possibly `null`).

    - #### iterateToFindDomainBounds

          public static Range iterateToFindDomainBounds(XYDataset dataset,
                                                        java.util.List visibleSeriesKeys,
                                                        boolean includeInterval)

      Returns the range of x-values in the specified dataset for the data items belonging to the visible series.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `visibleSeriesKeys` - the visible series keys (`null` not permitted).
        `includeInterval` - a flag that determines whether or not the y-interval for the dataset is included (this only applies if the dataset is an instance of IntervalXYDataset).
      Returns:
        The x-range (possibly `null`).
      Since:
        1.0.13

    - #### iterateToFindRangeBounds

          public static Range iterateToFindRangeBounds(XYDataset dataset,
                                                       java.util.List visibleSeriesKeys,
                                                       Range xRange,
                                                       boolean includeInterval)

      Returns the range of y-values in the specified dataset for the data items belonging to the visible series and with x-values in the given range.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `visibleSeriesKeys` - the visible series keys (`null` not permitted).
        `xRange` - the x-range (`null` not permitted).
        `includeInterval` - a flag that determines whether or not the y-interval for the dataset is included (this only applies if the dataset is an instance of IntervalXYDataset).
      Returns:
        The y-range (possibly `null`).
      Since:
        1.0.13

    - #### iterateToFindZBounds

          public static Range iterateToFindZBounds(XYZDataset dataset,
                                                   java.util.List visibleSeriesKeys,
                                                   Range xRange,
                                                   boolean includeInterval)

      Returns the range of z-values in the specified dataset for the data items belonging to the visible series and with x-values in the given range.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `visibleSeriesKeys` - the visible series keys (`null` not permitted).
        `xRange` - the x-range (`null` not permitted).
        `includeInterval` - a flag that determines whether or not the z-interval for the dataset is included (this only applies if the dataset has an interval, which is currently not supported).
      Returns:
        The y-range (possibly `null`).

    - #### findMinimumDomainValue

          public static java.lang.Number findMinimumDomainValue(XYDataset dataset)

      Finds the minimum domain (or X) value for the specified dataset. This is easy if the dataset implements the `DomainInfo` interface (a good idea if there is an efficient way to determine the minimum value). Otherwise, it involves iterating over the entire data-set.

      Returns `null` if all the data values in the dataset are `null`.

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

    - #### findMaximumDomainValue

          public static java.lang.Number findMaximumDomainValue(XYDataset dataset)

      Returns the maximum domain value for the specified dataset. This is easy if the dataset implements the `DomainInfo` interface (a good idea if there is an efficient way to determine the maximum value). Otherwise, it involves iterating over the entire data-set. Returns `null` if all the data values in the dataset are `null`.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The maximum value (possibly `null`).

    - #### findMinimumRangeValue

          public static java.lang.Number findMinimumRangeValue(XYDataset dataset)

      Returns the minimum range value for the specified dataset. This is easy if the dataset implements the `RangeInfo` interface (a good idea if there is an efficient way to determine the minimum value). Otherwise, it involves iterating over the entire data-set. Returns `null` if all the data values in the dataset are `null`.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The minimum value (possibly `null`).

    - #### findMaximumRangeValue

          public static java.lang.Number findMaximumRangeValue(XYDataset dataset)

      Returns the maximum range value for the specified dataset. This is easy if the dataset implements the `RangeInfo` interface (a good idea if there is an efficient way to determine the maximum value). Otherwise, it involves iterating over the entire data-set. Returns `null` if all the data values are `null`.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The maximum value (possibly `null`).

    - #### findStackedRangeBounds

          public static Range findStackedRangeBounds(TableXYDataset dataset)

      Returns the minimum and maximum values for the dataset's range, assuming that the series are stacked.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
      Returns:
        The range ([0.0, 0.0] if the dataset contains no values).

    - #### findStackedRangeBounds

          public static Range findStackedRangeBounds(TableXYDataset dataset,
                                                     double base)

      Returns the minimum and maximum values for the dataset's range, assuming that the series are stacked, using the specified base value.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `base` - the base value.
      Returns:
        The range (`null` if the dataset contains no values).

    - #### calculateStackTotal

          public static double calculateStackTotal(TableXYDataset dataset,
                                                   int item)

      Calculates the total for the y-values in all series for a given item index.
      Parameters:
        `dataset` - the dataset.
        `item` - the item index.
      Returns:
        The total.
      Since:
        1.0.5

    - #### findYValue

          public static double findYValue(XYDataset dataset,
                                          int series,
                                          double x)

      Returns the interpolated value of y that corresponds to the specified x-value in the given series. If the x-value falls outside the range of x-values for the dataset, this method returns `Double.NaN`.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `series` - the series index.
        `x` - the x-value.
      Returns:
        The y value.
      Since:
        1.0.16

    - #### findItemIndicesForX

          public static int[] findItemIndicesForX(XYDataset dataset,
                                                  int series,
                                                  double x)

      Finds the indices of the the items in the dataset that span the specified x-value. There are three cases for the return value:
      - there is an exact match for the x-value at index i (returns `int[] {i, i}`);
      - the x-value falls between two (adjacent) items at index i and i+1 (returns `int[] {i, i+1}`);
      - the x-value falls outside the domain bounds, in which case the method returns `int[] {-1, -1}`.
      Parameters:
        `dataset` - the dataset (`null` not permitted).
        `series` - the series index.
        `x` - the x-value.
      Returns:
        The indices of the two items that span the x-value.
      Since:
        1.0.16
      See Also:
        `findYValue(org.jfree.data.xy.XYDataset, int, double)`