View Javadoc

1   /*
2    * Copyright (C) 2004 Christian Siefkes <christian@siefkes.net>.
3    * Development of this software is supported by the German Research Society,
4    * Berlin-Brandenburg Graduate School in Distributed Information Systems
5    * (DFG grant no. GRK 316).
6    *
7    * This library is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU Lesser General Public
9    * License as published by the Free Software Foundation; either
10   * version 2.1 of the License, or (at your option) any later version.
11   *
12   * This library is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15   * Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public
18   * License along with this library; if not, visit
19   * http://www.gnu.org/licenses/lgpl.html or write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
21   */
22  package de.fu_berlin.ties.classify;
23  
24  import java.util.Iterator;
25  import java.util.SortedSet;
26  import java.util.TreeSet;
27  
28  import org.apache.commons.lang.builder.ToStringBuilder;
29  
30  import de.fu_berlin.ties.util.InvertedComparator;
31  
32  /***
33   * A distribution over the classes predicted by a classifier. The contained
34   * predictions are sorted in descending order, so the most probably prediction
35   * comes first.
36   *
37   * @author Christian Siefkes
38   * @version $Revision: 1.7 $, $Date: 2004/09/06 17:21:59 $, $Author: siefkes $
39   */
40  public class PredictionDistribution {
41  
42      /***
43       * Stores the predictions, in inverted order, so the most probably
44       * prediction comes first.
45       */
46      private final SortedSet<Prediction> store = new TreeSet<Prediction>
47              (new InvertedComparator<Prediction>(new PredictionComparator()));
48  
49      /***
50       * Creates a new instance.
51       */
52      public PredictionDistribution() {
53          super();
54      }
55  
56      /***
57       * Creates a new instance, adding a prediction.
58       * @param pred the prediction to add
59       */
60      public PredictionDistribution(final Prediction pred) {
61          this();
62          add(pred);
63      }
64  
65      /***
66       * Adds a new prediction to this distribution.
67       *
68       * @param pred the prediction to add
69       * @throws IllegalArgumentException if the distribution already contains
70       * a prediction considered equal by {@link PredictionComparator}
71       */
72      public void add(final Prediction pred) throws IllegalArgumentException {
73          final boolean didAdd = store.add(pred);
74  
75          if (!didAdd) {
76              throw new IllegalArgumentException("Cannot add " + pred
77                  + " because another prediction in this distribution is "
78                  + " considered equal");
79          }
80      }
81  
82      /***
83       * Returns the best (most probably) prediction in this distribution.
84       * @return the best prediction
85       */
86      public Prediction best() {
87          return store.first();
88      }
89  
90      /***
91       * Returns an iterator over the predictions in this distribution,
92       * in descending order (most probably class comes first).
93       *
94       * @return an iterator over the predictions
95       */
96      public Iterator iterator() {
97          return store.iterator();
98      }
99  
100     /***
101      * Returns the number of predictions (classes) in this distribution.
102      *
103      * @return the number of predictions
104      */
105     public int size() {
106         return store.size();
107     }
108 
109     /***
110      * Returns a string representation of this object.
111      *
112      * @return a textual representation
113      */
114     public String toString() {
115         return new ToStringBuilder(this)
116             .append("stored predictions", store)
117             .toString();
118     }
119 
120 }