001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2013, 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 * 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
053package org.jfree.data.statistics;
054
055import java.util.List;
056
057import 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 */
066public 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 a list 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 list of outliers for the specified series and item
155     *         (possibly <code>null</code>).
156     */
157    public List getOutliers(int series, int item);
158
159    /**
160     * Returns the value used as the outlier coefficient. The outlier
161     * coefficient gives an indication of the degree of certainty in an
162     * unskewed distribution.  Increasing the coefficient increases the number
163     * of values included.  Currently only used to ensure farout coefficient
164     * is greater than the outlier coefficient
165     *
166     * @return A <code>double</code> representing the value used to calculate
167     *         outliers
168     */
169    public double getOutlierCoefficient();
170
171    /**
172     * Returns the value used as the farout coefficient. The farout coefficient
173     * allows the calculation of which values will be off the graph.
174     *
175     * @return A <code>double</code> representing the value used to calculate
176     *         farouts
177     */
178    public double getFaroutCoefficient();
179
180}