001 /* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2008, 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 * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
025 * in the United States and other countries.]
026 *
027 * ---------------------------
028 * BoxAndWhiskerXYDataset.java
029 * ---------------------------
030 * (C) Copyright 2003-2008, by David Browning and Contributors.
031 *
032 * Original Author: David Browning (for Australian Institute of Marine
033 * Science);
034 * Contributor(s): David Gilbert (for Object Refinery Limited);
035 *
036 * Changes
037 * -------
038 * 05-Aug-2003 : Version 1, contributed by David Browning (DG);
039 * 12-Aug-2003 : Added new methods: getMaxNonOutlierValue
040 * getMaxNonFaroutValue
041 * getOutlierCoefficient
042 * setOutlierCoefficient
043 * getFaroutCoefficient
044 * setFaroutCoefficient
045 * getInterquartileRange (DB)
046 * 27-Aug-2003 : Renamed BoxAndWhiskerDataset --> BoxAndWhiskerXYDataset, and
047 * cut down methods (DG);
048 * ------------- JFREECHART 1.0.x ---------------------------------------------
049 * 02-Feb-2007 : Removed author tags from all over JFreeChart sources (DG);
050 *
051 */
052
053 package org.jfree.data.statistics;
054
055 import java.util.List;
056
057 import org.jfree.data.xy.XYDataset;
058
059 /**
060 * An interface that defines data in the form of (x, max, min, average, median)
061 * tuples.
062 * <P>
063 * Example: JFreeChart uses this interface to obtain data for AIMS
064 * max-min-average-median plots.
065 */
066 public interface BoxAndWhiskerXYDataset extends XYDataset {
067
068 /**
069 * Returns the mean for the specified series and item.
070 *
071 * @param series the series (zero-based index).
072 * @param item the item (zero-based index).
073 *
074 * @return The mean for the specified series and item.
075 */
076 public Number getMeanValue(int series, int item);
077
078 /**
079 * Returns the median-value for the specified series and item.
080 *
081 * @param series the series (zero-based index).
082 * @param item the item (zero-based index).
083 *
084 * @return The median-value for the specified series and item.
085 */
086 public Number getMedianValue(int series, int item);
087
088 /**
089 * Returns the Q1 median-value for the specified series and item.
090 *
091 * @param series the series (zero-based index).
092 * @param item the item (zero-based index).
093 *
094 * @return The Q1 median-value for the specified series and item.
095 */
096 public Number getQ1Value(int series, int item);
097
098 /**
099 * 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 }