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 org.apache.commons.lang.builder.ToStringBuilder;
25  
26  /***
27   * Wraps a probability. Optionally also wraps a "pR" value that can be used
28   * to decide between probabilities that are very similar
29   * (e.g. ~1.0), because it is less sensitive to rounding issues.
30   *
31   * Instance of this class are immutable and thus thread-safe.
32   * 
33   * @author Christian Siefkes
34   * @version $Revision: 1.5 $, $Date: 2006/10/21 16:03:55 $, $Author: siefkes $
35   */
36  public class Probability {
37  
38      /***
39       * The actual probability; must be in value in the range from 0 to 1; or -1
40       * if the actual value is unknown/not applicable.
41       */
42      private double prob;
43  
44      /***
45       * An optional pR: <em>pR</em> = log(<em>p</em> /
46       * (1-<em>p</em>)); or {@link Double#NaN} if not known/not relevant.
47       */
48      private double pR;
49  
50  
51      /***
52       * Creates a new instance, setting the {@linkplain #getPR() pR} to
53       * {@link Double#NaN} (unknown).
54       *
55       * @param theProb the probability of the prediction (must be in the range
56       * from 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer
57       * key)
58       */
59      public Probability(final double theProb) {
60          this(theProb, Double.NaN);
61      }
62  
63      /***
64       * Creates a new instance.
65       *
66       * @param theProb the probability of the prediction (must be in the range
67       * from 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer
68       * key)
69       * @param thePR the {@linkplain #getPR() pR} of the prediction;
70       * or {@link Double#NaN} if not known
71       */
72      public Probability(final double theProb, final double thePR) {
73          super();
74          // check arguments
75          if (((theProb < 0.0) && (theProb != -1.0)) || (theProb > 1.0)) {
76              throw new IllegalArgumentException("Not a probability: " + theProb);
77          }
78          prob = theProb;
79          pR = thePR;
80      }
81  
82  
83      /***
84       * Returns the optional pR: <em>pR</em> = log(<em>p</em> /
85       * (1-<em>p</em>)); or {@link Double#NaN} if not known/not relevant.
86       *
87       * @return the value of the attribute
88       */
89      public double getPR() {
90          return pR;
91      }
92  
93      /***
94       * Returns the actual probability; will be in value in the range from
95       * 0 to 1; or -1 if the actual value is unknown/not applicable.
96       *
97       * @return the value of the attribute
98       */
99      public double getProb() {
100         return prob;
101     }
102 
103     /***
104      * Returns a string representation of this object.
105      *
106      * @return a textual representation
107      */
108     public String toString() {
109         final ToStringBuilder builder = new ToStringBuilder(this)
110             .append(prob);
111 
112         // omit pR if not-a-number, i.e. unknown
113         if (!Double.isNaN(pR)) {
114             builder.append("pR", pR);
115         }
116 
117         return builder.toString();
118     }
119 
120 }