cc.mallet.grmm.types
Interface Factor

All Superinterfaces:
java.lang.Cloneable, java.io.Serializable
All Known Subinterfaces:
DiscreteFactor, ParameterizedFactor
All Known Implementing Classes:
AbstractFactor, AbstractTableFactor, ACRF.UnrolledGraph, Assignment, BetaFactor, BinaryUnaryFactor, BoltzmannPairFactor, BoltzmannUnaryFactor, ConstantFactor, CPT, DirectedModel, FactorGraph, LabelsAssignment, LogTableFactor, NormalFactor, PottsTableFactor, SkeletonFactor, TableFactor, UndirectedGrid, UndirectedModel, UniformFactor, UniNormalFactor

public interface Factor
extends java.lang.Cloneable, java.io.Serializable

Interface for multivariate discrete probability distributions. All distributions are assumed to be over 0...k. If you want a distribution over some other discrete set, use the @see getAlphabet and @see setAlphabet members. (I thought about having a single Potential interface, for both continuous and discrete, but then all the method parameters were java.lang.Object, and the lack of type safety was both inefficient and disturbing.) Created: Mon Sep 15 14:04:58 2003

Version:
$Id: Factor.java,v 1.1 2007/10/22 21:37:44 mccallum Exp $
Author:
Charles Sutton

Method Summary
 boolean almostEquals(Factor p)
          Returns whether this is almost equal to another potential.
 boolean almostEquals(Factor p, double epsilon)
           
 int argmax()
          Returns the assignment that maximizes this potential.
 AssignmentIterator assignmentIterator()
          Returns an iterator over all Assignmentss to this potential.
 AbstractTableFactor asTable()
           
 boolean containsVar(Variable var)
          Returns whether the potential is over the given variable.
 void divideBy(Factor pot)
          Computes this /= pot
 java.lang.String dumpToString()
           
 Factor duplicate()
           
 double entropy()
          Returns the expected log factor value, i.e., sum_x factor.value(x) * Math.log (factor.value (x)) where the summation is taken over all passible assignments.
 void exponentiate(double power)
           
 Factor extractMax(java.util.Collection vars)
          Returns a potential phi over the given variables obtained by taking phi (x) = max_[all v that contain x] this.prob (x)
 Factor extractMax(Variable var)
          Returns a potential phi over the given variables obtained by taking phi (x) = max_[all v that contain x] this.prob (x)
 Factor extractMax(Variable[] vars)
          Returns a potential phi over the given variables obtained by taking phi (x) = max_[all v that contain x] this.prob (x)
 Variable getVariable(int i)
           
 boolean isNaN()
           
 double logValue(Assignment assn)
           
 double logValue(AssignmentIterator it)
           
 double logValue(int loc)
           
 Factor marginalize(java.util.Collection vars)
          Returns the marginal of this distribution over the given variables.
 Factor marginalize(Variable var)
          Returns the marginal of this distribution over one variable.
 Factor marginalize(Variable[] vars)
          Returns the marginal of this distribution over the given variables.
 Factor marginalizeOut(Variable var)
          Returns the marginal distribution attained by summing out the given variable.
 Factor marginalizeOut(VarSet varset)
          Returns the marginal distribution attained by summing out the given set of variables.
 Factor multiply(Factor dist)
          Returns the elementwise product of this factor with another.
 void multiplyBy(Factor pot)
          Does this *= pot.
 Factor normalize()
          Multiplies this potential by a constant such that it sums to 1.
 java.lang.String prettyOutputString()
           
 Assignment sample(Randoms r)
          Return an assignment sampled from this factor, interpreting it as an unnormalized probability distribution.
 Factor slice(Assignment assn)
           
 double sum()
          Returns the sum of this potential over all cases.
 double value(Assignment assn)
          Returns the value of the local function for a given assignment.
 double value(AssignmentIterator it)
          Returns the probability of an assignment to these variables.
 VarSet varSet()
          Returns set of variables in this potential.
 

Method Detail

value

double value(Assignment assn)
Returns the value of the local function for a given assignment. All variables in the potential must be included, but it's okay if the assignment uses variables not in the potential.


value

double value(AssignmentIterator it)
Returns the probability of an assignment to these variables. The assignment used is the curret assignment from the given AssignmentIterator.

This can be used to do things like

         DiscretePotential phi = createMyPtl ();
         for (AssignmentIterator it = phi.assignmentIterator; it.hasNext(); it.advance()) {
           double val = ptl.phi (it);
                 // do something with val
   }
  

This is equivalent to creating an assignment object explicitly using (Assignment) it.next(), but can be much faster.


normalize

Factor normalize()
Multiplies this potential by a constant such that it sums to 1. Destructive; returns this factor.


marginalize

Factor marginalize(Variable[] vars)
Returns the marginal of this distribution over the given variables.


marginalize

Factor marginalize(java.util.Collection vars)
Returns the marginal of this distribution over the given variables.


marginalize

Factor marginalize(Variable var)
Returns the marginal of this distribution over one variable.


marginalizeOut

Factor marginalizeOut(Variable var)
Returns the marginal distribution attained by summing out the given variable.


marginalizeOut

Factor marginalizeOut(VarSet varset)
Returns the marginal distribution attained by summing out the given set of variables.


extractMax

Factor extractMax(java.util.Collection vars)
Returns a potential phi over the given variables obtained by taking phi (x) = max_[all v that contain x] this.prob (x)


extractMax

Factor extractMax(Variable var)
Returns a potential phi over the given variables obtained by taking phi (x) = max_[all v that contain x] this.prob (x)


extractMax

Factor extractMax(Variable[] vars)
Returns a potential phi over the given variables obtained by taking phi (x) = max_[all v that contain x] this.prob (x)


argmax

int argmax()
Returns the assignment that maximizes this potential.


sample

Assignment sample(Randoms r)
Return an assignment sampled from this factor, interpreting it as an unnormalized probability distribution.


sum

double sum()
Returns the sum of this potential over all cases.


entropy

double entropy()
Returns the expected log factor value, i.e., sum_x factor.value(x) * Math.log (factor.value (x)) where the summation is taken over all passible assignments.


multiply

Factor multiply(Factor dist)
Returns the elementwise product of this factor with another.


multiplyBy

void multiplyBy(Factor pot)
Does this *= pot.

If both potentials are currently in log space, then does addition instead.

Throws:
java.lang.UnsupportedOperationException - If one potential is in log space and the other isn't.

exponentiate

void exponentiate(double power)

divideBy

void divideBy(Factor pot)
Computes this /= pot

If both potentials are currently in log space, then does subtraction instead.

Throws:
java.lang.UnsupportedOperationException - If one potential is in log space and the other isn't.

containsVar

boolean containsVar(Variable var)
Returns whether the potential is over the given variable.


varSet

VarSet varSet()
Returns set of variables in this potential.


assignmentIterator

AssignmentIterator assignmentIterator()
Returns an iterator over all Assignmentss to this potential.


almostEquals

boolean almostEquals(Factor p)
Returns whether this is almost equal to another potential.


almostEquals

boolean almostEquals(Factor p,
                     double epsilon)

duplicate

Factor duplicate()

isNaN

boolean isNaN()

logValue

double logValue(AssignmentIterator it)

logValue

double logValue(Assignment assn)

logValue

double logValue(int loc)

getVariable

Variable getVariable(int i)

dumpToString

java.lang.String dumpToString()

prettyOutputString

java.lang.String prettyOutputString()

slice

Factor slice(Assignment assn)

asTable

AbstractTableFactor asTable()