HistogramDataset


1   /* ===========================================================
2    * JFreeChart : a free chart library for the Java(tm) platform
3    * ===========================================================
4    *
5    * (C) Copyright 2000-2006, by Object Refinery Limited and Contributors.
6    *
7    * Project Info:  http://www.jfree.org/jfreechart/index.html
8    *
9    * This library is free software; you can redistribute it and/or modify it 
10   * under the terms of the GNU Lesser General Public License as published by 
11   * the Free Software Foundation; either version 2.1 of the License, or 
12   * (at your option) any later version.
13   *
14   * This library is distributed in the hope that it will be useful, but 
15   * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
16   * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
17   * License for more details.
18   *
19   * You should have received a copy of the GNU Lesser General Public
20   * License along with this library; if not, write to the Free Software
21   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
22   * USA.  
23   *
24   * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
25   * in the United States and other countries.]
26   *
27   * ---------------------
28   * HistogramDataset.java
29   * ---------------------
30   * (C) Copyright 2003-2006, by Jelai Wang and Contributors.
31   *
32   * Original Author:  Jelai Wang (jelaiw AT mindspring.com);
33   * Contributor(s):   David Gilbert (for Object Refinery Limited);
34   *                   Cameron Hayne;
35   *                   Rikard Bj?rklind;
36   *
37   * $Id: HistogramDataset.java,v 1.9.2.7 2006/09/07 15:26:49 mungady Exp $
38   *
39   * Changes
40   * -------
41   * 06-Jul-2003 : Version 1, contributed by Jelai Wang (DG);
42   * 07-Jul-2003 : Changed package and added Javadocs (DG);
43   * 15-Oct-2003 : Updated Javadocs and removed array sorting (JW);
44   * 09-Jan-2004 : Added fix by "Z." posted in the JFreeChart forum (DG);
45   * 01-Mar-2004 : Added equals() and clone() methods and implemented 
46   *               Serializable.  Also added new addSeries() method (DG);
47   * 06-May-2004 : Now extends AbstractIntervalXYDataset (DG);
48   * 15-Jul-2004 : Switched getX() with getXValue() and getY() with 
49   *               getYValue() (DG);
50   * 20-May-2005 : Speed up binning - see patch 1026151 contributed by Cameron
51   *               Hayne (DG);
52   * 08-Jun-2005 : Fixed bug in getSeriesKey() method (DG);
53   * 22-Nov-2005 : Fixed cast in getSeriesKey() method - see patch 1329287 (DG);
54   * ------------- JFREECHART 1.0.0 ---------------------------------------------
55   * 03-Aug-2006 : Improved precision of bin boundary calculation (DG);
56   * 07-Sep-2006 : Fixed bug 1553088 (DG);
57   * 
58   */
59  
60  package org.jfree.data.statistics;
61  
62  import java.io.Serializable  ;
63  import java.util.ArrayList  ;
64  import java.util.HashMap  ;
65  import java.util.List  ;
66  import java.util.Map  ;
67  
68  import org.jfree.data.general.DatasetChangeEvent;
69  import org.jfree.data.xy.AbstractIntervalXYDataset;
70  import org.jfree.data.xy.IntervalXYDataset;
71  import org.jfree.util.ObjectUtilities;
72  import org.jfree.util.PublicCloneable;
73  
74  /**
75   * A dataset that can be used for creating histograms.
76   * 
77   * @see SimpleHistogramDataset
78   */
79  public class HistogramDataset extends AbstractIntervalXYDataset 
80                                implements IntervalXYDataset, 
81                                           Cloneable  , PublicCloneable, 
82                                           Serializable   {
83  
84      /** For serialization. */
85      private static final long serialVersionUID = -6341668077370231153L;
86      
87      /** A list of maps. */
88      private List   list;
89      
90      /** The histogram type. */
91      private HistogramType type;
92  
93      /**
94       * Creates a new (empty) dataset with a default type of 
95       * {@link HistogramType}.FREQUENCY.
96       */
97      public HistogramDataset() {
98          this.list = new ArrayList  ();
99          this.type = HistogramType.FREQUENCY;
100     }
101     
102     /**
103      * Returns the histogram type. 
104      * 
105      * @return The type (never <code>null</code>).
106      */
107     public HistogramType getType() { 
108         return this.type; 
109     }
110 
111     /**
112      * Sets the histogram type and sends a {@link DatasetChangeEvent} to all 
113      * registered listeners.
114      * 
115      * @param type  the type (<code>null</code> not permitted).
116      */
117     public void setType(HistogramType type) {
118         if (type == null) {
119             throw new IllegalArgumentException  ("Null 'type' argument");
120         }
121         this.type = type;   
122         notifyListeners(new DatasetChangeEvent(this, this));
123     }
124 
125     /**
126      * Adds a series to the dataset, using the specified number of bins.
127      * 
128      * @param key  the series key (<code>null</code> not permitted).
129      * @param values the values (<code>null</code> not permitted).
130      * @param bins  the number of bins (must be at least 1).
131      */
132     public void addSeries(Comparable   key, double[] values, int bins) {
133         // defer argument checking...
134         double minimum = getMinimum(values);
135         double maximum = getMaximum(values);
136         addSeries(key, values, bins, minimum, maximum);
137     }
138 
139     /**
140      * Adds a series to the dataset. Any data value less than minimum will be
141      * assigned to the first bin, and any data value greater than maximum will
142      * be assigned to the last bin.  Values falling on the boundary of 
143      * adjacent bins will be assigned to the higher indexed bin.
144      * 
145      * @param key  the series key (<code>null</code> not permitted).
146      * @param values  the raw observations.
147      * @param bins  the number of bins (must be at least 1).
148      * @param minimum  the lower bound of the bin range.
149      * @param maximum  the upper bound of the bin range.
150      */
151     public void addSeries(Comparable   key, 
152                           double[] values, 
153                           int bins, 
154                           double minimum, 
155                           double maximum) {
156         
157         if (key == null) {
158             throw new IllegalArgumentException  ("Null 'key' argument.");   
159         }
160         if (values == null) {
161             throw new IllegalArgumentException  ("Null 'values' argument.");
162         }
163         else if (bins < 1) {
164             throw new IllegalArgumentException  (
165                     "The 'bins' value must be at least 1.");
166         }
167         double binWidth = (maximum - minimum) / bins;
168 
169         double lower = minimum;
170         double upper;
171         List   binList = new ArrayList  (bins);
172         for (int i = 0; i < bins; i++) {
173             HistogramBin bin;
174             // make sure bins[bins.length]'s upper boundary ends at maximum
175             // to avoid the rounding issue. the bins[0] lower boundary is
176             // guaranteed start from min
177             if (i == bins - 1) {
178                 bin = new HistogramBin(lower, maximum);
179             }
180             else {
181                 upper = minimum + (i + 1) * binWidth;
182                 bin = new HistogramBin(lower, upper);
183                 lower = upper;
184             }
185             binList.add(bin);
186         }        
187         // fill the bins
188         for (int i = 0; i < values.length; i++) {
189             int binIndex = bins - 1;
190             if (values[i] < maximum) {
191                 double fraction = (values[i] - minimum) / (maximum - minimum);
192                 if (fraction < 0.0) {
193                     fraction = 0.0;
194                 }
195                 binIndex = (int) (fraction * bins);
196                 // rounding could result in binIndex being equal to bins
197                 // which will cause an IndexOutOfBoundsException - see bug
198                 // report 1553088
199                 if (binIndex >= bins) {
200                     binIndex = bins - 1;
201                 }
202             }
203             HistogramBin bin = (HistogramBin) binList.get(binIndex);
204             bin.incrementCount();
205         }
206         // generic map for each series
207         Map   map = new HashMap  ();
208         map.put("key", key);
209         map.put("bins", binList);
210         map.put("values.length", new Integer  (values.length));
211         map.put("bin width", new Double  (binWidth));
212         this.list.add(map);
213     }
214     
215     /**
216      * Returns the minimum value in an array of values.
217      * 
218      * @param values  the values (<code>null</code> not permitted and 
219      *                zero-length array not permitted).
220      * 
221      * @return The minimum value.
222      */
223     private double getMinimum(double[] values) {
224         if (values == null || values.length < 1) {
225             throw new IllegalArgumentException  (
226                     "Null or zero length 'values' argument.");
227         }
228         double min = Double.MAX_VALUE;
229         for (int i = 0; i < values.length; i++) {
230             if (values[i] < min) {
231                 min = values[i];
232             }
233         }
234         return min;
235     }
236 
237     /**
238      * Returns the maximum value in an array of values.
239      * 
240      * @param values  the values (<code>null</code> not permitted and 
241      *                zero-length array not permitted).
242      * 
243      * @return The maximum value.
244      */
245     private double getMaximum(double[] values) {
246         if (values == null || values.length < 1) {
247             throw new IllegalArgumentException  (
248                     "Null or zero length 'values' argument.");
249         }
250         double max = -Double.MAX_VALUE;
251         for (int i = 0; i < values.length; i++) {
252             if (values[i] > max) {
253                 max = values[i];
254             }
255         }
256         return max;
257     }
258 
259     /**
260      * Returns the bins for a series.
261      * 
262      * @param series  the series index (in the range <code>0</code> to 
263      *     <code>getSeriesCount() - 1</code>).
264      * 
265      * @return A list of bins.
266      * 
267      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
268      *     specified range.
269      */
270     List   getBins(int series) {
271         Map   map = (Map  ) this.list.get(series);
272         return (List  ) map.get("bins"); 
273     }
274 
275     /**
276      * Returns the total number of observations for a series.
277      * 
278      * @param series  the series index.
279      * 
280      * @return The total.
281      */
282     private int getTotal(int series) {
283         Map   map = (Map  ) this.list.get(series);
284         return ((Integer  ) map.get("values.length")).intValue(); 
285     }
286 
287     /**
288      * Returns the bin width for a series.
289      * 
290      * @param series  the series index (zero based).
291      * 
292      * @return The bin width.
293      */
294     private double getBinWidth(int series) {
295         Map   map = (Map  ) this.list.get(series);
296         return ((Double  ) map.get("bin width")).doubleValue(); 
297     }
298 
299     /**
300      * Returns the number of series in the dataset.
301      * 
302      * @return The series count.
303      */
304     public int getSeriesCount() { 
305         return this.list.size(); 
306     }
307     
308     /**
309      * Returns the key for a series.
310      * 
311      * @param series  the series index (in the range <code>0</code> to 
312      *     <code>getSeriesCount() - 1</code>).
313      * 
314      * @return The series key.
315      * 
316      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
317      *     specified range.
318      */
319     public Comparable   getSeriesKey(int series) {
320         Map   map = (Map  ) this.list.get(series);
321         return (Comparable  ) map.get("key"); 
322     }
323 
324     /**
325      * Returns the number of data items for a series.
326      * 
327      * @param series  the series index (in the range <code>0</code> to 
328      *     <code>getSeriesCount() - 1</code>).
329      * 
330      * @return The item count.
331      * 
332      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
333      *     specified range.
334      */
335     public int getItemCount(int series) {
336         return getBins(series).size(); 
337     }
338 
339     /**
340      * Returns the X value for a bin.  This value won't be used for plotting 
341      * histograms, since the renderer will ignore it.  But other renderers can 
342      * use it (for example, you could use the dataset to create a line
343      * chart).
344      * 
345      * @param series  the series index (in the range <code>0</code> to 
346      *     <code>getSeriesCount() - 1</code>).
347      * @param item  the item index (zero based).
348      * 
349      * @return The start value.
350      * 
351      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
352      *     specified range.
353      */
354     public Number   getX(int series, int item) {
355         List   bins = getBins(series);
356         HistogramBin bin = (HistogramBin) bins.get(item);
357         double x = (bin.getStartBoundary() + bin.getEndBoundary()) / 2.;
358         return new Double  (x);
359     }
360 
361     /**
362      * Returns the y-value for a bin (calculated to take into account the 
363      * histogram type).
364      * 
365      * @param series  the series index (in the range <code>0</code> to 
366      *     <code>getSeriesCount() - 1</code>).
367      * @param item  the item index (zero based).
368      * 
369      * @return The y-value.
370      * 
371      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
372      *     specified range.
373      */
374     public Number   getY(int series, int item) {
375         List   bins = getBins(series);
376         HistogramBin bin = (HistogramBin) bins.get(item);
377         double total = getTotal(series);
378         double binWidth = getBinWidth(series);
379 
380         if (this.type == HistogramType.FREQUENCY) {
381             return new Double  (bin.getCount());
382         }
383         else if (this.type == HistogramType.RELATIVE_FREQUENCY) {
384             return new Double  (bin.getCount() / total);
385         }
386         else if (this.type == HistogramType.SCALE_AREA_TO_1) {
387             return new Double  (bin.getCount() / (binWidth * total));
388         }
389         else { // pretty sure this shouldn't ever happen
390             throw new IllegalStateException  ();
391         }
392     }
393 
394     /**
395      * Returns the start value for a bin.
396      * 
397      * @param series  the series index (in the range <code>0</code> to 
398      *     <code>getSeriesCount() - 1</code>).
399      * @param item  the item index (zero based).
400      * 
401      * @return The start value.
402      * 
403      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
404      *     specified range.
405      */
406     public Number   getStartX(int series, int item) {
407         List   bins = getBins(series);
408         HistogramBin bin = (HistogramBin) bins.get(item);
409         return new Double  (bin.getStartBoundary());
410     }
411 
412     /**
413      * Returns the end value for a bin.
414      * 
415      * @param series  the series index (in the range <code>0</code> to 
416      *     <code>getSeriesCount() - 1</code>).
417      * @param item  the item index (zero based).
418      * 
419      * @return The end value.
420      * 
421      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
422      *     specified range.
423      */
424     public Number   getEndX(int series, int item) {
425         List   bins = getBins(series);
426         HistogramBin bin = (HistogramBin) bins.get(item);
427         return new Double  (bin.getEndBoundary());
428     }
429 
430     /**
431      * Returns the start y-value for a bin (which is the same as the y-value, 
432      * this method exists only to support the general form of the 
433      * {@link IntervalXYDataset} interface).
434      * 
435      * @param series  the series index (in the range <code>0</code> to 
436      *     <code>getSeriesCount() - 1</code>).
437      * @param item  the item index (zero based).
438      * 
439      * @return The y-value.
440      * 
441      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
442      *     specified range.
443      */
444     public Number   getStartY(int series, int item) {
445         return getY(series, item);
446     }
447 
448     /**
449      * Returns the end y-value for a bin (which is the same as the y-value, 
450      * this method exists only to support the general form of the 
451      * {@link IntervalXYDataset} interface).
452      * 
453      * @param series  the series index (in the range <code>0</code> to 
454      *     <code>getSeriesCount() - 1</code>).
455      * @param item  the item index (zero based).
456      * 
457      * @return The Y value.
458      * 
459      * @throws IndexOutOfBoundsException if <code>series</code> is outside the
460      *     specified range.
461      */    
462     public Number   getEndY(int series, int item) {
463         return getY(series, item);
464     }
465 
466     /**
467      * Tests this dataset for equality with an arbitrary object.
468      * 
469      * @param obj  the object to test against (<code>null</code> permitted).
470      * 
471      * @return A boolean.
472      */
473     public boolean equals(Object   obj) {
474         if (obj == this) {
475             return true;   
476         }
477         if (!(obj instanceof HistogramDataset)) {
478             return false;
479         }
480         HistogramDataset that = (HistogramDataset) obj;
481         if (!ObjectUtilities.equal(this.type, that.type)) {
482             return false;
483         }
484         if (!ObjectUtilities.equal(this.list, that.list)) {
485             return false;
486         }
487         return true;   
488     }
489 
490     /**
491      * Returns a clone of the dataset.
492      * 
493      * @return A clone of the dataset.
494      * 
495      * @throws CloneNotSupportedException if the object cannot be cloned.
496      */
497     public Object   clone() throws CloneNotSupportedException   {
498         return super.clone();   
499     }
500 
501 }
502
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags