the class for computing K2 scores (actually their log2 value) More...

#include <agrum/BN/learning/scores_and_tests/scoreK2.h>

Inheritance diagram for gum::learning::ScoreK2< ALLOC >:

Collaboration diagram for gum::learning::ScoreK2< ALLOC >:

Public Member Functions
Constructors / Destructors
	ScoreK2 (const DBRowGeneratorParser< ALLOC > &parser, const Apriori< ALLOC > &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...

	ScoreK2 (const DBRowGeneratorParser< ALLOC > &parser, const Apriori< ALLOC > &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...

	ScoreK2 (const ScoreK2< ALLOC > &from)
	copy constructor More...

	ScoreK2 (const ScoreK2< ALLOC > &from, const allocator_type &alloc)
	copy constructor with a given allocator More...

	ScoreK2 (ScoreK2< ALLOC > &&from)
	move constructor More...

	ScoreK2 (ScoreK2< ALLOC > &&from, const allocator_type &alloc)
	move constructor with a given allocator More...

virtual ScoreK2< ALLOC > *	clone () const
	virtual copy constructor More...

virtual ScoreK2< ALLOC > *	clone (const allocator_type &alloc) const
	virtual copy constructor with a given allocator More...

virtual	~ScoreK2 ()
	destructor More...

Operators
ScoreK2< ALLOC > &	operator= (const ScoreK2< ALLOC > &from)
	copy operator More...

ScoreK2< ALLOC > &	operator= (ScoreK2< ALLOC > &&from)
	move operator More...

Accessors / Modifiers
virtual std::string	isAprioriCompatible () const final
	indicates whether the apriori is compatible (meaningful) with the score More...

virtual const Apriori< ALLOC > &	internalApriori () const final
	returns the internal apriori of the score 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...

allocator_type	getAllocator () const
	returns the allocator used by the score More...

Static Public Member Functions
static std::string	isAprioriCompatible (const std::string &apriori_type, double weight=1.0f)
	indicates whether the apriori is compatible (meaningful) with the score More...

static std::string	isAprioriCompatible (const Apriori< ALLOC > &apriori)
	indicates whether the apriori is compatible (meaningful) with the score More...

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

Protected Attributes
const double	one_log2_ {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
virtual double	score_ (const IdCondSet< ALLOC > &idset) final
	returns the score for a given IdCondSet 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::ScoreK2< ALLOC >

the class for computing K2 scores (actually their log2 value)

Warning: As the K2 score already includes an implicit Laplace 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 additional apriori will be included in addition to the implicit Laplace apriori in a BD fashion, i.e., we will resort to the Bayesian Dirichlet (BD) formula to include the sum of the two aprioris into the score.

Definition at line 60 of file scoreK2.h.

Member Typedef Documentation

◆ allocator_type

template<template< typename > class ALLOC = std::allocator>

using gum::learning::ScoreK2< ALLOC >::allocator_type = ALLOC< NodeId >

type for the allocators passed in arguments of methods

Definition at line 63 of file scoreK2.h.

Constructor & Destructor Documentation

◆ ScoreK2() [1/6]

template<template< typename > class ALLOC = std::allocator>

gum::learning::ScoreK2< ALLOC >::ScoreK2	(	const DBRowGeneratorParser< ALLOC > &	parser,
		const Apriori< ALLOC > &	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

Parameters

parser	the parser used to parse the database
apriori	An apriori that we add to the computation of the score
ranges	a 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.
nodeId2Columns	a 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.
alloc	the 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.

◆ ScoreK2() [2/6]

template<template< typename > class ALLOC = std::allocator>

gum::learning::ScoreK2< ALLOC >::ScoreK2	(	const DBRowGeneratorParser< ALLOC > &	parser,
		const Apriori< ALLOC > &	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

Parameters

parser	the parser used to parse the database
apriori	An apriori that we add to the computation of the score
nodeId2Columns	a 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.
alloc	the 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.

◆ ScoreK2() [3/6]

template<template< typename > class ALLOC = std::allocator>

gum::learning::ScoreK2< ALLOC >::ScoreK2 ( const ScoreK2< ALLOC > & from )

copy constructor

◆ ScoreK2() [4/6]

template<template< typename > class ALLOC = std::allocator>

gum::learning::ScoreK2< ALLOC >::ScoreK2	(	const ScoreK2< ALLOC > &	from,
		const allocator_type &	alloc
	)

copy constructor with a given allocator

◆ ScoreK2() [5/6]

template<template< typename > class ALLOC = std::allocator>

gum::learning::ScoreK2< ALLOC >::ScoreK2 ( ScoreK2< ALLOC > && from )

move constructor

◆ ScoreK2() [6/6]

template<template< typename > class ALLOC = std::allocator>

gum::learning::ScoreK2< ALLOC >::ScoreK2	(	ScoreK2< ALLOC > &&	from,
		const allocator_type &	alloc
	)

move constructor with a given allocator

◆ ~ScoreK2()

template<template< typename > class ALLOC = std::allocator>

virtual gum::learning::ScoreK2< ALLOC >::~ScoreK2 ( )

virtual

destructor

Member Function Documentation

◆ clear()

template<template< typename > class ALLOC = std::allocator>

void gum::learning::Score< ALLOC >::clear ( )

inherited

clears all the data structures from memory, including the cache

◆ clearCache()

template<template< typename > class ALLOC = std::allocator>

void gum::learning::Score< ALLOC >::clearCache ( )

inherited

clears the current cache

◆ clearRanges()

template<template< typename > class ALLOC = std::allocator>

void gum::learning::Score< ALLOC >::clearRanges ( )

inherited

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

◆ clone() [1/2]

template<template< typename > class ALLOC = std::allocator>

virtual ScoreK2< ALLOC >* gum::learning::ScoreK2< ALLOC >::clone ( ) const

virtual

virtual copy constructor

Implements gum::learning::Score< ALLOC >.

◆ clone() [2/2]

template<template< typename > class ALLOC = std::allocator>

virtual ScoreK2< ALLOC >* gum::learning::ScoreK2< ALLOC >::clone ( const allocator_type & alloc ) const

virtual

virtual copy constructor with a given allocator

Implements gum::learning::Score< ALLOC >.

◆ database()

template<template< typename > class ALLOC = std::allocator>

const DatabaseTable< ALLOC >& gum::learning::Score< ALLOC >::database ( ) const

inherited

return the database used by the score

◆ getAllocator()

template<template< typename > class ALLOC = std::allocator>

allocator_type gum::learning::Score< ALLOC >::getAllocator ( ) const

inherited

returns the allocator used by the score

◆ internalApriori()

template<template< typename > class ALLOC = std::allocator>

virtual const Apriori< ALLOC >& gum::learning::ScoreK2< ALLOC >::internalApriori ( ) const

finalvirtual

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) ). K2 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.

Implements gum::learning::Score< ALLOC >.

◆ isAprioriCompatible() [1/3]

template<template< typename > class ALLOC = std::allocator>

virtual std::string gum::learning::ScoreK2< ALLOC >::isAprioriCompatible ( ) const

finalvirtual

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 corresponds 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.

Returns: a non empty string if the apriori is compatible with the score.

Implements gum::learning::Score< ALLOC >.

◆ isAprioriCompatible() [2/3]

template<template< typename > class ALLOC = std::allocator>

static std::string gum::learning::ScoreK2< ALLOC >::isAprioriCompatible	(	const std::string &	apriori_type,
		double	weight = `1.0f`
	)

static

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

Returns: a non empty string if the apriori is compatible with the score.

◆ isAprioriCompatible() [3/3]

template<template< typename > class ALLOC = std::allocator>

static std::string gum::learning::ScoreK2< ALLOC >::isAprioriCompatible ( const Apriori< ALLOC > & apriori )

static

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

a non empty string if the apriori is compatible with the score.

◆ isUsingCache()

template<template< typename > class ALLOC = std::allocator>

bool gum::learning::Score< ALLOC >::isUsingCache ( ) const

inherited

indicates whether the score uses a cache

◆ 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

protectedinherited

returns a counting vector where variables are marginalized from N_xyz

Parameters

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

◆ minNbRowsPerThread()

template<template< typename > class ALLOC = std::allocator>

virtual std::size_t gum::learning::Score< ALLOC >::minNbRowsPerThread ( ) const

virtualinherited

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

virtualinherited

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

inherited

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>

ScoreK2< ALLOC >& gum::learning::ScoreK2< ALLOC >::operator= ( const ScoreK2< ALLOC > & from )

copy operator

◆ operator=() [2/2]

template<template< typename > class ALLOC = std::allocator>

ScoreK2< ALLOC >& gum::learning::ScoreK2< ALLOC >::operator= ( ScoreK2< ALLOC > && from )

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

inherited

returns the current ranges

◆ score() [1/2]

template<template< typename > class ALLOC = std::allocator>

double gum::learning::Score< ALLOC >::score ( const NodeId var )

inherited

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
	)

inherited

returns the score of a single node given some other nodes

Parameters

var	the variable on the left side of the conditioning bar
rhs_ids	the set of variables on the right side of the conditioning bar

◆ score_()

template<template< typename > class ALLOC = std::allocator>

virtual double gum::learning::ScoreK2< ALLOC >::score_ ( const IdCondSet< ALLOC > & idset )

finalprotectedvirtual

returns the score for a given IdCondSet

Exceptions

OperationNotAllowed is 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).

Implements gum::learning::Score< ALLOC >.

◆ setMaxNbThreads()

template<template< typename > class ALLOC = std::allocator>

virtual void gum::learning::Score< ALLOC >::setMaxNbThreads ( std::size_t nb ) const

virtualinherited

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

virtualinherited

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 )

inherited

sets new ranges to perform the countings used by the score

Parameters

ranges a 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.

◆ useCache()

template<template< typename > class ALLOC = std::allocator>

void gum::learning::Score< ALLOC >::useCache ( const bool on_off )

inherited

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

Member Data Documentation

◆ apriori_

template<template< typename > class ALLOC = std::allocator>

Apriori< ALLOC >* gum::learning::Score< ALLOC >::apriori_ {nullptr}

protectedinherited

the expert knowledge a priori we add to the score

Definition at line 235 of file score.h.

◆ cache_

template<template< typename > class ALLOC = std::allocator>

ScoringCache< ALLOC > gum::learning::Score< ALLOC >::cache_

protectedinherited

the scoring cache

Definition at line 241 of file score.h.

◆ counter_

template<template< typename > class ALLOC = std::allocator>

RecordCounter< ALLOC > gum::learning::Score< ALLOC >::counter_

protectedinherited

the record counter used for the countings over discrete variables

Definition at line 238 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_

protectedinherited

an empty vector

Definition at line 247 of file score.h.

◆ one_log2_

template<template< typename > class ALLOC = std::allocator>

const double gum::learning::Score< ALLOC >::one_log2_ {M_LOG2E}

protectedinherited

1 / log(2)

Definition at line 232 of file score.h.

◆ use_cache_

template<template< typename > class ALLOC = std::allocator>

bool gum::learning::Score< ALLOC >::use_cache_ {true}

protectedinherited

a Boolean indicating whether we wish to use the cache

Definition at line 244 of file score.h.

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

agrum/BN/learning/scores_and_tests/scoreK2.h

Public Member Functions

Static Public Member Functions

Public Types

Protected Attributes

Protected Member Functions

Detailed Description

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

Member Typedef Documentation

◆ allocator_type

Constructor & Destructor Documentation

◆ ScoreK2() [1/6]

◆ ScoreK2() [2/6]

◆ ScoreK2() [3/6]

◆ ScoreK2() [4/6]

◆ ScoreK2() [5/6]

◆ ScoreK2() [6/6]

◆ ~ScoreK2()

Member Function Documentation

◆ clear()

◆ clearCache()

◆ clearRanges()

◆ clone() [1/2]

◆ clone() [2/2]

◆ database()

◆ getAllocator()

◆ internalApriori()

◆ isAprioriCompatible() [1/3]

◆ isAprioriCompatible() [2/3]

◆ isAprioriCompatible() [3/3]

◆ isUsingCache()

◆ marginalize_()

◆ minNbRowsPerThread()

◆ nbThreads()

◆ nodeId2Columns()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ranges()

◆ score() [1/2]

◆ score() [2/2]

◆ score_()

◆ setMaxNbThreads()

◆ setMinNbRowsPerThread()

◆ setRanges()

◆ useCache()

Member Data Documentation

◆ apriori_

◆ cache_

◆ counter_

◆ empty_ids_

◆ one_log2_

◆ use_cache_

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