47195ca2bc2f317bad24b966367b35f3f1243712
[libdai.git] / include / dai / factorgraph.h
1 /* This file is part of libDAI - http://www.libdai.org/
2 *
3 * libDAI is licensed under the terms of the GNU General Public License version
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]
8 * Copyright (C) 2006-2007 Radboud University Nijmegen, The Netherlands
9 */
10
11
12 /// \file
13 /// \brief Defines the FactorGraph class, which represents factor graphs (e.g., Bayesian networks or Markov random fields)
14
15
16 #ifndef __defined_libdai_factorgraph_h
17 #define __defined_libdai_factorgraph_h
18
19
20 #include <iostream>
21 #include <map>
22 #include <dai/bipgraph.h>
23 #include <dai/graph.h>
24 #include <dai/factor.h>
25
26
27 namespace dai {
28
29
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 * \todo Write a method that applies evidence (should we represent evidence as a map<Var,size_t> or as a map<size_t,size_t>?)
67 */
68 class FactorGraph {
69 private:
70 /// Stores the neighborhood structure
71 BipartiteGraph _G;
72 /// Stores the variables
73 std::vector<Var> _vars;
74 /// Stores the factors
75 std::vector<Factor> _factors;
76 /// Stores backups of some factors
77 std::map<size_t,Factor> _backup;
78
79 public:
80 /// \name Constructors and destructors
81 //@{
82 /// Default constructor
83 FactorGraph() : _G(), _vars(), _factors(), _backup() {}
84
85 /// Constructs a factor graph from a vector of factors
86 FactorGraph( const std::vector<Factor>& P );
87
88 /// Constructs a factor graph from given factor and variable iterators
89 /** \tparam FactorInputIterator Iterates over instances of type dai::Factor
90 * \tparam VarInputIterator Iterates over instances of type Var
91 * \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)
92 */
93 template<typename FactorInputIterator, typename VarInputIterator>
94 FactorGraph(FactorInputIterator facBegin, FactorInputIterator facEnd, VarInputIterator varBegin, VarInputIterator varEnd, size_t nrFacHint = 0, size_t nrVarHint = 0 );
95
96 /// Destructor
97 virtual ~FactorGraph() {}
98
99 /// Virtual copy constructor
100 virtual FactorGraph* clone() const { return new FactorGraph(*this); }
101 //@}
102
103 /// \name Accessors and mutators
104 //@{
105 /// Returns constant reference the \a i 'th variable
106 const Var& var( size_t i ) const {
107 DAI_DEBASSERT( i < nrVars() );
108 return _vars[i];
109 }
110
111 /// Returns constant reference to all variables
112 const std::vector<Var>& vars() const { return _vars; }
113
114 /// Returns constant reference to \a I 'th factor
115 const Factor& factor( size_t I ) const {
116 DAI_DEBASSERT( I < nrFactors() );
117 return _factors[I];
118 }
119 /// Returns constant reference to all factors
120 const std::vector<Factor>& factors() const { return _factors; }
121
122 /// Returns constant reference to neighbors of the \a i 'th variable
123 const Neighbors& nbV( size_t i ) const { return _G.nb1(i); }
124 /// Returns constant reference to neighbors of the \a I 'th factor
125 const Neighbors& nbF( size_t I ) const { return _G.nb2(I); }
126 /// Returns constant reference to the \a _I 'th neighbor of the \a i 'th variable
127 const Neighbor& nbV( size_t i, size_t _I ) const { return _G.nb1(i)[_I]; }
128 /// Returns constant reference to the \a _i 'th neighbor of the \a I 'th factor
129 const Neighbor& nbF( size_t I, size_t _i ) const { return _G.nb2(I)[_i]; }
130 //@}
131
132 /// \name Queries
133 //@{
134 /// Returns neighborhood structure
135 const BipartiteGraph& bipGraph() const { return _G; }
136 /// Returns number of variables
137 size_t nrVars() const { return vars().size(); }
138 /// Returns number of factors
139 size_t nrFactors() const { return factors().size(); }
140 /// Calculates number of edges
141 /** \note Time complexity: O(nrVars())
142 */
143 size_t nrEdges() const { return _G.nrEdges(); }
144
145 /// Returns the index of a particular variable
146 /** \note Time complexity: O(nrVars())
147 * \throw OBJECT_NOT_FOUND if the variable is not part of this factor graph
148 */
149 size_t findVar( const Var& n ) const {
150 size_t i = find( vars().begin(), vars().end(), n ) - vars().begin();
151 if( i == nrVars() )
152 DAI_THROW(OBJECT_NOT_FOUND);
153 return i;
154 }
155
156 /// Returns a set of indexes corresponding to a set of variables
157 /** \note Time complexity: O( nrVars() * ns.size() )
158 * \throw OBJECT_NOT_FOUND if one of the variables is not part of this factor graph
159 */
160 SmallSet<size_t> findVars( const VarSet& ns ) const {
161 SmallSet<size_t> result;
162 for( VarSet::const_iterator n = ns.begin(); n != ns.end(); n++ )
163 result.insert( findVar( *n ) );
164 return result;
165 }
166
167 /// Returns index of the first factor that depends on the variables
168 /** \note Time complexity: O(nrFactors())
169 * \throw OBJECT_NOT_FOUND if no factor in this factor graph depends on those variables
170 */
171 size_t findFactor( const VarSet& ns ) const {
172 size_t I;
173 for( I = 0; I < nrFactors(); I++ )
174 if( factor(I).vars() == ns )
175 break;
176 if( I == nrFactors() )
177 DAI_THROW(OBJECT_NOT_FOUND);
178 return I;
179 }
180
181 /// Return all variables that occur in a factor involving the \a i 'th variable, itself included
182 VarSet Delta( size_t i ) const;
183
184 /// Return all variables that occur in a factor involving some variable in \a vs, \a vs itself included
185 VarSet Delta( const VarSet& vs ) const;
186
187 /// Return all variables that occur in a factor involving the \a i 'th variable, itself excluded
188 VarSet delta( size_t i ) const {
189 return( Delta( i ) / var( i ) );
190 }
191
192 /// Return all variables that occur in a factor involving some variable in \a vs, \a vs itself excluded
193 VarSet delta( const VarSet& vs ) const {
194 return Delta( vs ) / vs;
195 }
196
197 /// Returns \c true if the factor graph is connected
198 bool isConnected() const { return _G.isConnected(); }
199
200 /// Returns \c true if the factor graph is a tree (i.e., has no cycles and is connected)
201 bool isTree() const { return _G.isTree(); }
202
203 /// Returns \c true if each factor depends on at most two variables
204 bool isPairwise() const;
205
206 /// Returns \c true if each variable has only two possible values
207 bool isBinary() const;
208
209 /// Constructs the corresponding Markov graph
210 /** \note The Markov graph has the variables as nodes and an edge
211 * between two variables if and only if the variables share a factor.
212 */
213 GraphAL MarkovGraph() const;
214
215 /// Returns whether the \a I 'th factor is maximal
216 /** \note A factor (domain) is \a maximal if and only if it is not a
217 * strict subset of another factor domain.
218 */
219 bool isMaximal( size_t I ) const;
220
221 /// Returns the index of a maximal factor that contains the \a I 'th factor
222 /** \note A factor (domain) is \a maximal if and only if it is not a
223 * strict subset of another factor domain.
224 */
225 size_t maximalFactor( size_t I ) const;
226
227 /// Returns the maximal factor domains in this factorgraph
228 /** \note A factor domain is \a maximal if and only if it is not a
229 * strict subset of another factor domain.
230 */
231 std::vector<VarSet> maximalFactorDomains() const;
232
233 /// Evaluates the log score (i.e., minus the energy) of the joint configuration \a statevec
234 Real logScore( const std::vector<size_t>& statevec );
235 //@}
236
237 /// \name Backup/restore mechanism for factors
238 //@{
239 /// Set the content of the \a I 'th factor and make a backup of its old content if \a backup == \c true
240 virtual void setFactor( size_t I, const Factor& newFactor, bool backup = false ) {
241 DAI_ASSERT( newFactor.vars() == factor(I).vars() );
242 if( backup )
243 backupFactor( I );
244 _factors[I] = newFactor;
245 }
246
247 /// Set the contents of all factors as specified by \a facs and make a backup of the old contents if \a backup == \c true
248 virtual void setFactors( const std::map<size_t, Factor>& facs, bool backup = false ) {
249 for( std::map<size_t, Factor>::const_iterator fac = facs.begin(); fac != facs.end(); fac++ ) {
250 if( backup )
251 backupFactor( fac->first );
252 setFactor( fac->first, fac->second );
253 }
254 }
255
256 /// Makes a backup of the \a I 'th factor
257 /** \throw MULTIPLE_UNDO if a backup already exists
258 */
259 void backupFactor( size_t I );
260
261 /// Restores the \a I 'th factor from the backup (it should be backed up first)
262 /** \throw OBJECT_NOT_FOUND if a backup does not exist
263 */
264 void restoreFactor( size_t I );
265
266 /// Backup the factors specified by indices in \a facs
267 /** \throw MULTIPLE_UNDO if a backup already exists
268 */
269 virtual void backupFactors( const std::set<size_t>& facs );
270
271 /// Restore all factors to the backup copies
272 virtual void restoreFactors();
273
274 /// Makes a backup of all factors connected to a set of variables
275 /** \throw MULTIPLE_UNDO if a backup already exists
276 */
277 void backupFactors( const VarSet& ns );
278
279 /// Restores all factors connected to a set of variables from their backups
280 void restoreFactors( const VarSet& ns );
281 //@}
282
283 /// \name Transformations
284 //@{
285 /// Returns a copy of \c *this, where all factors that are subsumed by some larger factor are merged with the larger factors.
286 FactorGraph maximalFactors() const;
287
288 /// Returns a copy of \c *this, where the \a i 'th variable has been clamped to value \a x
289 /** \note This version changes the factor graph structure and thus returns a newly constructed FactorGraph
290 * and keeps the current one constant, contrary to clamp()
291 */
292 FactorGraph clamped( size_t i, size_t x ) const;
293 //@}
294
295 /// \name Operations
296 //@{
297 /// Clamp the \a i 'th variable to value \a x (i.e. multiply with a Kronecker delta \f$\delta_{x_i, x}\f$)
298 /** If \a backup == \c true, make a backup of all factors that are changed
299 */
300 virtual void clamp( size_t i, size_t x, bool backup = false );
301
302 /// Clamp a variable in a factor graph to have one out of a list of values
303 /** If \a backup == \c true, make a backup of all factors that are changed
304 */
305 void clampVar( size_t i, const std::vector<size_t>& xis, bool backup = false );
306
307 /// Clamp a factor in a factor graph to have one out of a list of values
308 /** If \a backup == \c true, make a backup of all factors that are changed
309 */
310 void clampFactor( size_t I, const std::vector<size_t>& xIs, bool backup = false );
311
312 /// Set all factors interacting with the \a i 'th variable to 1
313 /** If \a backup == \c true, make a backup of all factors that are changed
314 */
315 virtual void makeCavity( size_t i, bool backup = false );
316 //@}
317
318 /// \name Input/Output
319 //@{
320 /// Reads a factor graph from a file
321 /** \see \ref fileformats-factorgraph
322 * \throw CANNOT_READ_FILE if the file cannot be opened
323 * \throw INVALID_FACTORGRAPH_FILE if the file is not valid
324 */
325 virtual void ReadFromFile( const char *filename );
326
327 /// Writes a factor graph to a file
328 /** \see \ref fileformats-factorgraph
329 * \throw CANNOT_WRITE_FILE if the file cannot be written
330 */
331 virtual void WriteToFile( const char *filename, size_t precision=15 ) const;
332
333 /// Writes a factor graph to an output stream
334 /** \see \ref fileformats-factorgraph
335 */
336 friend std::ostream& operator<< (std::ostream& os, const FactorGraph& fg );
337
338 /// Reads a factor graph from an input stream
339 /** \see \ref fileformats-factorgraph
340 * \throw INVALID_FACTORGRAPH_FILE if the input stream is not valid
341 */
342 friend std::istream& operator>> (std::istream& is, FactorGraph& fg );
343
344 /// Writes a factor graph to a GraphViz .dot file
345 virtual void printDot( std::ostream& os ) const;
346 //@}
347
348 private:
349 /// Part of constructors (creates edges, neighbors and adjacency matrix)
350 void constructGraph( size_t nrEdges );
351 };
352
353
354 template<typename FactorInputIterator, typename VarInputIterator>
355 FactorGraph::FactorGraph(FactorInputIterator facBegin, FactorInputIterator facEnd, VarInputIterator varBegin, VarInputIterator varEnd, size_t nrFacHint, size_t nrVarHint ) : _G(), _backup() {
356 // add factors
357 size_t nrEdges = 0;
358 _factors.reserve( nrFacHint );
359 for( FactorInputIterator p2 = facBegin; p2 != facEnd; ++p2 ) {
360 _factors.push_back( *p2 );
361 nrEdges += p2->vars().size();
362 }
363
364 // add variables
365 _vars.reserve( nrVarHint );
366 for( VarInputIterator p1 = varBegin; p1 != varEnd; ++p1 )
367 _vars.push_back( *p1 );
368
369 // create graph structure
370 constructGraph( nrEdges );
371 }
372
373
374 /** \example example_sprinkler.cpp
375 * This example illustrates how to manually construct a factor graph and
376 * write it to a file.
377 */
378
379
380 } // end of namespace dai
381
382
383 #endif