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

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

Inheritance diagram for gum::learning::DBTranslator4RangeVariable:

Collaboration diagram for gum::learning::DBTranslator4RangeVariable:

Public Member Functions
Constructors / Destructors
	DBTranslator4RangeVariable (const std::vector< std::string > &missing_symbols, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor without any initial variable
	DBTranslator4RangeVariable (std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor without any initial variable nor missing symbols
	DBTranslator4RangeVariable (const RangeVariable &var, const std::vector< std::string > &missing_symbols, const bool editable_dictionary=false, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor with a range variable as translator
	DBTranslator4RangeVariable (const RangeVariable &var, const bool editable_dictionary=false, std::size_t max_dico_entries=std::numeric_limits< std::size_t >::max())
	default constructor with a range variable as translator but without missing symbols
	DBTranslator4RangeVariable (const DBTranslator4RangeVariable &from)
	copy constructor
	DBTranslator4RangeVariable (DBTranslator4RangeVariable &&from)
	move constructor
virtual DBTranslator4RangeVariable *	clone () const
	virtual copy constructor
virtual	~DBTranslator4RangeVariable ()
	destructor
Operators
DBTranslator4RangeVariable &	operator= (const DBTranslator4RangeVariable &from)
	copy operator
DBTranslator4RangeVariable &	operator= (DBTranslator4RangeVariable &&from)
	move operator
Accessors / Modifiers
virtual DBTranslatedValue	translate (const std::string &str) final
	returns the translation of a string
virtual std::string	translateBack (const DBTranslatedValue translated_val) const final
	returns the original value for a given translation
virtual std::size_t	domainSize () const final
	returns the domain size of a variable corresponding to the translations
virtual bool	needsReordering () const final
	indicates whether a reordering is needed to make the translations sorted by increasing numbers
virtual HashTable< std::size_t, std::size_t >	reorder () final
	performs a reordering of the dictionary and returns a mapping from the old translated values to the new ones.
virtual const RangeVariable *	variable () const final
	returns the variable stored into the translator
virtual DBTranslatedValue	missingValue () const final
	returns the translation of a missing value
Operators
DBTranslatedValue	operator<< (const std::string &str)
	alias for method translate
std::string	operator>> (const DBTranslatedValue translated_val)
	alias for method translateBack
Accessors / Modifiers
virtual bool	hasEditableDictionary () const
	indicates whether the translator has an editable dictionary or not
virtual void	setEditableDictionaryMode (bool new_mode)
	sets/unset the editable dictionary mode
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 (const std::string &str) const
	indicates whether a string corresponds to a missing symbol
void	setVariableName (const std::string &str) const
	sets the name of the variable stored into the translator
void	setVariableDescription (const std::string &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 range 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 DBTranslator4RangeVariable is a translator that contains and exploits a RangeVariable for translations. Each time a string needs be translated, we ask the RangeVariable whether its domain contains the integer value represented in the string. If this is the case, then the DBTranslatedValue corresponding to the translation of the string contains in its discr_val field this integer value.

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::learning::DBTranslator4RangeVariable translator ( missing );

// gets the DBTranslatedValue corresponding to some strings

auto val1 = translator.translate("5");

auto val2 = translator.translate("4");

// at this point, val1 and val2 are equal to

// gum::learning::DBTranslatedValue { std::size_t(0) } and

// gum::learning::DBTranslatedValue { std::size_t(1) } respectively.

// In addition, the RangeVariable stored into the translator has

// a domain equal to {4,5}.

auto val3 = translator << "7";

// val3 is encoded as gum::learning::DBTranslatedValue { std::size_t(3) }

// because string "6" is implicitly encoded as

// gum::learning::DBTranslatedValue { std::size_t(3) }.

// In addition, the domain of the range variable is expanded to {4,5,6,7}.

// add the numbers assigned to val1, val2, val3

std::size_t sum = val1.discr_val + val2.discr_val + val3.discr_val;

// translate missing values: val4 and val5 will be equal to:

// DBTranslatedValue { std::numeric_limits<float>::max () }

auto val4 = translator << "N/A";

auto val5 = translator.translate ( "???" );

// the following instructions raise TypeError exceptions because the

// strings cannot be translated into integers

auto val6 = translator << "422x";

auto val7 = translator.translate ( "xxx" );

// given a DBTranslatedValue that is supposed to contain an integer in

// the range of the RangeVariable, get the corresponding string.

std::string str;

str = translator.translateBack ( val1 ); // str = "5"

str = translator >> val2; // str = "4"

str = translator >> gum::learning::DBTranslatedValue {std::size_t(2)};

// str = "6"

// 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::RangeVariable* var =

dynamic_cast<const gum::RangeVariable*> ( translator.variable () );

// it is possible to create a translator for an already known variable.

// In this case, by default, the translator is not in editable mode, but

// this behavior can be changed passing the right arguments to the

// constructor of the translator, or using the setEditableDictionaryMode

// method. Here, we create a range variable whose domain is {-2,...,10}

gum::RangeVariable var ( "X", "", -2, 10 );

gum::learning::DBTranslator4RangeVariable translator2 ( var, missing );

auto xval1 = translator2.translate ( "-1" ).discr_val; // xval1 = 1

auto xval2 = translator2.translate ( "7" ).discr_val; // xval2 = 9

auto xval3 = translator2.translate ( "N/A" ).discr_val;

// here xval3 corresponds to a missing value, hence it is equal to

// std::numeric_limits<size_t>::max ()

// trying to translate a string which is outside the domain of var will

// raise Exception NotFound

translator2.translate ( "20" ); // NotFound

gum::RangeVariable
Defines a discrete random variable over an integer interval.
Definition rangeVariable.h:72

gum::learning::DBTranslator4RangeVariable
The databases' cell translators for range variables.
Definition DBTranslator4RangeVariable.h:149

gum::learning::DBTranslatedValue
The union class for storing the translated values in learning databases.
Definition DBTranslatedValue.h:88

Definition at line 149 of file DBTranslator4RangeVariable.h.

Constructor & Destructor Documentation

◆ DBTranslator4RangeVariable() [1/6]

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

default constructor without any initial variable

When using this constructor, it is assumed implicitly that the dictionary contained into the translator is editable. So, when reading the database, if we observe a value that has not been encountered before, we update the range of the dictionary of the translator (hence that of the variable contained by the translator).

Parameters

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. If we try to add new entries in the dictionary, this will be considered as an error and a SizeError exception will be raised

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

Here is the caller graph for this function:

◆ DBTranslator4RangeVariable() [2/6]

gum::learning::DBTranslator4RangeVariable::DBTranslator4RangeVariable ( std::size_t max_dico_entries = std::numeric_limits< std::size_t >::max() )

default constructor without any initial variable nor missing symbols

When using this constructor, it is assumed implicitly that the dictionary contained into the translator is editable. So, when reading the database, if we observe a value that has not been encountered before, we update the range of the dictionary of the translator (hence that of the variable contained by the translator).

Parameters

max_dico_entries the max number of entries that the dictionary can contain. If we try to add new entries in the dictionary, this will be considered as an error and a SizeError exception will be raised

◆ DBTranslator4RangeVariable() [3/6]

gum::learning::DBTranslator4RangeVariable::DBTranslator4RangeVariable	(	const RangeVariable &	var,
		const std::vector< std::string > &	missing_symbols,
		const bool	editable_dictionary = false,
		std::size_t	max_dico_entries = std::numeric_limits< std::size_t >::max() )

default constructor with a range variable as translator

Parameters

var	a range 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
editable_dictionary	the mode in which the translator will perform translations: when false (the default), the translation of a string that does not correspond to an integer within the range of var will raise a NotFound exception; when true, the translator will try to expand the domain of the RangeVariable so that the number represented in the string belongs to this domain ((and therefore to the dictionary)
max_dico_entries	the max number of entries that the dictionary can contain. If we try to add new entries in the dictionary, this will be considered as an error and a SizeError exception will be raised

Warning: If the variable contained into the translator has a value in the range that is equal to a missing value symbol, the range value will be taken into account in the translations, not the missing value.

◆ DBTranslator4RangeVariable() [4/6]

gum::learning::DBTranslator4RangeVariable::DBTranslator4RangeVariable	(	const RangeVariable &	var,
		const bool	editable_dictionary = false,
		std::size_t	max_dico_entries = std::numeric_limits< std::size_t >::max() )

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

Parameters

var	a range variable which will be used for translations. The translator keeps a copy of this variable
editable_dictionary	the mode in which the translator will perform translations: when false (the default), the translation of a string that does not correspond to an integer within the range of var will raise a NotFound exception; when true, the translator will try to expand the domain of the RangeVariable so that the number represented in the string belongs to this domain ((and therefore to the dictionary)
max_dico_entries	the max number of entries that the dictionary can contain. If we try to add new entries in the dictionary, this will be considered as an error and a SizeError exception will be raised

Warning: If the variable contained into the translator has a value in the range that is equal to a missing value symbol, the range value will be taken into account in the translations, not the missing value.

◆ DBTranslator4RangeVariable() [5/6]

gum::learning::DBTranslator4RangeVariable::DBTranslator4RangeVariable ( const DBTranslator4RangeVariable & from )

copy constructor

References DBTranslator4RangeVariable().

Here is the call graph for this function:

◆ DBTranslator4RangeVariable() [6/6]

gum::learning::DBTranslator4RangeVariable::DBTranslator4RangeVariable ( DBTranslator4RangeVariable && from )

move constructor

References DBTranslator4RangeVariable().

Here is the call graph for this function:

◆ ~DBTranslator4RangeVariable()

virtual gum::learning::DBTranslator4RangeVariable::~DBTranslator4RangeVariable ( )

virtual

destructor

Member Function Documentation

◆ clone()

virtual DBTranslator4RangeVariable * gum::learning::DBTranslator4RangeVariable::clone ( ) const

virtual

virtual copy constructor

Implements gum::learning::DBTranslator.

References DBTranslator4RangeVariable().

Here is the call graph for this function:

◆ domainSize()

virtual std::size_t gum::learning::DBTranslator4RangeVariable::domainSize ( ) const

finalvirtual

returns the domain size of a variable corresponding to the translations

Returns the size of the range of the variable.

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()

virtual bool gum::learning::DBTranslator::hasEditableDictionary ( ) const

virtualinherited

indicates whether the translator has an editable dictionary or not

Reimplemented in gum::learning::DBTranslator4DiscretizedVariable, gum::learning::DBTranslator4IntegerVariable, and gum::learning::DBTranslator4NumericalDiscreteVariable.

◆ 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 ( const std::string & 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()

virtual DBTranslatedValue gum::learning::DBTranslator4RangeVariable::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()

virtual bool gum::learning::DBTranslator4RangeVariable::needsReordering ( ) const

finalvirtual

indicates whether a reordering is needed to make the translations sorted by increasing numbers

When constructing dynamically its dictionary, the translator may assign wrong DBTranslatedValue values to strings. For instance, a translator reading sequentially integer strings 2, 1, 3, may map 2 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 {2,1,3}. The user may prefer having domain {1,2,3}, 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.

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<< ( const std::string & str )

inherited

alias for method translate

◆ operator=() [1/2]

DBTranslator4RangeVariable & gum::learning::DBTranslator4RangeVariable::operator= ( const DBTranslator4RangeVariable & from )

copy operator

References DBTranslator4RangeVariable().

Here is the call graph for this function:

◆ operator=() [2/2]

DBTranslator4RangeVariable & gum::learning::DBTranslator4RangeVariable::operator= ( DBTranslator4RangeVariable && from )

move operator

References DBTranslator4RangeVariable().

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()

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

finalvirtual

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.

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()

virtual void gum::learning::DBTranslator::setEditableDictionaryMode ( bool new_mode )

virtualinherited

sets/unset the editable dictionary mode

Reimplemented in gum::learning::DBTranslator4DiscretizedVariable, gum::learning::DBTranslator4IntegerVariable, and gum::learning::DBTranslator4NumericalDiscreteVariable.

◆ setVariableDescription()

void gum::learning::DBTranslator::setVariableDescription ( const std::string & str ) const

inherited

sets the name of the variable stored into the translator

◆ setVariableName()

void gum::learning::DBTranslator::setVariableName ( const std::string & str ) const

inherited

sets the name of the variable stored into the translator

◆ translate()

virtual DBTranslatedValue gum::learning::DBTranslator4RangeVariable::translate ( const std::string & 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 two situations can obtain:

if the translator is not in an editable dictionary mode, then the translator raises a NotFound exception.
if the translator is in an editable dictionary mode, i.e., it is allowed to update its dictionary, then it tries to update the range of its dictionary to include the new value. Upon success, it returns the translated value, otherwise, it raises either:
- a TypeError exception if the string cannot be converted into a value that can be inserted into the dictionary
- an OperationNotAllowed exception if the translation would induce incoherent behavior (e.g., a translator that contains a variable whose domain is [x,y] as well as a missing value symbol z \(\in\) [x,y]).
- a SizeError exception if the number of entries in the dictionary, i.e., the domain size of the RangeVariable, has already reached its maximum.

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 value in its range equal to a missing value symbol, then this value 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 and the translator is not in an editable dictionary mode.
SizeError	is raised if the number of entries (the range) in the dictionary has already reached its maximum.
TypeError	is raised if the translation cannot be found and the translator is in an editable dictionary mode and the string does not correspond to an integer.
OperationNotAllowed	exception is raised if the translation cannot be found and the insertion of the string into the translator's dictionary fails because it would induce incoherent behavior (e.g., a translator that contains a variable whose domain is {x,y,z,t} as well as a missing value symbol z).

Implements gum::learning::DBTranslator.

◆ translateBack()

virtual std::string gum::learning::DBTranslator4RangeVariable::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()

virtual const RangeVariable * gum::learning::DBTranslator4RangeVariable::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 399 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 385 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 382 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 388 of file DBTranslator.h.

◆ missing_symbols_

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

protectedinherited

the set of missing symbols

Definition at line 391 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 402 of file DBTranslator.h.

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

agrum/base/database/DBTranslator4RangeVariable.h

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DBTranslator4RangeVariable() [1/6]

◆ DBTranslator4RangeVariable() [2/6]

◆ DBTranslator4RangeVariable() [3/6]

◆ DBTranslator4RangeVariable() [4/6]

◆ DBTranslator4RangeVariable() [5/6]

◆ DBTranslator4RangeVariable() [6/6]

◆ ~DBTranslator4RangeVariable()

Member Function Documentation

◆ clone()

◆ domainSize()

◆ getDictionary()

◆ getValType()

◆ hasEditableDictionary()

◆ isLossless()

◆ isMissingSymbol()

◆ isMissingValue()

◆ missingSymbols()

◆ missingValue()

◆ needsReordering()

◆ operator<<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator>>()

◆ reorder()

◆ setEditableDictionaryMode()

◆ setVariableDescription()

◆ setVariableName()

◆ translate()

◆ translateBack()

◆ variable()

Member Data Documentation

◆ back_dico_

◆ is_dictionary_dynamic_

◆ is_lossless_

◆ max_dico_entries_

◆ missing_symbols_

◆ val_type_