001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-present, by David Gilbert 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-present, by David Browning and Contributors.
031 *
032 * Original Author:  David Browning (for Australian Institute of Marine
033 *                   Science);
034 * Contributor(s):   David Gilbert;
035 *
036 */
037
038package org.jfree.data.statistics;
039
040import java.util.List;
041
042import org.jfree.data.xy.XYDataset;
043
044/**
045 * An interface that defines data in the form of (x, max, min, average, median)
046 * tuples.
047 * <P>
048 * Example: JFreeChart uses this interface to obtain data for AIMS
049 * max-min-average-median plots.
050 */
051public interface BoxAndWhiskerXYDataset extends XYDataset {
052
053    /**
054     * Returns the mean for the specified series and item.
055     *
056     * @param series  the series (zero-based index).
057     * @param item  the item (zero-based index).
058     *
059     * @return The mean for the specified series and item.
060     */
061    Number getMeanValue(int series, int item);
062
063    /**
064     * Returns the median-value for the specified series and item.
065     *
066     * @param series  the series (zero-based index).
067     * @param item  the item (zero-based index).
068     *
069     * @return The median-value for the specified series and item.
070     */
071    Number getMedianValue(int series, int item);
072
073    /**
074     * Returns the Q1 median-value for the specified series and item.
075     *
076     * @param series  the series (zero-based index).
077     * @param item  the item (zero-based index).
078     *
079     * @return The Q1 median-value for the specified series and item.
080     */
081    Number getQ1Value(int series, int item);
082
083    /**
084     * Returns the Q3 median-value for the specified series and item.
085     *
086     * @param series  the series (zero-based index).
087     * @param item  the item (zero-based index).
088     *
089     * @return The Q3 median-value for the specified series and item.
090     */
091    Number getQ3Value(int series, int item);
092
093    /**
094     * Returns the min-value for the specified series and item.
095     *
096     * @param series  the series (zero-based index).
097     * @param item  the item (zero-based index).
098     *
099     * @return The min-value for the specified series and item.
100     */
101    Number getMinRegularValue(int series, int item);
102
103    /**
104     * Returns the max-value for the specified series and item.
105     *
106     * @param series  the series (zero-based index).
107     * @param item  the item (zero-based index).
108     *
109     * @return The max-value for the specified series and item.
110     */
111    Number getMaxRegularValue(int series, int item);
112
113    /**
114     * Returns the minimum value which is not a farout.
115     * @param series  the series (zero-based index).
116     * @param item  the item (zero-based index).
117     *
118     * @return A {@code Number} representing the maximum non-farout value.
119     */
120    Number getMinOutlier(int series, int item);
121
122    /**
123     * Returns the maximum value which is not a farout, ie Q3 + (interquartile
124     * range * farout coefficient).
125     *
126     * @param series  the series (zero-based index).
127     * @param item  the item (zero-based index).
128     *
129     * @return A {@code Number} representing the maximum non-farout value.
130     */
131    Number getMaxOutlier(int series, int item);
132
133    /**
134     * Returns a list of outliers for the specified series and item.
135     *
136     * @param series  the series (zero-based index).
137     * @param item  the item (zero-based index).
138     *
139     * @return The list of outliers for the specified series and item
140     *         (possibly {@code null}).
141     */
142    List getOutliers(int series, int item);
143
144    /**
145     * Returns the value used as the outlier coefficient. The outlier
146     * coefficient gives an indication of the degree of certainty in an
147     * unskewed distribution.  Increasing the coefficient increases the number
148     * of values included.  Currently only used to ensure farout coefficient
149     * is greater than the outlier coefficient
150     *
151     * @return A {@code double} representing the value used to calculate
152     *         outliers
153     */
154    double getOutlierCoefficient();
155
156    /**
157     * Returns the value used as the farout coefficient. The farout coefficient
158     * allows the calculation of which values will be off the graph.
159     *
160     * @return A {@code double} representing the value used to calculate
161     *         farouts
162     */
163    double getFaroutCoefficient();
164
165}