aGrUM 3.2.0
a C++ library for (probabilistic) graphical models
gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR > Class Template Reference

InformationTheory is a template class which aims at gathering the implementation of informational functions (entropy, mutual information, etc.). More...

#include <informationTheory.h>

Collaboration diagram for gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >:
[legend]

Public Member Functions

 InformationTheory (INFERENCE_ENGINE< GUM_SCALAR > &engine, NodeSet X, NodeSet Y, NodeSet Z)
 InformationTheory (INFERENCE_ENGINE< GUM_SCALAR > &engine, const NodeSet &X, const NodeSet &Y)
 InformationTheory (INFERENCE_ENGINE< GUM_SCALAR > &engine, const std::vector< std::string > &Xnames, const std::vector< std::string > &Ynames)
 InformationTheory (INFERENCE_ENGINE< GUM_SCALAR > &engine, const std::vector< std::string > &Xnames, const std::vector< std::string > &Ynames, const std::vector< std::string > &Znames)
 ~InformationTheory ()
GUM_SCALAR entropyXY ()
GUM_SCALAR entropyX ()
GUM_SCALAR entropyY ()
GUM_SCALAR entropyXgivenY ()
GUM_SCALAR entropyYgivenX ()
GUM_SCALAR mutualInformationXY ()
GUM_SCALAR variationOfInformationXY ()
GUM_SCALAR entropyXgivenZ ()
GUM_SCALAR entropyYgivenZ ()
GUM_SCALAR entropyXYgivenZ ()
GUM_SCALAR entropyXgivenYZ ()
GUM_SCALAR mutualInformationXYgivenZ ()

Protected Member Functions

void makeInference_ ()

Protected Attributes

INFERENCE_ENGINE< GUM_SCALAR > & engine_
const NodeSet X_
const NodeSet Y_
const NodeSet Z_
VariableSet vX_
VariableSet vY_
VariableSet vZ_
Tensor< GUM_SCALAR > pXYZ_
Tensor< GUM_SCALAR > pXY_
Tensor< GUM_SCALAR > pXZ_
Tensor< GUM_SCALAR > pYZ_
Tensor< GUM_SCALAR > pX_
Tensor< GUM_SCALAR > pY_
Tensor< GUM_SCALAR > pZ_

Detailed Description

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
class gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >

InformationTheory is a template class which aims at gathering the implementation of informational functions (entropy, mutual information, etc.).

All these operations start with the inference of a joint distribution. Moreover, it is possible to want to condition these calculations. The inference (able to compute joint distributions) passed as an argument can therefore have previously defined evidence.

Warning
The joint distribution underlying the computations has a definition domain of exponential size depending on the number of variables passed as arguments. One must be aware of the complexity of the inference that will initially be carried out.
Note
All computations are made with std::log2
Template Parameters
INFERENCE_ENGINE: the inference engine
GUM_SCALAR: the numeric type of parameters

Definition at line 83 of file informationTheory.h.

Constructor & Destructor Documentation

◆ InformationTheory() [1/4]

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::InformationTheory ( INFERENCE_ENGINE< GUM_SCALAR > & engine,
gum::NodeSet X,
gum::NodeSet Y,
gum::NodeSet Z )

Definition at line 63 of file informationTheory_tpl.h.

69 if ((!(X_ * Y_).empty()) || (!(X_ * Z_).empty()) || (!(Z_ * Y_).empty()))
70 GUM_ERROR(OperationNotAllowed, "The intersection between the set of variables must be empty")
72 }
InformationTheory is a template class which aims at gathering the implementation of informational fun...
InformationTheory(INFERENCE_ENGINE< GUM_SCALAR > &engine, NodeSet X, NodeSet Y, NodeSet Z)
INFERENCE_ENGINE< GUM_SCALAR > & engine_

References InformationTheory(), engine_, GUM_ERROR, makeInference_(), X_, Y_, and Z_.

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

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

◆ InformationTheory() [2/4]

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::InformationTheory ( INFERENCE_ENGINE< GUM_SCALAR > & engine,
const NodeSet & X,
const NodeSet & Y )

Definition at line 75 of file informationTheory_tpl.h.

References InformationTheory().

Here is the call graph for this function:

◆ InformationTheory() [3/4]

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::InformationTheory ( INFERENCE_ENGINE< GUM_SCALAR > & engine,
const std::vector< std::string > & Xnames,
const std::vector< std::string > & Ynames )

Definition at line 81 of file informationTheory_tpl.h.

84 :
86 engine.model().nodeset(Xnames),
87 engine.model().nodeset(Ynames),
88 NodeSet()) {}

References InformationTheory().

Here is the call graph for this function:

◆ InformationTheory() [4/4]

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::InformationTheory ( INFERENCE_ENGINE< GUM_SCALAR > & engine,
const std::vector< std::string > & Xnames,
const std::vector< std::string > & Ynames,
const std::vector< std::string > & Znames )

Definition at line 91 of file informationTheory_tpl.h.

95 :
97 engine.model().nodeset(Xnames),
98 engine.model().nodeset(Ynames),
99 engine.model().nodeset(Znames)) {}

References InformationTheory().

Here is the call graph for this function:

◆ ~InformationTheory()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::~InformationTheory ( )

Definition at line 102 of file informationTheory_tpl.h.

102 {
104 }

References InformationTheory().

Here is the call graph for this function:

Member Function Documentation

◆ entropyX()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyX ( )

Definition at line 151 of file informationTheory_tpl.h.

151{ return pX_.entropy(); }
Tensor< GUM_SCALAR > pX_

References pX_.

◆ entropyXgivenY()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyXgivenY ( )

Definition at line 162 of file informationTheory_tpl.h.

162 {
163 return -pXY_.expectedValue([this](const gum::Instantiation& i) -> GUM_SCALAR {
164 // f(x,y)=log (p(x,y)/p(y))
165 const auto& pxy = pXY_[i];
166 if (pxy == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
167
168 const auto& py = pY_[i];
169 if (py == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
170
171 return GUM_LOG2_OR_0(pxy / py);
172 });
173 }
Tensor< GUM_SCALAR > pY_
Tensor< GUM_SCALAR > pXY_

References GUM_LOG2_OR_0, pXY_, and pY_.

◆ entropyXgivenYZ()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyXgivenYZ ( )

Definition at line 257 of file informationTheory_tpl.h.

257 {
258 if (Z_.empty()) GUM_ERROR(ArgumentError, "Z has not been specified.")
260 // f(x,y,z)= -log(p(x,y,z)/p(y,z))
261 const auto& pxyz = pXYZ_[i];
262 if (pxyz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
263
264 const auto& pyz = pYZ_[i];
265 if (pyz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
266
267 return -GUM_LOG2_OR_0(pxyz / pyz);
268 });
269 }
Tensor< GUM_SCALAR > pXYZ_
Tensor< GUM_SCALAR > pYZ_

References GUM_ERROR, GUM_LOG2_OR_0, pXYZ_, pYZ_, and Z_.

◆ entropyXgivenZ()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyXgivenZ ( )

Definition at line 190 of file informationTheory_tpl.h.

190 {
191 if (Z_.empty()) GUM_ERROR(ArgumentError, "Z has not been specified.")
193 // f(x,z)=log (p(x,z)/p(z))
194 const auto& pxz = pXZ_[i];
195 if (pxz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
196
197 const auto& pz = pZ_[i];
198 if (pz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
199
200 return GUM_LOG2_OR_0(pxz / pz);
201 });
202 }
Tensor< GUM_SCALAR > pXZ_
Tensor< GUM_SCALAR > pZ_

References GUM_ERROR, GUM_LOG2_OR_0, pXZ_, pZ_, and Z_.

◆ entropyXY()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyXY ( )

Definition at line 157 of file informationTheory_tpl.h.

157 {
158 return pXY_.entropy();
159 }

References pXY_.

◆ entropyXYgivenZ()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyXYgivenZ ( )

Definition at line 242 of file informationTheory_tpl.h.

242 {
243 if (Z_.empty()) GUM_ERROR(ArgumentError, "Z has not been specified.")
245 // f(x,y,z)= -log(p(x,y,z)/p(z))
246 const auto& pxyz = pXYZ_[i];
247 if (pxyz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
248
249 const auto& pz = pZ_[i];
250 if (pz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
251
252 return -GUM_LOG2_OR_0(pxyz / pz);
253 });
254 }

References GUM_ERROR, GUM_LOG2_OR_0, pXYZ_, pZ_, and Z_.

◆ entropyY()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyY ( )

Definition at line 154 of file informationTheory_tpl.h.

154{ return pY_.entropy(); }

References pY_.

◆ entropyYgivenX()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyYgivenX ( )

Definition at line 176 of file informationTheory_tpl.h.

176 {
177 return -pXY_.expectedValue([this](const gum::Instantiation& i) -> GUM_SCALAR {
178 // f(x,y)=log (p(x,y)/p(x))
179 const auto& pxy = pXY_[i];
180 if (pxy == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
181
182 const auto& px = pX_[i];
183 if (px == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
184
185 return GUM_LOG2_OR_0(pxy / px);
186 });
187 }

References GUM_LOG2_OR_0, pX_, and pXY_.

◆ entropyYgivenZ()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::entropyYgivenZ ( )

Definition at line 205 of file informationTheory_tpl.h.

205 {
206 if (Z_.empty()) GUM_ERROR(ArgumentError, "Z has not been specified.")
208 // f(y,z)=log (p(y,z)/p(z))
209 const auto& pyz = pYZ_[i];
210 if (pyz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
211
212 const auto& pz = pZ_[i];
213 if (pz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
214
215 return GUM_LOG2_OR_0(pyz / pz);
216 });
217 }

References GUM_ERROR, GUM_LOG2_OR_0, pYZ_, pZ_, and Z_.

◆ makeInference_()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE void gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::makeInference_ ( )
protected

Definition at line 107 of file informationTheory_tpl.h.

107 {
108 vX_.clear();
109 for (const auto x: X_)
110 vX_.insert(&engine_.model().variable(x));
111
112 vY_.clear();
113 for (const auto y: Y_)
114 vY_.insert(&engine_.model().variable(y));
115
116 vZ_.clear();
117 for (const auto z: Z_)
118 vZ_.insert(&engine_.model().variable(z));
119
120 const NodeSet joint_vars = X_ + Y_ + Z_;
121 if (!engine_.isJointTarget(joint_vars)) {
122 // we check if it is not an implicit target : containng a node and some of its parent (could
123 // be better)
124 bool implicit_target = false;
125 for (const auto node: joint_vars)
126 if (engine_.model().family(node).isSupersetOrEqual(joint_vars)) {
127 implicit_target = true;
128 break;
129 }
130 if (!implicit_target) {
131 engine_.eraseAllJointTargets();
132 engine_.addJointTarget(joint_vars);
133 }
134 }
135 engine_.makeInference();
136
137 if (!Z_.empty()) {
138 pXYZ_ = engine_.jointPosterior(joint_vars);
139 pXZ_ = pXYZ_.sumIn(vX_ + vZ_);
140 pYZ_ = pXYZ_.sumIn(vY_ + vZ_);
141 pZ_ = pXZ_.sumIn(vZ_);
142 pXY_ = pXYZ_.sumIn(vX_ + vY_);
143 } else {
144 pXY_ = engine_.jointPosterior(joint_vars);
145 }
146 pX_ = pXY_.sumIn(vX_);
147 pY_ = pXY_.sumIn(vY_);
148 }

References engine_, pX_, pXY_, pXYZ_, pXZ_, pY_, pYZ_, pZ_, vX_, vY_, vZ_, X_, Y_, and Z_.

Referenced by InformationTheory().

Here is the caller graph for this function:

◆ mutualInformationXY()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::mutualInformationXY ( )

Definition at line 220 of file informationTheory_tpl.h.

220 {
221 return pXY_.expectedValue([this](const gum::Instantiation& i) -> GUM_SCALAR {
222 // f(x,y)=log (p(x,y)/p(x)p(y))
223 const auto& pxy = pXY_[i];
224 if (pxy == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
225
226 const auto& pxpy = pY_[i] * pX_[i];
227 if (pxpy == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
228
229 return GUM_LOG2_OR_0(pxy / pxpy);
230 });
231 }

References GUM_LOG2_OR_0, pX_, pXY_, and pY_.

◆ mutualInformationXYgivenZ()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::mutualInformationXYgivenZ ( )

Definition at line 272 of file informationTheory_tpl.h.

272 {
273 if (Z_.empty()) GUM_ERROR(ArgumentError, "Z has not been specified.")
275 // f(x,y)=log (p(x,y)/p(x)p(y))
276 const auto& pzpxyz = pXYZ_[i] * pZ_[i];
277 if (pzpxyz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
278
279 const auto& pxzpyz = pXZ_[i] * pYZ_[i];
280 if (pxzpyz == GUM_SCALAR(0.0)) return GUM_SCALAR(0.0);
281
282 return GUM_LOG2_OR_0(pzpxyz / pxzpyz);
283 });
284 }

References GUM_ERROR, GUM_LOG2_OR_0, pXYZ_, pXZ_, pYZ_, pZ_, and Z_.

◆ variationOfInformationXY()

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFORMATION_THEORY_TEMPLATE GUM_SCALAR gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::variationOfInformationXY ( )

Definition at line 234 of file informationTheory_tpl.h.

234 {
235 return -pXY_.expectedValue([this](const gum::Instantiation& i) -> GUM_SCALAR {
236 // f(x,y)= -log(p(x)*p(y))
237 return GUM_LOG2_OR_0(pY_[i] * pX_[i]);
238 });
239 }

References GUM_LOG2_OR_0, pX_, pXY_, and pY_.

Member Data Documentation

◆ engine_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
INFERENCE_ENGINE< GUM_SCALAR >& gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::engine_
protected

Definition at line 116 of file informationTheory.h.

Referenced by InformationTheory(), and makeInference_().

◆ pX_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pX_
protected

◆ pXY_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pXY_
protected

◆ pXYZ_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pXYZ_
protected

◆ pXZ_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pXZ_
protected

Definition at line 128 of file informationTheory.h.

Referenced by entropyXgivenZ(), makeInference_(), and mutualInformationXYgivenZ().

◆ pY_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pY_
protected

◆ pYZ_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pYZ_
protected

◆ pZ_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
Tensor< GUM_SCALAR > gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::pZ_
protected

◆ vX_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
VariableSet gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::vX_
protected

Definition at line 122 of file informationTheory.h.

Referenced by makeInference_().

◆ vY_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
VariableSet gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::vY_
protected

Definition at line 123 of file informationTheory.h.

Referenced by makeInference_().

◆ vZ_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
VariableSet gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::vZ_
protected

Definition at line 124 of file informationTheory.h.

Referenced by makeInference_().

◆ X_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
const NodeSet gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::X_
protected

Definition at line 118 of file informationTheory.h.

Referenced by InformationTheory(), and makeInference_().

◆ Y_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
const NodeSet gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::Y_
protected

Definition at line 119 of file informationTheory.h.

Referenced by InformationTheory(), and makeInference_().

◆ Z_

template<template< typename > class INFERENCE_ENGINE, typename GUM_SCALAR>
const NodeSet gum::InformationTheory< INFERENCE_ENGINE, GUM_SCALAR >::Z_
protected

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