Source for org.jfree.data.statistics.BoxAndWhiskerXYDataset

   1: /* ===========================================================
   2:  * JFreeChart : a free chart library for the Java(tm) platform
   3:  * ===========================================================
   4:  *
   5:  * (C) Copyright 2000-2007, 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:  * BoxAndWhiskerXYDataset.java
  29:  * ---------------------------
  30:  * (C) Copyright 2003, 2007, by David Browning and Contributors.
  31:  *
  32:  * Original Author:  David Browning (for Australian Institute of Marine 
  33:  *                   Science);
  34:  * Contributor(s):   David Gilbert (for Object Refinery Limited);
  35:  *
  36:  * Changes
  37:  * -------
  38:  * 05-Aug-2003 : Version 1, contributed by David Browning (DG);
  39:  * 12-Aug-2003 : Added new methods: getMaxNonOutlierValue
  40:  *                                  getMaxNonFaroutValue
  41:  *                                  getOutlierCoefficient
  42:  *                                  setOutlierCoefficient
  43:  *                                  getFaroutCoefficient
  44:  *                                  setFaroutCoefficient
  45:  *                                  getInterquartileRange (DB)
  46:  * 27-Aug-2003 : Renamed BoxAndWhiskerDataset --> BoxAndWhiskerXYDataset, and 
  47:  *               cut down methods (DG);
  48:  * ------------- JFREECHART 1.0.x ---------------------------------------------
  49:  * 02-Feb-2007 : Removed author tags from all over JFreeChart sources (DG);
  50:  * 
  51:  */
  52: 
  53: package org.jfree.data.statistics;
  54: 
  55: import java.util.List;
  56: 
  57: import org.jfree.data.xy.XYDataset;
  58: 
  59: /**
  60:  * An interface that defines data in the form of (x, max, min, average, median) 
  61:  * tuples.
  62:  * <P>
  63:  * Example: JFreeChart uses this interface to obtain data for AIMS 
  64:  * max-min-average-median plots.
  65:  */
  66: public interface BoxAndWhiskerXYDataset extends XYDataset {
  67: 
  68:     /**
  69:      * Returns the mean for the specified series and item.
  70:      *
  71:      * @param series  the series (zero-based index).
  72:      * @param item  the item (zero-based index).
  73:      *
  74:      * @return The mean for the specified series and item.
  75:      */
  76:     public Number getMeanValue(int series, int item);
  77: 
  78:     /**
  79:      * Returns the median-value for the specified series and item.
  80:      *
  81:      * @param series  the series (zero-based index).
  82:      * @param item  the item (zero-based index).
  83:      *
  84:      * @return The median-value for the specified series and item.
  85:      */
  86:     public Number getMedianValue(int series, int item);
  87: 
  88:     /**
  89:      * Returns the Q1 median-value for the specified series and item.
  90:      *
  91:      * @param series  the series (zero-based index).
  92:      * @param item  the item (zero-based index).
  93:      *
  94:      * @return The Q1 median-value for the specified series and item.
  95:      */
  96:     public Number getQ1Value(int series, int item);
  97: 
  98:     /**
  99:      * Returns the Q3 median-value for the specified series and item.
 100:      *
 101:      * @param series  the series (zero-based index).
 102:      * @param item  the item (zero-based index).
 103:      *
 104:      * @return The Q3 median-value for the specified series and item.
 105:      */
 106:     public Number getQ3Value(int series, int item);
 107: 
 108:     /**
 109:      * Returns the min-value for the specified series and item.
 110:      *
 111:      * @param series  the series (zero-based index).
 112:      * @param item  the item (zero-based index).
 113:      *
 114:      * @return The min-value for the specified series and item.
 115:      */
 116:     public Number getMinRegularValue(int series, int item);
 117: 
 118:     /**
 119:      * Returns the max-value for the specified series and item.
 120:      *
 121:      * @param series  the series (zero-based index).
 122:      * @param item  the item (zero-based index).
 123:      *
 124:      * @return The max-value for the specified series and item.
 125:      */
 126:     public Number getMaxRegularValue(int series, int item);
 127: 
 128:     /**
 129:      * Returns the minimum value which is not a farout.
 130:      * @param series  the series (zero-based index).
 131:      * @param item  the item (zero-based index).
 132:      *
 133:      * @return A <code>Number</code> representing the maximum non-farout value.
 134:      */
 135:     public Number getMinOutlier(int series, int item);
 136: 
 137:     /**
 138:      * Returns the maximum value which is not a farout, ie Q3 + (interquartile 
 139:      * range * farout coefficient).
 140:      * 
 141:      * @param series  the series (zero-based index).
 142:      * @param item  the item (zero-based index).
 143:      *
 144:      * @return A <code>Number</code> representing the maximum non-farout value.
 145:      */
 146:     public Number getMaxOutlier(int series, int item);
 147:     
 148:     /**
 149:      * Returns an array of outliers for the specified series and item.
 150:      *
 151:      * @param series  the series (zero-based index).
 152:      * @param item  the item (zero-based index).
 153:      *
 154:      * @return The array of outliers for the specified series and item.
 155:      */
 156:     public List getOutliers(int series, int item);
 157: 
 158:     /**
 159:      * Returns the value used as the outlier coefficient. The outlier 
 160:      * coefficient gives an indication of the degree of certainty in an 
 161:      * unskewed distribution.  Increasing the coefficient increases the number 
 162:      * of values included.  Currently only used to ensure farout coefficient 
 163:      * is greater than the outlier coefficient
 164:      *
 165:      * @return A <code>double</code> representing the value used to calculate 
 166:      *         outliers
 167:      */
 168:     public double getOutlierCoefficient();
 169: 
 170:     /**
 171:      * Returns the value used as the farout coefficient. The farout coefficient
 172:      * allows the calculation of which values will be off the graph.
 173:      *
 174:      * @return A <code>double</code> representing the value used to calculate 
 175:      *         farouts
 176:      */
 177:     public double getFaroutCoefficient();
 178: 
 179: }