Improved documentation of include/dai/treeep.h
authorJoris Mooij <joris.mooij@tuebingen.mpg.de>
Mon, 9 Nov 2009 14:04:02 +0000 (15:04 +0100)
committerJoris Mooij <joris.mooij@tuebingen.mpg.de>
Mon, 9 Nov 2009 14:04:02 +0000 (15:04 +0100)
TODO
include/dai/treeep.h
src/treeep.cpp

diff --git a/TODO b/TODO
index 55666e6..e322914 100644 (file)
--- a/TODO
+++ b/TODO
@@ -2,7 +2,6 @@ To do for the next release (0.2.3):
 
 Improve documentation:
 
-       treeep.h
        lc.h
        mr.h
        gibbs.h
index 40050a0..5cc269e 100644 (file)
@@ -10,8 +10,7 @@
 
 
 /// \file
-/// \brief Defines class TreeEP
-/// \todo Improve documentation
+/// \brief Defines class TreeEP, which implements Tree Expectation Propagation
 
 
 #ifndef __defined_libdai_treeep_h
@@ -34,7 +33,7 @@
 namespace dai {
 
 
-/// Approximate inference algorithm "TreeEP" by Minka and Qi
+/// Approximate inference algorithm "Tree Expectation Propagation" [\ref MiQ04]
 class TreeEP : public JTree {
     private:
         /// Maximum difference encountered so far
@@ -46,7 +45,13 @@ class TreeEP : public JTree {
         /// Parameters of this inference algorithm
         struct Properties {
             /// Enumeration of possible choices for the tree
-            DAI_ENUM(TypeType,ORG,ALT)
+            /** The two possibilities are:
+             *  - \c ORG: take the maximum spanning tree where the weights are crude
+             *            estimates of the mutual information between the nodes;
+             *  - \c ALT: take the maximum spanning tree where the weights are upper
+             *            bounds on the effective interaction strengths between pairs of nodes.
+             */
+            DAI_ENUM(TypeType,ORG,ALT);
 
             /// Verbosity
             size_t verbose;
@@ -59,12 +64,13 @@ class TreeEP : public JTree {
 
             /// How to choose the tree
             TypeType type;
-        } props; // FIXME: should be props2 because of conflict with JTree::props?
+        } props;
 
         /// Name of this inference method
         static const char *Name;
 
     private:
+        /// Stores the data structures needed to efficiently update the approximation of an off-tree factor
         class TreeEPSubTree {
             private:
                 std::vector<Factor>  _Qa;
@@ -105,6 +111,7 @@ class TreeEP : public JTree {
                 const Factor *& I() { return _I; }
         };
 
+        /// Stores a TreeEPSubTree object for each off-tree factor
         std::map<size_t, TreeEPSubTree>  _Q;
 
     public:
@@ -133,7 +140,7 @@ class TreeEP : public JTree {
             return *this;
         }
 
-        /// Construct from FactorGraph fg and PropertySet opts
+        /// Construct from FactorGraph \a fg and PropertySet \a opts
         TreeEP( const FactorGraph &fg, const PropertySet &opts );
 
 
@@ -154,7 +161,9 @@ class TreeEP : public JTree {
 
 
     private:
-        void ConstructRG( const RootedTree &tree );
+        /// Helper function for constructors
+        void construct( const RootedTree &tree );
+        /// Returns \c true if factor \a I is not part of the tree
         bool offtree( size_t I ) const { return (fac2OR[I] == -1U); }
 };
 
index ed4e87c..19d47f1 100644 (file)
@@ -192,7 +192,7 @@ TreeEP::TreeEP( const FactorGraph &fg, const PropertySet &opts ) : JTree(fg, opt
     DAI_ASSERT( fg.isConnected() );
 
     if( opts.hasKey("tree") ) {
-        ConstructRG( opts.GetAs<RootedTree>("tree") );
+        construct( opts.GetAs<RootedTree>("tree") );
     } else {
         if( props.type == Properties::TypeType::ORG || props.type == Properties::TypeType::ALT ) {
             // ORG: construct weighted graph with as weights a crude estimate of the
@@ -234,14 +234,14 @@ TreeEP::TreeEP( const FactorGraph &fg, const PropertySet &opts ) : JTree(fg, opt
             }
 
             // find maximal spanning tree
-            ConstructRG( MaxSpanningTreePrims( wg ) );
+            construct( MaxSpanningTreePrims( wg ) );
         } else
             DAI_THROW(UNKNOWN_ENUM_VALUE);
     }
 }
 
 
-void TreeEP::ConstructRG( const RootedTree &tree ) {
+void TreeEP::construct( const RootedTree &tree ) {
     vector<VarSet> Cliques;
     for( size_t i = 0; i < tree.size(); i++ )
         Cliques.push_back( VarSet( var(tree[i].n1), var(tree[i].n2) ) );