001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2017, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * -----------------
028 * DatasetUtils.java
029 * -----------------
030 * (C) Copyright 2000-2020, by Object Refinery Limited and Contributors.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   Andrzej Porebski (bug fix);
034 *                   Jonathan Nash (bug fix);
035 *                   Richard Atkinson;
036 *                   Andreas Schroeder;
037 *                   Rafal Skalny (patch 1925366);
038 *                   Jerome David (patch 2131001);
039 *                   Peter Kolb (patch 2791407);
040 *                   Martin Hoeller (patch 2952086);
041 *
042 * Changes (from 18-Sep-2001)
043 * --------------------------
044 * 18-Sep-2001 : Added standard header and fixed DOS encoding problem (DG);
045 * 22-Oct-2001 : Renamed DataSource.java --> Dataset.java etc. (DG);
046 * 15-Nov-2001 : Moved to package com.jrefinery.data.* in the JCommon class
047 *               library (DG);
048 *               Changed to handle null values from datasets (DG);
049 *               Bug fix (thanks to Andrzej Porebski) - initial value now set
050 *               to positive or negative infinity when iterating (DG);
051 * 22-Nov-2001 : Datasets with containing no data now return null for min and
052 *               max calculations (DG);
053 * 13-Dec-2001 : Extended to handle HighLowDataset and IntervalXYDataset (DG);
054 * 15-Feb-2002 : Added getMinimumStackedRangeValue() and
055 *               getMaximumStackedRangeValue() (DG);
056 * 28-Feb-2002 : Renamed Datasets.java --> DatasetUtilities.java (DG);
057 * 18-Mar-2002 : Fixed bug in min/max domain calculation for datasets that
058 *               implement the CategoryDataset interface AND the XYDataset
059 *               interface at the same time.  Thanks to Jonathan Nash for the
060 *               fix (DG);
061 * 23-Apr-2002 : Added getDomainExtent() and getRangeExtent() methods (DG);
062 * 13-Jun-2002 : Modified range measurements to handle
063 *               IntervalCategoryDataset (DG);
064 * 12-Jul-2002 : Method name change in DomainInfo interface (DG);
065 * 30-Jul-2002 : Added pie dataset summation method (DG);
066 * 01-Oct-2002 : Added a method for constructing an XYDataset from a Function2D
067 *               instance (DG);
068 * 24-Oct-2002 : Amendments required following changes to the CategoryDataset
069 *               interface (DG);
070 * 18-Nov-2002 : Changed CategoryDataset to TableDataset (DG);
071 * 04-Mar-2003 : Added isEmpty(XYDataset) method (DG);
072 * 05-Mar-2003 : Added a method for creating a CategoryDataset from a
073 *               KeyedValues instance (DG);
074 * 15-May-2003 : Renamed isEmpty --> isEmptyOrNull (DG);
075 * 25-Jun-2003 : Added limitPieDataset methods (RA);
076 * 26-Jun-2003 : Modified getDomainExtent() method to accept null datasets (DG);
077 * 27-Jul-2003 : Added getStackedRangeExtent(TableXYDataset data) (RA);
078 * 18-Aug-2003 : getStackedRangeExtent(TableXYDataset data) now handles null
079 *               values (RA);
080 * 02-Sep-2003 : Added method to check for null or empty PieDataset (DG);
081 * 18-Sep-2003 : Fix for bug 803660 (getMaximumRangeValue for
082 *               CategoryDataset) (DG);
083 * 20-Oct-2003 : Added getCumulativeRangeExtent() method (DG);
084 * 09-Jan-2003 : Added argument checking code to the createCategoryDataset()
085 *               method (DG);
086 * 23-Mar-2004 : Fixed bug in getMaximumStackedRangeValue() method (DG);
087 * 31-Mar-2004 : Exposed the extent iteration algorithms to use one of them and
088 *               applied noninstantiation pattern (AS);
089 * 11-May-2004 : Renamed getPieDatasetTotal --> calculatePieDatasetTotal (DG);
090 * 15-Jul-2004 : Switched getX() with getXValue() and getY() with getYValue();
091 * 24-Aug-2004 : Added argument checks to createCategoryDataset() method (DG);
092 * 04-Oct-2004 : Renamed ArrayUtils --> ArrayUtilities (DG);
093 * 06-Oct-2004 : Renamed findDomainExtent() --> findDomainBounds(),
094 *               findRangeExtent() --> findRangeBounds() (DG);
095 * 07-Jan-2005 : Renamed findStackedRangeExtent() --> findStackedRangeBounds(),
096 *               findCumulativeRangeExtent() --> findCumulativeRangeBounds(),
097 *               iterateXYRangeExtent() --> iterateXYRangeBounds(),
098 *               removed deprecated methods (DG);
099 * 03-Feb-2005 : The findStackedRangeBounds() methods now return null for
100 *               empty datasets (DG);
101 * 03-Mar-2005 : Moved createNumberArray() and createNumberArray2D() methods
102 *               from DatasetUtilities --> DataUtilities (DG);
103 * 22-Sep-2005 : Added new findStackedRangeBounds() method that takes base
104 *               argument (DG);
105 * ------------- JFREECHART 1.0.x ---------------------------------------------
106 * 15-Mar-2007 : Added calculateStackTotal() method (DG);
107 * 27-Mar-2008 : Fixed bug in findCumulativeRangeBounds() method (DG);
108 * 28-Mar-2008 : Fixed sample count in sampleFunction2D() method, renamed
109 *               iterateXYRangeBounds() --> iterateRangeBounds(XYDataset), and
110 *               fixed a bug in findRangeBounds(XYDataset, false) (DG);
111 * 28-Mar-2008 : Applied a variation of patch 1925366 (from Rafal Skalny) for
112 *               slightly more efficient iterateRangeBounds() methods (DG);
113 * 08-Apr-2008 : Fixed typo in iterateRangeBounds() (DG);
114 * 08-Oct-2008 : Applied patch 2131001 by Jerome David, with some modifications
115 *               and additions and some new unit tests (DG);
116 * 12-Feb-2009 : Added sampleFunction2DToSeries() method (DG);
117 * 27-Mar-2009 : Added new methods to find domain and range bounds taking into
118 *               account hidden series (DG);
119 * 01-Apr-2009 : Handle a StatisticalCategoryDataset in
120 *               iterateToFindRangeBounds() (DG);
121 * 16-May-2009 : Patch 2791407 - fix iterateToFindRangeBounds for
122 *               MultiValueCategoryDataset (PK);
123 * 10-Sep-2009 : Fix bug 2849731 for IntervalCategoryDataset (DG);
124 * 16-Feb-2010 : Patch 2952086 - find z-bounds (MH);
125 * 02-Jul-2013 : Use ParamChecks (DG);
126 * 22-Sep-2015 : Fix bugs in iterateToFindDomainBounds() and 
127 *               iterateToFindRangeBounds() (DG);
128 */
129
130package org.jfree.data.general;
131
132import java.util.ArrayList;
133import java.util.Iterator;
134import java.util.List;
135import org.jfree.chart.util.ArrayUtils;
136import org.jfree.chart.util.Args;
137
138import org.jfree.data.DomainInfo;
139import org.jfree.data.DomainOrder;
140import org.jfree.data.KeyToGroupMap;
141import org.jfree.data.KeyedValues;
142import org.jfree.data.Range;
143import org.jfree.data.RangeInfo;
144import org.jfree.data.category.CategoryDataset;
145import org.jfree.data.category.CategoryRangeInfo;
146import org.jfree.data.category.DefaultCategoryDataset;
147import org.jfree.data.category.IntervalCategoryDataset;
148import org.jfree.data.function.Function2D;
149import org.jfree.data.statistics.BoxAndWhiskerCategoryDataset;
150import org.jfree.data.statistics.BoxAndWhiskerXYDataset;
151import org.jfree.data.statistics.MultiValueCategoryDataset;
152import org.jfree.data.statistics.StatisticalCategoryDataset;
153import org.jfree.data.xy.IntervalXYDataset;
154import org.jfree.data.xy.OHLCDataset;
155import org.jfree.data.xy.TableXYDataset;
156import org.jfree.data.xy.XYDataset;
157import org.jfree.data.xy.XYDomainInfo;
158import org.jfree.data.xy.XYRangeInfo;
159import org.jfree.data.xy.XYSeries;
160import org.jfree.data.xy.XYSeriesCollection;
161import org.jfree.data.xy.XYZDataset;
162
163/**
164 * A collection of useful static methods relating to datasets.
165 */
166public final class DatasetUtils {
167
168    /**
169     * Private constructor for non-instanceability.
170     */
171    private DatasetUtils() {
172        // now try to instantiate this ;-)
173    }
174
175    /**
176     * Calculates the total of all the values in a {@link PieDataset}.  If
177     * the dataset contains negative or {@code null} values, they are
178     * ignored.
179     *
180     * @param dataset  the dataset ({@code null} not permitted).
181     *
182     * @return The total.
183     */
184    public static double calculatePieDatasetTotal(PieDataset dataset) {
185        Args.nullNotPermitted(dataset, "dataset");
186        List keys = dataset.getKeys();
187        double totalValue = 0;
188        Iterator iterator = keys.iterator();
189        while (iterator.hasNext()) {
190            Comparable current = (Comparable) iterator.next();
191            if (current != null) {
192                Number value = dataset.getValue(current);
193                double v = 0.0;
194                if (value != null) {
195                    v = value.doubleValue();
196                }
197                if (v > 0) {
198                    totalValue = totalValue + v;
199                }
200            }
201        }
202        return totalValue;
203    }
204
205    /**
206     * Creates a pie dataset from a table dataset by taking all the values
207     * for a single row.
208     *
209     * @param dataset  the dataset ({@code null} not permitted).
210     * @param rowKey  the row key.
211     *
212     * @return A pie dataset.
213     */
214    public static PieDataset createPieDatasetForRow(CategoryDataset dataset,
215            Comparable rowKey) {
216        int row = dataset.getRowIndex(rowKey);
217        return createPieDatasetForRow(dataset, row);
218    }
219
220    /**
221     * Creates a pie dataset from a table dataset by taking all the values
222     * for a single row.
223     *
224     * @param dataset  the dataset ({@code null} not permitted).
225     * @param row  the row (zero-based index).
226     *
227     * @return A pie dataset.
228     */
229    public static PieDataset createPieDatasetForRow(CategoryDataset dataset,
230            int row) {
231        DefaultPieDataset result = new DefaultPieDataset();
232        int columnCount = dataset.getColumnCount();
233        for (int current = 0; current < columnCount; current++) {
234            Comparable columnKey = dataset.getColumnKey(current);
235            result.setValue(columnKey, dataset.getValue(row, current));
236        }
237        return result;
238    }
239
240    /**
241     * Creates a pie dataset from a table dataset by taking all the values
242     * for a single column.
243     *
244     * @param dataset  the dataset ({@code null} not permitted).
245     * @param columnKey  the column key.
246     *
247     * @return A pie dataset.
248     */
249    public static PieDataset createPieDatasetForColumn(CategoryDataset dataset,
250            Comparable columnKey) {
251        int column = dataset.getColumnIndex(columnKey);
252        return createPieDatasetForColumn(dataset, column);
253    }
254
255    /**
256     * Creates a pie dataset from a {@link CategoryDataset} by taking all the
257     * values for a single column.
258     *
259     * @param dataset  the dataset ({@code null} not permitted).
260     * @param column  the column (zero-based index).
261     *
262     * @return A pie dataset.
263     */
264    public static PieDataset createPieDatasetForColumn(CategoryDataset dataset,
265            int column) {
266        DefaultPieDataset result = new DefaultPieDataset();
267        int rowCount = dataset.getRowCount();
268        for (int i = 0; i < rowCount; i++) {
269            Comparable rowKey = dataset.getRowKey(i);
270            result.setValue(rowKey, dataset.getValue(i, column));
271        }
272        return result;
273    }
274
275    /**
276     * Creates a new pie dataset based on the supplied dataset, but modified
277     * by aggregating all the low value items (those whose value is lower
278     * than the {@code percentThreshold}) into a single item with the
279     * key "Other".
280     *
281     * @param source  the source dataset ({@code null} not permitted).
282     * @param key  a new key for the aggregated items ({@code null} not
283     *             permitted).
284     * @param minimumPercent  the percent threshold.
285     *
286     * @return The pie dataset with (possibly) aggregated items.
287     */
288    public static PieDataset createConsolidatedPieDataset(PieDataset source,
289            Comparable key, double minimumPercent) {
290        return DatasetUtils.createConsolidatedPieDataset(source, key,
291                minimumPercent, 2);
292    }
293
294    /**
295     * Creates a new pie dataset based on the supplied dataset, but modified
296     * by aggregating all the low value items (those whose value is lower
297     * than the {@code percentThreshold}) into a single item.  The
298     * aggregated items are assigned the specified key.  Aggregation only
299     * occurs if there are at least {@code minItems} items to aggregate.
300     *
301     * @param source  the source dataset ({@code null} not permitted).
302     * @param key  the key to represent the aggregated items.
303     * @param minimumPercent  the percent threshold (ten percent is 0.10).
304     * @param minItems  only aggregate low values if there are at least this
305     *                  many.
306     *
307     * @return The pie dataset with (possibly) aggregated items.
308     */
309    public static PieDataset createConsolidatedPieDataset(PieDataset source,
310            Comparable key, double minimumPercent, int minItems) {
311
312        DefaultPieDataset result = new DefaultPieDataset();
313        double total = DatasetUtils.calculatePieDatasetTotal(source);
314
315        //  Iterate and find all keys below threshold percentThreshold
316        List keys = source.getKeys();
317        ArrayList otherKeys = new ArrayList();
318        Iterator iterator = keys.iterator();
319        while (iterator.hasNext()) {
320            Comparable currentKey = (Comparable) iterator.next();
321            Number dataValue = source.getValue(currentKey);
322            if (dataValue != null) {
323                double value = dataValue.doubleValue();
324                if (value / total < minimumPercent) {
325                    otherKeys.add(currentKey);
326                }
327            }
328        }
329
330        //  Create new dataset with keys above threshold percentThreshold
331        iterator = keys.iterator();
332        double otherValue = 0;
333        while (iterator.hasNext()) {
334            Comparable currentKey = (Comparable) iterator.next();
335            Number dataValue = source.getValue(currentKey);
336            if (dataValue != null) {
337                if (otherKeys.contains(currentKey)
338                    && otherKeys.size() >= minItems) {
339                    //  Do not add key to dataset
340                    otherValue += dataValue.doubleValue();
341                }
342                else {
343                    //  Add key to dataset
344                    result.setValue(currentKey, dataValue);
345                }
346            }
347        }
348        //  Add other category if applicable
349        if (otherKeys.size() >= minItems) {
350            result.setValue(key, otherValue);
351        }
352        return result;
353    }
354
355    /**
356     * Creates a {@link CategoryDataset} that contains a copy of the data in an
357     * array (instances of {@code double} are created to represent the
358     * data items).
359     * <p>
360     * Row and column keys are created by appending 0, 1, 2, ... to the
361     * supplied prefixes.
362     *
363     * @param rowKeyPrefix  the row key prefix.
364     * @param columnKeyPrefix  the column key prefix.
365     * @param data  the data.
366     *
367     * @return The dataset.
368     */
369    public static CategoryDataset createCategoryDataset(String rowKeyPrefix,
370            String columnKeyPrefix, double[][] data) {
371
372        DefaultCategoryDataset result = new DefaultCategoryDataset();
373        for (int r = 0; r < data.length; r++) {
374            String rowKey = rowKeyPrefix + (r + 1);
375            for (int c = 0; c < data[r].length; c++) {
376                String columnKey = columnKeyPrefix + (c + 1);
377                result.addValue(data[r][c], rowKey, columnKey);
378            }
379        }
380        return result;
381
382    }
383
384    /**
385     * Creates a {@link CategoryDataset} that contains a copy of the data in
386     * an array.
387     * <p>
388     * Row and column keys are created by appending 0, 1, 2, ... to the
389     * supplied prefixes.
390     *
391     * @param rowKeyPrefix  the row key prefix.
392     * @param columnKeyPrefix  the column key prefix.
393     * @param data  the data.
394     *
395     * @return The dataset.
396     */
397    public static CategoryDataset createCategoryDataset(String rowKeyPrefix,
398            String columnKeyPrefix, Number[][] data) {
399
400        DefaultCategoryDataset result = new DefaultCategoryDataset();
401        for (int r = 0; r < data.length; r++) {
402            String rowKey = rowKeyPrefix + (r + 1);
403            for (int c = 0; c < data[r].length; c++) {
404                String columnKey = columnKeyPrefix + (c + 1);
405                result.addValue(data[r][c], rowKey, columnKey);
406            }
407        }
408        return result;
409
410    }
411
412    /**
413     * Creates a {@link CategoryDataset} that contains a copy of the data in
414     * an array (instances of {@code double} are created to represent the
415     * data items).
416     * <p>
417     * Row and column keys are taken from the supplied arrays.
418     *
419     * @param rowKeys  the row keys ({@code null} not permitted).
420     * @param columnKeys  the column keys ({@code null} not permitted).
421     * @param data  the data.
422     *
423     * @return The dataset.
424     */
425    public static CategoryDataset createCategoryDataset(Comparable[] rowKeys,
426            Comparable[] columnKeys, double[][] data) {
427
428        Args.nullNotPermitted(rowKeys, "rowKeys");
429        Args.nullNotPermitted(columnKeys, "columnKeys");
430        if (ArrayUtils.hasDuplicateItems(rowKeys)) {
431            throw new IllegalArgumentException("Duplicate items in 'rowKeys'.");
432        }
433        if (ArrayUtils.hasDuplicateItems(columnKeys)) {
434            throw new IllegalArgumentException(
435                    "Duplicate items in 'columnKeys'.");
436        }
437        if (rowKeys.length != data.length) {
438            throw new IllegalArgumentException(
439                "The number of row keys does not match the number of rows in "
440                + "the data array.");
441        }
442        int columnCount = 0;
443        for (int r = 0; r < data.length; r++) {
444            columnCount = Math.max(columnCount, data[r].length);
445        }
446        if (columnKeys.length != columnCount) {
447            throw new IllegalArgumentException(
448                "The number of column keys does not match the number of "
449                + "columns in the data array.");
450        }
451
452        // now do the work...
453        DefaultCategoryDataset result = new DefaultCategoryDataset();
454        for (int r = 0; r < data.length; r++) {
455            Comparable rowKey = rowKeys[r];
456            for (int c = 0; c < data[r].length; c++) {
457                Comparable columnKey = columnKeys[c];
458                result.addValue(data[r][c], rowKey, columnKey);
459            }
460        }
461        return result;
462
463    }
464
465    /**
466     * Creates a {@link CategoryDataset} by copying the data from the supplied
467     * {@link KeyedValues} instance.
468     *
469     * @param rowKey  the row key ({@code null} not permitted).
470     * @param rowData  the row data ({@code null} not permitted).
471     *
472     * @return A dataset.
473     */
474    public static CategoryDataset createCategoryDataset(Comparable rowKey,
475            KeyedValues rowData) {
476
477        Args.nullNotPermitted(rowKey, "rowKey");
478        Args.nullNotPermitted(rowData, "rowData");
479        DefaultCategoryDataset result = new DefaultCategoryDataset();
480        for (int i = 0; i < rowData.getItemCount(); i++) {
481            result.addValue(rowData.getValue(i), rowKey, rowData.getKey(i));
482        }
483        return result;
484
485    }
486
487    /**
488     * Creates an {@link XYDataset} by sampling the specified function over a
489     * fixed range.
490     *
491     * @param f  the function ({@code null} not permitted).
492     * @param start  the start value for the range.
493     * @param end  the end value for the range.
494     * @param samples  the number of sample points (must be &gt; 1).
495     * @param seriesKey  the key to give the resulting series ({@code null} not
496     *     permitted).
497     *
498     * @return A dataset.
499     */
500    public static XYDataset sampleFunction2D(Function2D f, double start,
501            double end, int samples, Comparable seriesKey) {
502
503        // defer argument checking
504        XYSeries series = sampleFunction2DToSeries(f, start, end, samples,
505                seriesKey);
506        XYSeriesCollection collection = new XYSeriesCollection(series);
507        return collection;
508    }
509
510    /**
511     * Creates an {@link XYSeries} by sampling the specified function over a
512     * fixed range.
513     *
514     * @param f  the function ({@code null} not permitted).
515     * @param start  the start value for the range.
516     * @param end  the end value for the range.
517     * @param samples  the number of sample points (must be &gt; 1).
518     * @param seriesKey  the key to give the resulting series
519     *                   ({@code null} not permitted).
520     *
521     * @return A series.
522     *
523     * @since 1.0.13
524     */
525    public static XYSeries sampleFunction2DToSeries(Function2D f,
526            double start, double end, int samples, Comparable seriesKey) {
527
528        Args.nullNotPermitted(f, "f");
529        Args.nullNotPermitted(seriesKey, "seriesKey");
530        if (start >= end) {
531            throw new IllegalArgumentException("Requires 'start' < 'end'.");
532        }
533        if (samples < 2) {
534            throw new IllegalArgumentException("Requires 'samples' > 1");
535        }
536
537        XYSeries series = new XYSeries(seriesKey);
538        double step = (end - start) / (samples - 1);
539        for (int i = 0; i < samples; i++) {
540            double x = start + (step * i);
541            series.add(x, f.getValue(x));
542        }
543        return series;
544    }
545
546    /**
547     * Returns {@code true} if the dataset is empty (or {@code null}),
548     * and {@code false} otherwise.
549     *
550     * @param dataset  the dataset ({@code null} permitted).
551     *
552     * @return A boolean.
553     */
554    public static boolean isEmptyOrNull(PieDataset dataset) {
555
556        if (dataset == null) {
557            return true;
558        }
559
560        int itemCount = dataset.getItemCount();
561        if (itemCount == 0) {
562            return true;
563        }
564
565        for (int item = 0; item < itemCount; item++) {
566            Number y = dataset.getValue(item);
567            if (y != null) {
568                double yy = y.doubleValue();
569                if (yy > 0.0) {
570                    return false;
571                }
572            }
573        }
574
575        return true;
576
577    }
578
579    /**
580     * Returns {@code true} if the dataset is empty (or {@code null}),
581     * and {@code false} otherwise.
582     *
583     * @param dataset  the dataset ({@code null} permitted).
584     *
585     * @return A boolean.
586     */
587    public static boolean isEmptyOrNull(CategoryDataset dataset) {
588
589        if (dataset == null) {
590            return true;
591        }
592
593        int rowCount = dataset.getRowCount();
594        int columnCount = dataset.getColumnCount();
595        if (rowCount == 0 || columnCount == 0) {
596            return true;
597        }
598
599        for (int r = 0; r < rowCount; r++) {
600            for (int c = 0; c < columnCount; c++) {
601                if (dataset.getValue(r, c) != null) {
602                    return false;
603                }
604
605            }
606        }
607
608        return true;
609
610    }
611
612    /**
613     * Returns {@code true} if the dataset is empty (or {@code null}),
614     * and {@code false} otherwise.
615     *
616     * @param dataset  the dataset ({@code null} permitted).
617     *
618     * @return A boolean.
619     */
620    public static boolean isEmptyOrNull(XYDataset dataset) {
621        if (dataset != null) {
622            for (int s = 0; s < dataset.getSeriesCount(); s++) {
623                if (dataset.getItemCount(s) > 0) {
624                    return false;
625                }
626            }
627        }
628        return true;
629    }
630
631    /**
632     * Returns the range of values in the domain (x-values) of a dataset.
633     *
634     * @param dataset  the dataset ({@code null} not permitted).
635     *
636     * @return The range of values (possibly {@code null}).
637     */
638    public static Range findDomainBounds(XYDataset dataset) {
639        return findDomainBounds(dataset, true);
640    }
641
642    /**
643     * Returns the range of values in the domain (x-values) of a dataset.
644     *
645     * @param dataset  the dataset ({@code null} not permitted).
646     * @param includeInterval  determines whether or not the x-interval is taken
647     *                         into account (only applies if the dataset is an
648     *                         {@link IntervalXYDataset}).
649     *
650     * @return The range of values (possibly {@code null}).
651     */
652    public static Range findDomainBounds(XYDataset dataset,
653            boolean includeInterval) {
654
655        Args.nullNotPermitted(dataset, "dataset");
656
657        Range result;
658        // if the dataset implements DomainInfo, life is easier
659        if (dataset instanceof DomainInfo) {
660            DomainInfo info = (DomainInfo) dataset;
661            result = info.getDomainBounds(includeInterval);
662        }
663        else {
664            result = iterateDomainBounds(dataset, includeInterval);
665        }
666        return result;
667
668    }
669
670    /**
671     * Returns the bounds of the x-values in the specified {@code dataset}
672     * taking into account only the visible series and including any x-interval
673     * if requested.
674     *
675     * @param dataset  the dataset ({@code null} not permitted).
676     * @param visibleSeriesKeys  the visible series keys ({@code null}
677     *     not permitted).
678     * @param includeInterval  include the x-interval (if any)?
679     *
680     * @return The bounds (or {@code null} if the dataset contains no
681     *     values.
682     *
683     * @since 1.0.13
684     */
685    public static Range findDomainBounds(XYDataset dataset,
686            List visibleSeriesKeys, boolean includeInterval) {
687        
688        Args.nullNotPermitted(dataset, "dataset");
689        Range result;
690        if (dataset instanceof XYDomainInfo) {
691            XYDomainInfo info = (XYDomainInfo) dataset;
692            result = info.getDomainBounds(visibleSeriesKeys, includeInterval);
693        }
694        else {
695            result = iterateToFindDomainBounds(dataset, visibleSeriesKeys,
696                    includeInterval);
697        }
698        return result;
699    }
700
701    /**
702     * Iterates over the items in an {@link XYDataset} to find
703     * the range of x-values.  If the dataset is an instance of
704     * {@link IntervalXYDataset}, the starting and ending x-values
705     * will be used for the bounds calculation.
706     *
707     * @param dataset  the dataset ({@code null} not permitted).
708     *
709     * @return The range (possibly {@code null}).
710     */
711    public static Range iterateDomainBounds(XYDataset dataset) {
712        return iterateDomainBounds(dataset, true);
713    }
714
715    /**
716     * Iterates over the items in an {@link XYDataset} to find
717     * the range of x-values.
718     *
719     * @param dataset  the dataset ({@code null} not permitted).
720     * @param includeInterval  a flag that determines, for an
721     *          {@link IntervalXYDataset}, whether the x-interval or just the
722     *          x-value is used to determine the overall range.
723     *
724     * @return The range (possibly {@code null}).
725     */
726    public static Range iterateDomainBounds(XYDataset dataset,
727            boolean includeInterval) {
728        Args.nullNotPermitted(dataset, "dataset");
729        double minimum = Double.POSITIVE_INFINITY;
730        double maximum = Double.NEGATIVE_INFINITY;
731        int seriesCount = dataset.getSeriesCount();
732        double lvalue, uvalue;
733        if (includeInterval && dataset instanceof IntervalXYDataset) {
734            IntervalXYDataset intervalXYData = (IntervalXYDataset) dataset;
735            for (int series = 0; series < seriesCount; series++) {
736                int itemCount = dataset.getItemCount(series);
737                for (int item = 0; item < itemCount; item++) {
738                    double value = intervalXYData.getXValue(series, item);
739                    lvalue = intervalXYData.getStartXValue(series, item);
740                    uvalue = intervalXYData.getEndXValue(series, item);
741                    if (!Double.isNaN(value)) {
742                        minimum = Math.min(minimum, value);
743                        maximum = Math.max(maximum, value);
744                    }
745                    if (!Double.isNaN(lvalue)) {
746                        minimum = Math.min(minimum, lvalue);
747                        maximum = Math.max(maximum, lvalue);
748                    }
749                    if (!Double.isNaN(uvalue)) {
750                        minimum = Math.min(minimum, uvalue);
751                        maximum = Math.max(maximum, uvalue);
752                    }
753                }
754            }
755        }
756        else {
757            for (int series = 0; series < seriesCount; series++) {
758                int itemCount = dataset.getItemCount(series);
759                for (int item = 0; item < itemCount; item++) {
760                    lvalue = dataset.getXValue(series, item);
761                    uvalue = lvalue;
762                    if (!Double.isNaN(lvalue)) {
763                        minimum = Math.min(minimum, lvalue);
764                        maximum = Math.max(maximum, uvalue);
765                    }
766                }
767            }
768        }
769        if (minimum > maximum) {
770            return null;
771        }
772        else {
773            return new Range(minimum, maximum);
774        }
775    }
776
777    /**
778     * Returns the range of values in the range for the dataset.
779     *
780     * @param dataset  the dataset ({@code null} not permitted).
781     *
782     * @return The range (possibly {@code null}).
783     */
784    public static Range findRangeBounds(CategoryDataset dataset) {
785        return findRangeBounds(dataset, true);
786    }
787
788    /**
789     * Returns the range of values in the range for the dataset.
790     *
791     * @param dataset  the dataset ({@code null} not permitted).
792     * @param includeInterval  a flag that determines whether or not the
793     *                         y-interval is taken into account.
794     *
795     * @return The range (possibly {@code null}).
796     */
797    public static Range findRangeBounds(CategoryDataset dataset,
798            boolean includeInterval) {
799        Args.nullNotPermitted(dataset, "dataset");
800        Range result;
801        if (dataset instanceof RangeInfo) {
802            RangeInfo info = (RangeInfo) dataset;
803            result = info.getRangeBounds(includeInterval);
804        }
805        else {
806            result = iterateRangeBounds(dataset, includeInterval);
807        }
808        return result;
809    }
810
811    /**
812     * Finds the bounds of the y-values in the specified dataset, including
813     * only those series that are listed in visibleSeriesKeys.
814     *
815     * @param dataset  the dataset ({@code null} not permitted).
816     * @param visibleSeriesKeys  the keys for the visible series
817     *     ({@code null} not permitted).
818     * @param includeInterval  include the y-interval (if the dataset has a
819     *     y-interval).
820     *
821     * @return The data bounds.
822     *
823     * @since 1.0.13
824     */
825    public static Range findRangeBounds(CategoryDataset dataset,
826            List visibleSeriesKeys, boolean includeInterval) {
827        Args.nullNotPermitted(dataset, "dataset");
828        Range result;
829        if (dataset instanceof CategoryRangeInfo) {
830            CategoryRangeInfo info = (CategoryRangeInfo) dataset;
831            result = info.getRangeBounds(visibleSeriesKeys, includeInterval);
832        }
833        else {
834            result = iterateToFindRangeBounds(dataset, visibleSeriesKeys,
835                    includeInterval);
836        }
837        return result;
838    }
839
840    /**
841     * Returns the range of values in the range for the dataset.  This method
842     * is the partner for the {@link #findDomainBounds(XYDataset)} method.
843     *
844     * @param dataset  the dataset ({@code null} not permitted).
845     *
846     * @return The range (possibly {@code null}).
847     */
848    public static Range findRangeBounds(XYDataset dataset) {
849        return findRangeBounds(dataset, true);
850    }
851
852    /**
853     * Returns the range of values in the range for the dataset.  This method
854     * is the partner for the {@link #findDomainBounds(XYDataset, boolean)}
855     * method.
856     *
857     * @param dataset  the dataset ({@code null} not permitted).
858     * @param includeInterval  a flag that determines whether or not the
859     *                         y-interval is taken into account.
860     *
861     * @return The range (possibly {@code null}).
862     */
863    public static Range findRangeBounds(XYDataset dataset,
864            boolean includeInterval) {
865        Args.nullNotPermitted(dataset, "dataset");
866        Range result;
867        if (dataset instanceof RangeInfo) {
868            RangeInfo info = (RangeInfo) dataset;
869            result = info.getRangeBounds(includeInterval);
870        }
871        else {
872            result = iterateRangeBounds(dataset, includeInterval);
873        }
874        return result;
875    }
876
877    /**
878     * Finds the bounds of the y-values in the specified dataset, including
879     * only those series that are listed in visibleSeriesKeys, and those items
880     * whose x-values fall within the specified range.
881     *
882     * @param dataset  the dataset ({@code null} not permitted).
883     * @param visibleSeriesKeys  the keys for the visible series
884     *     ({@code null} not permitted).
885     * @param xRange  the x-range ({@code null} not permitted).
886     * @param includeInterval  include the y-interval (if the dataset has a
887     *     y-interval).
888     *
889     * @return The data bounds.
890     * 
891     * @since 1.0.13
892     */
893    public static Range findRangeBounds(XYDataset dataset,
894            List visibleSeriesKeys, Range xRange, boolean includeInterval) {
895        Args.nullNotPermitted(dataset, "dataset");
896        Range result;
897        if (dataset instanceof XYRangeInfo) {
898            XYRangeInfo info = (XYRangeInfo) dataset;
899            result = info.getRangeBounds(visibleSeriesKeys, xRange,
900                    includeInterval);
901        }
902        else {
903            result = iterateToFindRangeBounds(dataset, visibleSeriesKeys,
904                    xRange, includeInterval);
905        }
906        return result;
907    }
908
909    /**
910     * Iterates over the data item of the category dataset to find
911     * the range bounds.
912     *
913     * @param dataset  the dataset ({@code null} not permitted).
914     *
915     * @return The range (possibly {@code null}).
916     *
917     * @since 1.0.10
918     */
919    public static Range iterateRangeBounds(CategoryDataset dataset) {
920        return iterateRangeBounds(dataset, true);
921    }
922
923    /**
924     * Iterates over the data item of the category dataset to find
925     * the range bounds.
926     *
927     * @param dataset  the dataset ({@code null} not permitted).
928     * @param includeInterval  a flag that determines whether or not the
929     *                         y-interval is taken into account.
930     *
931     * @return The range (possibly {@code null}).
932     *
933     * @since 1.0.10
934     */
935    public static Range iterateRangeBounds(CategoryDataset dataset,
936            boolean includeInterval) {
937        double minimum = Double.POSITIVE_INFINITY;
938        double maximum = Double.NEGATIVE_INFINITY;
939        int rowCount = dataset.getRowCount();
940        int columnCount = dataset.getColumnCount();
941        if (includeInterval && dataset instanceof IntervalCategoryDataset) {
942            // handle the special case where the dataset has y-intervals that
943            // we want to measure
944            IntervalCategoryDataset icd = (IntervalCategoryDataset) dataset;
945            Number value, lvalue, uvalue;
946            for (int row = 0; row < rowCount; row++) {
947                for (int column = 0; column < columnCount; column++) {
948                    value = icd.getValue(row, column);
949                    double v;
950                    if ((value != null)
951                            && !Double.isNaN(v = value.doubleValue())) {
952                        minimum = Math.min(v, minimum);
953                        maximum = Math.max(v, maximum);
954                    }
955                    lvalue = icd.getStartValue(row, column);
956                    if (lvalue != null
957                            && !Double.isNaN(v = lvalue.doubleValue())) {
958                        minimum = Math.min(v, minimum);
959                        maximum = Math.max(v, maximum);
960                    }
961                    uvalue = icd.getEndValue(row, column);
962                    if (uvalue != null
963                            && !Double.isNaN(v = uvalue.doubleValue())) {
964                        minimum = Math.min(v, minimum);
965                        maximum = Math.max(v, maximum);
966                    }
967                }
968            }
969        }
970        else {
971            // handle the standard case (plain CategoryDataset)
972            for (int row = 0; row < rowCount; row++) {
973                for (int column = 0; column < columnCount; column++) {
974                    Number value = dataset.getValue(row, column);
975                    if (value != null) {
976                        double v = value.doubleValue();
977                        if (!Double.isNaN(v)) {
978                            minimum = Math.min(minimum, v);
979                            maximum = Math.max(maximum, v);
980                        }
981                    }
982                }
983            }
984        }
985        if (minimum == Double.POSITIVE_INFINITY) {
986            return null;
987        }
988        else {
989            return new Range(minimum, maximum);
990        }
991    }
992
993    /**
994     * Iterates over the data item of the category dataset to find
995     * the range bounds.
996     *
997     * @param dataset  the dataset ({@code null} not permitted).
998     * @param includeInterval  a flag that determines whether or not the
999     *                         y-interval is taken into account.
1000     * @param visibleSeriesKeys  the visible series keys.
1001     *
1002     * @return The range (possibly {@code null}).
1003     *
1004     * @since 1.0.13
1005     */
1006    public static Range iterateToFindRangeBounds(CategoryDataset dataset,
1007            List visibleSeriesKeys, boolean includeInterval) {
1008
1009        Args.nullNotPermitted(dataset, "dataset");
1010        Args.nullNotPermitted(visibleSeriesKeys, "visibleSeriesKeys");
1011
1012        double minimum = Double.POSITIVE_INFINITY;
1013        double maximum = Double.NEGATIVE_INFINITY;
1014        int columnCount = dataset.getColumnCount();
1015        if (includeInterval
1016                && dataset instanceof BoxAndWhiskerCategoryDataset) {
1017            // handle special case of BoxAndWhiskerDataset
1018            BoxAndWhiskerCategoryDataset bx
1019                    = (BoxAndWhiskerCategoryDataset) dataset;
1020            Iterator iterator = visibleSeriesKeys.iterator();
1021            while (iterator.hasNext()) {
1022                Comparable seriesKey = (Comparable) iterator.next();
1023                int series = dataset.getRowIndex(seriesKey);
1024                int itemCount = dataset.getColumnCount();
1025                for (int item = 0; item < itemCount; item++) {
1026                    Number lvalue = bx.getMinRegularValue(series, item);
1027                    if (lvalue == null) {
1028                        lvalue = bx.getValue(series, item);
1029                    }
1030                    Number uvalue = bx.getMaxRegularValue(series, item);
1031                    if (uvalue == null) {
1032                        uvalue = bx.getValue(series, item);
1033                    }
1034                    if (lvalue != null) {
1035                        minimum = Math.min(minimum, lvalue.doubleValue());
1036                    }
1037                    if (uvalue != null) {
1038                        maximum = Math.max(maximum, uvalue.doubleValue());
1039                    }
1040                }
1041            }
1042        }
1043        else if (includeInterval
1044                && dataset instanceof IntervalCategoryDataset) {
1045            // handle the special case where the dataset has y-intervals that
1046            // we want to measure
1047            IntervalCategoryDataset icd = (IntervalCategoryDataset) dataset;
1048            Number lvalue, uvalue;
1049            Iterator iterator = visibleSeriesKeys.iterator();
1050            while (iterator.hasNext()) {
1051                Comparable seriesKey = (Comparable) iterator.next();
1052                int series = dataset.getRowIndex(seriesKey);
1053                for (int column = 0; column < columnCount; column++) {
1054                    lvalue = icd.getStartValue(series, column);
1055                    uvalue = icd.getEndValue(series, column);
1056                    if (lvalue != null && !Double.isNaN(lvalue.doubleValue())) {
1057                        minimum = Math.min(minimum, lvalue.doubleValue());
1058                    }
1059                    if (uvalue != null && !Double.isNaN(uvalue.doubleValue())) {
1060                        maximum = Math.max(maximum, uvalue.doubleValue());
1061                    }
1062                }
1063            }
1064        }
1065        else if (includeInterval
1066                && dataset instanceof MultiValueCategoryDataset) {
1067            // handle the special case where the dataset has y-intervals that
1068            // we want to measure
1069            MultiValueCategoryDataset mvcd
1070                    = (MultiValueCategoryDataset) dataset;
1071            Iterator iterator = visibleSeriesKeys.iterator();
1072            while (iterator.hasNext()) {
1073                Comparable seriesKey = (Comparable) iterator.next();
1074                int series = dataset.getRowIndex(seriesKey);
1075                for (int column = 0; column < columnCount; column++) {
1076                    List values = mvcd.getValues(series, column);
1077                    Iterator valueIterator = values.iterator();
1078                    while (valueIterator.hasNext()) {
1079                        Object o = valueIterator.next();
1080                        if (o instanceof Number){
1081                            double v = ((Number) o).doubleValue();
1082                            if (!Double.isNaN(v)){
1083                                minimum = Math.min(minimum, v);
1084                                maximum = Math.max(maximum, v);
1085                            }
1086                        }
1087                    }
1088               }
1089            }
1090        }
1091        else if (includeInterval 
1092                && dataset instanceof StatisticalCategoryDataset) {
1093            // handle the special case where the dataset has y-intervals that
1094            // we want to measure
1095            StatisticalCategoryDataset scd
1096                    = (StatisticalCategoryDataset) dataset;
1097            Iterator iterator = visibleSeriesKeys.iterator();
1098            while (iterator.hasNext()) {
1099                Comparable seriesKey = (Comparable) iterator.next();
1100                int series = dataset.getRowIndex(seriesKey);
1101                for (int column = 0; column < columnCount; column++) {
1102                    Number meanN = scd.getMeanValue(series, column);
1103                    if (meanN != null) {
1104                        double std = 0.0;
1105                        Number stdN = scd.getStdDevValue(series, column);
1106                        if (stdN != null) {
1107                            std = stdN.doubleValue();
1108                            if (Double.isNaN(std)) {
1109                                std = 0.0;
1110                            }
1111                        }
1112                        double mean = meanN.doubleValue();
1113                        if (!Double.isNaN(mean)) {
1114                            minimum = Math.min(minimum, mean - std);
1115                            maximum = Math.max(maximum, mean + std);
1116                        }
1117                    }
1118                }
1119            }
1120        }
1121        else {
1122            // handle the standard case (plain CategoryDataset)
1123            Iterator iterator = visibleSeriesKeys.iterator();
1124            while (iterator.hasNext()) {
1125                Comparable seriesKey = (Comparable) iterator.next();
1126                int series = dataset.getRowIndex(seriesKey);
1127                for (int column = 0; column < columnCount; column++) {
1128                    Number value = dataset.getValue(series, column);
1129                    if (value != null) {
1130                        double v = value.doubleValue();
1131                        if (!Double.isNaN(v)) {
1132                            minimum = Math.min(minimum, v);
1133                            maximum = Math.max(maximum, v);
1134                        }
1135                    }
1136                }
1137            }
1138        }
1139        if (minimum == Double.POSITIVE_INFINITY) {
1140            return null;
1141        }
1142        else {
1143            return new Range(minimum, maximum);
1144        }
1145    }
1146
1147    /**
1148     * Iterates over the data item of the xy dataset to find
1149     * the range bounds.
1150     *
1151     * @param dataset  the dataset ({@code null} not permitted).
1152     *
1153     * @return The range (possibly {@code null}).
1154     *
1155     * @since 1.0.10
1156     */
1157    public static Range iterateRangeBounds(XYDataset dataset) {
1158        return iterateRangeBounds(dataset, true);
1159    }
1160
1161    /**
1162     * Iterates over the data items of the xy dataset to find
1163     * the range bounds.
1164     *
1165     * @param dataset  the dataset ({@code null} not permitted).
1166     * @param includeInterval  a flag that determines, for an
1167     *          {@link IntervalXYDataset}, whether the y-interval or just the
1168     *          y-value is used to determine the overall range.
1169     *
1170     * @return The range (possibly {@code null}).
1171     *
1172     * @since 1.0.10
1173     */
1174    public static Range iterateRangeBounds(XYDataset dataset,
1175            boolean includeInterval) {
1176        double minimum = Double.POSITIVE_INFINITY;
1177        double maximum = Double.NEGATIVE_INFINITY;
1178        int seriesCount = dataset.getSeriesCount();
1179
1180        // handle three cases by dataset type
1181        if (includeInterval && dataset instanceof IntervalXYDataset) {
1182            // handle special case of IntervalXYDataset
1183            IntervalXYDataset ixyd = (IntervalXYDataset) dataset;
1184            for (int series = 0; series < seriesCount; series++) {
1185                int itemCount = dataset.getItemCount(series);
1186                for (int item = 0; item < itemCount; item++) {
1187                    double value = ixyd.getYValue(series, item);
1188                    double lvalue = ixyd.getStartYValue(series, item);
1189                    double uvalue = ixyd.getEndYValue(series, item);
1190                    if (!Double.isNaN(value)) {
1191                        minimum = Math.min(minimum, value);
1192                        maximum = Math.max(maximum, value);
1193                    }
1194                    if (!Double.isNaN(lvalue)) {
1195                        minimum = Math.min(minimum, lvalue);
1196                        maximum = Math.max(maximum, lvalue);
1197                    }
1198                    if (!Double.isNaN(uvalue)) {
1199                        minimum = Math.min(minimum, uvalue);
1200                        maximum = Math.max(maximum, uvalue);
1201                    }
1202                }
1203            }
1204        }
1205        else if (includeInterval && dataset instanceof OHLCDataset) {
1206            // handle special case of OHLCDataset
1207            OHLCDataset ohlc = (OHLCDataset) dataset;
1208            for (int series = 0; series < seriesCount; series++) {
1209                int itemCount = dataset.getItemCount(series);
1210                for (int item = 0; item < itemCount; item++) {
1211                    double lvalue = ohlc.getLowValue(series, item);
1212                    double uvalue = ohlc.getHighValue(series, item);
1213                    if (!Double.isNaN(lvalue)) {
1214                        minimum = Math.min(minimum, lvalue);
1215                    }
1216                    if (!Double.isNaN(uvalue)) {
1217                        maximum = Math.max(maximum, uvalue);
1218                    }
1219                }
1220            }
1221        }
1222        else {
1223            // standard case - plain XYDataset
1224            for (int series = 0; series < seriesCount; series++) {
1225                int itemCount = dataset.getItemCount(series);
1226                for (int item = 0; item < itemCount; item++) {
1227                    double value = dataset.getYValue(series, item);
1228                    if (!Double.isNaN(value)) {
1229                        minimum = Math.min(minimum, value);
1230                        maximum = Math.max(maximum, value);
1231                    }
1232                }
1233            }
1234        }
1235        if (minimum == Double.POSITIVE_INFINITY) {
1236            return null;
1237        }
1238        else {
1239            return new Range(minimum, maximum);
1240        }
1241    }
1242
1243    /**
1244     * Returns the range of values in the z-dimension for the dataset. This
1245     * method is the partner for the {@link #findRangeBounds(XYDataset)}
1246     * and {@link #findDomainBounds(XYDataset)} methods.
1247     *
1248     * @param dataset  the dataset ({@code null} not permitted).
1249     *
1250     * @return The range (possibly {@code null}).
1251     */
1252    public static Range findZBounds(XYZDataset dataset) {
1253        return findZBounds(dataset, true);
1254    }
1255
1256    /**
1257     * Returns the range of values in the z-dimension for the dataset.  This
1258     * method is the partner for the
1259     * {@link #findRangeBounds(XYDataset, boolean)} and
1260     * {@link #findDomainBounds(XYDataset, boolean)} methods.
1261     *
1262     * @param dataset  the dataset ({@code null} not permitted).
1263     * @param includeInterval  a flag that determines whether or not the
1264     *                         z-interval is taken into account.
1265     *
1266     * @return The range (possibly {@code null}).
1267     */
1268    public static Range findZBounds(XYZDataset dataset,
1269            boolean includeInterval) {
1270        Args.nullNotPermitted(dataset, "dataset");
1271        Range result = iterateZBounds(dataset, includeInterval);
1272        return result;
1273    }
1274
1275    /**
1276     * Finds the bounds of the z-values in the specified dataset, including
1277     * only those series that are listed in visibleSeriesKeys, and those items
1278     * whose x-values fall within the specified range.
1279     *
1280     * @param dataset  the dataset ({@code null} not permitted).
1281     * @param visibleSeriesKeys  the keys for the visible series
1282     *     ({@code null} not permitted).
1283     * @param xRange  the x-range ({@code null} not permitted).
1284     * @param includeInterval  include the z-interval (if the dataset has a
1285     *     z-interval).
1286     *
1287     * @return The data bounds.
1288     */
1289    public static Range findZBounds(XYZDataset dataset,
1290            List visibleSeriesKeys, Range xRange, boolean includeInterval) {
1291        Args.nullNotPermitted(dataset, "dataset");
1292        Range result = iterateToFindZBounds(dataset, visibleSeriesKeys,
1293                    xRange, includeInterval);
1294        return result;
1295    }
1296
1297    /**
1298     * Iterates over the data item of the xyz dataset to find
1299     * the z-dimension bounds.
1300     *
1301     * @param dataset  the dataset ({@code null} not permitted).
1302     *
1303     * @return The range (possibly {@code null}).
1304     */
1305    public static Range iterateZBounds(XYZDataset dataset) {
1306        return iterateZBounds(dataset, true);
1307    }
1308
1309    /**
1310     * Iterates over the data items of the xyz dataset to find
1311     * the z-dimension bounds.
1312     *
1313     * @param dataset  the dataset ({@code null} not permitted).
1314     * @param includeInterval  include the z-interval (if the dataset has a
1315     *     z-interval.
1316     *
1317     * @return The range (possibly {@code null}).
1318     */
1319    public static Range iterateZBounds(XYZDataset dataset,
1320            boolean includeInterval) {
1321        double minimum = Double.POSITIVE_INFINITY;
1322        double maximum = Double.NEGATIVE_INFINITY;
1323        int seriesCount = dataset.getSeriesCount();
1324
1325        for (int series = 0; series < seriesCount; series++) {
1326            int itemCount = dataset.getItemCount(series);
1327            for (int item = 0; item < itemCount; item++) {
1328                double value = dataset.getZValue(series, item);
1329                if (!Double.isNaN(value)) {
1330                    minimum = Math.min(minimum, value);
1331                    maximum = Math.max(maximum, value);
1332                }
1333            }
1334        }
1335
1336        if (minimum == Double.POSITIVE_INFINITY) {
1337            return null;
1338        }
1339        else {
1340            return new Range(minimum, maximum);
1341        }
1342    }
1343
1344    /**
1345     * Returns the range of x-values in the specified dataset for the
1346     * data items belonging to the visible series.
1347     * 
1348     * @param dataset  the dataset ({@code null} not permitted).
1349     * @param visibleSeriesKeys  the visible series keys ({@code null} not
1350     *     permitted).
1351     * @param includeInterval  a flag that determines whether or not the
1352     *     y-interval for the dataset is included (this only applies if the
1353     *     dataset is an instance of IntervalXYDataset).
1354     * 
1355     * @return The x-range (possibly {@code null}).
1356     * 
1357     * @since 1.0.13
1358     */
1359    public static Range iterateToFindDomainBounds(XYDataset dataset,
1360            List visibleSeriesKeys, boolean includeInterval) {
1361        Args.nullNotPermitted(dataset, "dataset");
1362        Args.nullNotPermitted(visibleSeriesKeys, "visibleSeriesKeys");
1363
1364        double minimum = Double.POSITIVE_INFINITY;
1365        double maximum = Double.NEGATIVE_INFINITY;
1366
1367        if (includeInterval && dataset instanceof IntervalXYDataset) {
1368            // handle special case of IntervalXYDataset
1369            IntervalXYDataset ixyd = (IntervalXYDataset) dataset;
1370            Iterator iterator = visibleSeriesKeys.iterator();
1371            while (iterator.hasNext()) {
1372                Comparable seriesKey = (Comparable) iterator.next();
1373                int series = dataset.indexOf(seriesKey);
1374                int itemCount = dataset.getItemCount(series);
1375                for (int item = 0; item < itemCount; item++) {
1376                    double xvalue = ixyd.getXValue(series, item);
1377                    double lvalue = ixyd.getStartXValue(series, item);
1378                    double uvalue = ixyd.getEndXValue(series, item);
1379                    if (!Double.isNaN(xvalue)) {
1380                        minimum = Math.min(minimum, xvalue);
1381                        maximum = Math.max(maximum, xvalue);
1382                    }
1383                    if (!Double.isNaN(lvalue)) {
1384                        minimum = Math.min(minimum, lvalue);
1385                    }
1386                    if (!Double.isNaN(uvalue)) {
1387                        maximum = Math.max(maximum, uvalue);
1388                    }
1389                }
1390            }
1391        } else {
1392            // standard case - plain XYDataset
1393            Iterator iterator = visibleSeriesKeys.iterator();
1394            while (iterator.hasNext()) {
1395                Comparable seriesKey = (Comparable) iterator.next();
1396                int series = dataset.indexOf(seriesKey);
1397                int itemCount = dataset.getItemCount(series);
1398                for (int item = 0; item < itemCount; item++) {
1399                    double x = dataset.getXValue(series, item);
1400                    if (!Double.isNaN(x)) {
1401                        minimum = Math.min(minimum, x);
1402                        maximum = Math.max(maximum, x);
1403                    }
1404                }
1405            }
1406        }
1407
1408        if (minimum == Double.POSITIVE_INFINITY) {
1409            return null;
1410        } else {
1411            return new Range(minimum, maximum);
1412        }
1413    }
1414
1415    /**
1416     * Returns the range of y-values in the specified dataset for the
1417     * data items belonging to the visible series and with x-values in the
1418     * given range.
1419     *
1420     * @param dataset  the dataset ({@code null} not permitted).
1421     * @param visibleSeriesKeys  the visible series keys ({@code null} not
1422     *     permitted).
1423     * @param xRange  the x-range ({@code null} not permitted).
1424     * @param includeInterval  a flag that determines whether or not the
1425     *     y-interval for the dataset is included (this only applies if the
1426     *     dataset is an instance of IntervalXYDataset).
1427     *
1428     * @return The y-range (possibly {@code null}).
1429     *
1430     * @since 1.0.13
1431     */
1432    public static Range iterateToFindRangeBounds(XYDataset dataset,
1433            List visibleSeriesKeys, Range xRange, boolean includeInterval) {
1434
1435        Args.nullNotPermitted(dataset, "dataset");
1436        Args.nullNotPermitted(visibleSeriesKeys, "visibleSeriesKeys");
1437        Args.nullNotPermitted(xRange, "xRange");
1438
1439        double minimum = Double.POSITIVE_INFINITY;
1440        double maximum = Double.NEGATIVE_INFINITY;
1441
1442        // handle three cases by dataset type
1443        if (includeInterval && dataset instanceof OHLCDataset) {
1444            // handle special case of OHLCDataset
1445            OHLCDataset ohlc = (OHLCDataset) dataset;
1446            Iterator iterator = visibleSeriesKeys.iterator();
1447            while (iterator.hasNext()) {
1448                Comparable seriesKey = (Comparable) iterator.next();
1449                int series = dataset.indexOf(seriesKey);
1450                int itemCount = dataset.getItemCount(series);
1451                for (int item = 0; item < itemCount; item++) {
1452                    double x = ohlc.getXValue(series, item);
1453                    if (xRange.contains(x)) {
1454                        double lvalue = ohlc.getLowValue(series, item);
1455                        double uvalue = ohlc.getHighValue(series, item);
1456                        if (!Double.isNaN(lvalue)) {
1457                            minimum = Math.min(minimum, lvalue);
1458                        }
1459                        if (!Double.isNaN(uvalue)) {
1460                            maximum = Math.max(maximum, uvalue);
1461                        }
1462                    }
1463                }
1464            }
1465        }
1466        else if (includeInterval && dataset instanceof BoxAndWhiskerXYDataset) {
1467            // handle special case of BoxAndWhiskerXYDataset
1468            BoxAndWhiskerXYDataset bx = (BoxAndWhiskerXYDataset) dataset;
1469            Iterator iterator = visibleSeriesKeys.iterator();
1470            while (iterator.hasNext()) {
1471                Comparable seriesKey = (Comparable) iterator.next();
1472                int series = dataset.indexOf(seriesKey);
1473                int itemCount = dataset.getItemCount(series);
1474                for (int item = 0; item < itemCount; item++) {
1475                    double x = bx.getXValue(series, item);
1476                    if (xRange.contains(x)) {
1477                        Number lvalue = bx.getMinRegularValue(series, item);
1478                        Number uvalue = bx.getMaxRegularValue(series, item);
1479                        if (lvalue != null) {
1480                            minimum = Math.min(minimum, lvalue.doubleValue());
1481                        }
1482                        if (uvalue != null) {
1483                            maximum = Math.max(maximum, uvalue.doubleValue());
1484                        }
1485                    }
1486                }
1487            }
1488        }
1489        else if (includeInterval && dataset instanceof IntervalXYDataset) {
1490            // handle special case of IntervalXYDataset
1491            IntervalXYDataset ixyd = (IntervalXYDataset) dataset;
1492            Iterator iterator = visibleSeriesKeys.iterator();
1493            while (iterator.hasNext()) {
1494                Comparable seriesKey = (Comparable) iterator.next();
1495                int series = dataset.indexOf(seriesKey);
1496                int itemCount = dataset.getItemCount(series);
1497                for (int item = 0; item < itemCount; item++) {
1498                    double x = ixyd.getXValue(series, item);
1499                    if (xRange.contains(x)) {
1500                        double yvalue = ixyd.getYValue(series, item);
1501                        double lvalue = ixyd.getStartYValue(series, item);
1502                        double uvalue = ixyd.getEndYValue(series, item);
1503                        if (!Double.isNaN(yvalue)) {
1504                            minimum = Math.min(minimum, yvalue);
1505                            maximum = Math.max(maximum, yvalue);
1506                        }
1507                        if (!Double.isNaN(lvalue)) {
1508                            minimum = Math.min(minimum, lvalue);
1509                        }
1510                        if (!Double.isNaN(uvalue)) {
1511                            maximum = Math.max(maximum, uvalue);
1512                        }
1513                    }
1514                }
1515            }
1516        } else {
1517            // standard case - plain XYDataset
1518            Iterator iterator = visibleSeriesKeys.iterator();
1519            while (iterator.hasNext()) {
1520                Comparable seriesKey = (Comparable) iterator.next();
1521                int series = dataset.indexOf(seriesKey);
1522                int itemCount = dataset.getItemCount(series);
1523                for (int item = 0; item < itemCount; item++) {
1524                    double x = dataset.getXValue(series, item);
1525                    double y = dataset.getYValue(series, item);
1526                    if (xRange.contains(x)) {
1527                        if (!Double.isNaN(y)) {
1528                            minimum = Math.min(minimum, y);
1529                            maximum = Math.max(maximum, y);
1530                        }
1531                    }
1532                }
1533            }
1534        }
1535        if (minimum == Double.POSITIVE_INFINITY) {
1536            return null;
1537        } else {
1538            return new Range(minimum, maximum);
1539        }
1540    }
1541
1542    /**
1543     * Returns the range of z-values in the specified dataset for the
1544     * data items belonging to the visible series and with x-values in the
1545     * given range.
1546     *
1547     * @param dataset  the dataset ({@code null} not permitted).
1548     * @param visibleSeriesKeys  the visible series keys ({@code null} not
1549     *     permitted).
1550     * @param xRange  the x-range ({@code null} not permitted).
1551     * @param includeInterval  a flag that determines whether or not the
1552     *     z-interval for the dataset is included (this only applies if the
1553     *     dataset has an interval, which is currently not supported).
1554     *
1555     * @return The y-range (possibly {@code null}).
1556     */
1557    public static Range iterateToFindZBounds(XYZDataset dataset,
1558            List visibleSeriesKeys, Range xRange, boolean includeInterval) {
1559        Args.nullNotPermitted(dataset, "dataset");
1560        Args.nullNotPermitted(visibleSeriesKeys, "visibleSeriesKeys");
1561        Args.nullNotPermitted(xRange, "xRange");
1562    
1563        double minimum = Double.POSITIVE_INFINITY;
1564        double maximum = Double.NEGATIVE_INFINITY;
1565    
1566        Iterator iterator = visibleSeriesKeys.iterator();
1567        while (iterator.hasNext()) {
1568            Comparable seriesKey = (Comparable) iterator.next();
1569            int series = dataset.indexOf(seriesKey);
1570            int itemCount = dataset.getItemCount(series);
1571            for (int item = 0; item < itemCount; item++) {
1572                double x = dataset.getXValue(series, item);
1573                double z = dataset.getZValue(series, item);
1574                if (xRange.contains(x)) {
1575                    if (!Double.isNaN(z)) {
1576                        minimum = Math.min(minimum, z);
1577                        maximum = Math.max(maximum, z);
1578                    }
1579                }
1580            }
1581        }
1582
1583        if (minimum == Double.POSITIVE_INFINITY) {
1584            return null;
1585        } else {
1586            return new Range(minimum, maximum);
1587        }
1588    }
1589
1590    /**
1591     * Finds the minimum domain (or X) value for the specified dataset.  This
1592     * is easy if the dataset implements the {@link DomainInfo} interface (a
1593     * good idea if there is an efficient way to determine the minimum value).
1594     * Otherwise, it involves iterating over the entire data-set.
1595     * <p>
1596     * Returns {@code null} if all the data values in the dataset are
1597     * {@code null}.
1598     *
1599     * @param dataset  the dataset ({@code null} not permitted).
1600     *
1601     * @return The minimum value (possibly {@code null}).
1602     */
1603    public static Number findMinimumDomainValue(XYDataset dataset) {
1604        Args.nullNotPermitted(dataset, "dataset");
1605        Number result;
1606        // if the dataset implements DomainInfo, life is easy
1607        if (dataset instanceof DomainInfo) {
1608            DomainInfo info = (DomainInfo) dataset;
1609            return info.getDomainLowerBound(true);
1610        }
1611        else {
1612            double minimum = Double.POSITIVE_INFINITY;
1613            int seriesCount = dataset.getSeriesCount();
1614            for (int series = 0; series < seriesCount; series++) {
1615                int itemCount = dataset.getItemCount(series);
1616                for (int item = 0; item < itemCount; item++) {
1617
1618                    double value;
1619                    if (dataset instanceof IntervalXYDataset) {
1620                        IntervalXYDataset intervalXYData
1621                            = (IntervalXYDataset) dataset;
1622                        value = intervalXYData.getStartXValue(series, item);
1623                    }
1624                    else {
1625                        value = dataset.getXValue(series, item);
1626                    }
1627                    if (!Double.isNaN(value)) {
1628                        minimum = Math.min(minimum, value);
1629                    }
1630
1631                }
1632            }
1633            if (minimum == Double.POSITIVE_INFINITY) {
1634                result = null;
1635            }
1636            else {
1637                result = minimum;
1638            }
1639        }
1640        return result;
1641    }
1642
1643    /**
1644     * Returns the maximum domain value for the specified dataset.  This is
1645     * easy if the dataset implements the {@link DomainInfo} interface (a good
1646     * idea if there is an efficient way to determine the maximum value).
1647     * Otherwise, it involves iterating over the entire data-set.  Returns
1648     * {@code null} if all the data values in the dataset are
1649     * {@code null}.
1650     *
1651     * @param dataset  the dataset ({@code null} not permitted).
1652     *
1653     * @return The maximum value (possibly {@code null}).
1654     */
1655    public static Number findMaximumDomainValue(XYDataset dataset) {
1656        Args.nullNotPermitted(dataset, "dataset");
1657        Number result;
1658        // if the dataset implements DomainInfo, life is easy
1659        if (dataset instanceof DomainInfo) {
1660            DomainInfo info = (DomainInfo) dataset;
1661            return info.getDomainUpperBound(true);
1662        }
1663
1664        // hasn't implemented DomainInfo, so iterate...
1665        else {
1666            double maximum = Double.NEGATIVE_INFINITY;
1667            int seriesCount = dataset.getSeriesCount();
1668            for (int series = 0; series < seriesCount; series++) {
1669                int itemCount = dataset.getItemCount(series);
1670                for (int item = 0; item < itemCount; item++) {
1671
1672                    double value;
1673                    if (dataset instanceof IntervalXYDataset) {
1674                        IntervalXYDataset intervalXYData
1675                            = (IntervalXYDataset) dataset;
1676                        value = intervalXYData.getEndXValue(series, item);
1677                    }
1678                    else {
1679                        value = dataset.getXValue(series, item);
1680                    }
1681                    if (!Double.isNaN(value)) {
1682                        maximum = Math.max(maximum, value);
1683                    }
1684                }
1685            }
1686            if (maximum == Double.NEGATIVE_INFINITY) {
1687                result = null;
1688            }
1689            else {
1690                result = maximum;
1691            }
1692
1693        }
1694
1695        return result;
1696    }
1697
1698    /**
1699     * Returns the minimum range value for the specified dataset.  This is
1700     * easy if the dataset implements the {@link RangeInfo} interface (a good
1701     * idea if there is an efficient way to determine the minimum value).
1702     * Otherwise, it involves iterating over the entire data-set.  Returns
1703     * {@code null} if all the data values in the dataset are
1704     * {@code null}.
1705     *
1706     * @param dataset  the dataset ({@code null} not permitted).
1707     *
1708     * @return The minimum value (possibly {@code null}).
1709     */
1710    public static Number findMinimumRangeValue(CategoryDataset dataset) {
1711        Args.nullNotPermitted(dataset, "dataset");
1712        if (dataset instanceof RangeInfo) {
1713            RangeInfo info = (RangeInfo) dataset;
1714            return info.getRangeLowerBound(true);
1715        }
1716
1717        // hasn't implemented RangeInfo, so we'll have to iterate...
1718        else {
1719            double minimum = Double.POSITIVE_INFINITY;
1720            int seriesCount = dataset.getRowCount();
1721            int itemCount = dataset.getColumnCount();
1722            for (int series = 0; series < seriesCount; series++) {
1723                for (int item = 0; item < itemCount; item++) {
1724                    Number value;
1725                    if (dataset instanceof IntervalCategoryDataset) {
1726                        IntervalCategoryDataset icd
1727                                = (IntervalCategoryDataset) dataset;
1728                        value = icd.getStartValue(series, item);
1729                    }
1730                    else {
1731                        value = dataset.getValue(series, item);
1732                    }
1733                    if (value != null) {
1734                        minimum = Math.min(minimum, value.doubleValue());
1735                    }
1736                }
1737            }
1738            if (minimum == Double.POSITIVE_INFINITY) {
1739                return null;
1740            }
1741            else {
1742                return minimum;
1743            }
1744
1745        }
1746
1747    }
1748
1749    /**
1750     * Returns the minimum range value for the specified dataset.  This is
1751     * easy if the dataset implements the {@link RangeInfo} interface (a good
1752     * idea if there is an efficient way to determine the minimum value).
1753     * Otherwise, it involves iterating over the entire data-set.  Returns
1754     * {@code null} if all the data values in the dataset are
1755     * {@code null}.
1756     *
1757     * @param dataset  the dataset ({@code null} not permitted).
1758     *
1759     * @return The minimum value (possibly {@code null}).
1760     */
1761    public static Number findMinimumRangeValue(XYDataset dataset) {
1762        Args.nullNotPermitted(dataset, "dataset");
1763
1764        // work out the minimum value...
1765        if (dataset instanceof RangeInfo) {
1766            RangeInfo info = (RangeInfo) dataset;
1767            return info.getRangeLowerBound(true);
1768        }
1769
1770        // hasn't implemented RangeInfo, so we'll have to iterate...
1771        else {
1772            double minimum = Double.POSITIVE_INFINITY;
1773            int seriesCount = dataset.getSeriesCount();
1774            for (int series = 0; series < seriesCount; series++) {
1775                int itemCount = dataset.getItemCount(series);
1776                for (int item = 0; item < itemCount; item++) {
1777
1778                    double value;
1779                    if (dataset instanceof IntervalXYDataset) {
1780                        IntervalXYDataset intervalXYData
1781                                = (IntervalXYDataset) dataset;
1782                        value = intervalXYData.getStartYValue(series, item);
1783                    }
1784                    else if (dataset instanceof OHLCDataset) {
1785                        OHLCDataset highLowData = (OHLCDataset) dataset;
1786                        value = highLowData.getLowValue(series, item);
1787                    }
1788                    else {
1789                        value = dataset.getYValue(series, item);
1790                    }
1791                    if (!Double.isNaN(value)) {
1792                        minimum = Math.min(minimum, value);
1793                    }
1794
1795                }
1796            }
1797            if (minimum == Double.POSITIVE_INFINITY) {
1798                return null;
1799            }
1800            else {
1801                return minimum;
1802            }
1803
1804        }
1805
1806    }
1807
1808    /**
1809     * Returns the maximum range value for the specified dataset.  This is easy
1810     * if the dataset implements the {@link RangeInfo} interface (a good idea
1811     * if there is an efficient way to determine the maximum value).
1812     * Otherwise, it involves iterating over the entire data-set.  Returns
1813     * {@code null} if all the data values are {@code null}.
1814     *
1815     * @param dataset  the dataset ({@code null} not permitted).
1816     *
1817     * @return The maximum value (possibly {@code null}).
1818     */
1819    public static Number findMaximumRangeValue(CategoryDataset dataset) {
1820
1821        Args.nullNotPermitted(dataset, "dataset");
1822
1823        // work out the minimum value...
1824        if (dataset instanceof RangeInfo) {
1825            RangeInfo info = (RangeInfo) dataset;
1826            return info.getRangeUpperBound(true);
1827        }
1828
1829        // hasn't implemented RangeInfo, so we'll have to iterate...
1830        else {
1831
1832            double maximum = Double.NEGATIVE_INFINITY;
1833            int seriesCount = dataset.getRowCount();
1834            int itemCount = dataset.getColumnCount();
1835            for (int series = 0; series < seriesCount; series++) {
1836                for (int item = 0; item < itemCount; item++) {
1837                    Number value;
1838                    if (dataset instanceof IntervalCategoryDataset) {
1839                        IntervalCategoryDataset icd
1840                            = (IntervalCategoryDataset) dataset;
1841                        value = icd.getEndValue(series, item);
1842                    }
1843                    else {
1844                        value = dataset.getValue(series, item);
1845                    }
1846                    if (value != null) {
1847                        maximum = Math.max(maximum, value.doubleValue());
1848                    }
1849                }
1850            }
1851            if (maximum == Double.NEGATIVE_INFINITY) {
1852                return null;
1853            }
1854            else {
1855                return maximum;
1856            }
1857
1858        }
1859
1860    }
1861
1862    /**
1863     * Returns the maximum range value for the specified dataset.  This is
1864     * easy if the dataset implements the {@link RangeInfo} interface (a good
1865     * idea if there is an efficient way to determine the maximum value).
1866     * Otherwise, it involves iterating over the entire data-set.  Returns
1867     * {@code null} if all the data values are {@code null}.
1868     *
1869     * @param dataset  the dataset ({@code null} not permitted).
1870     *
1871     * @return The maximum value (possibly {@code null}).
1872     */
1873    public static Number findMaximumRangeValue(XYDataset dataset) {
1874
1875        Args.nullNotPermitted(dataset, "dataset");
1876
1877        // work out the minimum value...
1878        if (dataset instanceof RangeInfo) {
1879            RangeInfo info = (RangeInfo) dataset;
1880            return info.getRangeUpperBound(true);
1881        }
1882
1883        // hasn't implemented RangeInfo, so we'll have to iterate...
1884        else  {
1885
1886            double maximum = Double.NEGATIVE_INFINITY;
1887            int seriesCount = dataset.getSeriesCount();
1888            for (int series = 0; series < seriesCount; series++) {
1889                int itemCount = dataset.getItemCount(series);
1890                for (int item = 0; item < itemCount; item++) {
1891                    double value;
1892                    if (dataset instanceof IntervalXYDataset) {
1893                        IntervalXYDataset intervalXYData
1894                                = (IntervalXYDataset) dataset;
1895                        value = intervalXYData.getEndYValue(series, item);
1896                    }
1897                    else if (dataset instanceof OHLCDataset) {
1898                        OHLCDataset highLowData = (OHLCDataset) dataset;
1899                        value = highLowData.getHighValue(series, item);
1900                    }
1901                    else {
1902                        value = dataset.getYValue(series, item);
1903                    }
1904                    if (!Double.isNaN(value)) {
1905                        maximum = Math.max(maximum, value);
1906                    }
1907                }
1908            }
1909            if (maximum == Double.NEGATIVE_INFINITY) {
1910                return null;
1911            }
1912            else {
1913                return maximum;
1914            }
1915
1916        }
1917
1918    }
1919
1920    /**
1921     * Returns the minimum and maximum values for the dataset's range
1922     * (y-values), assuming that the series in one category are stacked.
1923     *
1924     * @param dataset  the dataset ({@code null} not permitted).
1925     *
1926     * @return The range ({@code null} if the dataset contains no values).
1927     */
1928    public static Range findStackedRangeBounds(CategoryDataset dataset) {
1929        return findStackedRangeBounds(dataset, 0.0);
1930    }
1931
1932    /**
1933     * Returns the minimum and maximum values for the dataset's range
1934     * (y-values), assuming that the series in one category are stacked.
1935     *
1936     * @param dataset  the dataset ({@code null} not permitted).
1937     * @param base  the base value for the bars.
1938     *
1939     * @return The range ({@code null} if the dataset contains no values).
1940     */
1941    public static Range findStackedRangeBounds(CategoryDataset dataset,
1942            double base) {
1943        Args.nullNotPermitted(dataset, "dataset");
1944        Range result = null;
1945        double minimum = Double.POSITIVE_INFINITY;
1946        double maximum = Double.NEGATIVE_INFINITY;
1947        int categoryCount = dataset.getColumnCount();
1948        for (int item = 0; item < categoryCount; item++) {
1949            double positive = base;
1950            double negative = base;
1951            int seriesCount = dataset.getRowCount();
1952            for (int series = 0; series < seriesCount; series++) {
1953                Number number = dataset.getValue(series, item);
1954                if (number != null) {
1955                    double value = number.doubleValue();
1956                    if (value > 0.0) {
1957                        positive = positive + value;
1958                    }
1959                    if (value < 0.0) {
1960                        negative = negative + value;
1961                        // '+', remember value is negative
1962                    }
1963                }
1964            }
1965            minimum = Math.min(minimum, negative);
1966            maximum = Math.max(maximum, positive);
1967        }
1968        if (minimum <= maximum) {
1969            result = new Range(minimum, maximum);
1970        }
1971        return result;
1972
1973    }
1974
1975    /**
1976     * Returns the minimum and maximum values for the dataset's range
1977     * (y-values), assuming that the series in one category are stacked.
1978     *
1979     * @param dataset  the dataset.
1980     * @param map  a structure that maps series to groups.
1981     *
1982     * @return The value range ({@code null} if the dataset contains no
1983     *         values).
1984     */
1985    public static Range findStackedRangeBounds(CategoryDataset dataset,
1986            KeyToGroupMap map) {
1987        Args.nullNotPermitted(dataset, "dataset");
1988        boolean hasValidData = false;
1989        Range result = null;
1990
1991        // create an array holding the group indices for each series...
1992        int[] groupIndex = new int[dataset.getRowCount()];
1993        for (int i = 0; i < dataset.getRowCount(); i++) {
1994            groupIndex[i] = map.getGroupIndex(map.getGroup(
1995                    dataset.getRowKey(i)));
1996        }
1997
1998        // minimum and maximum for each group...
1999        int groupCount = map.getGroupCount();
2000        double[] minimum = new double[groupCount];
2001        double[] maximum = new double[groupCount];
2002
2003        int categoryCount = dataset.getColumnCount();
2004        for (int item = 0; item < categoryCount; item++) {
2005            double[] positive = new double[groupCount];
2006            double[] negative = new double[groupCount];
2007            int seriesCount = dataset.getRowCount();
2008            for (int series = 0; series < seriesCount; series++) {
2009                Number number = dataset.getValue(series, item);
2010                if (number != null) {
2011                    hasValidData = true;
2012                    double value = number.doubleValue();
2013                    if (value > 0.0) {
2014                        positive[groupIndex[series]]
2015                                 = positive[groupIndex[series]] + value;
2016                    }
2017                    if (value < 0.0) {
2018                        negative[groupIndex[series]]
2019                                 = negative[groupIndex[series]] + value;
2020                                 // '+', remember value is negative
2021                    }
2022                }
2023            }
2024            for (int g = 0; g < groupCount; g++) {
2025                minimum[g] = Math.min(minimum[g], negative[g]);
2026                maximum[g] = Math.max(maximum[g], positive[g]);
2027            }
2028        }
2029        if (hasValidData) {
2030            for (int j = 0; j < groupCount; j++) {
2031                result = Range.combine(result, new Range(minimum[j],
2032                        maximum[j]));
2033            }
2034        }
2035        return result;
2036    }
2037
2038    /**
2039     * Returns the minimum value in the dataset range, assuming that values in
2040     * each category are "stacked".
2041     *
2042     * @param dataset  the dataset ({@code null} not permitted).
2043     *
2044     * @return The minimum value.
2045     *
2046     * @see #findMaximumStackedRangeValue(CategoryDataset)
2047     */
2048    public static Number findMinimumStackedRangeValue(CategoryDataset dataset) {
2049        Args.nullNotPermitted(dataset, "dataset");
2050        Number result = null;
2051        boolean hasValidData = false;
2052        double minimum = 0.0;
2053        int categoryCount = dataset.getColumnCount();
2054        for (int item = 0; item < categoryCount; item++) {
2055            double total = 0.0;
2056            int seriesCount = dataset.getRowCount();
2057            for (int series = 0; series < seriesCount; series++) {
2058                Number number = dataset.getValue(series, item);
2059                if (number != null) {
2060                    hasValidData = true;
2061                    double value = number.doubleValue();
2062                    if (value < 0.0) {
2063                        total = total + value;
2064                        // '+', remember value is negative
2065                    }
2066                }
2067            }
2068            minimum = Math.min(minimum, total);
2069        }
2070        if (hasValidData) {
2071            result = minimum;
2072        }
2073        return result;
2074    }
2075
2076    /**
2077     * Returns the maximum value in the dataset range, assuming that values in
2078     * each category are "stacked".
2079     *
2080     * @param dataset  the dataset ({@code null} not permitted).
2081     *
2082     * @return The maximum value (possibly {@code null}).
2083     *
2084     * @see #findMinimumStackedRangeValue(CategoryDataset)
2085     */
2086    public static Number findMaximumStackedRangeValue(CategoryDataset dataset) {
2087        Args.nullNotPermitted(dataset, "dataset");
2088        Number result = null;
2089        boolean hasValidData = false;
2090        double maximum = 0.0;
2091        int categoryCount = dataset.getColumnCount();
2092        for (int item = 0; item < categoryCount; item++) {
2093            double total = 0.0;
2094            int seriesCount = dataset.getRowCount();
2095            for (int series = 0; series < seriesCount; series++) {
2096                Number number = dataset.getValue(series, item);
2097                if (number != null) {
2098                    hasValidData = true;
2099                    double value = number.doubleValue();
2100                    if (value > 0.0) {
2101                        total = total + value;
2102                    }
2103                }
2104            }
2105            maximum = Math.max(maximum, total);
2106        }
2107        if (hasValidData) {
2108            result = maximum;
2109        }
2110        return result;
2111    }
2112
2113    /**
2114     * Returns the minimum and maximum values for the dataset's range,
2115     * assuming that the series are stacked.
2116     *
2117     * @param dataset  the dataset ({@code null} not permitted).
2118     *
2119     * @return The range ([0.0, 0.0] if the dataset contains no values).
2120     */
2121    public static Range findStackedRangeBounds(TableXYDataset dataset) {
2122        return findStackedRangeBounds(dataset, 0.0);
2123    }
2124
2125    /**
2126     * Returns the minimum and maximum values for the dataset's range,
2127     * assuming that the series are stacked, using the specified base value.
2128     *
2129     * @param dataset  the dataset ({@code null} not permitted).
2130     * @param base  the base value.
2131     *
2132     * @return The range ({@code null} if the dataset contains no values).
2133     */
2134    public static Range findStackedRangeBounds(TableXYDataset dataset,
2135            double base) {
2136        Args.nullNotPermitted(dataset, "dataset");
2137        double minimum = base;
2138        double maximum = base;
2139        for (int itemNo = 0; itemNo < dataset.getItemCount(); itemNo++) {
2140            double positive = base;
2141            double negative = base;
2142            int seriesCount = dataset.getSeriesCount();
2143            for (int seriesNo = 0; seriesNo < seriesCount; seriesNo++) {
2144                double y = dataset.getYValue(seriesNo, itemNo);
2145                if (!Double.isNaN(y)) {
2146                    if (y > 0.0) {
2147                        positive += y;
2148                    }
2149                    else {
2150                        negative += y;
2151                    }
2152                }
2153            }
2154            if (positive > maximum) {
2155                maximum = positive;
2156            }
2157            if (negative < minimum) {
2158                minimum = negative;
2159            }
2160        }
2161        if (minimum <= maximum) {
2162            return new Range(minimum, maximum);
2163        }
2164        else {
2165            return null;
2166        }
2167    }
2168
2169    /**
2170     * Calculates the total for the y-values in all series for a given item
2171     * index.
2172     *
2173     * @param dataset  the dataset.
2174     * @param item  the item index.
2175     *
2176     * @return The total.
2177     *
2178     * @since 1.0.5
2179     */
2180    public static double calculateStackTotal(TableXYDataset dataset, int item) {
2181        double total = 0.0;
2182        int seriesCount = dataset.getSeriesCount();
2183        for (int s = 0; s < seriesCount; s++) {
2184            double value = dataset.getYValue(s, item);
2185            if (!Double.isNaN(value)) {
2186                total = total + value;
2187            }
2188        }
2189        return total;
2190    }
2191
2192    /**
2193     * Calculates the range of values for a dataset where each item is the
2194     * running total of the items for the current series.
2195     *
2196     * @param dataset  the dataset ({@code null} not permitted).
2197     *
2198     * @return The range.
2199     *
2200     * @see #findRangeBounds(CategoryDataset)
2201     */
2202    public static Range findCumulativeRangeBounds(CategoryDataset dataset) {
2203        Args.nullNotPermitted(dataset, "dataset");
2204        boolean allItemsNull = true; // we'll set this to false if there is at
2205                                     // least one non-null data item...
2206        double minimum = 0.0;
2207        double maximum = 0.0;
2208        for (int row = 0; row < dataset.getRowCount(); row++) {
2209            double runningTotal = 0.0;
2210            for (int column = 0; column <= dataset.getColumnCount() - 1;
2211                 column++) {
2212                Number n = dataset.getValue(row, column);
2213                if (n != null) {
2214                    allItemsNull = false;
2215                    double value = n.doubleValue();
2216                    if (!Double.isNaN(value)) {
2217                        runningTotal = runningTotal + value;
2218                        minimum = Math.min(minimum, runningTotal);
2219                        maximum = Math.max(maximum, runningTotal);
2220                    }
2221                }
2222            }
2223        }
2224        if (!allItemsNull) {
2225            return new Range(minimum, maximum);
2226        }
2227        else {
2228            return null;
2229        }
2230    }
2231
2232    /**
2233     * Returns the interpolated value of y that corresponds to the specified
2234     * x-value in the given series.  If the x-value falls outside the range of
2235     * x-values for the dataset, this method returns {@code Double.NaN}.
2236     * 
2237     * @param dataset  the dataset ({@code null} not permitted).
2238     * @param series  the series index.
2239     * @param x  the x-value.
2240     * 
2241     * @return The y value.
2242     * 
2243     * @since 1.0.16
2244     */
2245    public static double findYValue(XYDataset dataset, int series, double x) {
2246        // delegate null check on dataset
2247        int[] indices = findItemIndicesForX(dataset, series, x);
2248        if (indices[0] == -1) {
2249            return Double.NaN;
2250        }
2251        if (indices[0] == indices[1]) {
2252            return dataset.getYValue(series, indices[0]);
2253        }
2254        double x0 = dataset.getXValue(series, indices[0]);
2255        double x1 = dataset.getXValue(series, indices[1]);
2256        double y0 = dataset.getYValue(series, indices[0]);
2257        double y1 = dataset.getYValue(series, indices[1]);
2258        return y0 + (y1 - y0) * (x - x0) / (x1 - x0);
2259    }
2260    
2261    /**
2262     * Finds the indices of the the items in the dataset that span the 
2263     * specified x-value.  There are three cases for the return value:
2264     * <ul>
2265     * <li>there is an exact match for the x-value at index i 
2266     * (returns {@code int[] {i, i}});</li>
2267     * <li>the x-value falls between two (adjacent) items at index i and i+1 
2268     * (returns {@code int[] {i, i+1}});</li>
2269     * <li>the x-value falls outside the domain bounds, in which case the 
2270     *    method returns {@code int[] {-1, -1}}.</li>
2271     * </ul>
2272     * @param dataset  the dataset ({@code null} not permitted).
2273     * @param series  the series index.
2274     * @param x  the x-value.
2275     *
2276     * @return The indices of the two items that span the x-value.
2277     *
2278     * @since 1.0.16
2279     * 
2280     * @see #findYValue(org.jfree.data.xy.XYDataset, int, double) 
2281     */
2282    public static int[] findItemIndicesForX(XYDataset dataset, int series,
2283            double x) {
2284        Args.nullNotPermitted(dataset, "dataset");
2285        int itemCount = dataset.getItemCount(series);
2286        if (itemCount == 0) {
2287            return new int[] {-1, -1};
2288        }
2289        if (itemCount == 1) {
2290            if (x == dataset.getXValue(series, 0)) {
2291                return new int[] {0, 0};
2292            } else {
2293                return new int[] {-1, -1};
2294            }
2295        }
2296        if (dataset.getDomainOrder() == DomainOrder.ASCENDING) {
2297            int low = 0;
2298            int high = itemCount - 1;
2299            double lowValue = dataset.getXValue(series, low);
2300            if (lowValue > x) {
2301                return new int[] {-1, -1};
2302            }
2303            if (lowValue == x) {
2304                return new int[] {low, low};
2305            }
2306            double highValue = dataset.getXValue(series, high);
2307            if (highValue < x) {
2308                return new int[] {-1, -1};
2309            }
2310            if (highValue == x) {
2311                return new int[] {high, high};
2312            }
2313            int mid = (low + high) / 2;
2314            while (high - low > 1) {
2315                double midV = dataset.getXValue(series, mid);
2316                if (x == midV) {
2317                    return new int[] {mid, mid};
2318                }
2319                if (midV < x) {
2320                    low = mid;
2321                }
2322                else {
2323                    high = mid;
2324                }
2325                mid = (low + high) / 2;
2326            }
2327            return new int[] {low, high};
2328        }
2329        else if (dataset.getDomainOrder() == DomainOrder.DESCENDING) {
2330            int high = 0;
2331            int low = itemCount - 1;
2332            double lowValue = dataset.getXValue(series, low);
2333            if (lowValue > x) {
2334                return new int[] {-1, -1};
2335            }
2336            double highValue = dataset.getXValue(series, high);
2337            if (highValue < x) {
2338                return new int[] {-1, -1};
2339            }
2340            int mid = (low + high) / 2;
2341            while (high - low > 1) {
2342                double midV = dataset.getXValue(series, mid);
2343                if (x == midV) {
2344                    return new int[] {mid, mid};
2345                }
2346                if (midV < x) {
2347                    low = mid;
2348                }
2349                else {
2350                    high = mid;
2351                }
2352                mid = (low + high) / 2;
2353            }
2354            return new int[] {low, high};
2355        }
2356        else {
2357            // we don't know anything about the ordering of the x-values,
2358            // so we iterate until we find the first crossing of x (if any)
2359            // we know there are at least 2 items in the series at this point
2360            double prev = dataset.getXValue(series, 0);
2361            if (x == prev) {
2362                return new int[] {0, 0}; // exact match on first item
2363            }
2364            for (int i = 1; i < itemCount; i++) {
2365                double next = dataset.getXValue(series, i);
2366                if (x == next) {
2367                    return new int[] {i, i}; // exact match
2368                }
2369                if ((x > prev && x < next) || (x < prev && x > next)) {
2370                    return new int[] {i - 1, i}; // spanning match
2371                }
2372            }
2373            return new int[] {-1, -1}; // no crossing of x
2374        }
2375    }
2376
2377}