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.winnow;
23  
24  import de.fu_berlin.ties.classify.Prediction;
25  import de.fu_berlin.ties.classify.Probability;
26  import de.fu_berlin.ties.eval.EvalStatus;
27  import de.fu_berlin.ties.io.FieldMap;
28  import de.fu_berlin.ties.util.Util;
29  
30  /***
31   * A prediction that also stores a raw score (activation value) and a normalized
32   * score, as calculated by the {@link de.fu_berlin.ties.classify.winnow.Winnow}
33   * algorithm. The {@linkplain de.fu_berlin.ties.classify.Probability#getPR() pR}
34   * is never set by this class.
35   *
36   * @author Christian Siefkes
37   * @version $Revision: 1.13 $, $Date: 2006/10/21 16:03:59 $, $Author: siefkes $
38   */
39  public class WinnowPrediction extends Prediction {
40  
41      /***
42       * Serialization key for the predicted class.
43       */
44      public static final String KEY_RAW = "Raw Score";
45  
46      /***
47       * Serialization key for the source identifier.
48       */
49      public static final String KEY_NORMALIZED = "Normalized Score";
50  
51      /***
52       * The raw score (activation value) of this prediction.
53       */
54      private final float rawScore;
55  
56      /***
57       * The {@link Winnow#normalizeScore(float, float, float) normalized score}
58       * (activation value) of this prediction; a non-negative value.
59       */
60      private final float normalizedScore;
61  
62      /***
63       * Creates a new instance from a field map, fulfilling the
64       * {@link de.fu_berlin.ties.io.Storable} contract.
65       *
66       * @param fieldMap map containing the serialized fields
67       */
68      public WinnowPrediction(final FieldMap fieldMap) {
69          super(fieldMap);
70          rawScore = Util.asFloat(fieldMap.get(KEY_RAW));
71          normalizedScore = Util.asFloat(fieldMap.get(KEY_NORMALIZED));
72  
73          // check argument
74          if ((normalizedScore < 0.0)) {
75              throw new IllegalArgumentException(
76                  "Illegal normalized score (negative): " + normalizedScore);
77          }
78      }
79  
80      /***
81       * Creates a new instance, setting the evaluation status to
82       * {@link EvalStatus#UNKNOWN}.
83       *
84       * @param predicted the predicted type
85       * @param prob the probability of the prediction (must be in the range from
86       * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
87       * @param raw the raw score (activation value) of this prediction
88       * @param normalized the {@link Winnow#normalizeScore(float, float, float)
89       * normalized score} (activation value) of this prediction; must be a
90       * non-negative value
91       */
92      public WinnowPrediction(final String predicted, final double prob,
93              final float raw, final float normalized) {
94          this(predicted, prob, raw, normalized, EvalStatus.UNKNOWN);
95      }
96  
97      /***
98       * Creates a new instance, without setting a source ID.
99       *
100      * @param predicted the predicted type
101      * @param prob the probability of the prediction (must be in the range from
102      * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
103      * @param raw the raw score (activation value) of this prediction
104      * @param normalized the {@link Winnow#normalizeScore(float, float, float)
105      * normalized score} (activation value) of this prediction; must be a
106      * non-negative value
107      * @param status the {@linkplain EvalStatus evaluation status} of this
108      * instance
109      */
110     public WinnowPrediction(final String predicted, final double prob,
111             final float raw, final float normalized, final EvalStatus status) {
112         this(predicted, null, prob, raw, normalized, status);
113     }
114 
115     /***
116      * Creates a new instance.
117      *
118      * @param predicted the predicted type
119      * @param sourceID an identifier of the source of this prediction (e.g., the
120      * file name), might be <code>null</code>
121      * @param prob the probability of the prediction (must be in the range from
122      * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
123      * @param raw the raw score (activation value) of this prediction
124      * @param normalized the {@link Winnow#normalizeScore(float, float, float)
125      * normalized score} (activation value) of this prediction; must be a
126      * non-negative value
127      * @param status the {@linkplain EvalStatus evaluation status} of this
128      * instance
129      */
130     public WinnowPrediction(final String predicted, final String sourceID,
131             final double prob, final float raw, final float normalized,
132             final EvalStatus status) {
133         super(predicted, sourceID, new Probability(prob), status);
134 
135         // check argument
136         if ((normalized < 0.0)) {
137             throw new IllegalArgumentException(
138                 "Illegal normalized score (negative): " + normalized);
139         }
140 
141         rawScore = raw;
142         normalizedScore = normalized;
143     }
144 
145     /***
146      * Returns the {@link Winnow#normalizeScore(float, float, float) normalized
147      * score} (activation value) of this prediction.
148      *
149      * @return the value of the attribute
150      */
151     public float getNormalizedScore() {
152         return normalizedScore;
153     }
154 
155     /***
156      * Returns the raw score (activation value) of this prediction.
157      * @return the value of the attribute
158      */
159     public float getRawScore() {
160         return rawScore;
161     }
162 
163     /***
164      * Stores all relevant fields of this object in a field map for
165      * serialization. An equivalent object can be created by calling
166      * {@link de.fu_berlin.ties.io.FieldMap#createObject(Class)} on the created
167      * field map.
168      *
169      * @return the created field map
170      */
171     public FieldMap storeFields() {
172         final FieldMap result = super.storeFields();
173         result.put(KEY_RAW, new Float(rawScore));
174         result.put(KEY_NORMALIZED, new Float(normalizedScore));
175         return result;
176     }
177 
178 }