001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2020, 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 final List<OutlierList> 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}.
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}.
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} 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 {@code true} (as per the general contract of Collection.add).
134     */
135    public boolean add(Outlier outlier) {
136        if (this.outlierLists.isEmpty()) {
137            return this.outlierLists.add(new OutlierList(outlier));
138        }
139        else {
140            boolean updated = false;
141            for (OutlierList list : this.outlierLists) {
142                if (list.isOverlapped(outlier)) {
143                    updated = updateOutlierList(list, outlier);
144                }
145            }
146            if (!updated) {
147                //System.err.print(" creating new outlier list ");
148                updated = this.outlierLists.add(new OutlierList(outlier));
149            }
150            return updated;
151        }
152    }
153
154    /**
155     * Returns an iterator for the outlier lists.
156     *
157     * @return An iterator.
158     */
159    public Iterator<OutlierList> iterator() {
160        return this.outlierLists.iterator();
161    }
162
163
164    /**
165     * Updates the outlier list by adding the outlier to the end of the list and
166     * setting the averaged outlier to the average x and y coordinnate values
167     * of the outliers in the list.
168     *
169     * @param list  the outlier list to be updated.
170     * @param outlier  the outlier to be added
171     *
172     * @return <tt>true</tt> (as per the general contract of Collection.add).
173     */
174    private boolean updateOutlierList(OutlierList list, Outlier outlier) {
175        boolean result = false;
176        result = list.add(outlier);
177        list.updateAveragedOutlier();
178        list.setMultiple(true);
179        return result;
180    }
181
182}