New git HEAD version
[libdai.git] / include / dai / evidence.h
index 25ae67d..27789ed 100644 (file)
@@ -1,27 +1,13 @@
-/*  Copyright (C) 2009  Charles Vaske  [cvaske at soe dot ucsc dot edu]
-    University of California Santa Cruz
-
-    This file is part of libDAI.
-
-    libDAI is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    libDAI is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with libDAI; if not, write to the Free Software
-    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-*/
+/*  This file is part of libDAI - http://www.libdai.org/
+ *
+ *  Copyright (c) 2006-2011, The libDAI authors. All rights reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
+ */
 
 
 /// \file
 
 
 /// \file
-/// \brief Defines classes Evidence and Observation
-/// \todo Improve documentation
+/// \brief Defines class Evidence, which stores multiple observations of joint states of variables
 
 
 #ifndef __defined_libdai_evidence_h
 
 
 #ifndef __defined_libdai_evidence_h
 namespace dai {
 
 
 namespace dai {
 
 
-/// Stores observed values of a subset of variables
-class Observation {
-    private:
-        std::map<Var, size_t> _obs;
-
+/// 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:
     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
-        void applyEvidence( InfAlg& alg ) const;
-};
-
+        /// Stores joint state of a set of variables
+        typedef std::map<Var, size_t> Observation;
 
 
-/// Stores multiple observations of variables
-class Evidence {
     private:
     private:
+        /// Each sample is an observed joint state of some variables
         std::vector<Observation> _samples;
 
     public:
         /// Default constructor
         Evidence() : _samples() {}
         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.
-         */
-        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. 
+        /// Construct from \a samples
+        Evidence( std::vector<Observation> &samples ) : _samples(samples) {}
+
+        /// 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);
-      
-        /// Returns total number of samples
+        void addEvidenceTabFile( std::istream& is, FactorGraph& fg );
+
+        /// Returns number of stored samples
         size_t nrSamples() const { return _samples.size(); }
 
         size_t nrSamples() const { return _samples.size(); }
 
-        /// @name iterator interface
-        //@{
+    /// \name Iterator interface
+    //@{
+        /// Iterator over the samples
         typedef std::vector<Observation>::iterator iterator;
         typedef std::vector<Observation>::iterator iterator;
+        /// Constant iterator over the samples
         typedef std::vector<Observation>::const_iterator const_iterator;
 
         typedef std::vector<Observation>::const_iterator const_iterator;
 
+        /// Returns iterator that points to the first sample
         iterator begin() { return _samples.begin(); }
         iterator begin() { return _samples.begin(); }
+        /// Returns constant iterator that points to the first sample
         const_iterator begin() const { return _samples.begin(); }
         const_iterator begin() const { return _samples.begin(); }
+        /// Returns iterator that points beyond the last sample
         iterator end() { return _samples.end(); }
         iterator end() { return _samples.end(); }
+        /// Returns constant iterator that points beyond the last sample
         const_iterator end() const { return _samples.end(); }
         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 );
 };
 
 
 };