dai::TFactor< T > Class Template Reference

Represents a (probability) factor. More...

#include <dai/factor.h>

Inheritance diagram for dai::TFactor< T >:

dai::FRegion

List of all members.

Public Member Functions

Constructors and destructors
 TFactor (T p=1)
 Constructs factor depending on no variables with value p.
 TFactor (const Var &v)
 Constructs factor depending on the variable v with uniform distribution.
 TFactor (const VarSet &vars)
 Constructs factor depending on variables in vars with uniform distribution.
 TFactor (const VarSet &vars, T p)
 Constructs factor depending on variables in vars with all values set to p.
template<typename S>
 TFactor (const VarSet &vars, const std::vector< S > &x)
 Constructs factor depending on variables in vars, copying the values from a std::vector<>.
 TFactor (const VarSet &vars, const T *p)
 Constructs factor depending on variables in vars, copying the values from an array.
 TFactor (const VarSet &vars, const TProb< T > &p)
 Constructs factor depending on variables in vars, copying the values from p.
 TFactor (const std::vector< Var > &vars, const std::vector< T > &p)
 Constructs factor depending on variables in vars, permuting the values given in p accordingly.
Get/set individual entries
void set (size_t i, T val)
 Sets i 'th entry to val.
get (size_t i) const
 Gets i 'th entry.
Queries
const TProb< T > & p () const
 Returns constant reference to value vector.
TProb< T > & p ()
 Returns reference to value vector.
operator[] (size_t i) const
 Returns a copy of the i 'th entry of the value vector.
const VarSetvars () const
 Returns constant reference to variable set (i.e., the variables on which the factor depends).
VarSetvars ()
 Returns reference to variable set (i.e., the variables on which the factor depends).
size_t nrStates () const
 Returns the number of possible joint states of the variables on which the factor depends, $\prod_{l\in L} S_l$.
entropy () const
 Returns the Shannon entropy of *this, $-\sum_i p_i \log p_i$.
max () const
 Returns maximum of all values.
min () const
 Returns minimum of all values.
sum () const
 Returns sum of all values.
sumAbs () const
 Returns sum of absolute values.
maxAbs () const
 Returns maximum absolute value of all values.
bool hasNaNs () const
 Returns true if one or more values are NaN.
bool hasNegatives () const
 Returns true if one or more values are negative.
strength (const Var &i, const Var &j) const
 Returns strength of this factor (between variables i and j), as defined in eq. (52) of [MoK07b].
bool operator== (const TFactor< T > &y) const
 Comparison.
Unary transformations
TFactor< T > operator- () const
 Returns negative of *this.
TFactor< T > abs () const
 Returns pointwise absolute value.
TFactor< T > exp () const
 Returns pointwise exponent.
TFactor< T > log (bool zero=false) const
 Returns pointwise logarithm.
TFactor< T > inverse (bool zero=true) const
 Returns pointwise inverse.
TFactor< T > normalized (ProbNormType norm=NORMPROB) const
 Returns normalized copy of *this, using the specified norm.
Unary operations
TFactor< T > & randomize ()
 Draws all values i.i.d. from a uniform distribution on [0,1).
TFactor< T > & setUniform ()
 Sets all values to $1/n$ where n is the number of states.
TFactor< T > & takeAbs ()
 Applies absolute value pointwise.
TFactor< T > & takeExp ()
 Applies exponent pointwise.
TFactor< T > & takeLog (bool zero=false)
 Applies logarithm pointwise.
normalize (ProbNormType norm=NORMPROB)
 Normalizes factor using the specified norm.
Operations with scalars
TFactor< T > & fill (T x)
 Sets all values to x.
TFactor< T > & operator+= (T x)
 Adds scalar x to each value.
TFactor< T > & operator-= (T x)
 Subtracts scalar x from each value.
TFactor< T > & operator*= (T x)
 Multiplies each value with scalar x.
TFactor< T > & operator/= (T x)
 Divides each entry by scalar x.
TFactor< T > & operator^= (T x)
 Raises values to the power x.
Transformations with scalars
TFactor< T > operator+ (T x) const
 Returns sum of *this and scalar x.
TFactor< T > operator- (T x) const
 Returns difference of *this and scalar x.
TFactor< T > operator* (T x) const
 Returns product of *this with scalar x.
TFactor< T > operator/ (T x) const
 Returns quotient of *this with scalar x.
TFactor< T > operator^ (T x) const
 Returns *this raised to the power x.
Operations with other factors
template<typename binOp>
TFactor< T > & binaryOp (const TFactor< T > &g, binOp op)
 Applies binary operation op on two factors, *this and g.
TFactor< T > & operator+= (const TFactor< T > &g)
 Adds g to *this.
TFactor< T > & operator-= (const TFactor< T > &g)
 Subtracts g from *this.
TFactor< T > & operator*= (const TFactor< T > &g)
 Multiplies *this with g.
TFactor< T > & operator/= (const TFactor< T > &g)
 Divides *this by g (where division by zero yields zero).
Transformations with other factors
template<typename binOp>
TFactor< T > binaryTr (const TFactor< T > &g, binOp op) const
 Returns result of applying binary operation op on two factors, *this and g.
TFactor< T > operator+ (const TFactor< T > &g) const
 Returns sum of *this and g.
TFactor< T > operator- (const TFactor< T > &g) const
 Returns *this minus g.
TFactor< T > operator* (const TFactor< T > &g) const
 Returns product of *this with g.
TFactor< T > operator/ (const TFactor< T > &g) const
 Returns quotient of *this by f (where division by zero yields zero).
Miscellaneous operations
TFactor< T > slice (const VarSet &vars, size_t varsState) const
 Returns a slice of *this, where the subset vars is in state varsState.
TFactor< T > embed (const VarSet &vars) const
 Embeds this factor in a larger VarSet.
TFactor< T > marginal (const VarSet &vars, bool normed=true) const
 Returns marginal on vars, obtained by summing out all variables except those in vars, and normalizing the result if normed == true.
TFactor< T > maxMarginal (const VarSet &vars, bool normed=true) const
 Returns max-marginal on vars, obtained by maximizing all variables except those in vars, and normalizing the result if normed == true.

Private Attributes

VarSet _vs
 Stores the variables on which the factor depends.
TProb< T > _p
 Stores the factor values.

Related Functions

(Note that these are not member functions.)

template<typename T>
std::ostream & operator<< (std::ostream &os, const TFactor< T > &f)
 Writes a factor to an output stream.
template<typename T>
dist (const TFactor< T > &f, const TFactor< T > &g, ProbDistType dt)
 Returns distance between two factors f and g, according to the distance measure dt.
template<typename T>
TFactor< T > max (const TFactor< T > &f, const TFactor< T > &g)
 Returns the pointwise maximum of two factors.
template<typename T>
TFactor< T > min (const TFactor< T > &f, const TFactor< T > &g)
 Returns the pointwise minimum of two factors.
template<typename T>
MutualInfo (const TFactor< T > &f)
 Calculates the mutual information between the two variables that f depends on, under the distribution given by f.


Detailed Description

template<typename T>
class dai::TFactor< T >

Represents a (probability) factor.

Mathematically, a factor is a function mapping joint states of some variables to the nonnegative real numbers. More formally, denoting a discrete variable with label $l$ by $x_l$ and its state space by $X_l = \{0,1,\dots,S_l-1\}$, a factor depending on the variables $\{x_l\}_{l\in L}$ is a function $f_L : \prod_{l\in L} X_l \to [0,\infty)$.

In libDAI, a factor is represented by a TFactor<T> object, which has two components:

The factor values are stored in the entries of the TProb in a particular ordering, which is defined by the one-to-one correspondence of a joint state in $\prod_{l\in L} X_l$ with a linear index in $\{0,1,\dots,\prod_{l\in L} S_l-1\}$ according to the mapping $\sigma$ induced by dai::calcLinearState().

Template Parameters:
T Should be a scalar that is castable from and to double and should support elementary arithmetic operations.
Todo:
Define a better fileformat for .fg files (maybe using XML)?
Todo:
Add support for sparse factors.

Constructor & Destructor Documentation

template<typename T>
dai::TFactor< T >::TFactor ( p = 1  )  [inline]

Constructs factor depending on no variables with value p.

template<typename T>
dai::TFactor< T >::TFactor ( const Var v  )  [inline]

Constructs factor depending on the variable v with uniform distribution.

template<typename T>
dai::TFactor< T >::TFactor ( const VarSet vars  )  [inline]

Constructs factor depending on variables in vars with uniform distribution.

template<typename T>
dai::TFactor< T >::TFactor ( const VarSet vars,
p 
) [inline]

Constructs factor depending on variables in vars with all values set to p.

template<typename T>
template<typename S>
dai::TFactor< T >::TFactor ( const VarSet vars,
const std::vector< S > &  x 
) [inline]

Constructs factor depending on variables in vars, copying the values from a std::vector<>.

Template Parameters:
S Type of values of x
Parameters:
vars contains the variables that the new factor should depend on.
x Vector with values to be copied.

template<typename T>
dai::TFactor< T >::TFactor ( const VarSet vars,
const T *  p 
) [inline]

Constructs factor depending on variables in vars, copying the values from an array.

Parameters:
vars contains the variables that the new factor should depend on.
p Points to array of values to be added.

template<typename T>
dai::TFactor< T >::TFactor ( const VarSet vars,
const TProb< T > &  p 
) [inline]

Constructs factor depending on variables in vars, copying the values from p.

template<typename T>
dai::TFactor< T >::TFactor ( const std::vector< Var > &  vars,
const std::vector< T > &  p 
) [inline]

Constructs factor depending on variables in vars, permuting the values given in p accordingly.


Member Function Documentation

template<typename T>
void dai::TFactor< T >::set ( size_t  i,
val 
) [inline]

Sets i 'th entry to val.

template<typename T>
T dai::TFactor< T >::get ( size_t  i  )  const [inline]

Gets i 'th entry.

template<typename T>
const TProb<T>& dai::TFactor< T >::p (  )  const [inline]

Returns constant reference to value vector.

template<typename T>
TProb<T>& dai::TFactor< T >::p (  )  [inline]

Returns reference to value vector.

template<typename T>
T dai::TFactor< T >::operator[] ( size_t  i  )  const [inline]

Returns a copy of the i 'th entry of the value vector.

template<typename T>
const VarSet& dai::TFactor< T >::vars (  )  const [inline]

Returns constant reference to variable set (i.e., the variables on which the factor depends).

template<typename T>
VarSet& dai::TFactor< T >::vars (  )  [inline]

Returns reference to variable set (i.e., the variables on which the factor depends).

template<typename T>
size_t dai::TFactor< T >::nrStates (  )  const [inline]

Returns the number of possible joint states of the variables on which the factor depends, $\prod_{l\in L} S_l$.

Note:
This is equal to the length of the value vector.

template<typename T>
T dai::TFactor< T >::entropy (  )  const [inline]

Returns the Shannon entropy of *this, $-\sum_i p_i \log p_i$.

template<typename T>
T dai::TFactor< T >::max (  )  const [inline]

Returns maximum of all values.

template<typename T>
T dai::TFactor< T >::min (  )  const [inline]

Returns minimum of all values.

template<typename T>
T dai::TFactor< T >::sum (  )  const [inline]

Returns sum of all values.

template<typename T>
T dai::TFactor< T >::sumAbs (  )  const [inline]

Returns sum of absolute values.

template<typename T>
T dai::TFactor< T >::maxAbs (  )  const [inline]

Returns maximum absolute value of all values.

template<typename T>
bool dai::TFactor< T >::hasNaNs (  )  const [inline]

Returns true if one or more values are NaN.

template<typename T>
bool dai::TFactor< T >::hasNegatives (  )  const [inline]

Returns true if one or more values are negative.

template<typename T>
T dai::TFactor< T >::strength ( const Var i,
const Var j 
) const [inline]

Returns strength of this factor (between variables i and j), as defined in eq. (52) of [MoK07b].

template<typename T>
bool dai::TFactor< T >::operator== ( const TFactor< T > &  y  )  const [inline]

Comparison.

template<typename T>
TFactor<T> dai::TFactor< T >::operator- (  )  const [inline]

Returns negative of *this.

template<typename T>
TFactor<T> dai::TFactor< T >::abs (  )  const [inline]

Returns pointwise absolute value.

template<typename T>
TFactor<T> dai::TFactor< T >::exp (  )  const [inline]

Returns pointwise exponent.

template<typename T>
TFactor<T> dai::TFactor< T >::log ( bool  zero = false  )  const [inline]

Returns pointwise logarithm.

If zero == true, uses log(0)==0; otherwise, log(0)==-Inf.

template<typename T>
TFactor<T> dai::TFactor< T >::inverse ( bool  zero = true  )  const [inline]

Returns pointwise inverse.

If zero == true, uses 1/0==0; otherwise, 1/0==Inf.

template<typename T>
TFactor<T> dai::TFactor< T >::normalized ( ProbNormType  norm = NORMPROB  )  const [inline]

Returns normalized copy of *this, using the specified norm.

Exceptions:
NOT_NORMALIZABLE if the norm is zero

template<typename T>
TFactor<T>& dai::TFactor< T >::randomize (  )  [inline]

Draws all values i.i.d. from a uniform distribution on [0,1).

template<typename T>
TFactor<T>& dai::TFactor< T >::setUniform (  )  [inline]

Sets all values to $1/n$ where n is the number of states.

template<typename T>
TFactor<T>& dai::TFactor< T >::takeAbs (  )  [inline]

Applies absolute value pointwise.

template<typename T>
TFactor<T>& dai::TFactor< T >::takeExp (  )  [inline]

Applies exponent pointwise.

template<typename T>
TFactor<T>& dai::TFactor< T >::takeLog ( bool  zero = false  )  [inline]

Applies logarithm pointwise.

If zero == true, uses log(0)==0; otherwise, log(0)==-Inf.

template<typename T>
T dai::TFactor< T >::normalize ( ProbNormType  norm = NORMPROB  )  [inline]

Normalizes factor using the specified norm.

Exceptions:
NOT_NORMALIZABLE if the norm is zero

template<typename T>
TFactor<T>& dai::TFactor< T >::fill ( x  )  [inline]

Sets all values to x.

template<typename T>
TFactor<T>& dai::TFactor< T >::operator+= ( x  )  [inline]

Adds scalar x to each value.

template<typename T>
TFactor<T>& dai::TFactor< T >::operator-= ( x  )  [inline]

Subtracts scalar x from each value.

template<typename T>
TFactor<T>& dai::TFactor< T >::operator*= ( x  )  [inline]

Multiplies each value with scalar x.

template<typename T>
TFactor<T>& dai::TFactor< T >::operator/= ( x  )  [inline]

Divides each entry by scalar x.

template<typename T>
TFactor<T>& dai::TFactor< T >::operator^= ( x  )  [inline]

Raises values to the power x.

template<typename T>
TFactor<T> dai::TFactor< T >::operator+ ( x  )  const [inline]

Returns sum of *this and scalar x.

template<typename T>
TFactor<T> dai::TFactor< T >::operator- ( x  )  const [inline]

Returns difference of *this and scalar x.

template<typename T>
TFactor<T> dai::TFactor< T >::operator* ( x  )  const [inline]

Returns product of *this with scalar x.

template<typename T>
TFactor<T> dai::TFactor< T >::operator/ ( x  )  const [inline]

Returns quotient of *this with scalar x.

template<typename T>
TFactor<T> dai::TFactor< T >::operator^ ( x  )  const [inline]

Returns *this raised to the power x.

template<typename T>
template<typename binOp>
TFactor<T>& dai::TFactor< T >::binaryOp ( const TFactor< T > &  g,
binOp  op 
) [inline]

Applies binary operation op on two factors, *this and g.

Template Parameters:
binOp Type of function object that accepts two arguments of type T and outputs a type T
Parameters:
g Right operand
op Operation of type binOp

template<typename T>
TFactor<T>& dai::TFactor< T >::operator+= ( const TFactor< T > &  g  )  [inline]

Adds g to *this.

The sum of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[f+g : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto f(x_L) + g(x_M).\]

template<typename T>
TFactor<T>& dai::TFactor< T >::operator-= ( const TFactor< T > &  g  )  [inline]

Subtracts g from *this.

The difference of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[f-g : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto f(x_L) - g(x_M).\]

template<typename T>
TFactor<T>& dai::TFactor< T >::operator*= ( const TFactor< T > &  g  )  [inline]

Multiplies *this with g.

The product of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[fg : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto f(x_L) g(x_M).\]

template<typename T>
TFactor<T>& dai::TFactor< T >::operator/= ( const TFactor< T > &  g  )  [inline]

Divides *this by g (where division by zero yields zero).

The quotient of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[\frac{f}{g} : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto \frac{f(x_L)}{g(x_M)}.\]

template<typename T>
template<typename binOp>
TFactor<T> dai::TFactor< T >::binaryTr ( const TFactor< T > &  g,
binOp  op 
) const [inline]

Returns result of applying binary operation op on two factors, *this and g.

Template Parameters:
binOp Type of function object that accepts two arguments of type T and outputs a type T
Parameters:
g Right operand
op Operation of type binOp

template<typename T>
TFactor<T> dai::TFactor< T >::operator+ ( const TFactor< T > &  g  )  const [inline]

Returns sum of *this and g.

The sum of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[f+g : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto f(x_L) + g(x_M).\]

template<typename T>
TFactor<T> dai::TFactor< T >::operator- ( const TFactor< T > &  g  )  const [inline]

Returns *this minus g.

The difference of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[f-g : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto f(x_L) - g(x_M).\]

template<typename T>
TFactor<T> dai::TFactor< T >::operator* ( const TFactor< T > &  g  )  const [inline]

Returns product of *this with g.

The product of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[fg : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto f(x_L) g(x_M).\]

template<typename T>
TFactor<T> dai::TFactor< T >::operator/ ( const TFactor< T > &  g  )  const [inline]

Returns quotient of *this by f (where division by zero yields zero).

The quotient of two factors is defined as follows: if $f : \prod_{l\in L} X_l \to [0,\infty)$ and $g : \prod_{m\in M} X_m \to [0,\infty)$, then

\[\frac{f}{g} : \prod_{l\in L\cup M} X_l \to [0,\infty) : x \mapsto \frac{f(x_L)}{g(x_M)}.\]

template<typename T>
TFactor< T > dai::TFactor< T >::slice ( const VarSet vars,
size_t  varsState 
) const [inline]

Returns a slice of *this, where the subset vars is in state varsState.

Precondition:
vars sould be a subset of vars()

varsState < vars.nrStates()

The result is a factor that depends on the variables of *this except those in vars, obtained by setting the variables in vars to the joint state specified by the linear index varsState. Formally, if *this corresponds with the factor $f : \prod_{l\in L} X_l \to [0,\infty)$, $M \subset L$ corresponds with vars and varsState corresponds with a mapping $s$ that maps a variable $x_m$ with $m\in M$ to its state $s(x_m) \in X_m$, then the slice returned corresponds with the factor $g : \prod_{l \in L \setminus M} X_l \to [0,\infty)$ defined by $g(\{x_l\}_{l\in L \setminus M}) = f(\{x_l\}_{l\in L \setminus M}, \{s(x_m)\}_{m\in M})$.

template<typename T>
TFactor<T> dai::TFactor< T >::embed ( const VarSet vars  )  const [inline]

Embeds this factor in a larger VarSet.

Precondition:
vars() should be a subset of vars
If *this corresponds with $f : \prod_{l\in L} X_l \to [0,\infty)$ and $L \subset M$, then the embedded factor corresponds with $g : \prod_{m\in M} X_m \to [0,\infty) : x \mapsto f(x_L)$.

template<typename T>
TFactor< T > dai::TFactor< T >::marginal ( const VarSet vars,
bool  normed = true 
) const [inline]

Returns marginal on vars, obtained by summing out all variables except those in vars, and normalizing the result if normed == true.

template<typename T>
TFactor< T > dai::TFactor< T >::maxMarginal ( const VarSet vars,
bool  normed = true 
) const [inline]

Returns max-marginal on vars, obtained by maximizing all variables except those in vars, and normalizing the result if normed == true.


Friends And Related Function Documentation

template<typename T>
std::ostream & operator<< ( std::ostream &  os,
const TFactor< T > &  f 
) [related]

Writes a factor to an output stream.

template<typename T>
T dist ( const TFactor< T > &  f,
const TFactor< T > &  g,
ProbDistType  dt 
) [related]

Returns distance between two factors f and g, according to the distance measure dt.

Precondition:
f.vars() == g.vars()

template<typename T>
TFactor< T > max ( const TFactor< T > &  f,
const TFactor< T > &  g 
) [related]

Returns the pointwise maximum of two factors.

Precondition:
f.vars() == g.vars()

template<typename T>
TFactor< T > min ( const TFactor< T > &  f,
const TFactor< T > &  g 
) [related]

Returns the pointwise minimum of two factors.

Precondition:
f.vars() == g.vars()

template<typename T>
T MutualInfo ( const TFactor< T > &  f  )  [related]

Calculates the mutual information between the two variables that f depends on, under the distribution given by f.

Precondition:
f.vars().size() == 2


Member Data Documentation

template<typename T>
VarSet dai::TFactor< T >::_vs [private]

Stores the variables on which the factor depends.

template<typename T>
TProb<T> dai::TFactor< T >::_p [private]

Stores the factor values.


The documentation for this class was generated from the following file:

Generated on Thu Aug 5 19:04:06 2010 for libDAI by  doxygen 1.5.5