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