edu.northwestern.at.utils.math

## Class Probability

- java.lang.Object
- - edu.northwestern.at.utils.math.Probability

- All Implemented Interfaces:
    XCloneable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

      public class Probability
      extends java.lang.Object
      implements XCloneable, java.lang.Comparable, java.io.Serializable

  Probability: stores and operates on log probabilties.

  When working with large numbers of small probabilities, it is helpful to work in "log space", e.g., the natural log of the probabilities, to avoid problems with overflow and underflow. This class provides for storing a probability in log form, and adding, substracting, multiplying, and dividing the log probabilities to minimize accuracy loss.

  Probabilities must be floating point values from zero through one inclusive, e.g., [0 , 1].

  A probability of zero is stored as -infinity, which correctly propagates through arithmetic operations. The value of exp(-infinity) is 0.0 as it should be.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected double` | `logProbability` Natural log of the probability.
    `static Probability` | `ONE_PROBABILITY` One probability.
    `static Probability` | `ZERO_PROBABILITY` Zero probability.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Probability()` Create a Probability.
    `Probability(double probability)` Create a Probability.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `clone()` Get clone of this object.
    `int` | `compareTo(java.lang.Object object)` Compare this probability to another.
    `boolean` | `equals(java.lang.Object object)` Test for this probability equaling another.
    `double` | `getLogProbability()` Get log probability.
    `double` | `getProbability()` Get probability.
    `int` | `hashCode()` Get a hash code for this object.
    `Probability` | `multiply(Probability otherProbability)` Multiply this probability by another.
    `Probability` | `multiply(Probability otherProbability1, Probability otherProbability2)` Multiply this probability by two others.
    `Probability` | `multiply(Probability otherProbability1, Probability otherProbability2, Probability otherProbability3)` Multiply this probability by three others.
    `void` | `setLogProbability(double logProbability)` Set the log probability.
    `void` | `setProbability(double probability)` Set the probability.
    `java.lang.String` | `toString()` Return string version of probability.

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### logProbability

          protected double logProbability

      Natural log of the probability.

    - #### ZERO_PROBABILITY

          public static final Probability ZERO_PROBABILITY

      Zero probability.

    - #### ONE_PROBABILITY

          public static final Probability ONE_PROBABILITY

      One probability.

  - ### Constructor Detail

    - #### Probability

          public Probability()
                      throws java.lang.IllegalArgumentException

      Create a Probability.
      Throws:
        `java.lang.IllegalArgumentException`

    - #### Probability

          public Probability(double probability)
                      throws java.lang.IllegalArgumentException

      Create a Probability.
      Parameters:
        `probability` - Probability value in range 0 through 1 inclusive.
      Throws:
        `java.lang.IllegalArgumentException`

  - ### Method Detail

    - #### setProbability

          public void setProbability(double probability)
                              throws java.lang.IllegalArgumentException

      Set the probability.
      Parameters:
        `probability` - Probability value in range 0 through 1 inclusive.
      Throws:
        `java.lang.IllegalArgumentException` - If probability is not in the range 0 through 1 inclusive.

    - #### setLogProbability

          public void setLogProbability(double logProbability)
                                 throws java.lang.IllegalArgumentException

      Set the log probability.
      Parameters:
        `logProbability` - Log probability value in range -infinity through 0 inclusive.
      Throws:
        `java.lang.IllegalArgumentException` - If probability is not in the range -infinity through 0 inclusive.

    - #### getProbability

          public double getProbability()

      Get probability.
      Returns:
        probability from 0 through 1 inclusive.

        Note: This can overflow!

    - #### getLogProbability

          public double getLogProbability()

      Get log probability.
      Returns:
        log probability from -infinity through 0 inclusive.

    - #### multiply

          public Probability multiply(Probability otherProbability)

      Multiply this probability by another.
      Parameters:
        `otherProbability` - The other probability.
      Returns:
        Resulting probability.

    - #### multiply

          public Probability multiply(Probability otherProbability1,
                             Probability otherProbability2)

      Multiply this probability by two others.
      Parameters:
        `otherProbability1` - First other probability.
        `otherProbability2` - Second other probability.
      Returns:
        Resulting probability.

    - #### multiply

          public Probability multiply(Probability otherProbability1,
                             Probability otherProbability2,
                             Probability otherProbability3)

      Multiply this probability by three others.
      Parameters:
        `otherProbability1` - First other probability.
        `otherProbability2` - Second other probability.
        `otherProbability3` - Third other probability.
      Returns:
        Resulting probability.

    - #### toString

          public java.lang.String toString()

      Return string version of probability.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        Probability converted to string.

    - #### clone

          public java.lang.Object clone()

      Get clone of this object.
      Specified by:
        `clone` in interface `XCloneable`
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        Clone of this object.

    - #### compareTo

          public int compareTo(java.lang.Object object)

      Compare this probability to another.
      Specified by:
        `compareTo` in interface `java.lang.Comparable`
      Parameters:
        `object` - The other probability.

    - #### equals

          public boolean equals(java.lang.Object object)

      Test for this probability equaling another.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `object` - Other object, presumably a Probability.
      Returns:
        true if other object is equal to this one.

    - #### hashCode

          public int hashCode()

      Get a hash code for this object.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        The hash code.

        Hash code same as for a Double.