Improved documentation of include/dai/exactinf.h
[libdai.git] / include / dai / evidence.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) 2009 Charles Vaske [cvaske at soe dot ucsc dot edu]
8 * Copyright (C) 2009 University of California, Santa Cruz
9 */
10
11
12 /// \file
13 /// \brief Defines classes Evidence and Observation
14 /// \todo Describe tabular data file format
15 /// \todo Improve documentation
16
17
18 #ifndef __defined_libdai_evidence_h
19 #define __defined_libdai_evidence_h
20
21
22 #include <istream>
23 #include <dai/daialg.h>
24
25
26 namespace dai {
27
28
29 /// Stores observed values of a subset of variables
30 class Observation {
31 private:
32 /// Used to store the state of some variables
33 std::map<Var, size_t> _obs;
34
35 public:
36 /// Default constructor
37 Observation() : _obs() {}
38
39 /// Get all observations
40 const std::map<Var, size_t>& observations() const { return _obs; }
41
42 /// Add an observation
43 void addObservation( Var node, size_t setting );
44
45 /// Clamp variables in the graphical model to their observed values
46 void applyEvidence( InfAlg& alg ) const;
47 };
48
49
50 /// Stores multiple joint observations of sets of variables.
51 /** The Evidence class stores multiple samples, where each sample is the joint
52 * observation of the states of some variables.
53 */
54 class Evidence {
55 private:
56 /// Each sample is the joint observation of the states of some variables
57 std::vector<Observation> _samples;
58
59 public:
60 /// Default constructor
61 Evidence() : _samples() {}
62
63 /// Construct from existing samples
64 Evidence( std::vector<Observation> &samples ) : _samples(samples) {}
65
66 /// Read in tabular data from a stream.
67 /** Each line contains one sample, and the first line is a header line with names.
68 */
69 void addEvidenceTabFile( std::istream& is, std::map<std::string, Var> &varMap );
70
71 /// Read in tabular data from a stream.
72 /** Each line contains one sample, and the first line is a header line with
73 * variable labels which should correspond with a subset of the variables in fg.
74 */
75 void addEvidenceTabFile( std::istream& is, FactorGraph& fg );
76
77 /// Returns number of stored samples
78 size_t nrSamples() const { return _samples.size(); }
79
80 /// \name Iterator interface
81 //@{
82 /// Iterator over the elements
83 typedef std::vector<Observation>::iterator iterator;
84 /// Constant iterator over the elements
85 typedef std::vector<Observation>::const_iterator const_iterator;
86
87 /// Returns iterator that points to the first element
88 iterator begin() { return _samples.begin(); }
89 /// Returns constant iterator that points to the first element
90 const_iterator begin() const { return _samples.begin(); }
91 /// Returns iterator that points beyond the last element
92 iterator end() { return _samples.end(); }
93 /// Returns constant iterator that points beyond the last element
94 const_iterator end() const { return _samples.end(); }
95 //@}
96 };
97
98
99 } // end of namespace dai
100
101
102 #endif