aGrUM  0.13.2
gum::learning::DBTranslatorSet< ALLOC > Class Template Reference

the class for packing together the translators used to preprocess the datasets More...

#include <agrum/learning/database/DBTranslatorSet.h>

Public Member Functions

Constructors / Destructors
 DBTranslatorSet (const allocator_type &alloc=allocator_type())
 default constructor More...
 
 DBTranslatorSet (const DBTranslatorSet< ALLOC > &from)
 copy constructor More...
 
 DBTranslatorSet (const DBTranslatorSet< ALLOC > &from, const allocator_type &alloc)
 copy constructor with a given allocator More...
 
 DBTranslatorSet (DBTranslatorSet< ALLOC > &&from)
 move constructor More...
 
 DBTranslatorSet (DBTranslatorSet< ALLOC > &&from, const allocator_type &alloc)
 move constructor with a given allocator More...
 
virtual DBTranslatorSet< ALLOC > * clone () const
 virtual copy constructor More...
 
virtual DBTranslatorSet< ALLOC > * clone (const allocator_type &alloc) const
 virtual copy constructor with a given allocator More...
 
virtual ~DBTranslatorSet ()
 destructor More...
 
Operators
DBTranslatorSet< ALLOC > & operator= (const DBTranslatorSet< ALLOC > &from)
 copy operator More...
 
DBTranslatorSet< ALLOC > & operator= (DBTranslatorSet< ALLOC > &&from)
 move operator More...
 
DBTranslator< ALLOC > & operator[] (const std::size_t k)
 returns the kth translator More...
 
const DBTranslator< ALLOC > & operator[] (const std::size_t k) const
 returns the kth translator More...
 
Accessors / Modifiers
template<template< template< typename > class > class Translator>
std::size_t insertTranslator (const Translator< ALLOC > &translator, const std::size_t column)
 inserts a new translator in the translator set More...
 
template<template< typename > class XALLOC>
std::size_t insertTranslator (const Variable &var, const std::size_t column, const std::vector< std::string, XALLOC< std::string > > &missing_symbols)
 inserts a new translator for a given variable in the translator set More...
 
std::size_t insertTranslator (const Variable &var, const std::size_t column)
 inserts a new translator for a given variable in the translator set More...
 
void eraseTranslator (const std::size_t k, const bool k_is_input_col=false)
 erases either the kth translator or that parsing the kth column of the input database More...
 
DBTranslator< ALLOC > & translator (const std::size_t k)
 returns the kth translator More...
 
const DBTranslator< ALLOC > & translator (const std::size_t k) const
 returns the kth translator More...
 
DBTranslator< ALLOC > & translatorSafe (const std::size_t k)
 returns the kth translator More...
 
const DBTranslator< ALLOC > & translatorSafe (const std::size_t k) const
 returns the kth translator More...
 
template<template< typename > class OTHER_ALLOC>
DBTranslatedValue translate (const std::vector< std::string, OTHER_ALLOC< std::string > > &row, const std::size_t k) const
 ask the kth translator to translate a string in a row of the database More...
 
template<template< typename > class OTHER_ALLOC>
DBTranslatedValue translateSafe (const std::vector< std::string, OTHER_ALLOC< std::string > > &row, const std::size_t k) const
 similar to method translate, except that it checks that the kth translator exists More...
 
std::string translateBack (const DBTranslatedValue translated_val, const std::size_t k) const
 returns the original string that was translated into translated_val More...
 
std::string translateBackSafe (const DBTranslatedValue translated_val, const std::size_t k) const
 similar to method translateBack, except that it checks that the kth translator exists More...
 
bool isMissingValue (const DBTranslatedValue translated_val, const std::size_t k) const
 indicates whether the kth translator considers a translated_val as a missing value More...
 
bool isMissingValueSafe (const DBTranslatedValue translated_val, const std::size_t k) const
 similar to method isMissingValue, except that it checks that the kth translator exists More...
 
std::size_t domainSize (const std::size_t k) const
 returns the domain size of the variable stored into the kth translator More...
 
std::size_t domainSizeSafe (const std::size_t k) const
 returns the domain size of the variable stored into the kth translator More...
 
const Variablevariable (const std::size_t k) const
 returns the variable stored into the kth translator More...
 
const VariablevariableSafe (const std::size_t k) const
 returns the variable stored into the kth translator More...
 
bool needsReordering (const std::size_t k) const
 indicates whether a reordering is needed to make the kth translator sorted More...
 
bool needsReorderingSafe (const std::size_t k) const
 same as method needsReordering but checks that the kth translator exists More...
 
HashTable< std::size_t, std::size_t, ALLOC< std::pair< std::size_t, std::size_t > > > reorder (const std::size_t k)
 performs a reordering of the dictionary and returns a mapping from the old translated values to the new ones. More...
 
HashTable< std::size_t, std::size_t, ALLOC< std::pair< std::size_t, std::size_t > > > reorderSafe (const std::size_t k)
 same as method reorder but checks that the kth translator exists More...
 
std::size_t inputColumn (const std::size_t k) const
 returns the column of the input database that will be read by the kth translator More...
 
std::size_t inputColumnSafe (const std::size_t k) const
 returns the column of the input database that will be read by the kth translator More...
 
std::size_t highestInputColumn () const
 returns the largest input database column index read by the translators More...
 
void clear ()
 remove all the translators More...
 
std::size_t nbTranslators () const
 returns the number of translators stored into the set More...
 
std::size_t size () const
 returns the number of translators stored into the set More...
 
allocator_type getAllocator () const
 returns the allocator used by the translator set More...
 
const std::vector< DBTranslator< ALLOC > *, ALLOC< DBTranslator< ALLOC > * > > & translators () const
 returns the set of translators More...
 

Public Types

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

Detailed Description

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

the class for packing together the translators used to preprocess the datasets

When learning Bayesian networks, the records of the train dataset are used to construct contingency tables that are either exploited in statistical conditional independence tests or in scores. In both cases, the values observed in the records must be translated into indices in the finite domain of the corresponding random variables. The DBTranslator classes are used for this purpose. To make the parsing of all the columns of the dataset easier, all the DBTranslator instances used are gathered into a DBTranslatorSet.

Here is an example of how to use this class:
// create an empty translator set
std::vector<std::string> missing { "?", "N/A", "???" };
// create the translators and add them to the translator set. First,
// create translator1 that will perform its translations on Column 1
// of the dataset (columns start from index 0)
std::size_t pos1 = set.insertTranslator ( translator1, 1 );
// currently, pos1 is equal to 0, that is, translator1 is the first
// translator in the translator set
// create a translator handling Column 0 of the dataset
std::size_t pos0 = set.insertTranslator ( translator0, 0 );
// translator0 has been inserted into the translator set at position pos0.
// pos0 = 0 because translators are sorted by increasing column order in
// the translator set. So, now, in the set, the first translator is
// translator0 and the the second one is translator1.
std::size_t pos2 = set.insertTranslator ( translator2, 2 );
// the set contains { translator0, translator1, translator2 }, in this order
// parsing the rows of the dataset
std::vector<std::string> row1 { ".33", "toto", "titi" };
float val0 = set.translate ( row1, 0 ).cont_val; // val0 = 0.33f
std::size_t val1 = set.translate ( row1, 1 ).discr_val; // val1 = 0 (toto)
std::size_t val2 = set.translate ( row1, 2 ).discr_val; // val2 = 0 (titi)
std::vector<std::string> row2 { "4.22x", "???", "??" };
val0 = set.translate ( row2, 0 ).cont_val; // raises gum::TypeError
val1 = set.translate ( row2, 1 ).discr_val;
// = std::numeric_limits<std::size_t>::max ()
val2 = set.translate ( row2, 2 ).discr_val; // = 1 (??)
// with method translateSafe, an exception is raised whenever we try to
// translate a column that is not taken into account by the translators
set.translateSafe ( row2, 3 ); // raises gum::UndefinedElement

Definition at line 112 of file DBTranslatorSet.h.

Member Typedef Documentation

template<template< typename > class ALLOC = std::allocator>
using gum::learning::DBTranslatorSet< ALLOC >::allocator_type = typename DBTranslator< ALLOC >::allocator_type

type for the allocators passed in arguments of methods

Definition at line 115 of file DBTranslatorSet.h.

Constructor & Destructor Documentation

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

default constructor

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

copy constructor

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

copy constructor with a given allocator

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

move constructor

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

move constructor with a given allocator

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

destructor

Member Function Documentation

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

remove all the translators

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

virtual copy constructor

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

virtual copy constructor with a given allocator

template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::domainSize ( const std::size_t  k) const

returns the domain size of the variable stored into the kth translator

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method domainSizeSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::domainSizeSafe ( const std::size_t  k) const

returns the domain size of the variable stored into the kth translator

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
void gum::learning::DBTranslatorSet< ALLOC >::eraseTranslator ( const std::size_t  k,
const bool  k_is_input_col = false 
)

erases either the kth translator or that parsing the kth column of the input database

DBTranslatorSets do not necessarily read all the columns of their input database. For instance, a CSV may contain 10 columns, but the DBTranslatorSet may only contain two translators reading columns 3 and 5 respectively. When k_is_input_col is set to false, Parameter k passed in argument corresponds to either 0 or 1, i.e., to the index of one of the two translators stored into the DBTranslatorSet. When k_is_input_col is set to true, the translator to be erased is the one that parses the kth column of the input database.

Warning
if the translator does not exists, nothing is done. In particular, no exception is raised.
template<template< typename > class ALLOC = std::allocator>
allocator_type gum::learning::DBTranslatorSet< ALLOC >::getAllocator ( ) const

returns the allocator used by the translator set

template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::highestInputColumn ( ) const

returns the largest input database column index read by the translators

template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::inputColumn ( const std::size_t  k) const

returns the column of the input database that will be read by the kth translator

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method inputColumnSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::inputColumnSafe ( const std::size_t  k) const

returns the column of the input database that will be read by the kth translator

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
template<template< template< typename > class > class Translator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::insertTranslator ( const Translator< ALLOC > &  translator,
const std::size_t  column 
)

inserts a new translator in the translator set

Parameters
translatora translator that will be copied into the translator set
columnthe index of the column that this new translator should read in the database.
Returns
the position of the translator within the translator set.
Warning
Translators are order by increasing column within the translator set. As a consequence, their position may change when other translators are added.
Exceptions
DuplicateElementis raised if there already exists a translator reading the column passed in argument.

Referenced by gum::learning::genericBNLearner::__readFile(), and gum::learning::readFile().

+ Here is the caller graph for this function:

template<template< typename > class ALLOC = std::allocator>
template<template< typename > class XALLOC>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::insertTranslator ( const Variable var,
const std::size_t  column,
const std::vector< std::string, XALLOC< std::string > > &  missing_symbols 
)

inserts a new translator for a given variable in the translator set

The first template parameter (GUM_SCALAR) is necessary only for inserting variables of true types DiscretizedVariable and ContinuousVariable, which depend on the GUM_SCALAR parameter type. However, usually, when you use this function, this is to add into the TranslatorSet the variables of a BayesNet<GUM_SCALAR>. As such, you can safely call insert all the variables of this Bayesian network using inertTranslator<GUM_SCALAR> ( bn.variable() ... ) instructions.

Parameters
varthe variable that will be contained into the translator
columnthe index of the column that this new translator should read in the database.
missing_symbolsthe set of symbols in the database representing missing values
Exceptions
DuplicateElementis raised if there already exists a translator reading the column passed in argument.
template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::insertTranslator ( const Variable var,
const std::size_t  column 
)

inserts a new translator for a given variable in the translator set

The first template parameter (GUM_SCALAR) is necessary only for inserting variables of true types DiscretizedVariable and ContinuousVariable, which depend on the GUM_SCALAR parameter type. However, usually, when you use this function, this is to add into the TranslatorSet the variables of a BayesNet<GUM_SCALAR>. As such, you can safely call insert all the variables of this Bayesian network using inertTranslator<GUM_SCALAR> ( bn.variable() ... ) instructions.

Parameters
varthe variable that will be contained into the translator
columnthe index of the column that this new translator should read in the database.
Exceptions
DuplicateElementis raised if there already exists a translator reading the column passed in argument.
template<template< typename > class ALLOC = std::allocator>
bool gum::learning::DBTranslatorSet< ALLOC >::isMissingValue ( const DBTranslatedValue  translated_val,
const std::size_t  k 
) const

indicates whether the kth translator considers a translated_val as a missing value

Parameters
translated_valthe value that we compare to the translation of a missing value
kthe index of the translator that performed the translation
Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method isMissingValueSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
bool gum::learning::DBTranslatorSet< ALLOC >::isMissingValueSafe ( const DBTranslatedValue  translated_val,
const std::size_t  k 
) const

similar to method isMissingValue, except that it checks that the kth translator exists

Parameters
translated_valthe value that we compare to the translation of a missing value
kthe index of the translator that performed the translation
Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::nbTranslators ( ) const

returns the number of translators stored into the set

template<template< typename > class ALLOC = std::allocator>
bool gum::learning::DBTranslatorSet< ALLOC >::needsReordering ( const std::size_t  k) const

indicates whether a reordering is needed to make the kth translator sorted

For a given translator, if the strings represented by the translations are only numbers, the translations are considered to be sorted if and only if they are sorted by increasing number. If the strings do not only represent numbers, then translations are considered to be sorted if and only if they are sorted lexicographically.

When constructing dynamically its dictionary, the translator may assign wrong DBTranslatedValue values to strings. For instance, a translator reading sequentially integer strings 4, 1, 3, may map 4 into DBTranslatedValue{std::size_t(0)}, 1 into DBTranslatedValue{std::size_t(1)} and 3 into DBTranslatedValue{std::size_t(2)}, resulting in random variables having domain {4,1,3}. The user may prefer having domain {1,3,4}, i.e., a domain specified with increasing values. This requires a reordering. Method needsReodering() returns a Boolean indicating whether such a reordering should be performed or whether the current order is OK.

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method needsReorderingSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
bool gum::learning::DBTranslatorSet< ALLOC >::needsReorderingSafe ( const std::size_t  k) const

same as method needsReordering but checks that the kth translator exists

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
DBTranslatorSet< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::operator= ( const DBTranslatorSet< ALLOC > &  from)

copy operator

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

move operator

template<template< typename > class ALLOC = std::allocator>
DBTranslator< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::operator[] ( const std::size_t  k)

returns the kth translator

Warning
this operator assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method translatorSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
const DBTranslator< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::operator[] ( const std::size_t  k) const

returns the kth translator

Warning
this operator assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method translatorSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
HashTable< std::size_t, std::size_t, ALLOC< std::pair< std::size_t, std::size_t > > > gum::learning::DBTranslatorSet< ALLOC >::reorder ( const std::size_t  k)

performs a reordering of the dictionary and returns a mapping from the old translated values to the new ones.

When a reordering is needed, i.e., string values must be translated differently, Method reorder() computes how the translations should be changed. It updates accordingly the dictionary and returns the mapping that enables changing the old dictionary values into the new ones. Note that the hash table returned is expressed in terms of std::size_t because only the translations for discrete random variables need be reordered, those for continuous random variables are identity mappings.

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method reorderSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
HashTable< std::size_t, std::size_t, ALLOC< std::pair< std::size_t, std::size_t > > > gum::learning::DBTranslatorSet< ALLOC >::reorderSafe ( const std::size_t  k)

same as method reorder but checks that the kth translator exists

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
std::size_t gum::learning::DBTranslatorSet< ALLOC >::size ( ) const

returns the number of translators stored into the set

template<template< typename > class ALLOC = std::allocator>
template<template< typename > class OTHER_ALLOC>
DBTranslatedValue gum::learning::DBTranslatorSet< ALLOC >::translate ( const std::vector< std::string, OTHER_ALLOC< std::string > > &  row,
const std::size_t  k 
) const

ask the kth translator to translate a string in a row of the database

Parameters
rowa row of the original database
kthe index of the translator that will perform the translation
Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method translateSafe that performs this check.
as there is not necessarily an identity mapping between the set of columns of the database and the set of translators used, k may not necessarily corresponds to the index of a column in the database: this is the index of a translator within the set
template<template< typename > class ALLOC = std::allocator>
std::string gum::learning::DBTranslatorSet< ALLOC >::translateBack ( const DBTranslatedValue  translated_val,
const std::size_t  k 
) const

returns the original string that was translated into translated_val

Parameters
translated_valthe value from which we look for the original string
kthe index of the translator that performed the translation
Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method translateBackSafe that performs this check.
as there is not necessarily an identity mapping between the set of columns of the database and the set of translators used, k may not necessarily corresponds to the index of a column in the database: this is the index of a translator within the set
template<template< typename > class ALLOC = std::allocator>
std::string gum::learning::DBTranslatorSet< ALLOC >::translateBackSafe ( const DBTranslatedValue  translated_val,
const std::size_t  k 
) const

similar to method translateBack, except that it checks that the kth translator exists

Parameters
translated_valthe value from which we look for the original string
kthe index of the translator that performed the translation
Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
Warning
as there is not necessarily an identity mapping between the set of columns of the database and the set of translators used, k may not necessarily corresponds to the index of a column in the database: this is the index of a translator within the set
template<template< typename > class ALLOC = std::allocator>
template<template< typename > class OTHER_ALLOC>
DBTranslatedValue gum::learning::DBTranslatorSet< ALLOC >::translateSafe ( const std::vector< std::string, OTHER_ALLOC< std::string > > &  row,
const std::size_t  k 
) const

similar to method translate, except that it checks that the kth translator exists

Parameters
rowa row of the original database
kthe index of the translator that will perform the translation
Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
Warning
as there is not necessarily an identity mapping between the set of columns of the database and the set of translators used, k may not necessarily corresponds to the index of a column in the database: this is the index of a translator within the set
template<template< typename > class ALLOC = std::allocator>
DBTranslator< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::translator ( const std::size_t  k)

returns the kth translator

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method translatorSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
const DBTranslator< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::translator ( const std::size_t  k) const

returns the kth translator

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method translatorSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
const std::vector< DBTranslator< ALLOC >*, ALLOC< DBTranslator< ALLOC >* > >& gum::learning::DBTranslatorSet< ALLOC >::translators ( ) const

returns the set of translators

template<template< typename > class ALLOC = std::allocator>
DBTranslator< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::translatorSafe ( const std::size_t  k)

returns the kth translator

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
const DBTranslator< ALLOC >& gum::learning::DBTranslatorSet< ALLOC >::translatorSafe ( const std::size_t  k) const

returns the kth translator

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.
template<template< typename > class ALLOC = std::allocator>
const Variable& gum::learning::DBTranslatorSet< ALLOC >::variable ( const std::size_t  k) const

returns the variable stored into the kth translator

Warning
this method assumes that there are at least k translators. So, it won't check that the kth translator actually exists. If unsure, use method variableSafe that performs this check.
template<template< typename > class ALLOC = std::allocator>
const Variable& gum::learning::DBTranslatorSet< ALLOC >::variableSafe ( const std::size_t  k) const

returns the variable stored into the kth translator

Exceptions
UndefinedElementis raised if there are fewer than k translators in the translator set.

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