    001/* ===========================================================
    002 * JFreeChart : a free chart library for the Java(tm) platform
    003 * ===========================================================
    004 *
    005 * (C) Copyright 2000-2011, 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 * OutlierListCollection.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):   -;
    035 *
    036 * Changes
    037 * -------
    038 * 05-Aug-2003 : Version 1, contributed by David Browning (DG);
    039 * 01-Sep-2003 : Made storage internal rather than extending ArrayList (DG);
    040 * ------------- JFREECHART 1.0.x ---------------------------------------------
    041 * 02-Feb-2007 : Removed author tags from all over JFreeChart sources (DG);
    042 *
    043 */
    044
    045package org.jfree.chart.renderer;
    046
    047import java.util.ArrayList;
    048import java.util.Iterator;
    049import java.util.List;
    050
    051/**
    052 * A collection of outlier lists for a box and whisker plot. Each collection is
    053 * associated with a single box and whisker entity.
    054 *
    055 * Outliers are grouped in lists for each entity. Lists contain
    056 * one or more outliers, determined by whether overlaps have
    057 * occurred. Overlapping outliers are grouped in the same list.
    058 *
    059 * @see org.jfree.chart.renderer.OutlierList
    060 */
    061public class OutlierListCollection {
    062
    063    /** Storage for the outlier lists. */
    064    private List outlierLists;
    065
    066    /**
    067     * Unbelievably, outliers which are more than 2 * interquartile range are
    068     * called far outs...  See Tukey EDA  (a classic one of a kind...)
    069     */
    070    private boolean highFarOut = false;
    071
    072    /**
    073     * A flag that indicates whether or not the collection contains low far
    074     * out values.
    075     */
    076    private boolean lowFarOut = false;
    077
    078    /**
    079     * Creates a new empty collection.
    080     */
    081    public OutlierListCollection() {
    082        this.outlierLists = new ArrayList();
    083    }
    084
    085    /**
    086     * A flag to indicate the presence of one or more far out values at the
    087     * top end of the range.
    088     *
    089     * @return A <code>boolean</code>.
    090     */
    091    public boolean isHighFarOut() {
    092        return this.highFarOut;
    093    }
    094
    095    /**
    096     * Sets the flag that indicates the presence of one or more far out values
    097     * at the top end of the range.
    098     *
    099     * @param farOut  the flag.
    100     */
    101    public void setHighFarOut(boolean farOut) {
    102        this.highFarOut = farOut;
    103    }
    104
    105    /**
    106     * A flag to indicate the presence of one or more far out values at the
    107     * bottom end of the range.
    108     *
    109     * @return A <code>boolean</code>.
    110     */
    111    public boolean isLowFarOut() {
    112        return this.lowFarOut;
    113    }
    114
    115    /**
    116     * Sets the flag that indicates the presence of one or more far out values
    117     * at the bottom end of the range.
    118     *
    119     * @param farOut  the flag.
    120     */
    121    public void setLowFarOut(boolean farOut) {
    122        this.lowFarOut = farOut;
    123    }
    124    /**
    125     * Appends the specified element as a new <code>OutlierList</code> to the
    126     * end of this list if it does not overlap an outlier in an existing list.
    127     *
    128     * If it does overlap, it is appended to the outlier list which it overlaps
    129     * and that list is updated.
    130     *
    131     * @param outlier  element to be appended to this list.
    132     *
    133     * @return <tt>true</tt> (as per the general contract of Collection.add).
    134     */
    135    public boolean add(Outlier outlier) {
    136
    137        if (this.outlierLists.isEmpty()) {
    138            return this.outlierLists.add(new OutlierList(outlier));
    139        }
    140        else {
    141            boolean updated = false;
    142            for (Iterator iterator = this.outlierLists.iterator();
    143                 iterator.hasNext();) {
    144                OutlierList list = (OutlierList) iterator.next();
    145                if (list.isOverlapped(outlier)) {
    146                    updated = updateOutlierList(list, outlier);
    147                }
    148            }
    149            if (!updated) {
    150                //System.err.print(" creating new outlier list ");
    151                updated = this.outlierLists.add(new OutlierList(outlier));
    152            }
    153            return updated;
    154        }
    155
    156    }
    157
    158    /**
    159     * Returns an iterator for the outlier lists.
    160     *
    161     * @return An iterator.
    162     */
    163    public Iterator iterator() {
    164        return this.outlierLists.iterator();
    165    }
    166
    167
    168    /**
    169     * Updates the outlier list by adding the outlier to the end of the list and
    170     * setting the averaged outlier to the average x and y coordinnate values
    171     * of the outliers in the list.
    172     *
    173     * @param list  the outlier list to be updated.
    174     * @param outlier  the outlier to be added
    175     *
    176     * @return <tt>true</tt> (as per the general contract of Collection.add).
    177     */
    178    private boolean updateOutlierList(OutlierList list, Outlier outlier) {
    179        boolean result = false;
    180        result = list.add(outlier);
    181        list.updateAveragedOutlier();
    182        list.setMultiple(true);
    183        return result;
    184    }
    185
    186}