ConditionalProbabilityDistribution.java

package aima.core.probability.bayes;

import java.util.Set;

import aima.core.probability.ProbabilityDistribution;
import aima.core.probability.RandomVariable;
import aima.core.probability.proposition.AssignmentProposition;

/**
 * A conditional probability distribution on a RandomVariable X<sub>i</sub>:<br>
 * <br>
 * P(X<sub>i</sub> | Parents(X<sub>i</sub>)) that quantifies the effect of the
 * parents on X<sub>i</sub>.
 * 
 * @author Ciaran O'Reilly
 * 
 */
public interface ConditionalProbabilityDistribution {
	/**
	 * @return the Random Variable this conditional probability distribution is
	 *         on.
	 */
	RandomVariable getOn();

	/**
	 * @return a consistent ordered Set (e.g. LinkedHashSet) of the parent
	 *         Random Variables for this conditional distribution.
	 */
	Set<RandomVariable> getParents();

	/**
	 * A convenience method for merging the elements of getParents() and getOn()
	 * into a consistent ordered set (i.e. getOn() should always be the last
	 * Random Variable returned when iterating over the set).
	 * 
	 * @return a consistent ordered Set (e.g. LinkedHashSet) of the random
	 *         variables this conditional probability distribution is for.
	 */
	Set<RandomVariable> getFor();

	/**
	 * 
	 * @param rv
	 *            the Random Variable to be checked.
	 * @return true if the conditional distribution is for the passed in Random
	 *         Variable, false otherwise.
	 */
	boolean contains(RandomVariable rv);

	/**
	 * Get the value for the provided set of values for the random variables
	 * comprising the Conditional Distribution (ordering and size of each must
	 * equal getFor() and their domains must match).
	 * 
	 * @param eventValues
	 *            the values for the random variables comprising the Conditional
	 *            Distribution
	 * @return the value for the possible worlds associated with the assignments
	 *         for the random variables comprising the Conditional Distribution.
	 */
	double getValue(Object... eventValues);

	/**
	 * Get the value for the provided set of AssignmentPropositions for the
	 * random variables comprising the Conditional Distribution (size of each
	 * must equal and their random variables must match).
	 * 
	 * @param eventValues
	 *            the assignment propositions for the random variables
	 *            comprising the Conditional Distribution
	 * @return the value for the possible worlds associated with the assignments
	 *         for the random variables comprising the Conditional Distribution.
	 */
	double getValue(AssignmentProposition... eventValues);

	/**
	 * A conditioning case is just a possible combination of values for the
	 * parent nodes - a miniature possible world, if you like. The returned
	 * distribution must sum to 1, because the entries represent an exhaustive
	 * set of cases for the random variable.
	 * 
	 * @param parentValues
	 *            for the conditioning case. The ordering and size of
	 *            parentValues must equal getParents() and their domains must
	 *            match.
	 * @return the Probability Distribution for the Random Variable the
	 *         Conditional Probability Distribution is On.
	 * @see ConditionalProbabilityDistribution#getOn()
	 * @see ConditionalProbabilityDistribution#getParents()
	 */
	ProbabilityDistribution getConditioningCase(Object... parentValues);

	/**
	 * A conditioning case is just a possible combination of values for the
	 * parent nodes - a miniature possible world, if you like. The returned
	 * distribution must sum to 1, because the entries represent an exhaustive
	 * set of cases for the random variable.
	 * 
	 * @param parentValues
	 *            for the conditioning case. The size of parentValues must equal
	 *            getParents() and their Random Variables must match.
	 * @return the Probability Distribution for the Random Variable the
	 *         Conditional Probability Distribution is On.
	 * @see ConditionalProbabilityDistribution#getOn()
	 * @see ConditionalProbabilityDistribution#getParents()
	 */
	ProbabilityDistribution getConditioningCase(
			AssignmentProposition... parentValues);

	/**
	 * Retrieve a specific example for the Random Variable this conditional
	 * distribution is on.
	 * 
	 * @param probabilityChoice
	 *            a double value, from the range [0.0d, 1.0d), i.e. 0.0d
	 *            (inclusive) to 1.0d (exclusive).
	 * @param parentValues
	 *            for the conditioning case. The ordering and size of
	 *            parentValues must equal getParents() and their domains must
	 *            match.
	 * @return a sample value from the domain of the Random Variable this
	 *         distribution is on, based on the probability argument passed in.
	 * @see ConditionalProbabilityDistribution#getOn()
	 */
	Object getSample(double probabilityChoice, Object... parentValues);

	/**
	 * Retrieve a specific example for the Random Variable this conditional
	 * distribution is on.
	 * 
	 * @param probabilityChoice
	 *            a double value, from the range [0.0d, 1.0d), i.e. 0.0d
	 *            (inclusive) to 1.0d (exclusive).
	 * @param parentValues
	 *            for the conditioning case. The size of parentValues must equal
	 *            getParents() and their Random Variables must match.
	 * @return a sample value from the domain of the Random Variable this
	 *         distribution is on, based on the probability argument passed in.
	 * @see ConditionalProbabilityDistribution#getOn()
	 */
	Object getSample(double probabilityChoice,
			AssignmentProposition... parentValues);
}