aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
gum::Estimator< GUM_SCALAR > Class Template Reference

#include <estimator.h>

Collaboration diagram for gum::Estimator< GUM_SCALAR >:
[legend]

Public Member Functions

 Estimator ()
 Default constructor.
 Estimator (const IBayesNet< GUM_SCALAR > *bn)
 Constructor with Bayesian network.
 ~Estimator ()
GUM_SCALAR confidence ()
 computes the maximum length of confidence interval for each possible value of each variable
bool isPriorOutweighed () const
 returns true if the generated samples outnumber the virtual ones of the prior (if any)
void update (Instantiation I, GUM_SCALAR w)
 updates the estimator with a given sample
const Tensor< GUM_SCALAR > & posterior (const DiscreteVariable &var)
 returns the posterior of a node
void clear ()
 refresh the estimator state as empty
void setFromBN (const IBayesNet< GUM_SCALAR > *bn, const NodeSet &hardEvidence)
 estimator initializing
void setFromLBP (LoopyBeliefPropagation< GUM_SCALAR > *lbp, const NodeSet &hardEvidence, GUM_SCALAR virtualLBPSize)
 sets the estimatoor object with posteriors obtained by LoopyBeliefPropagation

Private Member Functions

GUM_SCALAR EV (std::string_view name, Idx val)
 returns expected value of Bernouilli variable (called by it's name) of given parameter
GUM_SCALAR variance (std::string_view name, Idx val)
 returns variance of Bernouilli variable (called by it's name) of given parameter

Private Attributes

HashTable< std::string, std::vector< GUM_SCALAR > > estimator_
 estimator represented by hashtable between each variable name and a vector of cumulative sample weights (generated samples only)
HashTable< std::string, std::vector< GUM_SCALAR > > prior_
 prior distribution of each variable (e.g. LBP posteriors), if any
GUM_SCALAR wtotal_
 cumulated weights of the generated samples
Size ntotal_
 number of generated samples
GUM_SCALAR nvirtual_
 size of the prior as a number of virtual samples (0 if no prior)
const IBayesNet< GUM_SCALAR > * bn_
 Bayesian network on which approximation is done.
HashTable< std::string, Tensor< GUM_SCALAR > * > _target_posteriors_
 the set of single posteriors computed during the last inference

Detailed Description

template<GUM_Numeric GUM_SCALAR>
class gum::Estimator< GUM_SCALAR >

Definition at line 60 of file estimator.h.

Constructor & Destructor Documentation

◆ Estimator() [1/2]

template<GUM_Numeric GUM_SCALAR>
Estimator::Estimator ( )

Default constructor.

Definition at line 56 of file estimator_tpl.h.

56 {
58 wtotal_ = (GUM_SCALAR)0.;
59 ntotal_ = (Size)0;
61 bn_ = nullptr;
62 }
GUM_SCALAR wtotal_
cumulated weights of the generated samples
Definition estimator.h:154
const IBayesNet< GUM_SCALAR > * bn_
Bayesian network on which approximation is done.
Definition estimator.h:163
GUM_SCALAR nvirtual_
size of the prior as a number of virtual samples (0 if no prior)
Definition estimator.h:160
Estimator()
Default constructor.
Size ntotal_
number of generated samples
Definition estimator.h:157

References Estimator(), bn_, ntotal_, nvirtual_, and wtotal_.

Referenced by Estimator(), Estimator(), and ~Estimator().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ Estimator() [2/2]

template<GUM_Numeric GUM_SCALAR>
Estimator::Estimator ( const IBayesNet< GUM_SCALAR > * bn)
explicit

Constructor with Bayesian network.

Definition at line 65 of file estimator_tpl.h.

65 : Estimator() {
66 bn_ = bn;
67
68 for (gum::NodeGraphPartIterator iter = bn->nodes().begin(); iter != bn->nodes().end(); ++iter)
69 estimator_.insert(bn->variable(*iter).name(),
70 std::vector< GUM_SCALAR >(bn->variable(*iter).domainSize(), 0.0));
71
73 }
HashTable< std::string, std::vector< GUM_SCALAR > > estimator_
estimator represented by hashtable between each variable name and a vector of cumulative sample weigh...
Definition estimator.h:148

References Estimator(), gum::NodeGraphPart::begin(), bn_, gum::DiscreteVariable::domainSize(), gum::NodeGraphPart::end(), estimator_, gum::HashTable< Key, Val >::insert(), gum::Variable::name(), gum::DAGmodel::nodes(), and gum::DiscreteGraphicalModel::variable().

Here is the call graph for this function:

◆ ~Estimator()

template<GUM_Numeric GUM_SCALAR>
Estimator::~Estimator ( )

Definition at line 76 of file estimator_tpl.h.

76 {
78 // remove all the posteriors computed
79 clear();
80 }
void clear()
refresh the estimator state as empty

References Estimator(), and clear().

Here is the call graph for this function:

Member Function Documentation

◆ clear()

template<GUM_Numeric GUM_SCALAR>
void Estimator::clear ( )

refresh the estimator state as empty

this function remove all the statistics in order to restart the computations.

Definition at line 222 of file estimator_tpl.h.

222 {
223 estimator_.clear();
224 prior_.clear();
225 wtotal_ = (GUM_SCALAR)0;
226 ntotal_ = Size(0);
228 for (const auto& pot: _target_posteriors_)
229 delete pot.second;
231 }
HashTable< std::string, std::vector< GUM_SCALAR > > prior_
prior distribution of each variable (e.g. LBP posteriors), if any
Definition estimator.h:151
HashTable< std::string, Tensor< GUM_SCALAR > * > _target_posteriors_
the set of single posteriors computed during the last inference
Definition estimator.h:193

References _target_posteriors_, estimator_, ntotal_, nvirtual_, prior_, and wtotal_.

Referenced by ~Estimator().

Here is the caller graph for this function:

◆ confidence()

template<GUM_Numeric GUM_SCALAR>
GUM_SCALAR Estimator::confidence ( )

computes the maximum length of confidence interval for each possible value of each variable

Returns
maximum length of confidence interval

Definition at line 206 of file estimator_tpl.h.

206 {
207 GUM_SCALAR ic_max = 0;
208
209 for (auto iter = estimator_.begin(); iter != estimator_.end(); ++iter) {
210 for (Idx i = 0; i < iter.val().size(); i++) {
211 // the virtual samples of the prior (if any) count in the size of the sample
213 2 * 1.96 * std::sqrt(variance(iter.key(), i) / (nvirtual_ + (GUM_SCALAR)ntotal_ - 1)));
214 if (ic > ic_max) ic_max = ic;
215 }
216 }
217
218 return ic_max;
219 }
GUM_SCALAR variance(std::string_view name, Idx val)
returns variance of Bernouilli variable (called by it's name) of given parameter

References estimator_, ntotal_, nvirtual_, and variance().

Here is the call graph for this function:

◆ EV()

template<GUM_Numeric GUM_SCALAR>
GUM_SCALAR Estimator::EV ( std::string_view name,
Idx val )
private

returns expected value of Bernouilli variable (called by it's name) of given parameter

Returns
Expected value of Bernouilli variable (called by it's name) of given parameter
Parameters
namevariable's name, considered as a Bernouilli variable
valthe parameter of the Bernouilli variable

computes the amount of cumulative weights for paramater val over the amount of total cumulative weights

Definition at line 179 of file estimator_tpl.h.

179 {
180 if (nvirtual_ > (GUM_SCALAR)0) {
181 if (const auto prior = prior_.tryGet(name)) {
182 // The prior is worth nvirtual_ samples of the mean weight of the generated samples: the
183 // weights of the generated samples (e.g. likelihood or importance weights) may be far from
184 // 1, the prior must be expressed in the same unit to be balanced against them.
185 const auto n = (GUM_SCALAR)ntotal_;
186 const auto sampled
188 return (nvirtual_ * (*prior)[val] + n * sampled) / (nvirtual_ + n);
189 }
190 }
191 return estimator_[name][val] / wtotal_;
192 }

References estimator_, ntotal_, nvirtual_, prior_, and wtotal_.

Referenced by posterior(), and variance().

Here is the caller graph for this function:

◆ isPriorOutweighed()

template<GUM_Numeric GUM_SCALAR>
bool Estimator::isPriorOutweighed ( ) const

returns true if the generated samples outnumber the virtual ones of the prior (if any)

When the estimator is initialized from a prior (e.g. by setFromLBP), this prior counts as virtual samples, each with the mean weight of the generated samples. As long as they outnumber the generated samples, the estimation hardly moves and the convergence criteria are meaningless.

Definition at line 131 of file estimator_tpl.h.

131 {
132 return (GUM_SCALAR)ntotal_ >= nvirtual_;
133 }

References ntotal_, and nvirtual_.

◆ posterior()

template<GUM_Numeric GUM_SCALAR>
const Tensor< GUM_SCALAR > & Estimator::posterior ( const DiscreteVariable & var)

returns the posterior of a node

Returns
a constant ref to the posterior probability of the variable node
Parameters
varthe variable node which we want posterior for

returns the vector of cumulated weight bias for each value of the variable normalized as a CPT

Exceptions
NotFoundif variable node is not in estimator.

Definition at line 150 of file estimator_tpl.h.

150 {
151 Tensor< GUM_SCALAR >* p = nullptr;
152
153 if (!estimator_.exists(var.name())) GUM_ERROR(NotFound, "Target variable not found")
154
155 // check if we have already computed the posterior
157 p = _target_posteriors_[var.name()];
158 } else {
159 p = new Tensor< GUM_SCALAR >();
160 *p << var;
161 _target_posteriors_.insert(var.name(), p);
162 }
163
164 if (nvirtual_ > (GUM_SCALAR)0 && prior_.exists(var.name())) {
165 std::vector< GUM_SCALAR > v(var.domainSize());
166 for (Idx i = 0; i < v.size(); ++i)
167 v[i] = EV(var.name(), i);
168 p->fillWith(v);
169 } else {
170 p->fillWith(estimator_[var.name()]);
171 }
172 p->normalize();
173 return *p;
174 }
GUM_SCALAR EV(std::string_view name, Idx val)
returns expected value of Bernouilli variable (called by it's name) of given parameter

References _target_posteriors_, gum::DiscreteVariable::domainSize(), estimator_, EV(), GUM_ERROR, gum::Variable::name(), nvirtual_, and prior_.

Here is the call graph for this function:

◆ setFromBN()

template<GUM_Numeric GUM_SCALAR>
void Estimator::setFromBN ( const IBayesNet< GUM_SCALAR > * bn,
const NodeSet & hardEvidence )

estimator initializing

sets the estimator object with 0-filled vectors corresponding to each non evidence node

Definition at line 85 of file estimator_tpl.h.

86 {
87 prior_.clear();
89 for (gum::NodeGraphPartIterator iter = bn->nodes().begin(); iter != bn->nodes().end(); ++iter) {
90 auto v = bn->variable(*iter).name();
91
92 if (!hardEvidence.contains(*iter)) {
93 if (estimator_.exists(v))
95 = std::vector< GUM_SCALAR >(bn->variable(*iter).domainSize(), (GUM_SCALAR)0.0);
96 else
97 estimator_.insert(
98 v,
99 std::vector< GUM_SCALAR >(bn->variable(*iter).domainSize(), (GUM_SCALAR)0.0));
100 }
101 }
102 }

References gum::NodeGraphPart::begin(), gum::Set< Key >::contains(), gum::DiscreteVariable::domainSize(), gum::NodeGraphPart::end(), estimator_, gum::Variable::name(), gum::DAGmodel::nodes(), nvirtual_, prior_, and gum::DiscreteGraphicalModel::variable().

Here is the call graph for this function:

◆ setFromLBP()

template<GUM_Numeric GUM_SCALAR>
void Estimator::setFromLBP ( LoopyBeliefPropagation< GUM_SCALAR > * lbp,
const NodeSet & hardEvidence,
GUM_SCALAR virtualLBPSize )

sets the estimatoor object with posteriors obtained by LoopyBeliefPropagation

Definition at line 107 of file estimator_tpl.h.

109 {
110 for (const auto& node: lbp->BN().nodes()) {
111 if (!hardEvidence.contains(node)) {
113 auto p = lbp->posterior(node);
115
116 for (inst.setFirst(); !inst.end(); ++inst) {
117 v.push_back(p[inst]);
118 }
119
120 const auto& name = lbp->BN().variable(node).name();
122 prior_.insert(name, std::move(v));
123 }
124 }
125 ntotal_ = (Size)0;
127 wtotal_ = (GUM_SCALAR)0.;
128 }
const Tensor< GUM_SCALAR > & posterior(const DiscreteVariable &var)
returns the posterior of a node

References gum::BayesNetInference< GUM_SCALAR >::BN(), gum::Set< Key >::contains(), gum::Instantiation::end(), estimator_, ntotal_, nvirtual_, gum::MarginalTargetedInference< GUM_SCALAR >::posterior(), prior_, gum::Instantiation::setFirst(), and wtotal_.

Here is the call graph for this function:

◆ update()

template<GUM_Numeric GUM_SCALAR>
void Estimator::update ( Instantiation I,
GUM_SCALAR w )

updates the estimator with a given sample

Parameters
Ithe sample used to update the estimators
weightbias for the given sample

adds the sample weight to each node's given value in the estimator

Definition at line 138 of file estimator_tpl.h.

138 {
139 wtotal_ += w;
140 ntotal_ += (Size)1;
141
142 for (Idx i = 0; i < I.nbrDim(); i++) {
143 if (estimator_.exists(I.variable(i).name())) estimator_[I.variable(i).name()][I.val(i)] += w;
144 }
145 }

References estimator_, gum::Variable::name(), gum::Instantiation::nbrDim(), ntotal_, gum::Instantiation::val(), gum::Instantiation::variable(), and wtotal_.

Here is the call graph for this function:

◆ variance()

template<GUM_Numeric GUM_SCALAR>
GUM_SCALAR Estimator::variance ( std::string_view name,
Idx val )
private

returns variance of Bernouilli variable (called by it's name) of given parameter

Returns
variance of Bernouilli variable (called by it's name) of given parameter
Parameters
namevariable's name, considered as a Bernouilli variable
valthe parameter of the Bernouilli variable

computes variance for Bernouilli law using EV(name, val)

Definition at line 197 of file estimator_tpl.h.

197 {
198 GUM_SCALAR p = EV(name, val);
199 return p * (1 - p);
200 }

References EV().

Referenced by confidence().

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ _target_posteriors_

template<GUM_Numeric GUM_SCALAR>
HashTable< std::string, Tensor< GUM_SCALAR >* > gum::Estimator< GUM_SCALAR >::_target_posteriors_
private

the set of single posteriors computed during the last inference

the posteriors are owned by LazyPropagation.

Definition at line 193 of file estimator.h.

Referenced by clear(), and posterior().

◆ bn_

template<GUM_Numeric GUM_SCALAR>
const IBayesNet< GUM_SCALAR >* gum::Estimator< GUM_SCALAR >::bn_
private

Bayesian network on which approximation is done.

Definition at line 163 of file estimator.h.

Referenced by Estimator(), and Estimator().

◆ estimator_

template<GUM_Numeric GUM_SCALAR>
HashTable< std::string, std::vector< GUM_SCALAR > > gum::Estimator< GUM_SCALAR >::estimator_
private

estimator represented by hashtable between each variable name and a vector of cumulative sample weights (generated samples only)

Definition at line 148 of file estimator.h.

Referenced by Estimator(), clear(), confidence(), EV(), posterior(), setFromBN(), setFromLBP(), and update().

◆ ntotal_

template<GUM_Numeric GUM_SCALAR>
Size gum::Estimator< GUM_SCALAR >::ntotal_
private

number of generated samples

Definition at line 157 of file estimator.h.

Referenced by Estimator(), clear(), confidence(), EV(), isPriorOutweighed(), setFromLBP(), and update().

◆ nvirtual_

template<GUM_Numeric GUM_SCALAR>
GUM_SCALAR gum::Estimator< GUM_SCALAR >::nvirtual_
private

size of the prior as a number of virtual samples (0 if no prior)

Definition at line 160 of file estimator.h.

Referenced by Estimator(), clear(), confidence(), EV(), isPriorOutweighed(), posterior(), setFromBN(), and setFromLBP().

◆ prior_

template<GUM_Numeric GUM_SCALAR>
HashTable< std::string, std::vector< GUM_SCALAR > > gum::Estimator< GUM_SCALAR >::prior_
private

prior distribution of each variable (e.g. LBP posteriors), if any

Definition at line 151 of file estimator.h.

Referenced by clear(), EV(), posterior(), setFromBN(), and setFromLBP().

◆ wtotal_

template<GUM_Numeric GUM_SCALAR>
GUM_SCALAR gum::Estimator< GUM_SCALAR >::wtotal_
private

cumulated weights of the generated samples

Definition at line 154 of file estimator.h.

Referenced by Estimator(), clear(), EV(), setFromLBP(), and update().


The documentation for this class was generated from the following files: