Cleaned up error handling by introducing the DAI_THROWE macro.
[libdai.git] / include / dai / evidence.h
index 44a7984..275c3bf 100644 (file)
@@ -21,7 +21,7 @@
 
 /// \file
 /// \brief Defines classes Evidence and Observation
-/// \todo Improve documentation
+/// \todo Describe tabular data file format
 
 
 #ifndef __defined_libdai_evidence_h
@@ -38,53 +38,65 @@ namespace dai {
 /// Stores observed values of a subset of variables
 class Observation {
     private:
+        /// Used to store the state of some variables
         std::map<Var, size_t> _obs;
 
     public:
         /// Default constructor
         Observation() : _obs() {}
+
         /// Get all observations
         const std::map<Var, size_t>& observations() const { return _obs; }
+        
         /// Add an observation
         void addObservation( Var node, size_t setting );
-        /// Clamp variables to observed values
+        
+        /// Clamp variables in the graphical model to their observed values
         void applyEvidence( InfAlg& alg ) const;
 };
 
 
-/// Stores multiple observations of variables
-/** The Evidence class contains multiple samples, where a sample is the joint
+/// Stores multiple joint observations of sets of variables.
+/** The Evidence class stores multiple samples, where each sample is the joint
  *  observation of the states of some variables.
  */
 class Evidence {
     private:
+        /// Each sample is the joint observation of the states of some variables
         std::vector<Observation> _samples;
 
     public:
         /// Default constructor
         Evidence() : _samples() {}
       
-        /** Read in tab-data from a stream. Each line contains one sample, and
-         *  the first line is a header line with names.
+        /// Read in tabular data from a stream. 
+        /** Each line contains one sample, and the first line is a header line with names.
          */
-        void addEvidenceTabFile(std::istream& is, std::map<std::string, Var>& varMap);
+        void addEvidenceTabFile( std::istream& is, std::map<std::string, Var> &varMap );
 
-        /** Read in tab-data from a stream. Each line contains one sample,
-         *  and the first line is a header line with variable labels. 
+        /// Read in tabular data from a stream. 
+        /** Each line contains one sample, and the first line is a header line with 
+         *  variable labels which should correspond with a subset of the variables in fg.
          */
-        void addEvidenceTabFile(std::istream& is, FactorGraph& fg);
+        void addEvidenceTabFile( std::istream& is, FactorGraph& fg );
       
-        /// Returns total number of samples
+        /// Returns number of stored samples
         size_t nrSamples() const { return _samples.size(); }
 
-        /// @name iterator interface
+        /// @name Iterator interface
         //@{
+        /// Iterator over the elements
         typedef std::vector<Observation>::iterator iterator;
+        /// Constant iterator over the elements
         typedef std::vector<Observation>::const_iterator const_iterator;
 
+        /// Returns iterator that points to the first element
         iterator begin() { return _samples.begin(); }
+        /// Returns constant iterator that points to the first element
         const_iterator begin() const { return _samples.begin(); }
+        /// Returns iterator that points beyond the last element
         iterator end() { return _samples.end(); }
+        /// Returns constant iterator that points beyond the last element
         const_iterator end() const { return _samples.end(); }
         //@}
 };