Package com.isaac_lef.probability

Class Probability

java.lang.Object
com.isaac_lef.probability.Probability
All Implemented Interfaces:
Serializable, Comparable<Probability>
public final class Probability extends Object implements Comparable<Probability>, Serializable
Immutable class representing measures of chance/likelihood, supporting many units: probability, log probability, odds, log odds, probit.
Author:
Isaac Lefebvre
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    CERTAIN
    The maximum value for probabilities, corresponding to an event that always happens.
    static final double
    CERTAIN_LOGODDS
    The maximum value for log-odds, corresponding to an event that always happens.
    static final double
    CERTAIN_LOGPROBA
    The maximum value for log-probabilities, corresponding to an event that always happens.
    static final double
    CERTAIN_ODDS
    The maximum value for odds, corresponding to an event that always happens.
    static final double
    CERTAIN_PROBIT
    The maximum value for odds, corresponding to an event that always happens.
    static final double
    IMPOSSIBLE
    The minimum value for probabilities, corresponding to an event that never happens.
    static final double
    IMPOSSIBLE_LOGODDS
    The minimum value for log-odds, corresponding to an event that never happens.
    static final double
    IMPOSSIBLE_LOGPROBA
    The minimum value for log-probabilities, corresponding to an event that never happens.
    static final double
    IMPOSSIBLE_ODDS
    The minimum value for odds, corresponding to an event that never happens.
    static final double
    IMPOSSIBLE_PROBIT
    The minimum value for probits, corresponding to an event that never happens.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Probability(double value)
    Constructs a newly allocated Probability object from the given value.

  • Method Summary

    Modifier and Type
    Method
    Description
    Probability
    add(Probability addend)
    Returns the sum between the current probability and the given probability.
    boolean
    apply()
    Returns true at random, with a chance matching the value it holds.
    <T> boolean
    apply(T t)
    A Predicate that takes whatever object/value, and returns the result of apply().
    static Probability
    certain()
    Returns a probability corresponding to a certain event.
    static int
    compare(Probability p1, Probability p2)
    Compares the value() of the two given probabilities, using Double.compare(double, double).
    int
    compareTo(Probability probability)
    Compares the value() of the caller Probability with that of the given Probability, using Double.compareTo(Double).
    Probability
    complement()
    Assuming the current Probability corresponds to an event E, this returns the probability of the complement event not(E).
    Probability
    divide(Probability divisor)
    Returns the division between the current probability and the given probability.
    boolean
    equals(Object obj)
    Returns whether this probability is equal to the given obj.
    static Probability
    fromLogOdds(double logOdds)
    Converts the given log-odds to a probability.
    static Probability
    fromLogOdds(double logOdds, double base)
    Converts the given log-odds to a probability, using a specified logarithm base.
    static Probability
    fromLogProbability(double logProba)
    Converts the given log-probability to a probability.
    static Probability
    fromLogProbability(double logProba, double base)
    Converts the given log-probability to a probability, using a specified logarithm base.
    static Probability
    fromOdds(double odds)
    Converts the given odds to a probability.
    static Probability
    fromProbit(double probit)
    Converts the given probit to a probability.
    static Probability
    impossible()
    Returns a probability corresponding to an impossible event.
    boolean
    isCertain()
    Returns whether this probability corresponds to a certain event.
    boolean
    isImpossible()
    Returns whether this probability corresponds to an impossible event.
    protected static SecureRandom
    makeSecureRandom()
    Creates and returns one of the strongest possible instances of SecureRandom.
    Probability
    multiply(Probability factor)
    Returns the product between the current probability and the given probability.
    Probability
    pow(double exponent)
    Returns the current probability raised to the power of the given exponent.
    boolean
    secureApply()
    Returns true at random, with a chance matching the value it holds.
    Probability
    subtract(Probability subtrahend)
    Returns the subtraction between the current probability and the given probability.
    double
    toLogOdds()
    Converts a probability into log-odds.
    double
    toLogOdds(double base)
    Converts a probability into log-odds, using a specified logarithm base.
    double
    toLogProbability()
    Converts a probability into a log-probability.
    double
    toLogProbability(double base)
    Converts a probability into a log-probability, using a specified logarithm base.
    double
    toOdds()
    Converts a probability into odds.
    double
    toProbit()
    Converts a probability into a probit.
    String
    toString()
    Returns a String representation of this probability.
    double
    value()
    Access the value of the probability.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • IMPOSSIBLE

      public static final double IMPOSSIBLE
      The minimum value for probabilities, corresponding to an event that never happens.
      See Also:

    • CERTAIN

      public static final double CERTAIN
      The maximum value for probabilities, corresponding to an event that always happens.
      See Also:

    • IMPOSSIBLE_ODDS

      public static final double IMPOSSIBLE_ODDS
      The minimum value for odds, corresponding to an event that never happens.
      See Also:

    • CERTAIN_ODDS

      public static final double CERTAIN_ODDS
      The maximum value for odds, corresponding to an event that always happens.
      See Also:

    • IMPOSSIBLE_LOGPROBA

      public static final double IMPOSSIBLE_LOGPROBA
      The minimum value for log-probabilities, corresponding to an event that never happens. True for a logarithm base greater than 1. For a base smaller than 1, the values are inverted.
      See Also:

    • CERTAIN_LOGPROBA

      public static final double CERTAIN_LOGPROBA
      The maximum value for log-probabilities, corresponding to an event that always happens. True for a logarithm base greater than 1. For a base smaller than 1, the values are inverted.
      See Also:

    • IMPOSSIBLE_LOGODDS

      public static final double IMPOSSIBLE_LOGODDS
      The minimum value for log-odds, corresponding to an event that never happens. True for a logarithm base greater than 1. For a base smaller than 1, the values are inverted.
      See Also:

    • CERTAIN_LOGODDS

      public static final double CERTAIN_LOGODDS
      The maximum value for log-odds, corresponding to an event that always happens. True for a logarithm base greater than 1. For a base smaller than 1, the values are inverted.
      See Also:

    • IMPOSSIBLE_PROBIT

      public static final double IMPOSSIBLE_PROBIT
      The minimum value for probits, corresponding to an event that never happens.
      See Also:

    • CERTAIN_PROBIT

      public static final double CERTAIN_PROBIT
      The maximum value for odds, corresponding to an event that always happens.
      See Also:

  • Constructor Details

    • Probability

      public Probability(double value)
      Constructs a newly allocated Probability object from the given value.
      Parameters:
      value - - a valid number between 0 and 1 included.

  • Method Details

    • fromOdds

      public static Probability fromOdds(double odds)
      Converts the given odds to a probability.
      Parameters:
      odds - - a valid number between 0 and +∞ included.
      Returns:
      a new Probability instance converted from odds.

    • fromLogProbability

      public static Probability fromLogProbability(double logProba)
      Converts the given log-probability to a probability. Natural logarithm (base e) is assumed.
      Parameters:
      logProba - - a valid number between -∞ and 0 included.
      Returns:
      a new Probability instance converted from logProba.
      See Also:

    • fromLogProbability

      public static Probability fromLogProbability(double logProba, double base)
      Converts the given log-probability to a probability, using a specified logarithm base.
      Parameters:
      logProba - - a valid number between -∞ and 0 if base is greater than 1, between 0 and +∞ otherwise.
      base - - the base of the logarithm, a valid positive number except 1.
      Returns:
      a new Probability instance converted from logProba.
      See Also:

    • fromLogOdds

      public static Probability fromLogOdds(double logOdds)
      Converts the given log-odds to a probability.
      Parameters:
      logOdds - - a valid number between -∞ and +∞ included.
      Returns:
      a new Probability instance converted from logOdds.
      See Also:

    • fromLogOdds

      public static Probability fromLogOdds(double logOdds, double base)
      Converts the given log-odds to a probability, using a specified logarithm base.
      Parameters:
      logOdds - - a valid number between -∞ and +∞ included.
      base - - the base of the logarithm, a valid positive number except 1.
      Returns:
      a new Probability instance converted from logOdds.
      See Also:

    • fromProbit

      public static Probability fromProbit(double probit)
      Converts the given probit to a probability.
      Parameters:
      probit - - a valid number between -∞ and +∞ included.
      Returns:
      a new Probability instance converted from probit.

    • impossible

      public static Probability impossible()
      Returns a probability corresponding to an impossible event.
      Returns:
      a Probability instance corresponding to an event that never occurs.

    • certain

      public static Probability certain()
      Returns a probability corresponding to a certain event.
      Returns:
      a Probability instance corresponding to an event that always occurs.

    • makeSecureRandom

      protected static SecureRandom makeSecureRandom()
      Creates and returns one of the strongest possible instances of SecureRandom.
      Returns:
      A SecureRandom instance, as strong as possible.

    • value

      public double value()
      Access the value of the probability.
      Returns:
      a double from 0 to 1 included.

    • complement

      public Probability complement()

      Assuming the current Probability corresponds to an event E, this returns the probability of the complement event not(E).

      Example : p is the probability of getting an even number when throwing a dice. then p.complement() is the probability of getting an odd number.

      Returns:
      P(¬E) as a new Probability instance.

    • add

      public Probability add(Probability addend)
      Returns the sum between the current probability and the given probability.
      Parameters:
      addend - - another Probability instance.
      Returns:
      a Probability intance containing the sum between the values of the caller and of the given Probability.

    • subtract

      public Probability subtract(Probability subtrahend)
      Returns the subtraction between the current probability and the given probability.
      Parameters:
      subtrahend - - another Probability instance.
      Returns:
      a Probability instance containing the value of the caller minus that of the given Probability.

    • multiply

      public Probability multiply(Probability factor)
      Returns the product between the current probability and the given probability.
      Parameters:
      factor - - another Probability instance.
      Returns:
      a Probability instance containing the product between the values of the caller and of the given Probability.

    • divide

      public Probability divide(Probability divisor)
      Returns the division between the current probability and the given probability.
      Parameters:
      divisor - - another Probability instance.
      Returns:
      a Probability instance containing the value of the caller divided by that of the given Probability.

    • pow

      public Probability pow(double exponent)
      Returns the current probability raised to the power of the given exponent.
      Parameters:
      exponent - - the exponent.
      Returns:
      a Probability instance containing the value of the caller Probability, raised to the power of the given exponent.

    • apply

      public boolean apply()

      Returns true at random, with a chance matching the value it holds.

      Example:

       Probability p = new Probability(0.5);
 if (p.apply()) {
     // this block has a 50% probability of being executed
 }

      Uses ThreadLocalRandom.

      Not cryptographically secure! For these cases, use secureApply() instead.

      Returns:
      true randomly with a probability of value(), false in all other cases.

    • apply

      public <T> boolean apply(T t)

      A Predicate that takes whatever object/value, and returns the result of apply().

      For use in Stream.filter() :

       
 Probability p = new Probability(0.5);
 int[] randomInts = IntStream.range(0, 1000)
        .filter(p::apply)
        .toArray();
      Type Parameters:
      T - - the runtime type of t.
      Parameters:
      t - - the input argument.
      Returns:
      a random boolean, independent from the input.

    • secureApply

      public boolean secureApply()

      Returns true at random, with a chance matching the value it holds.

      Cryptographically secure using SecureRandom.

      May block as entropy is being gathered. If cryptographic safety isn't required, use apply() for better performance.

      Returns:
      true randomly with a probability of value(), false in all other cases.

    • isImpossible

      public boolean isImpossible()
      Returns whether this probability corresponds to an impossible event.
      Returns:
      true if the caller Probability corresponds to an event that never occurs; false otherwise.

    • isCertain

      public boolean isCertain()
      Returns whether this probability corresponds to a certain event.
      Returns:
      true if the caller Probability corresponds to an event that always occurs; false otherwise.

    • toOdds

      public double toOdds()
      Converts a probability into odds.
      Returns:
      the caller Probability converted into odds, as a double.

    • toLogProbability

      public double toLogProbability()
      Converts a probability into a log-probability.
      Returns:
      the caller Probability converted into a log-probability, as a double.

    • toLogProbability

      public double toLogProbability(double base)
      Converts a probability into a log-probability, using a specified logarithm base.
      Parameters:
      base - - the base of the logarithm, a valid positive number except 1.
      Returns:
      the caller Probability converted into odds, as a double.

    • toLogOdds

      public double toLogOdds()
      Converts a probability into log-odds.
      Returns:
      the caller Probability converted into log-odds, as a double.

    • toLogOdds

      public double toLogOdds(double base)
      Converts a probability into log-odds, using a specified logarithm base.
      Parameters:
      base - - the base of the logarithm, a valid positive number except 1.
      Returns:
      the caller Probability converted into log-odds, as a double.

    • toProbit

      public double toProbit()
      Converts a probability into a probit.
      Returns:
      the caller Probability converted into a probit, as a double.

    • compareTo

      public int compareTo(Probability probability)
      Compares the value() of the caller Probability with that of the given Probability, using Double.compareTo(Double).
      Specified by:
      compareTo in interface Comparable<Probability>
      Parameters:
      probability - - the Probability to be compared.
      Returns:
      0 if the values are numerically identical; a value less than 0 if the caller is less than probability; and a value greater than 0 if the caller is greater than probability.

    • compare

      public static int compare(Probability p1, Probability p2)
      Compares the value() of the two given probabilities, using Double.compare(double, double).
      Parameters:
      p1 - - the first Probability to compare.
      p2 - - the second Probability to compare.
      Returns:
      0 if the values are numerically identical; a value less than 0 if p1 is less than p2; and a value greater than 0 if p1 is greater than p2.

    • equals

      public boolean equals(Object obj)
      Returns whether this probability is equal to the given obj.
      Overrides:
      equals in class Object
      Parameters:
      obj - - the object to be compared.
      Returns:
      true if the given obj is an instance of Probability with the same value(); false otherwise.

    • toString

      public String toString()
      Returns a String representation of this probability.
      Overrides:
      toString in class Object
      Returns:
      a String representation of the caller Probability, as a percentage.