X-Git-Url: http://git.tuebingen.mpg.de/?p=libdai.git;a=blobdiff_plain;f=include%2Fdai%2Fevidence.h;h=27789ede5bcc274d44cb67bd7fb0a7c6cf028f67;hp=aecddb6d413c00b9532d4586574171712ed20974;hb=HEAD;hpb=0f1bd762747c1f41159728bdb6b5e065b2e9d488

diff --git a/include/dai/evidence.h b/include/dai/evidence.h
index aecddb6..27789ed 100644
--- a/include/dai/evidence.h
+++ b/include/dai/evidence.h
@@ -1,20 +1,13 @@
 /*  This file is part of libDAI - http://www.libdai.org/
  *
- *  libDAI is licensed under the terms of the GNU General Public License version
- *  2, or (at your option) any later version. libDAI is distributed without any
- *  warranty. See the file COPYING for more details.
+ *  Copyright (c) 2006-2011, The libDAI authors. All rights reserved.
  *
- *  Copyright (C) 2009  Charles Vaske  [cvaske at soe dot ucsc dot edu]
- *  Copyright (C) 2009  University of California, Santa Cruz
+ *  Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
  */
 
 
 /// \file
-/** \brief Defines classes Evidence and Observation
- *  \todo Describe tabular data file format
- *  \todo Improve documentation
- *  \author Charles Vaske
- */
+/// \brief Defines class Evidence, which stores multiple observations of joint states of variables
 
 
 #ifndef __defined_libdai_evidence_h
@@ -28,55 +21,33 @@
 namespace dai {
 
 
-/// Stores observed values of a subset of variables
-/** \author Charles Vaske
- */  
-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 in the graphical model to their observed values
-        void applyEvidence( InfAlg& alg ) const;
-};
-
-
-/// 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.
+/// Stores a data set consisting of multiple samples, where each sample is the observed joint state of some variables.
+/** \note Each sample can describe the joint state of a different set of variables,
+ *  in order to be able to deal with missing data.
  *
  *  \author Charles Vaske
  */
 class Evidence {
+    public:
+        /// Stores joint state of a set of variables
+        typedef std::map<Var, size_t> Observation;
+
     private:
-        /// Each sample is the joint observation of the states of some variables
+        /// Each sample is an observed joint state of some variables
         std::vector<Observation> _samples;
 
     public:
         /// Default constructor
         Evidence() : _samples() {}
 
-        /// Construct from existing samples
+        /// Construct from \a samples
         Evidence( std::vector<Observation> &samples ) : _samples(samples) {}
 
-        /// 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 );
-
-        /// 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.
+        /// Read in tabular data from a stream and add the read samples to \c *this.
+        /** \param is Input stream in .tab file format, describing joint observations of variables in \a fg
+         *  \param fg Factor graph describing the corresponding variables
+         *  \see \ref fileformats-evidence
+         *  \throw INVALID_EVIDENCE_FILE if the input stream is not valid
          */
         void addEvidenceTabFile( std::istream& is, FactorGraph& fg );
 
@@ -85,20 +56,24 @@ class Evidence {
 
     /// \name Iterator interface
     //@{
-        /// Iterator over the elements
+        /// Iterator over the samples
         typedef std::vector<Observation>::iterator iterator;
-        /// Constant iterator over the elements
+        /// Constant iterator over the samples
         typedef std::vector<Observation>::const_iterator const_iterator;
 
-        /// Returns iterator that points to the first element
+        /// Returns iterator that points to the first sample
         iterator begin() { return _samples.begin(); }
-        /// Returns constant iterator that points to the first element
+        /// Returns constant iterator that points to the first sample
         const_iterator begin() const { return _samples.begin(); }
-        /// Returns iterator that points beyond the last element
+        /// Returns iterator that points beyond the last sample
         iterator end() { return _samples.end(); }
-        /// Returns constant iterator that points beyond the last element
+        /// Returns constant iterator that points beyond the last sample
         const_iterator end() const { return _samples.end(); }
     //@}
+
+    private:
+        /// Read in tabular data from a stream and add the read samples to \c *this.
+        void addEvidenceTabFile( std::istream& is, std::map<std::string, Var> &varMap );
 };