View Javadoc

1   /*
2    * Copyright (C) 2004-2006 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 program is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU General Public License as published by
9    * the Free Software Foundation; either version 2 of the License, or
10   * (at your option) any later version.
11   *
12   * This program 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
15   * GNU General Public License for more details.
16   *
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, visit
19   * http://www.gnu.org/licenses/gpl.html or write to the Free Software
20   * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  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.13 $, $Date: 2006/10/21 16:03:54 $, $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       * Convenience method that looks up the prediction for a given type.
92       *
93       * @param type the type to look up
94       * @return the prediction for the given type, or <code>null</code> if there
95       * is no prediction of that {@linkplain Prediction#getType() type} in this
96       * distribution
97       */
98      public Prediction getPredictionForType(final String type) {
99          final Iterator<Prediction> predIter = iterator();
100         Prediction currentPred;
101 
102         // find matching prediction
103         while (predIter.hasNext()) {
104             currentPred = predIter.next();
105             if (currentPred.getType().equals(type)) {
106                 // got it!
107                 return currentPred;
108             }
109         }
110 
111         // no match
112         return null;
113     }
114 
115     /***
116      * Returns an iterator over the predictions in this distribution,
117      * in descending order (most probably class comes first).
118      *
119      * @return an iterator over the predictions
120      */
121     public Iterator<Prediction> iterator() {
122         return store.iterator();
123     }
124 
125     /***
126      * Returns the number of predictions (classes) in this distribution.
127      *
128      * @return the number of predictions
129      */
130     public int size() {
131         return store.size();
132     }
133 
134     /***
135      * Returns a string representation of this object.
136      *
137      * @return a textual representation
138      */
139     public String toString() {
140         return new ToStringBuilder(this)
141             .append("stored predictions", store)
142             .toString();
143     }
144 
145 }