1 /* This file is part of libDAI - http://www.libdai.org/
2 *
4 * 2, or (at your option) any later version. libDAI is distributed without any
5 * warranty. See the file COPYING for more details.
6 *
7 * Copyright (C) 2006-2010 Joris Mooij [joris dot mooij at libdai dot org]
9 */
12 /// \file
13 /// \brief Defines the FactorGraph class, which represents factor graphs (e.g., Bayesian networks or Markov random fields)
16 #ifndef __defined_libdai_factorgraph_h
17 #define __defined_libdai_factorgraph_h
20 #include <iostream>
21 #include <map>
22 #include <dai/bipgraph.h>
23 #include <dai/graph.h>
24 #include <dai/factor.h>
27 namespace dai {
30 /// Represents a factor graph.
31 /** Both Bayesian Networks and Markov random fields can be represented in a
32 * unifying representation, called <em>factor graph</em> [\ref KFL01],
33 * implemented in libDAI by the FactorGraph class.
34 *
35 * Consider a probability distribution over \f$N\f$ discrete random variables
36 * \f$x_0,x_1,\dots,x_{N-1}\f$ that factorizes as a product of \f$M\f$ factors, each of
37 * which depends on some subset of the variables:
38 * \f[
39 * P(x_0,x_1,\dots,x_{N-1}) = \frac{1}{Z} \prod_{I=0}^{M-1} f_I(x_I), \qquad
40 * Z = \sum_{x_0}\dots\sum_{x_{N-1}} \prod_{I=0}^{M-1} f_I(X_I).
41 * \f]
42 * Each factor \f$f_I\f$ is a function from an associated subset
43 * of variables \f$X_I \subset \{x_0,x_1,\dots,x_{N-1}\}\f$ to the nonnegative
44 * real numbers.
45 *
46 * For a Bayesian network, each factor corresponds to a (conditional)
47 * probability table, whereas for a Markov random field, each factor
48 * corresponds to a maximal clique of the undirected graph.
49 *
50 * Factor graphs explicitly express the factorization structure of the
51 * corresponding probability distribution. A factor graph is a bipartite graph,
52 * containing variable nodes and factor nodes, and an edge between a variable
53 * node and a factor node if the corresponding factor depends on that variable.
54 * In libDAI, this structure is represented by a BipartiteGraph.
55 *
56 * So basically, a FactorGraph consists of a BipartiteGraph, a vector of Var 's
57 * and a vector of TFactor 's.
58 *
59 * \idea Alternative implementation of undo factor changes: the only things that have to be
60 * undone currently are setting a factor to 1 and setting a factor to a Kronecker delta. This
61 * could also be implemented in the TFactor itself, which could maintain its state
62 * (ones/delta/full) and act accordingly. Update: it seems that the proposed functionality
63 * would not be enough for CBP, for which it would make more sense to add more levels of
64 * backup/restore.
65 */
66 class FactorGraph {
67 public:
68 /// Shorthand for BipartiteGraph::Neighbor
69 typedef BipartiteGraph::Neighbor Neighbor;
71 /// Shorthand for BipartiteGraph::Neighbors
72 typedef BipartiteGraph::Neighbors Neighbors;
74 /// Shorthand for BipartiteGraph::Edge
75 typedef BipartiteGraph::Edge Edge;
77 /// Iterator over factors
78 typedef std::vector<Factor>::iterator iterator;
80 /// Constant iterator over factors
81 typedef std::vector<Factor>::const_iterator const_iterator;
83 private:
84 /// Stores the neighborhood structure
85 BipartiteGraph _G;
86 /// Stores the variables
87 std::vector<Var> _vars;
88 /// Stores the factors
89 std::vector<Factor> _factors;
90 /// Stores backups of some factors
91 std::map<size_t,Factor> _backup;
93 public:
94 /// \name Constructors and destructors
95 //@{
96 /// Default constructor
97 FactorGraph() : _G(), _vars(), _factors(), _backup() {}
99 /// Constructs a factor graph from a vector of factors
100 FactorGraph( const std::vector<Factor>& P );
102 /// Constructs a factor graph from given factor and variable iterators
103 /** \tparam FactorInputIterator Iterates over instances of type dai::Factor
104 * \tparam VarInputIterator Iterates over instances of type Var
105 * \pre Assumes that the set of variables in [\a varBegin, \a varEnd) is the union of the variables in the factors in [\a facBegin, \a facEnd)
106 */
107 template<typename FactorInputIterator, typename VarInputIterator>
108 FactorGraph(FactorInputIterator facBegin, FactorInputIterator facEnd, VarInputIterator varBegin, VarInputIterator varEnd, size_t nrFacHint = 0, size_t nrVarHint = 0 );
110 /// Destructor
111 virtual ~FactorGraph() {}
113 /// Virtual copy constructor
114 virtual FactorGraph* clone() const { return new FactorGraph(*this); }
115 //@}
117 /// \name Accessors and mutators
118 //@{
119 /// Returns constant reference the \a i 'th variable
120 const Var& var( size_t i ) const {
121 DAI_DEBASSERT( i < nrVars() );
122 return _vars[i];
123 }
125 /// Returns constant reference to all variables
126 const std::vector<Var>& vars() const { return _vars; }
128 /// Returns reference to \a I 'th factor
129 Factor& factor( size_t I ) {
130 DAI_DEBASSERT( I < nrFactors() );
131 return _factors[I];
132 }
134 /// Returns constant reference to \a I 'th factor
135 const Factor& factor( size_t I ) const {
136 DAI_DEBASSERT( I < nrFactors() );
137 return _factors[I];
138 }
139 /// Returns constant reference to all factors
140 const std::vector<Factor>& factors() const { return _factors; }
142 /// Returns constant reference to neighbors of the \a i 'th variable
143 const Neighbors& nbV( size_t i ) const { return _G.nb1(i); }
144 /// Returns constant reference to neighbors of the \a I 'th factor
145 const Neighbors& nbF( size_t I ) const { return _G.nb2(I); }
146 /// Returns constant reference to the \a _I 'th neighbor of the \a i 'th variable
147 const Neighbor& nbV( size_t i, size_t _I ) const { return _G.nb1(i)[_I]; }
148 /// Returns constant reference to the \a _i 'th neighbor of the \a I 'th factor
149 const Neighbor& nbF( size_t I, size_t _i ) const { return _G.nb2(I)[_i]; }
150 //@}
152 /// \name Iterator interface
153 //@{
154 /// Returns iterator pointing to first factor
155 iterator begin() { return _factors.begin(); }
156 /// Returns constant iterator pointing to first factor
157 const_iterator begin() const { return _factors.begin(); }
158 /// Returns iterator pointing beyond last factor
159 iterator end() { return _factors.end(); }
160 /// Returns constant iterator pointing beyond last factor
161 const_iterator end() const { return _factors.end(); }
162 //@}
164 /// \name Queries
165 //@{
166 /// Returns neighborhood structure
167 const BipartiteGraph& bipGraph() const { return _G; }
168 /// Returns number of variables
169 size_t nrVars() const { return vars().size(); }
170 /// Returns number of factors
171 size_t nrFactors() const { return factors().size(); }
172 /// Calculates number of edges
173 /** \note Time complexity: O(nrVars())
174 */
175 size_t nrEdges() const { return _G.nrEdges(); }
177 /// Returns the index of a particular variable
178 /** \note Time complexity: O(nrVars())
179 * \throw OBJECT_NOT_FOUND if the variable is not part of this factor graph
180 */
181 size_t findVar( const Var& n ) const {
182 size_t i = find( vars().begin(), vars().end(), n ) - vars().begin();
183 if( i == nrVars() )
184 DAI_THROW(OBJECT_NOT_FOUND);
185 return i;
186 }
188 /// Returns a set of indexes corresponding to a set of variables
189 /** \note Time complexity: O( nrVars() * ns.size() )
190 * \throw OBJECT_NOT_FOUND if one of the variables is not part of this factor graph
191 */
192 SmallSet<size_t> findVars( const VarSet& ns ) const {
193 SmallSet<size_t> result;
194 for( VarSet::const_iterator n = ns.begin(); n != ns.end(); n++ )
195 result.insert( findVar( *n ) );
196 return result;
197 }
199 /// Returns index of the first factor that depends on the variables
200 /** \note Time complexity: O(nrFactors())
201 * \throw OBJECT_NOT_FOUND if no factor in this factor graph depends on those variables
202 */
203 size_t findFactor( const VarSet& ns ) const {
204 size_t I;
205 for( I = 0; I < nrFactors(); I++ )
206 if( factor(I).vars() == ns )
207 break;
208 if( I == nrFactors() )
209 DAI_THROW(OBJECT_NOT_FOUND);
210 return I;
211 }
213 /// Return all variables that occur in a factor involving the \a i 'th variable, itself included
214 VarSet Delta( size_t i ) const;
216 /// Return all variables that occur in a factor involving some variable in \a vs, \a vs itself included
217 VarSet Delta( const VarSet& vs ) const;
219 /// Return all variables that occur in a factor involving the \a i 'th variable, itself excluded
220 VarSet delta( size_t i ) const {
221 return( Delta( i ) / var( i ) );
222 }
224 /// Return all variables that occur in a factor involving some variable in \a vs, \a vs itself excluded
225 VarSet delta( const VarSet& vs ) const {
226 return Delta( vs ) / vs;
227 }
229 /// Returns \c true if the factor graph is connected
230 bool isConnected() const { return _G.isConnected(); }
232 /// Returns \c true if the factor graph is a tree (i.e., has no cycles and is connected)
233 bool isTree() const { return _G.isTree(); }
235 /// Returns \c true if each factor depends on at most two variables
236 bool isPairwise() const;
238 /// Returns \c true if each variable has only two possible values
239 bool isBinary() const;
241 /// Constructs the corresponding Markov graph
242 /** \note The Markov graph has the variables as nodes and an edge
243 * between two variables if and only if the variables share a factor.
244 */
245 GraphAL MarkovGraph() const;
247 /// Returns the maximal factor domains in this factorgraph
248 /** \note A factor domain is \a maximal if and only if it is not a
249 * strict subset of another factor domain.
250 */
251 std::vector<VarSet> maximalFactorDomains() const;
253 /// Returns the maximal factors domains in this factorgraph
255 */
256 std::vector<VarSet> cliques() const {
257 return maximalFactorDomains();
258 }
259 //@}
261 /// \name Backup/restore mechanism for factors
262 //@{
263 /// Set the content of the \a I 'th factor and make a backup of its old content if \a backup == \c true
264 virtual void setFactor( size_t I, const Factor& newFactor, bool backup = false ) {
265 DAI_ASSERT( newFactor.vars() == factor(I).vars() );
266 if( backup )
267 backupFactor( I );
268 _factors[I] = newFactor;
269 }
271 /// Set the contents of all factors as specified by \a facs and make a backup of the old contents if \a backup == \c true
272 virtual void setFactors( const std::map<size_t, Factor>& facs, bool backup = false ) {
273 for( std::map<size_t, Factor>::const_iterator fac = facs.begin(); fac != facs.end(); fac++ ) {
274 if( backup )
275 backupFactor( fac->first );
276 setFactor( fac->first, fac->second );
277 }
278 }
280 /// Makes a backup of the \a I 'th factor
281 /** \throw MULTIPLE_UNDO if a backup already exists
282 */
283 void backupFactor( size_t I );
285 /// Restores the \a I 'th factor from the backup (it should be backed up first)
286 /** \throw OBJECT_NOT_FOUND if a backup does not exist
287 */
288 void restoreFactor( size_t I );
290 /// Backup the factors specified by indices in \a facs
291 /** \throw MULTIPLE_UNDO if a backup already exists
292 */
293 virtual void backupFactors( const std::set<size_t>& facs );
295 /// Restore all factors to the backup copies
296 virtual void restoreFactors();
298 /// Makes a backup of all factors connected to a set of variables
299 /** \throw MULTIPLE_UNDO if a backup already exists
300 */
301 void backupFactors( const VarSet& ns );
303 /// Restores all factors connected to a set of variables from their backups
304 void restoreFactors( const VarSet& ns );
305 //@}
307 /// \name Transformations
308 //@{
309 /// Returns a copy of \c *this, where all factors that are subsumed by some larger factor are merged with the larger factors.
310 FactorGraph maximalFactors() const;
312 /// Returns a copy of \c *this, where the \a i 'th variable has been clamped to value \a x
313 /** \note This version changes the factor graph structure and thus returns a newly constructed FactorGraph
314 * and keeps the current one constant, contrary to clamp()
315 */
316 FactorGraph clamped( size_t i, size_t x ) const;
317 //@}
319 /// \name Operations
320 //@{
321 /// Clamp the \a i 'th variable to value \a x (i.e. multiply with a Kronecker delta \f$\delta_{x_i, x}\f$)
322 /** If \a backup == \c true, make a backup of all factors that are changed
323 */
324 virtual void clamp( size_t i, size_t x, bool backup = false );
326 /// Clamp a variable in a factor graph to have one out of a list of values
327 /** If \a backup == \c true, make a backup of all factors that are changed
328 */
329 void clampVar( size_t i, const std::vector<size_t>& xis, bool backup = false );
331 /// Clamp a factor in a factor graph to have one out of a list of values
332 /** If \a backup == \c true, make a backup of all factors that are changed
333 */
334 void clampFactor( size_t I, const std::vector<size_t>& xIs, bool backup = false );
336 /// Set all factors interacting with the \a i 'th variable to 1
337 /** If \a backup == \c true, make a backup of all factors that are changed
338 */
339 virtual void makeCavity( size_t i, bool backup = false );
340 //@}
342 /// \name Input/Output
343 //@{
344 /// Reads a factor graph from a file
345 /** \see \ref fileformats-factorgraph
346 * \throw CANNOT_READ_FILE if the file cannot be opened
347 * \throw INVALID_FACTORGRAPH_FILE if the file is not valid
348 */
349 void ReadFromFile( const char *filename );
351 /// Writes a factor graph to a file
352 /** \see \ref fileformats-factorgraph
353 * \throw CANNOT_WRITE_FILE if the file cannot be written
354 */
355 void WriteToFile( const char *filename, size_t precision=15 ) const;
357 /// Writes a factor graph to an output stream
358 /** \see \ref fileformats-factorgraph
359 */
360 friend std::ostream& operator<< (std::ostream& os, const FactorGraph& fg );
362 /// Reads a factor graph from an input stream
363 /** \see \ref fileformats-factorgraph
364 * \throw INVALID_FACTORGRAPH_FILE if the input stream is not valid
365 */
366 friend std::istream& operator>> (std::istream& is, FactorGraph& fg );
368 /// Writes a factor graph to a GraphViz .dot file
369 void printDot( std::ostream& os ) const;
370 //@}
372 private:
373 /// Part of constructors (creates edges, neighbors and adjacency matrix)
374 void constructGraph( size_t nrEdges );
375 };
378 template<typename FactorInputIterator, typename VarInputIterator>
379 FactorGraph::FactorGraph(FactorInputIterator facBegin, FactorInputIterator facEnd, VarInputIterator varBegin, VarInputIterator varEnd, size_t nrFacHint, size_t nrVarHint ) : _G(), _backup() {
381 size_t nrEdges = 0;
382 _factors.reserve( nrFacHint );
383 for( FactorInputIterator p2 = facBegin; p2 != facEnd; ++p2 ) {
384 _factors.push_back( *p2 );
385 nrEdges += p2->vars().size();
386 }
389 _vars.reserve( nrVarHint );
390 for( VarInputIterator p1 = varBegin; p1 != varEnd; ++p1 )
391 _vars.push_back( *p1 );
393 // create graph structure
394 constructGraph( nrEdges );
395 }
398 /** \example example.cpp
399 * This example illustrates how to read a factor graph from a file and how to
400 * run several inference algorithms (junction tree, loopy belief propagation,
401 * and the max-product algorithm) on it.
402 */
405 /** \example example_sprinkler.cpp
406 * This example illustrates how to manually construct a factor graph and
407 * write it to a file.
408 */
411 } // end of namespace dai
414 #endif