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.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 sigmoid
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.8 $, $Date: 2004/11/19 14:04:28 $, $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_SIGMOID = "Sigmoid Score";
50  
51      /***
52       * The raw score (activation value) of this prediction.
53       */
54      private final float rawScore;
55  
56      /***
57       * The {@link Winnow#sigmoid(float, float, float) sigmoid score} (activation
58       * value) of this prediction; a value in the range from 0 to 1.
59       */
60      private final float sigmoidScore;
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          sigmoidScore = Util.asFloat(fieldMap.get(KEY_SIGMOID));
72  
73          // check argument
74          if ((sigmoidScore < 0.0) || (sigmoidScore > 1.0)) {
75              throw new IllegalArgumentException(
76                  "Illegal sigmoid score (out of range from 0 to 1): "
77                  + sigmoidScore);
78          }
79      }
80  
81      /***
82       * Creates a new instance, setting the evaluation status to
83       * {@link EvalStatus#UNKNOWN}.
84       *
85       * @param predicted the predicted type
86       * @param prob the probability of the prediction (must be in the range from
87       * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
88       * @param raw the raw score (activation value) of this prediction
89       * @param sigmoid the {@link Winnow#sigmoid(float, float, float) sigmoid
90       * score} (activation value) of this prediction; must be a value in the
91       * range from 0 to 1
92       */
93      public WinnowPrediction(final String predicted, final double prob,
94              final float raw, final float sigmoid) {
95          this(predicted, prob, raw, sigmoid, EvalStatus.UNKNOWN);
96      }
97  
98      /***
99       * Creates a new instance, without setting a source ID.
100      *
101      * @param predicted the predicted type
102      * @param prob the probability of the prediction (must be in the range from
103      * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
104      * @param raw the raw score (activation value) of this prediction
105      * @param sigmoid the {@link Winnow#sigmoid(float, float, float) sigmoid
106      * score} (activation value) of this prediction; must be a value in the
107      * range from 0 to 1
108      * @param status the {@linkplain EvalStatus evaluation status} of this
109      * instance
110      */
111     public WinnowPrediction(final String predicted, final double prob,
112             final float raw, final float sigmoid, final EvalStatus status) {
113         this(predicted, null, prob, raw, sigmoid, status);
114     }
115 
116     /***
117      * Creates a new instance.
118      *
119      * @param predicted the predicted type
120      * @param sourceID an identifier of the source of this prediction (e.g., the
121      * file name), might be <code>null</code>
122      * @param prob the probability of the prediction (must be in the range from
123      * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
124      * @param raw the raw score (activation value) of this prediction
125      * @param sigmoid the {@link Winnow#sigmoid(float, float, float) sigmoid
126      * score} (activation value) of this prediction; must be a value in the
127      * range from 0 to 1
128      * @param status the {@linkplain EvalStatus evaluation status} of this
129      * instance
130      */
131     public WinnowPrediction(final String predicted, final String sourceID,
132             final double prob, final float raw, final float sigmoid,
133             final EvalStatus status) {
134         super(predicted, sourceID, new Probability(prob), status);
135 
136         // check argument
137         if ((sigmoid < 0.0) || (sigmoid > 1.0)) {
138             throw new IllegalArgumentException(
139                 "Illegal sigmoid score (out of range from 0 to 1): " + sigmoid);
140         }
141 
142         rawScore = raw;
143         sigmoidScore = sigmoid;
144     }
145 
146     /***
147      * Returns the raw score (activation value) of this prediction.
148      * @return the value of the attribute
149      */
150     public float getRawScore() {
151         return rawScore;
152     }
153 
154     /***
155      * Returns the {@link Winnow#sigmoid(float, float, float) sigmoid score}
156      * (activation value) of this prediction.
157      *
158      * @return the value of the attribute; a value in the range from 0 to 1
159      */
160     public float getSigmoidScore() {
161         return sigmoidScore;
162     }
163 
164     /***
165      * Stores all relevant fields of this object in a field map for
166      * serialization. An equivalent object can be created by calling
167      * {@link de.fu_berlin.ties.io.FieldMap#createObject(Class)} on the created
168      * field map.
169      *
170      * @return the created field map
171      */
172     public FieldMap storeFields() {
173         final FieldMap result = super.storeFields();
174         result.put(KEY_RAW, new Float(rawScore));
175         result.put(KEY_SIGMOID, new Float(sigmoidScore));
176         return result;
177     }
178 
179 }