Represents a (probability) factor. More...

#include <dai/factor.h>

Public Member Functions
Constructors and destructors
	TFactor (T p=1)
	Constructs factor depending on no variables with value p. More...

	TFactor (const Var &v)
	Constructs factor depending on the variable v with uniform distribution. More...

	TFactor (const VarSet &vars)
	Constructs factor depending on variables in vars with uniform distribution. More...

	TFactor (const VarSet &vars, T p)
	Constructs factor depending on variables in vars with all values set to p. More...

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<> More...

	TFactor (const VarSet &vars, const T *p)
	Constructs factor depending on variables in vars, copying the values from an array. More...

	TFactor (const VarSet &vars, const TProb< T > &p)
	Constructs factor depending on variables in vars, copying the values from p. More...

	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. More...

Get/set individual entries
void	set (size_t i, T val)
	Sets i 'th entry to val. More...

T	get (size_t i) const
	Gets i 'th entry. More...

Queries
const TProb< T > &	p () const
	Returns constant reference to value vector. More...

TProb< T > &	p ()
	Returns reference to value vector. More...

T	operator[] (size_t i) const
	Returns a copy of the i 'th entry of the value vector. More...

const VarSet &	vars () const
	Returns constant reference to variable set (i.e., the variables on which the factor depends) More...

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

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$ . More...

T	entropy () const
	Returns the Shannon entropy of `*this`, $-\sum_i p_i \log p_i$ . More...

T	max () const
	Returns maximum of all values. More...

T	min () const
	Returns minimum of all values. More...

T	sum () const
	Returns sum of all values. More...

T	sumAbs () const
	Returns sum of absolute values. More...

T	maxAbs () const
	Returns maximum absolute value of all values. More...

bool	hasNaNs () const
	Returns `true` if one or more values are NaN. More...

bool	hasNegatives () const
	Returns `true` if one or more values are negative. More...

T	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]. More...

bool	operator== (const TFactor< T > &y) const
	Comparison. More...

std::string	toString () const
	Formats a factor as a string. More...

Unary transformations
TFactor< T >	operator- () const
	Returns negative of `*this`. More...

TFactor< T >	abs () const
	Returns pointwise absolute value. More...

TFactor< T >	exp () const
	Returns pointwise exponent. More...

TFactor< T >	log (bool zero=false) const
	Returns pointwise logarithm. More...

TFactor< T >	inverse (bool zero=true) const
	Returns pointwise inverse. More...

TFactor< T >	normalized (ProbNormType norm=NORMPROB) const
	Returns normalized copy of `*this`, using the specified norm. More...

Unary operations
TFactor< T > &	randomize ()
	Draws all values i.i.d. from a uniform distribution on [0,1) More...

TFactor< T > &	setUniform ()
	Sets all values to where n is the number of states. More...

TFactor< T > &	takeAbs ()
	Applies absolute value pointwise. More...

TFactor< T > &	takeExp ()
	Applies exponent pointwise. More...

TFactor< T > &	takeLog (bool zero=false)
	Applies logarithm pointwise. More...

T	normalize (ProbNormType norm=NORMPROB)
	Normalizes factor using the specified norm. More...

Operations with scalars
TFactor< T > &	fill (T x)
	Sets all values to x. More...

TFactor< T > &	operator+= (T x)
	Adds scalar x to each value. More...

TFactor< T > &	operator-= (T x)
	Subtracts scalar x from each value. More...

TFactor< T > &	operator*= (T x)
	Multiplies each value with scalar x. More...

TFactor< T > &	operator/= (T x)
	Divides each entry by scalar x. More...

TFactor< T > &	operator^= (T x)
	Raises values to the power x. More...

Transformations with scalars
TFactor< T >	operator+ (T x) const
	Returns sum of `*this` and scalar x. More...

TFactor< T >	operator- (T x) const
	Returns difference of `*this` and scalar x. More...

TFactor< T >	operator* (T x) const
	Returns product of `*this` with scalar x. More...

TFactor< T >	operator/ (T x) const
	Returns quotient of `*this` with scalar x. More...

TFactor< T >	operator^ (T x) const
	Returns `*this` raised to the power x. More...

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. More...

TFactor< T > &	operator+= (const TFactor< T > &g)
	Adds g to `*this`. More...

TFactor< T > &	operator-= (const TFactor< T > &g)
	Subtracts g from `*this`. More...

TFactor< T > &	operator*= (const TFactor< T > &g)
	Multiplies `*this` with g. More...

TFactor< T > &	operator/= (const TFactor< T > &g)
	Divides `*this` by g (where division by zero yields zero) More...

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. More...

TFactor< T >	operator+ (const TFactor< T > &g) const
	Returns sum of `*this` and g. More...

TFactor< T >	operator- (const TFactor< T > &g) const
	Returns `*this` minus g. More...

TFactor< T >	operator* (const TFactor< T > &g) const
	Returns product of `*this` with g. More...

TFactor< T >	operator/ (const TFactor< T > &g) const
	Returns quotient of `*this` by f (where division by zero yields zero) More...

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. More...

TFactor< T >	embed (const VarSet &vars) const
	Embeds this factor in a larger VarSet. More...

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`. More...

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`. More...

Private Attributes
VarSet	_vs
	Stores the variables on which the factor depends. More...

TProb< T >	_p
	Stores the factor values. More...

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. More...

template<typename T >
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. More...

template<typename T >
TFactor< T >	max (const TFactor< T > &f, const TFactor< T > &g)
	Returns the pointwise maximum of two factors. More...

template<typename T >
TFactor< T >	min (const TFactor< T > &f, const TFactor< T > &g)
	Returns the pointwise minimum of two factors. More...

template<typename T >
T	MutualInfo (const TFactor< T > &f)
	Calculates the mutual information between the two variables that f depends on, under the distribution given by f. More...

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:

a VarSet, corresponding with the set of variables $\{x_l\}_{l\in L}$ that the factor depends on;
a TProb, a vector containing the value of the factor for each possible joint state of the variables.

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)?

Add support for sparse factors.

Constructor & Destructor Documentation

template<typename T>

dai::TFactor< T >::TFactor ( T 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,
		T	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,
		T	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

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>

std::string dai::TFactor< T >::toString ( ) const

inline

Formats a factor as a string.

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 ( T x )

inline

Sets all values to x.

template<typename T>

TFactor<T>& dai::TFactor< T >::operator+= ( T x )

inline

Adds scalar x to each value.

template<typename T>

TFactor<T>& dai::TFactor< T >::operator-= ( T x )

inline

Subtracts scalar x from each value.

template<typename T>

TFactor<T>& dai::TFactor< T >::operator*= ( T x )

inline

Multiplies each value with scalar x.

template<typename T>

TFactor<T>& dai::TFactor< T >::operator/= ( T x )

inline

Divides each entry by scalar x.

template<typename T>

TFactor<T>& dai::TFactor< T >::operator^= ( T x )

inline

Raises values to the power x.

template<typename T>

TFactor<T> dai::TFactor< T >::operator+ ( T x ) const

inline

Returns sum of *this and scalar x.

template<typename T>

TFactor<T> dai::TFactor< T >::operator- ( T x ) const

inline

Returns difference of *this and scalar x.

template<typename T>

TFactor<T> dai::TFactor< T >::operator* ( T x ) const

inline

Returns product of *this with scalar x.

template<typename T>

TFactor<T> dai::TFactor< T >::operator/ ( T x ) const

inline

Returns quotient of *this with scalar x.

template<typename T>

TFactor<T> dai::TFactor< T >::operator^ ( T 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

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

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

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
	)

template<typename T >

T dist	(	const TFactor< T > &	f,
		const TFactor< T > &	g,
		ProbDistType	dt
	)

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

template<typename T >

TFactor< T > max	(	const TFactor< T > &	f,
		const TFactor< T > &	g
	)

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

template<typename T >

TFactor< T > min	(	const TFactor< T > &	f,
		const TFactor< T > &	g
	)

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

template<typename T >

T MutualInfo ( const TFactor< T > & 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:

include/dai/factor.h

Public Member Functions

Private Attributes

Related Functions

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

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