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 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.1 $, $Date: 2004/11/19 14:04:19 $, $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 from
56       * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
57       */
58      public Probability(final double theProb) {
59          this(theProb, Double.NaN);
60      }
61  
62      /***
63       * Creates a new instance.
64       *
65       * @param theProb the probability of the prediction (must be in the range from
66       * 0.0 to 1.0; or -1 if this is a confirmed prediction or an answer key)
67       * @param thePR the {@linkplain #getPR() pR} of the prediction;
68       * or {@link Double#NaN} if not known
69       */
70      public Probability(final double theProb, final double thePR) {
71          super();
72          // check arguments
73          if (((theProb < 0.0) && (theProb != -1.0)) || (theProb > 1.0)) {
74              throw new IllegalArgumentException("Not a probability: " + theProb);
75          }
76          prob = theProb;
77          pR = thePR;
78      }
79  
80      
81      /***
82       * Returns the optional pR: <em>pR</em> = log(<em>p</em> /
83       * (1-<em>p</em>)); or {@link Double#NaN} if not known/not relevant.
84       *
85       * @return the value of the attribute
86       */
87      public double getPR() {
88          return pR;
89      }
90  
91      /***
92       * Returns the actual probability; will be in value in the range from
93       * 0 to 1; or -1 if the actual value is unknown/not applicable.
94       *
95       * @return the value of the attribute
96       */
97      public double getProb() {
98          return prob;
99      }
100 
101     /***
102      * Returns a string representation of this object.
103      *
104      * @return a textual representation
105      */
106     public String toString() {
107         final ToStringBuilder builder = new ToStringBuilder(this)
108             .append(prob);
109 
110         // omit pR if not-a-number, i.e. unknown
111         if (!Double.isNaN(pR)) {
112             builder.append("pR", pR);
113         }
114 
115         return builder.toString();
116     }
117 
118 }