aGrUM  0.15.1
gum::learning::Score< ALLOC > Class Template Referenceabstract

The base class for all the scores used for learning (BIC, BDeu, etc) More...

#include <agrum/learning/scores_and_tests/score.h>

+ Inheritance diagram for gum::learning::Score< ALLOC >:
+ Collaboration diagram for gum::learning::Score< ALLOC >:

Public Member Functions

Constructors / Destructors
 Score (const DBRowGeneratorParser< ALLOC > &parser, const Apriori< ALLOC > &external_apriori, const std::vector< std::pair< std::size_t, std::size_t >, ALLOC< std::pair< std::size_t, std::size_t > > > &ranges, const Bijection< NodeId, std::size_t, ALLOC< std::size_t > > &nodeId2columns=Bijection< NodeId, std::size_t, ALLOC< std::size_t > >(), const allocator_type &alloc=allocator_type())
 default constructor More...
 
 Score (const DBRowGeneratorParser< ALLOC > &parser, const Apriori< ALLOC > &external_apriori, const Bijection< NodeId, std::size_t, ALLOC< std::size_t > > &nodeId2columns=Bijection< NodeId, std::size_t, ALLOC< std::size_t > >(), const allocator_type &alloc=allocator_type())
 default constructor More...
 
virtual Score< ALLOC > * clone () const =0
 virtual copy constructor More...
 
virtual Score< ALLOC > * clone (const allocator_type &alloc) const =0
 virtual copy constructor with a given allocator More...
 
virtual ~Score ()
 destructor More...
 
Accessors / Modifiers
virtual void setMaxNbThreads (std::size_t nb) const
 changes the max number of threads used to parse the database More...
 
virtual std::size_t nbThreads () const
 returns the number of threads used to parse the database More...
 
virtual void setMinNbRowsPerThread (const std::size_t nb) const
 changes the number min of rows a thread should process in a multithreading context More...
 
virtual std::size_t minNbRowsPerThread () const
 returns the minimum of rows that each thread should process More...
 
template<template< typename > class XALLOC>
void setRanges (const std::vector< std::pair< std::size_t, std::size_t >, XALLOC< std::pair< std::size_t, std::size_t > > > &new_ranges)
 sets new ranges to perform the countings used by the score More...
 
void clearRanges ()
 reset the ranges to the one range corresponding to the whole database More...
 
const std::vector< std::pair< std::size_t, std::size_t >, ALLOC< std::pair< std::size_t, std::size_t > > > & ranges () const
 returns the current ranges More...
 
double score (const NodeId var)
 returns the score of a single node More...
 
double score (const NodeId var, const std::vector< NodeId, ALLOC< NodeId > > &rhs_ids)
 returns the score of a single node given some other nodes More...
 
void clear ()
 clears all the data structures from memory, including the cache More...
 
void clearCache ()
 clears the current cache More...
 
void useCache (const bool on_off)
 turn on/off the use of a cache of the previously computed score More...
 
bool isUsingCache () const
 indicates whether the score uses a cache More...
 
const Bijection< NodeId, std::size_t, ALLOC< std::size_t > > & nodeId2Columns () const
 return the mapping between the columns of the database and the node ids More...
 
const DatabaseTable< ALLOC > & database () const
 return the database used by the score More...
 
virtual std::string isAprioriCompatible () const =0
 indicates whether the apriori is compatible (meaningful) with the score More...
 
virtual const Apriori< ALLOC > & internalApriori () const =0
 returns the internal apriori of the score More...
 
allocator_type getAllocator () const
 returns the allocator used by the score More...
 

Public Types

using allocator_type = ALLOC< NodeId >
 type for the allocators passed in arguments of methods More...
 

Protected Attributes

const double _1log2 {M_LOG2E}
 1 / log(2) More...
 
Apriori< ALLOC > * _apriori {nullptr}
 the expert knowledge a priori we add to the score More...
 
RecordCounter< ALLOC > _counter
 the record counter used for the countings over discrete variables More...
 
ScoringCache< ALLOC > _cache
 the scoring cache More...
 
bool _use_cache {true}
 a Boolean indicating whether we wish to use the cache More...
 
const std::vector< NodeId, ALLOC< NodeId > > _empty_ids
 an empty vector More...
 

Protected Member Functions

 Score (const Score< ALLOC > &from)
 copy constructor More...
 
 Score (const Score< ALLOC > &from, const allocator_type &alloc)
 copy constructor with a given allocator More...
 
 Score (Score< ALLOC > &&from)
 move constructor More...
 
 Score (Score< ALLOC > &&from, const allocator_type &alloc)
 move constructor with a given allocator More...
 
Score< ALLOC > & operator= (const Score< ALLOC > &from)
 copy operator More...
 
Score< ALLOC > & operator= (Score< ALLOC > &&from)
 move operator More...
 
virtual double _score (const IdSet< ALLOC > &idset)=0
 returns the score for a given IdSet More...
 
std::vector< double, ALLOC< double > > _marginalize (const NodeId X_id, const std::vector< double, ALLOC< double > > &N_xyz) const
 returns a counting vector where variables are marginalized from N_xyz More...
 

Detailed Description

template<template< typename > class ALLOC = std::allocator>
class gum::learning::Score< ALLOC >

The base class for all the scores used for learning (BIC, BDeu, etc)

Definition at line 52 of file score.h.

Member Typedef Documentation

◆ allocator_type

template<template< typename > class ALLOC = std::allocator>
using gum::learning::Score< ALLOC >::allocator_type = ALLOC< NodeId >

type for the allocators passed in arguments of methods

Definition at line 55 of file score.h.

Constructor & Destructor Documentation

◆ Score() [1/6]

template<template< typename > class ALLOC = std::allocator>
gum::learning::Score< ALLOC >::Score ( const DBRowGeneratorParser< ALLOC > &  parser,
const Apriori< ALLOC > &  external_apriori,
const std::vector< std::pair< std::size_t, std::size_t >, ALLOC< std::pair< std::size_t, std::size_t > > > &  ranges,
const Bijection< NodeId, std::size_t, ALLOC< std::size_t > > &  nodeId2columns = BijectionNodeId, std::size_t, ALLOC< std::size_t > >(),
const allocator_type alloc = allocator_type() 
)

default constructor

Parameters
parserthe parser used to parse the database
external_aprioriAn apriori that we add to the computation of the score (this should come from expert knowledge)
rangesa set of pairs {(X1,Y1),...,(Xn,Yn)} of database's rows indices. The countings are then performed only on the union of the rows [Xi,Yi), i in {1,...,n}. This is useful, e.g, when performing cross validation tasks, in which part of the database should be ignored. An empty set of ranges is equivalent to an interval [X,Y) ranging over the whole database.
nodeId2Columnsa mapping from the ids of the nodes in the graphical model to the corresponding column in the DatabaseTable parsed by the parser. This enables estimating from a database in which variable A corresponds to the 2nd column the parameters of a BN in which variable A has a NodeId of 5. An empty nodeId2Columns bijection means that the mapping is an identity, i.e., the value of a NodeId is equal to the index of the column in the DatabaseTable.
allocthe allocator used to allocate the structures within the Score.
Warning
If nodeId2columns is not empty, then only the scores over the ids belonging to this bijection can be computed: applying method score() over other ids will raise exception NotFound.

◆ Score() [2/6]

template<template< typename > class ALLOC = std::allocator>
gum::learning::Score< ALLOC >::Score ( const DBRowGeneratorParser< ALLOC > &  parser,
const Apriori< ALLOC > &  external_apriori,
const Bijection< NodeId, std::size_t, ALLOC< std::size_t > > &  nodeId2columns = BijectionNodeId, std::size_t, ALLOC< std::size_t > >(),
const allocator_type alloc = allocator_type() 
)

default constructor

Parameters
parserthe parser used to parse the database
external_aprioriAn apriori that we add to the computation of the score (this should come from expert knowledge)
nodeId2Columnsa mapping from the ids of the nodes in the graphical model to the corresponding column in the DatabaseTable parsed by the parser. This enables estimating from a database in which variable A corresponds to the 2nd column the parameters of a BN in which variable A has a NodeId of 5. An empty nodeId2Columns bijection means that the mapping is an identity, i.e., the value of a NodeId is equal to the index of the column in the DatabaseTable.
allocthe allocator used to allocate the structures within the Score.
Warning
If nodeId2columns is not empty, then only the scores over the ids belonging to this bijection can be computed: applying method score() over other ids will raise exception NotFound.

◆ ~Score()

template<template< typename > class ALLOC = std::allocator>
virtual gum::learning::Score< ALLOC >::~Score ( )
virtual

destructor

◆ Score() [3/6]

template<template< typename > class ALLOC = std::allocator>
gum::learning::Score< ALLOC >::Score ( const Score< ALLOC > &  from)
protected

copy constructor

◆ Score() [4/6]

template<template< typename > class ALLOC = std::allocator>
gum::learning::Score< ALLOC >::Score ( const Score< ALLOC > &  from,
const allocator_type alloc 
)
protected

copy constructor with a given allocator

◆ Score() [5/6]

template<template< typename > class ALLOC = std::allocator>
gum::learning::Score< ALLOC >::Score ( Score< ALLOC > &&  from)
protected

move constructor

◆ Score() [6/6]

template<template< typename > class ALLOC = std::allocator>
gum::learning::Score< ALLOC >::Score ( Score< ALLOC > &&  from,
const allocator_type alloc 
)
protected

move constructor with a given allocator

Member Function Documentation

◆ _marginalize()

template<template< typename > class ALLOC = std::allocator>
std::vector< double, ALLOC< double > > gum::learning::Score< ALLOC >::_marginalize ( const NodeId  X_id,
const std::vector< double, ALLOC< double > > &  N_xyz 
) const
protected

returns a counting vector where variables are marginalized from N_xyz

Parameters
X_idthe id of the variable to marginalize (this is the first variable in table N_xyz
N_xyza counting vector of dimension X * cond_vars (in this order)

◆ _score()

template<template< typename > class ALLOC = std::allocator>
virtual double gum::learning::Score< ALLOC >::_score ( const IdSet< ALLOC > &  idset)
protectedpure virtual

returns the score for a given IdSet

Exceptions
OperationNotAllowedis raised if the score does not support calling method score such an idset (due to too many/too few variables in the left hand side or the right hand side of the idset).

Implemented in gum::learning::ScoreLog2Likelihood< ALLOC >, gum::learning::ScoreBD< ALLOC >, gum::learning::ScoreBDeu< ALLOC >, gum::learning::ScoreBIC< ALLOC >, gum::learning::ScoreK2< ALLOC >, gum::learning::ScorefNML< ALLOC >, and gum::learning::ScoreAIC< ALLOC >.

◆ clear()

template<template< typename > class ALLOC = std::allocator>
void gum::learning::Score< ALLOC >::clear ( )

clears all the data structures from memory, including the cache

◆ clearCache()

template<template< typename > class ALLOC = std::allocator>
void gum::learning::Score< ALLOC >::clearCache ( )

clears the current cache

◆ clearRanges()

template<template< typename > class ALLOC = std::allocator>
void gum::learning::Score< ALLOC >::clearRanges ( )

reset the ranges to the one range corresponding to the whole database

◆ clone() [1/2]

template<template< typename > class ALLOC = std::allocator>
virtual Score< ALLOC >* gum::learning::Score< ALLOC >::clone ( ) const
pure virtual

◆ clone() [2/2]

template<template< typename > class ALLOC = std::allocator>
virtual Score< ALLOC >* gum::learning::Score< ALLOC >::clone ( const allocator_type alloc) const
pure virtual

◆ database()

template<template< typename > class ALLOC = std::allocator>
const DatabaseTable< ALLOC >& gum::learning::Score< ALLOC >::database ( ) const

return the database used by the score

◆ getAllocator()

template<template< typename > class ALLOC = std::allocator>
allocator_type gum::learning::Score< ALLOC >::getAllocator ( ) const

returns the allocator used by the score

◆ internalApriori()

template<template< typename > class ALLOC = std::allocator>
virtual const Apriori< ALLOC >& gum::learning::Score< ALLOC >::internalApriori ( ) const
pure virtual

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 meaningful, a structure + parameter learning requires that the same aprioris are taken into account during structure learning and parameter learning.

Implemented in gum::learning::ScoreBD< ALLOC >, gum::learning::ScoreK2< ALLOC >, gum::learning::ScoreBDeu< ALLOC >, gum::learning::ScoreLog2Likelihood< ALLOC >, gum::learning::ScorefNML< ALLOC >, gum::learning::ScoreAIC< ALLOC >, and gum::learning::ScoreBIC< ALLOC >.

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

+ Here is the caller graph for this function:

◆ isAprioriCompatible()

template<template< typename > class ALLOC = std::allocator>
virtual std::string gum::learning::Score< ALLOC >::isAprioriCompatible ( ) const
pure virtual

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

The combination of some scores and aprioris can be meaningless. For instance, adding a Dirichlet apriori to the K2 score is not very meaningful since K2 corresonds to a BD score with a 1-smoothing apriori. aGrUM allows you to perform such combination, but you can check with method isAprioriCompatible () whether the result the score will give you is meaningful or not.

Implemented in gum::learning::ScoreBD< ALLOC >, gum::learning::ScoreK2< ALLOC >, gum::learning::ScoreBDeu< ALLOC >, gum::learning::ScoreLog2Likelihood< ALLOC >, gum::learning::ScorefNML< ALLOC >, gum::learning::ScoreAIC< ALLOC >, and gum::learning::ScoreBIC< ALLOC >.

◆ isUsingCache()

template<template< typename > class ALLOC = std::allocator>
bool gum::learning::Score< ALLOC >::isUsingCache ( ) const

indicates whether the score uses a cache

◆ minNbRowsPerThread()

template<template< typename > class ALLOC = std::allocator>
virtual std::size_t gum::learning::Score< ALLOC >::minNbRowsPerThread ( ) const
virtual

returns the minimum of rows that each thread should process

◆ nbThreads()

template<template< typename > class ALLOC = std::allocator>
virtual std::size_t gum::learning::Score< ALLOC >::nbThreads ( ) const
virtual

returns the number of threads used to parse the database

◆ nodeId2Columns()

template<template< typename > class ALLOC = std::allocator>
const Bijection< NodeId, std::size_t, ALLOC< std::size_t > >& gum::learning::Score< ALLOC >::nodeId2Columns ( ) const

return the mapping between the columns of the database and the node ids

Warning
An empty nodeId2Columns bijection means that the mapping is an identity, i.e., the value of a NodeId is equal to the index of the column in the DatabaseTable.

◆ operator=() [1/2]

template<template< typename > class ALLOC = std::allocator>
Score< ALLOC >& gum::learning::Score< ALLOC >::operator= ( const Score< ALLOC > &  from)
protected

copy operator

◆ operator=() [2/2]

template<template< typename > class ALLOC = std::allocator>
Score< ALLOC >& gum::learning::Score< ALLOC >::operator= ( Score< ALLOC > &&  from)
protected

move operator

◆ ranges()

template<template< typename > class ALLOC = std::allocator>
const std::vector< std::pair< std::size_t, std::size_t >, ALLOC< std::pair< std::size_t, std::size_t > > >& gum::learning::Score< ALLOC >::ranges ( ) const

returns the current ranges

◆ score() [1/2]

template<template< typename > class ALLOC = std::allocator>
double gum::learning::Score< ALLOC >::score ( const NodeId  var)

returns the score of a single node

◆ score() [2/2]

template<template< typename > class ALLOC = std::allocator>
double gum::learning::Score< ALLOC >::score ( const NodeId  var,
const std::vector< NodeId, ALLOC< NodeId > > &  rhs_ids 
)

returns the score of a single node given some other nodes

Parameters
varthe variable on the left side of the conditioning bar
rhs_idsthe set of variables on the right side of the conditioning bar

◆ setMaxNbThreads()

template<template< typename > class ALLOC = std::allocator>
virtual void gum::learning::Score< ALLOC >::setMaxNbThreads ( std::size_t  nb) const
virtual

changes the max number of threads used to parse the database

◆ setMinNbRowsPerThread()

template<template< typename > class ALLOC = std::allocator>
virtual void gum::learning::Score< ALLOC >::setMinNbRowsPerThread ( const std::size_t  nb) const
virtual

changes the number min of rows a thread should process in a multithreading context

When computing score, several threads are used by record counters to perform countings on the rows of the database, the MinNbRowsPerThread method indicates how many rows each thread should at least process. This is used to compute the number of threads actually run. This number is equal to the min between the max number of threads allowed and the number of records in the database divided by nb.

◆ setRanges()

template<template< typename > class ALLOC = std::allocator>
template<template< typename > class XALLOC>
void gum::learning::Score< ALLOC >::setRanges ( const std::vector< std::pair< std::size_t, std::size_t >, XALLOC< std::pair< std::size_t, std::size_t > > > &  new_ranges)

sets new ranges to perform the countings used by the score

Parameters
rangesa set of pairs {(X1,Y1),...,(Xn,Yn)} of database's rows indices. The countings are then performed only on the union of the rows [Xi,Yi), i in {1,...,n}. This is useful, e.g, when performing cross validation tasks, in which part of the database should be ignored. An empty set of ranges is equivalent to an interval [X,Y) ranging over the whole database.

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

+ Here is the caller graph for this function:

◆ useCache()

template<template< typename > class ALLOC = std::allocator>
void gum::learning::Score< ALLOC >::useCache ( const bool  on_off)

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

Member Data Documentation

◆ _1log2

template<template< typename > class ALLOC = std::allocator>
const double gum::learning::Score< ALLOC >::_1log2 {M_LOG2E}
protected

1 / log(2)

Definition at line 239 of file score.h.

◆ _apriori

template<template< typename > class ALLOC = std::allocator>
Apriori< ALLOC >* gum::learning::Score< ALLOC >::_apriori {nullptr}
protected

the expert knowledge a priori we add to the score

Definition at line 242 of file score.h.

◆ _cache

template<template< typename > class ALLOC = std::allocator>
ScoringCache< ALLOC > gum::learning::Score< ALLOC >::_cache
protected

the scoring cache

Definition at line 248 of file score.h.

◆ _counter

template<template< typename > class ALLOC = std::allocator>
RecordCounter< ALLOC > gum::learning::Score< ALLOC >::_counter
protected

the record counter used for the countings over discrete variables

Definition at line 245 of file score.h.

◆ _empty_ids

template<template< typename > class ALLOC = std::allocator>
const std::vector< NodeId, ALLOC< NodeId > > gum::learning::Score< ALLOC >::_empty_ids
protected

an empty vector

Definition at line 254 of file score.h.

◆ _use_cache

template<template< typename > class ALLOC = std::allocator>
bool gum::learning::Score< ALLOC >::_use_cache {true}
protected

a Boolean indicating whether we wish to use the cache

Definition at line 251 of file score.h.


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