aGrUM  0.13.2
gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc > Class Template Reference

The class for computing BDeu scores (actually their log2 value) More...

#include <scoreBDeu.h>

+ Inheritance diagram for gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >:
+ Collaboration diagram for gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >:

Public Member Functions

Constructors / Destructors
template<typename RowFilter >
 ScoreBDeu (const RowFilter &filter, const std::vector< Size > &var_modalities, Apriori< IdSetAlloc, CountAlloc > &apriori, Size min_range=0, Size max_range=std::numeric_limits< Size >::max())
 default constructor More...
 
 ScoreBDeu (const ScoreBDeu< IdSetAlloc, CountAlloc > &)
 copy constructor More...
 
 ScoreBDeu (ScoreBDeu< IdSetAlloc, CountAlloc > &&)
 move constructor More...
 
virtual ScoreBDeu< IdSetAlloc, CountAlloc > * copyFactory () const
 virtual copy factory More...
 
virtual ~ScoreBDeu ()
 destructor More...
 
Accessors / Modifiers
Idx addNodeSet (Idx var)
 add a new single variable to be counted More...
 
Idx addNodeSet (Idx var, const std::vector< Idx > &conditioning_ids)
 add a new target variable plus some conditioning vars More...
 
void clear ()
 clears all the data structures from memory More...
 
void clearCache ()
 clears the current cache (clear nodesets as well) More...
 
void useCache (bool on_off) noexcept
 turn on/off the use of a cache of the previously computed score More...
 
void setRange (Size min_range, Size max_range)
 sets the range of records taken into account by the counter More...
 

Protected Attributes

const double _1log2 {M_LOG2E}
 1 / log(2) More...
 
Apriori< IdSetAlloc, CountAlloc > * _apriori
 the a priori used by the score More...
 

Protected Member Functions

const std::vector< double, CountAlloc > & _getAllApriori (Idx index)
 returns the apriori vector for a given (conditioned) target set More...
 
const std::vector< double, CountAlloc > & _getConditioningApriori (Idx index)
 returns the apriori vector for a conditioning set More...
 
bool _isInCache (Idx nodeset_index) const noexcept
 indicates whether a score belongs to the cache More...
 
void _insertIntoCache (Idx nodeset_index, double score)
 inserts a new score into the cache More...
 
double _cachedScore (Idx nodeset_index) const noexcept
 returns a cached score More...
 
bool _isUsingCache () const noexcept
 indicates whether we use the cache or not More...
 

Accessors / Modifiers

double score (Idx nodeset_index)
 returns the log2(BDeu score) corresponding to a given nodeset More...
 
virtual bool isAprioriCompatible () const final
 indicates whether the apriori is compatible (meaningful) with the score More...
 
virtual const ScoreInternalApriori< IdSetAlloc, CountAlloc > & internalApriori () const noexceptfinal
 returns the internal apriori of the score More...
 
void setEffectiveSampleSize (double ess)
 sets the effective sample size of the internal apriori More...
 
static bool isAprioriCompatible (const std::string &apriori_type, double weight=1.0f)
 indicates whether the apriori is compatible (meaningful) with the score More...
 
static bool isAprioriCompatible (const Apriori< IdSetAlloc, CountAlloc > &apriori)
 indicates whether the apriori is compatible (meaningful) with the score More...
 

Detailed Description

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
class gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >

The class for computing BDeu scores (actually their log2 value)

Warning
This class does not actually compute a BDeu score but rather the log in base 2 of the BDeu score
As BDeu already includes an implicit ESS / (ri * qi) apriori on all the cells of contingency tables, the apriori passed to the score should be a NoApriori. But aGrUM will let you use another (certainly incompatible) apriori with the score. In this case, this apriori will be included in addition to the implicit BDeu apriori in a BD fashion, i.e., we will ressort to the Bayesian Dirichlet (BD) formula to include the sum of the two aprioris into the score.

The class should be used as follows: first, to speed-up computations, you should consider computing all the scores you need in one pass. To do so, use the appropriate addNodeSet methods. These will compute everything you need. Use methods score to retrieve the scores computed. See the Score class for details.

Definition at line 79 of file scoreBDeu.h.

Constructor & Destructor Documentation

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
template<typename RowFilter >
gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::ScoreBDeu ( const RowFilter &  filter,
const std::vector< Size > &  var_modalities,
Apriori< IdSetAlloc, CountAlloc > &  apriori,
Size  min_range = 0,
Size  max_range = std::numeric_limits< Size >::max() 
)

default constructor

Parameters
filterthe row filter that will be used to read the database
var_modalitiesthe domain sizes of the variables in the database
apriorithe apriori we add to the score. As BDeu already includes an implicit ESS / (ri * qi) apriori on all the cells of contingency tables, the apriori passed in argument should be a NoApriori. But aGrUM will let you use another (certainly incompatible) apriori with the score. In this case, this apriori will be included in addition to the implicit BDeu apriori in a BD fashion, i.e., we will ressort to the Bayesian Dirichlet (BD) formula to include the sum of the two aprioris into the score.
min_rangeThe minimal range.
max_rangeThe maximal range.
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::ScoreBDeu ( const ScoreBDeu< IdSetAlloc, CountAlloc > &  )

copy constructor

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::ScoreBDeu ( ScoreBDeu< IdSetAlloc, CountAlloc > &&  )

move constructor

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
virtual gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::~ScoreBDeu ( )
virtual

destructor

Member Function Documentation

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
double gum::learning::Score< IdSetAlloc, CountAlloc >::_cachedScore ( Idx  nodeset_index) const
protectednoexceptinherited

returns a cached score

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
const std::vector< double, CountAlloc >& gum::learning::Score< IdSetAlloc, CountAlloc >::_getAllApriori ( Idx  index)
protectedinherited

returns the apriori vector for a given (conditioned) target set

This method returns the observation countings for the set of variables whose index was returned by method addNodeSet or addNodeSet. If the set was conditioned, the countings correspond to the target variables and the conditioning variables. If you wish to get only the countings for the conditioning variables, prefer using method _getConditioningApriori.

Warning
the dimensions of the vector are as follows: first come the nodes of the conditioning set (in the order in which they were specified when callind addNodeset, and then the target nodes.
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
const std::vector< double, CountAlloc >& gum::learning::Score< IdSetAlloc, CountAlloc >::_getConditioningApriori ( Idx  index)
protectedinherited

returns the apriori vector for a conditioning set

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
void gum::learning::Score< IdSetAlloc, CountAlloc >::_insertIntoCache ( Idx  nodeset_index,
double  score 
)
protectedinherited

inserts a new score into the cache

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
bool gum::learning::Score< IdSetAlloc, CountAlloc >::_isInCache ( Idx  nodeset_index) const
protectednoexceptinherited

indicates whether a score belongs to the cache

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
bool gum::learning::Score< IdSetAlloc, CountAlloc >::_isUsingCache ( ) const
protectednoexceptinherited

indicates whether we use the cache or not

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
Idx gum::learning::Score< IdSetAlloc, CountAlloc >::addNodeSet ( Idx  var)
inherited

add a new single variable to be counted

Parameters
varrepresents the index of the variable in the filtered rows produced by the database cell filters whose observations shall be counted
Returns
the index of the produced counting vector: the user should use class Score to compute in one pass several scores or independence tests. These and their corresponding countings in the database are stored into a vector and the value returned by method addNodeSet is the index of the observed countings of "var" in this vector. The user shall pass this index as argument to methods _getAllCounts to get the corresponding counting vector.
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
Idx gum::learning::Score< IdSetAlloc, CountAlloc >::addNodeSet ( Idx  var,
const std::vector< Idx > &  conditioning_ids 
)
inherited

add a new target variable plus some conditioning vars

Parameters
varrepresents the index of the target variable in the filtered rows produced by the database cell filters
conditioning_idsthe indices of the variables of the conditioning set in the filtered rows
Returns
the index of the produced counting vector: the user should use class Score to compute in one pass several scores or independence tests. These and their corresponding countings in the database are stored into a vector and the value returned by method addNodeSet is the index of the countings of (var | conditioning_ids) in this vector. The user shall pass this index as argument to methods _getAllCounts and _getConditioningCounts to get the counting vectors of (conditioning_ids,vars) [in this order] and conditioning_ids respectively.
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
void gum::learning::Score< IdSetAlloc, CountAlloc >::clear ( )
inherited

clears all the data structures from memory

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
void gum::learning::Score< IdSetAlloc, CountAlloc >::clearCache ( )
inherited

clears the current cache (clear nodesets as well)

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
virtual ScoreBDeu< IdSetAlloc, CountAlloc >* gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::copyFactory ( ) const
virtual

virtual copy factory

Implements gum::learning::Score< IdSetAlloc, CountAlloc >.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
virtual const ScoreInternalApriori< IdSetAlloc, CountAlloc >& gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::internalApriori ( ) const
finalvirtualnoexcept

returns the internal apriori of the score

Some scores include an apriori. For instance, the K2 score is a BD score with a Laplace Apriori ( smoothing(1) ). BDeu is a BD score with a N'/(r_i * q_i) apriori, where N' is an effective sample size and r_i is the domain size of the target variable and q_i is the domain size of the Cartesian product of its parents. The goal of the score's internal apriori classes is to enable to account for these aprioris outside the score, e.g., when performing parameter estimation. It is important to note that, to be meaningfull a structure + parameter learning requires that the same aprioris are taken into account during structure learning and parameter learning.

Implements gum::learning::Score< IdSetAlloc, CountAlloc >.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
virtual bool gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::isAprioriCompatible ( ) const
finalvirtual

indicates whether the apriori is compatible (meaningful) with the score

When using the BDeu score, you should use a NoApriori: actually, BDeu already implicitly includes an ESS / (ri * qi) apriori on all the cells of contingency tables.

Returns
true if the apriori is compatible with the score.
Exceptions
IncompatibleScoreAprioriis raised if the apriori is known to be incompatible with the score. Such a case arises because the score already implicitly contains an apriori which should not be combined with the apriori passed in argument. aGrUM will nevertheless allow you to use this apriori with the score, but you should be warned that the result of learning will most probably be meaningless.
PossiblyIncompatibleScoreAprioriis raised if, in general, the apriori is incompatible with the score but, with its current weight, it becomes compatible (e.g., a Dirichlet apriori with a 0-weight is the same as a NoApriori). In such a case, you should not modify the weight. aGrUM will allow you to do so but the result of learning will most probably be meaningless.
InvalidArgumentis raised if the apriori is not handled yet by method isAprioriCompatible (the method needs be updated to take it into account).

Implements gum::learning::Score< IdSetAlloc, CountAlloc >.

Referenced by gum::learning::genericBNLearner::__checkScoreAprioriCompatibility().

+ Here is the caller graph for this function:

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
static bool gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::isAprioriCompatible ( const std::string &  apriori_type,
double  weight = 1.0f 
)
static

indicates whether the apriori is compatible (meaningful) with the score

When using the BDeu score, you should use a NoApriori: actually, BDeu already implicitly includes an ESS / (ri * qi) apriori on all the cells of contingency tables.

Returns
true if the apriori is compatible with the score.
Exceptions
IncompatibleScoreAprioriis raised if the apriori is known to be incompatible with the score. Such a case arises because the score already implicitly contains an apriori which should not be combined with the apriori passed in argument. aGrUM will nevertheless allow you to use this apriori with the score, but you should be warned that the result of learning will most probably be meaningless.
PossiblyIncompatibleScoreAprioriis raised if, in general, the apriori is incompatible with the score but, with its current weight, it becomes compatible (e.g., a Dirichlet apriori with a 0-weight is the same as a NoApriori). In such a case, you should not modify the weight. aGrUM will allow you to do so but the result of learning will most probably be meaningless.
InvalidArgumentis raised if the apriori is not handled yet by method isAprioriCompatible (the method needs be updated to take it into account).
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
static bool gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::isAprioriCompatible ( const Apriori< IdSetAlloc, CountAlloc > &  apriori)
static

indicates whether the apriori is compatible (meaningful) with the score

When using the BDeu score, you should use a NoApriori: actually, BDeu already implicitly includes an ESS / (ri * qi) apriori on all the cells of contingency tables.

Returns
true if the apriori is compatible with the score.
Exceptions
IncompatibleScoreAprioriis raised if the apriori is known to be incompatible with the score. Such a case arises because the score already implicitly contains an apriori which should not be combined with the apriori passed in argument. aGrUM will nevertheless allow you to use this apriori with the score, but you should be warned that the result of learning will most probably be meaningless.
PossiblyIncompatibleScoreAprioriis raised if, in general, the apriori is incompatible with the score but, with its current weight, it becomes compatible (e.g., a Dirichlet apriori with a 0-weight is the same as a NoApriori). In such a case, you should not modify the weight. aGrUM will allow you to do so but the result of learning will most probably be meaningless.
InvalidArgumentis raised if the apriori is not handled yet by method isAprioriCompatible (the method needs be updated to take it into account).
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
double gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::score ( Idx  nodeset_index)
virtual

returns the log2(BDeu score) corresponding to a given nodeset

Implements gum::learning::Score< IdSetAlloc, CountAlloc >.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
void gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::setEffectiveSampleSize ( double  ess)

sets the effective sample size of the internal apriori

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
void gum::learning::Score< IdSetAlloc, CountAlloc >::setRange ( Size  min_range,
Size  max_range 
)
inherited

sets the range of records taken into account by the counter

Parameters
min_rangehe number of the first record to be taken into account during learning
max_rangethe number of the record after the last one taken into account
template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
void gum::learning::Score< IdSetAlloc, CountAlloc >::useCache ( bool  on_off)
noexceptinherited

turn on/off the use of a cache of the previously computed score

Member Data Documentation

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
const double gum::learning::Score< IdSetAlloc, CountAlloc >::_1log2 {M_LOG2E}
protectedinherited

1 / log(2)

Definition at line 201 of file score.h.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
double gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::__ess {1.0f}
private

the effective sample size of the internal apriori

Definition at line 240 of file scoreBDeu.h.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
GammaLog2 gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::__gammalog2
private

the log(gamma (n)) function: generalizes log((n-1)!)

Definition at line 234 of file scoreBDeu.h.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
ScoreInternalBDeuApriori< IdSetAlloc, CountAlloc > gum::learning::ScoreBDeu< IdSetAlloc, CountAlloc >::__internal_apriori
private

the internal apriori of the score

Definition at line 237 of file scoreBDeu.h.

template<typename IdSetAlloc = std::allocator< Idx >, typename CountAlloc = std::allocator< double >>
Apriori< IdSetAlloc, CountAlloc >* gum::learning::Score< IdSetAlloc, CountAlloc >::_apriori
protectedinherited

the a priori used by the score

Definition at line 204 of file score.h.


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