gum::learning::DBTranslator4DiscretizedVariable Class Reference

The databases' cell translators for discretized variables. More...

#include <agrum/base/database/DBTranslator4DiscretizedVariable.h>

Inheritance diagram for gum::learning::DBTranslator4DiscretizedVariable:

Collaboration diagram for gum::learning::DBTranslator4DiscretizedVariable:

Public Member Functions
Constructors / Destructors
template<GUM_Numeric GUM_SCALAR>
	DBTranslator4DiscretizedVariable (const DiscretizedVariable< GUM_SCALAR > &var, const std::vector< std::string > &missing_symbols, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor with a discretized variable as translator
template<GUM_Numeric GUM_SCALAR>
	DBTranslator4DiscretizedVariable (const DiscretizedVariable< GUM_SCALAR > &var, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor with a discretized variable as translator but without missing symbols
	DBTranslator4DiscretizedVariable (const IDiscretizedVariable &var, const std::vector< std::string > &missing_symbols, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor with a IDiscretized variable as translator
	DBTranslator4DiscretizedVariable (const IDiscretizedVariable &var, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor with a IDiscretized variable as translator but without missing symbols
	DBTranslator4DiscretizedVariable (const DBTranslator4DiscretizedVariable &from)
	copy constructor
	DBTranslator4DiscretizedVariable (DBTranslator4DiscretizedVariable &&from)
	move constructor
DBTranslator4DiscretizedVariable *	clone () const override
	virtual copy constructor
	~DBTranslator4DiscretizedVariable () override
	destructor
Operators
DBTranslator4DiscretizedVariable &	operator= (const DBTranslator4DiscretizedVariable &from)
	copy operator
DBTranslator4DiscretizedVariable &	operator= (DBTranslator4DiscretizedVariable &&from)
	move operator
Accessors / Modifiers
DBTranslatedValue	translate (std::string_view str) final
	returns the translation of a string
std::string	translateBack (const DBTranslatedValue translated_val) const final
	returns the original value for a given translation
std::size_t	domainSize () const final
	returns the number of discretization intervals used for translations
bool	hasEditableDictionary () const final
	indicates that the translator is never in editable dictionary mode
void	setEditableDictionaryMode (bool new_mode) final
	sets/unset the editable dictionary mode
bool	needsReordering () const final
	indicates that the translations should never be reordered
HashTable< std::size_t, std::size_t >	reorder () final
	returns an empty HashTable to indicate that no reordering is needed.
const IDiscretizedVariable *	variable () const final
	returns the variable stored into the translator
DBTranslatedValue	missingValue () const final
	returns the translation of a missing value
Operators
DBTranslatedValue	operator<< (std::string_view str)
	alias for method translate
std::string	operator>> (const DBTranslatedValue translated_val)
	alias for method translateBack
Accessors / Modifiers
virtual const Bijection< std::size_t, std::string > &	getDictionary () const
	returns the translation from database indices to input strings
const Set< std::string > &	missingSymbols () const
	returns the set of missing symbols taken into account by the translator
bool	isMissingSymbol (std::string_view str) const
	indicates whether a string corresponds to a missing symbol
void	setVariableName (std::string_view str) const
	sets the name of the variable stored into the translator
void	setVariableDescription (std::string_view str) const
	sets the name of the variable stored into the translator
DBTranslatedValueType	getValType () const
	returns the type of values handled by the translator
bool	isLossless () const
	returns a Boolean indicating whether the translation is lossless or not
bool	isMissingValue (const DBTranslatedValue &val) const
	indicates whether a translated value corresponds to a missing value

Protected Attributes
bool	is_lossless_
	indicates whether the translation is lossless (e.g., ranges) or not
bool	is_dictionary_dynamic_
	indicates whether the dictionary can be updated or not
std::size_t	max_dico_entries_
	the maximum number of entries that the dictionary is allowed to contain
Set< std::string >	missing_symbols_
	the set of missing symbols
Bijection< std::size_t, std::string >	back_dico_
	the bijection relating back translated values and their original strings.
DBTranslatedValueType	val_type_
	the type of the values translated by the translator

Detailed Description

The databases' cell translators for discretized variables.

Translators are used by DatabaseTable instances to transform datasets' strings into DBTranslatedValue instances. The point is that strings are not adequate for fast learning, they need to be preprocessed into a type that can be analyzed quickly (the so-called DBTranslatedValue type).

A DBTranslator4DiscretizedVariable is a translator that contains and exploits a DiscretizedVariable for translations. Each time a string needs be translated, we ask the DiscretizedVariable which discretization interval contains the number represented by the string. The DBTranslatedValue corresponding to the translation of the string contains in its discr_val field the index of this discretization interval.

Warning

Translators for discretized variables are not editable, that is, you must provide the const variable that will be used for translations. Enabling the editable mode would not make much sense.

Here is an example of how to use this class:

// create the translator, with possible missing symbols: "N/A" and "???"
// i.e., each time the translator reads a "N/A" or a "???" string, it
// won't translate it into a number but into a missing value.
std::vector<std::string> missing { "N/A", "???" };
gum::DiscretizedVariable<int> var ( "X1", "" );
var.addTick ( 1 );
var.addTick ( 3 );
var.addTick ( 10 );
gum::learning::DBTranslator4DiscretizedVariable translator( var,missing );
 
// gets the DBTranslatedValue corresponding to some strings
auto val1 = translator.translate("5.2");
auto val2 = translator << "2";
// at this point, val1 and val2 are equal to
// gum::learning::DBTranslatedValue { std::size_t(1) } and
// gum::learning::DBTranslatedValue { std::size_t(0) } respectively
// because the first discretization interval corresponds to [1;3[ and
// the second one to [3;10[.
 
// if the string contains a number outside the domain of the
// DiscretizedVariable, then a gum::NotFound exception is raised:
auto val3 = translator << "17"; // NotFound raised
 
// add the numbers assigned to val1, val2
std::size_t sum = val1.discr_val + val2.discr_val;
 
// translate missing values: val4 and val5 will be equal to:
// DBTranslatedValue { std::numeric_limits<std::size_t>::max () }
auto val4 = translator << "N/A";
auto val5 = translator.translate ( "???" );
 
// the following instructions raise TypeError exceptions because the
// strings are not numbers
auto val6 = translator << "422x";
auto val7 = translator.translate ( "xxx" );
 
// given a DBTranslatedValue that is supposed to contain the index of
// a discretization interval, get the string representing the interval.
std::string str;
str = translator.translateBack ( val1 );        // str = "[3,10["
str = translator >> val2;                       // str = "[1;3["
str = translator >> gum::learning::DBTranslatedValue {std::size_t(1)};
                                                // str = "[3;10["
 
// translate back missing values: the string will corresponds to one of
// the missing symbols known to the translator
str = translator >> val4; // str = "N/A" or "???"
str = translator >> val5; // str = "N/A" or "???"
 
// get the variable stored within the translator
const gum::DiscretizedVariable<float>* var =
  dynamic_cast<const gum::DiscretizedVariable<float>*>
    ( translator.variable () );

Definition at line 139 of file DBTranslator4DiscretizedVariable.h.

Constructor & Destructor Documentation

DBTranslator4DiscretizedVariable() [1/6]

template<GUM_Numeric GUM_SCALAR>

gum::learning::DBTranslator4DiscretizedVariable::DBTranslator4DiscretizedVariable	(	const DiscretizedVariable< GUM_SCALAR > &	var,
		const std::vector< std::string > &	missing_symbols,
		std::size_t	max_dico_entries = std::numeric_limits< std::size_t >::max() )

default constructor with a discretized variable as translator

Parameters

var	a discretized variable which will be used for translations. The translator keeps a copy of this variable
missing_symbols	the set of symbols in the dataset representing missing values
max_dico_entries	the max number of entries that the dictionary can contain. During the construction, we check that the discretized variable passed in argument has fewer discretization intervals than the admissible dictionary size

Warning

If the variable contained into the translator has a label equal to a missing value symbol, the label will be taken into account in the translation, not the missing value.

Referenced by DBTranslator4DiscretizedVariable(), DBTranslator4DiscretizedVariable(), clone(), operator=(), and operator=().

Here is the caller graph for this function:

DBTranslator4DiscretizedVariable() [2/6]

template<GUM_Numeric GUM_SCALAR>

gum::learning::DBTranslator4DiscretizedVariable::DBTranslator4DiscretizedVariable	(	const DiscretizedVariable< GUM_SCALAR > &	var,
		std::size_t	max_dico_entries = std::numeric_limits< std::size_t >::max() )

default constructor with a discretized variable as translator but without missing symbols

Parameters

var	a discretized variable which will be used for translations. The translator keeps a copy of this variable
max_dico_entries	the max number of entries that the dictionary can contain. During the construction, we check that the discretized variable passed in argument has fewer discretization intervals than the admissible dictionary size

Warning

If the variable contained into the translator has a label equal to a missing value symbol, the label will be taken into account in the translation, not the missing value.

DBTranslator4DiscretizedVariable() [3/6]

gum::learning::DBTranslator4DiscretizedVariable::DBTranslator4DiscretizedVariable	(	const IDiscretizedVariable &	var,
		const std::vector< std::string > &	missing_symbols,
		std::size_t	max_dico_entries = std::numeric_limits< std::size_t >::max() )

default constructor with a IDiscretized variable as translator

Parameters

var	a IDiscretized variable which will be used for translations. The translator keeps a copy of this variable
missing_symbols	the set of symbols in the dataset representing missing values
max_dico_entries	the max number of entries that the dictionary can contain. During the construction, we check that the discretized variable passed in argument has fewer discretization intervals than the admissible dictionary size

Warning

If the variable contained into the translator has a label equal to a missing value symbol, the label will be taken into account in the translation, not the missing value.

DBTranslator4DiscretizedVariable() [4/6]

gum::learning::DBTranslator4DiscretizedVariable::DBTranslator4DiscretizedVariable	(	const IDiscretizedVariable &	var,
		std::size_t	max_dico_entries = std::numeric_limits< std::size_t >::max() )

default constructor with a IDiscretized variable as translator but without missing symbols

Parameters

var	a discretized variable which will be used for translations. The translator keeps a copy of this variable
max_dico_entries	the max number of entries that the dictionary can contain. During the construction, we check that the discretized variable passed in argument has fewer discretization intervals than the admissible dictionary size

Warning

If the variable contained into the translator has a label equal to a missing value symbol, the label will be taken into account in the translation, not the missing value.

DBTranslator4DiscretizedVariable() [5/6]

gum::learning::DBTranslator4DiscretizedVariable::DBTranslator4DiscretizedVariable

(

const DBTranslator4DiscretizedVariable &

from

)

copy constructor

References DBTranslator4DiscretizedVariable().

Here is the call graph for this function:

DBTranslator4DiscretizedVariable() [6/6]

gum::learning::DBTranslator4DiscretizedVariable::DBTranslator4DiscretizedVariable

(

DBTranslator4DiscretizedVariable &&

from

)

move constructor

References DBTranslator4DiscretizedVariable().

Here is the call graph for this function:

~DBTranslator4DiscretizedVariable()

gum::learning::DBTranslator4DiscretizedVariable::~DBTranslator4DiscretizedVariable ( )

override

destructor

Member Function Documentation

clone()

DBTranslator4DiscretizedVariable * gum::learning::DBTranslator4DiscretizedVariable::clone ( ) const

nodiscardoverridevirtual

virtual copy constructor

Implements gum::learning::DBTranslator.

References DBTranslator4DiscretizedVariable().

Here is the call graph for this function:

domainSize()

std::size_t gum::learning::DBTranslator4DiscretizedVariable::domainSize ( ) const

finalvirtual

returns the number of discretization intervals used for translations

Warning

Note that missing values are encoded as std::numeric_limits::max () and are not taken into account in the domain sizes.

Implements gum::learning::DBTranslator.

getDictionary()

virtual const Bijection< std::size_t, std::string > & gum::learning::DBTranslator::getDictionary ( ) const

virtualinherited

returns the translation from database indices to input strings

getValType()

DBTranslatedValueType gum::learning::DBTranslator::getValType ( ) const

inherited

returns the type of values handled by the translator

Returns

either DBTranslatedValueType::DISCRETE if the translator includes a discrete variable or DBTranslatedValueType::CONTINUOUS if it contains a continuous variable. This is convenient to know how to interpret the DBTranslatedValue instances produced by the DBTranslator: either using their discr_val field or their cont_val field.

Referenced by gum::learning::BNDatabaseGenerator< GUM_SCALAR >::toDatabaseTable().

Here is the caller graph for this function:

hasEditableDictionary()

bool gum::learning::DBTranslator4DiscretizedVariable::hasEditableDictionary ( ) const

finalvirtual

indicates that the translator is never in editable dictionary mode

Reimplemented from gum::learning::DBTranslator.

References hasEditableDictionary().

Referenced by hasEditableDictionary().

Here is the call graph for this function:

Here is the caller graph for this function:

isLossless()

bool gum::learning::DBTranslator::isLossless ( ) const

inherited

returns a Boolean indicating whether the translation is lossless or not

Some translations can lose some information. For instance, a translator for a discretized variable will translate all the values of a discretization interval as the same value (the index of the interval). As such it looses some information because, knowing this index, it is impossible to get back to the original value that was translated. Method isLossless() indicates whether the translation never loses any information or not.

isMissingSymbol()

bool gum::learning::DBTranslator::isMissingSymbol ( std::string_view str ) const

inherited

indicates whether a string corresponds to a missing symbol

isMissingValue()

bool gum::learning::DBTranslator::isMissingValue ( const DBTranslatedValue & val ) const

inherited

indicates whether a translated value corresponds to a missing value

missingSymbols()

const Set< std::string > & gum::learning::DBTranslator::missingSymbols ( ) const

inherited

returns the set of missing symbols taken into account by the translator

missingValue()

DBTranslatedValue gum::learning::DBTranslator4DiscretizedVariable::missingValue ( ) const

finalvirtual

returns the translation of a missing value

Implements gum::learning::DBTranslator.

References missingValue().

Referenced by missingValue().

Here is the call graph for this function:

Here is the caller graph for this function:

needsReordering()

bool gum::learning::DBTranslator4DiscretizedVariable::needsReordering ( ) const

finalvirtual

indicates that the translations should never be reordered

Implements gum::learning::DBTranslator.

References needsReordering().

Referenced by needsReordering().

Here is the call graph for this function:

Here is the caller graph for this function:

operator<<()

DBTranslatedValue gum::learning::DBTranslator::operator<< ( std::string_view str )

inherited

alias for method translate

operator=() [1/2]

DBTranslator4DiscretizedVariable & gum::learning::DBTranslator4DiscretizedVariable::operator=

(

const DBTranslator4DiscretizedVariable &

from

)

copy operator

References DBTranslator4DiscretizedVariable().

Here is the call graph for this function:

operator=() [2/2]

DBTranslator4DiscretizedVariable & gum::learning::DBTranslator4DiscretizedVariable::operator=

(

DBTranslator4DiscretizedVariable &&

from

)

move operator

References DBTranslator4DiscretizedVariable().

Here is the call graph for this function:

operator>>()

std::string gum::learning::DBTranslator::operator>> ( const DBTranslatedValue translated_val )

inherited

alias for method translateBack

reorder()

HashTable< std::size_t, std::size_t > gum::learning::DBTranslator4DiscretizedVariable::reorder ( )

finalvirtual

returns an empty HashTable to indicate that no reordering is needed.

Implements gum::learning::DBTranslator.

References reorder().

Referenced by reorder().

Here is the call graph for this function:

Here is the caller graph for this function:

setEditableDictionaryMode()

void gum::learning::DBTranslator4DiscretizedVariable::setEditableDictionaryMode ( bool new_mode )

finalvirtual

sets/unset the editable dictionary mode

Reimplemented from gum::learning::DBTranslator.

References setEditableDictionaryMode().

Referenced by setEditableDictionaryMode().

Here is the call graph for this function:

Here is the caller graph for this function:

setVariableDescription()

void gum::learning::DBTranslator::setVariableDescription ( std::string_view str ) const

inherited

sets the name of the variable stored into the translator

setVariableName()

void gum::learning::DBTranslator::setVariableName ( std::string_view str ) const

inherited

sets the name of the variable stored into the translator

translate()

DBTranslatedValue gum::learning::DBTranslator4DiscretizedVariable::translate ( std::string_view str )

finalvirtual

returns the translation of a string

This method tries to translate a given string into the DBTranslatedValue that should be stored into a databaseTable. If the translator cannot find the translation in its current dictionary, then the translator raises either a TypeError if the string is not a number or a NotFound exception.

Warning

Note that missing values (i.e., string encoded as missing symbols) are translated as std::numeric_limits<std::size_t>::max ().

If the variable contained into the translator has a discretization interval that contains a missing value symbol, the interval will be taken into account in the translation, not the missing value.

Returns

the translated value of the string to be stored into a DatabaseTable

Exceptions

UnknownLabelInDatabase	is raised if the translation cannot be found.
TypeError	is raised if the translation cannot be found and the translator and the string does not correspond to a number.

Implements gum::learning::DBTranslator.

translateBack()

std::string gum::learning::DBTranslator4DiscretizedVariable::translateBack ( const DBTranslatedValue translated_val ) const

finalvirtual

returns the original value for a given translation

Returns

the string that was translated into a given DBTranslatedValue.

Exceptions

UnknownLabelInDatabase

is raised if this original value cannot be found

Implements gum::learning::DBTranslator.

variable()

const IDiscretizedVariable * gum::learning::DBTranslator4DiscretizedVariable::variable ( ) const

finalvirtual

returns the variable stored into the translator

Implements gum::learning::DBTranslator.

References variable().

Referenced by variable().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

back_dico_

Bijection< std::size_t, std::string > gum::learning::DBTranslator::back_dico_

mutableprotectedinherited

the bijection relating back translated values and their original strings.

Note that the translated values considered here are of type std::size_t because only the values for discrete variables need be stored, those for continuous variables are actually identity mappings.

Warning

only the values of the random variable are stored into this bijection. Missing values are not considered here.

Definition at line 401 of file DBTranslator.h.

is_dictionary_dynamic_

bool gum::learning::DBTranslator::is_dictionary_dynamic_

protectedinherited

indicates whether the dictionary can be updated or not

Definition at line 387 of file DBTranslator.h.

is_lossless_

bool gum::learning::DBTranslator::is_lossless_

protectedinherited

indicates whether the translation is lossless (e.g., ranges) or not

Definition at line 384 of file DBTranslator.h.

max_dico_entries_

std::size_t gum::learning::DBTranslator::max_dico_entries_

protectedinherited

the maximum number of entries that the dictionary is allowed to contain

Definition at line 390 of file DBTranslator.h.

missing_symbols_

Set< std::string > gum::learning::DBTranslator::missing_symbols_

protectedinherited

the set of missing symbols

Definition at line 393 of file DBTranslator.h.

val_type_

DBTranslatedValueType gum::learning::DBTranslator::val_type_

protectedinherited

the type of the values translated by the translator

Definition at line 404 of file DBTranslator.h.

---

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

• agrum/base/database/DBTranslator4DiscretizedVariable.h