gum::learning::DBTranslator4ContinuousVariable Class Reference

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

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

Inheritance diagram for gum::learning::DBTranslator4ContinuousVariable:

Collaboration diagram for gum::learning::DBTranslator4ContinuousVariable:

Public Member Functions
Constructors / Destructors
	DBTranslator4ContinuousVariable (const std::vector< std::string > &missing_symbols, const bool fit_range=false)
	default constructor without any initial variable
	DBTranslator4ContinuousVariable (const bool fit_range=false)
	default constructor without any initial variable nor missing symbol
template<typename GUM_SCALAR>
	DBTranslator4ContinuousVariable (const ContinuousVariable< GUM_SCALAR > &var, const std::vector< std::string > &missing_symbols, const bool fit_range=false)
	default constructor with a continuous variable as translator
template<typename GUM_SCALAR>
	DBTranslator4ContinuousVariable (const ContinuousVariable< GUM_SCALAR > &var, const bool fit_range=false)
	default constructor with a continuous variable as translator but without missing symbol
	DBTranslator4ContinuousVariable (const IContinuousVariable &var, const std::vector< std::string > &missing_symbols, const bool fit_range=false)
	default constructor with a IContinuous variable as translator
	DBTranslator4ContinuousVariable (const IContinuousVariable &var, const bool fit_range=false)
	default constructor with a IContinuous variable as translator but without missing symbol
	DBTranslator4ContinuousVariable (const DBTranslator4ContinuousVariable &from)
	copy constructor
	DBTranslator4ContinuousVariable (DBTranslator4ContinuousVariable &&from)
	move constructor
virtual DBTranslator4ContinuousVariable *	clone () const
	virtual copy constructor
virtual	~DBTranslator4ContinuousVariable ()
	destructor
Operators
DBTranslator4ContinuousVariable &	operator= (const DBTranslator4ContinuousVariable &from)
	copy operator
DBTranslator4ContinuousVariable &	operator= (DBTranslator4ContinuousVariable &&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 std::numeric_limits<std::size_t>::max ()
virtual bool	needsReordering () const final
	indicates that the translations should never be reordered
virtual HashTable< std::size_t, std::size_t >	reorder () final
	returns an empty mapping, indicating that old tanslations are equal to the newly reordered ones.
virtual const IContinuousVariable *	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 continuous 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 DBTranslator4ContinuousVariable is a translator that contains and exploits a ContinuousVariable for translations. Each time a string needs be translated, we ask the ContinuousVariable whether it belongs to its domain (which is supposed to be of type [x_min,x_max]). If this is the case, then the DBTranslatedValue corresponding to the translation of the string contains the floating point number specified in the string.

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::DBTranslator4ContinuousVariable translator ( missing );
 
// gets the DBTranslatedValue corresponding to some strings
auto val1 = translator.translate("5");   // val1 = DBTranslatedValue {5.0f}
auto val2 = translator.translate("4.2"); // val2 = DBTRanslatedValue {4.2f}
auto val3 = translator << "3.4";         // val3 = DBTranslatedValue {3.4f}
 
// add the numbers assigned to val1, val2, val3
float sum = val1.cont_val + val2.cont_val + val3.cont_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 real numbers
auto val6 = translator << "4.22x";
auto val7 = translator.translate ( "xxx" );
 
// given a DBTranslatedValue that is supposed to contain a float, get
// the corresponding string. The strings should be equivalent to those
// indicated below (maybe they could contain more zeroes after the dot).
std::string str;
str = translator.translateBack ( val1 );        // str ~ "5.0"
str = translator >> val2;                       // str ~ "4.2"
str = translator >> gum::learning::DBTranslatedValue {7.2e3f};
                                                // str ~ "7.2 e3"
 
// 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::ContinuousVariable<float>* var =
  dynamic_cast<const gum::ContinuousVariable<float>*>
    ( 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 continuous variable whose domain is [-2,10]
gum::ContinuousVariable<float> var ( "X", "", -2, 10 );
gum::learning::DBTranslator4ContinuousVariable translator2 (var,missing);
 
float xval1 = translator2.translate ( "-1.4" ).cont_val; // xval1 = -1.4
float xval2 = translator2.translate ( "7" ).cont_val;    // xval2 = 7
float xval3 = translator2.translate ( "N/A" ).cont_val;
// here xval3 corresponds to a missing value, hence it is equal to
// std::numeric_limits<float>::max ()
 
// trying to translate a string which is outside the domain of var will
// raise Exception NotFound
translator2.translate ( "20" ); // NotFound

Definition at line 144 of file DBTranslator4ContinuousVariable.h.

Constructor & Destructor Documentation

DBTranslator4ContinuousVariable() [1/8]

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable	(	const std::vector< std::string > &	missing_symbols,
		const bool	fit_range = false )

default constructor without any initial variable

When using this constructor, it is assumed implicitly that the continuous variable has a range from minus infinity to plus infinity. If the fit_range parameter is on, the range of the variable is updated so that it precisely fits the range of the observed values in the database.

Parameters

missing_symbols	the set of symbols in the database representing missing values
fit_range	if true, the range of the variable is updated so that it precisely fits the range of the observed values in the database, else the range is kept to (-inf,inf)

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

Here is the caller graph for this function:

DBTranslator4ContinuousVariable() [2/8]

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable

(

const bool

fit_range = false

)

default constructor without any initial variable nor missing symbol

When using this constructor, it is assumed implicitly that the continuous variable has a range from minus infinity to plus infinity. If the fit_range parameter is on, the range of the variable is updated so that it precisely fits the range of the observed values in the database.

Parameters

fit_range

if true, the range of the variable is updated so that it precisely fits the range of the observed values in the database, else the range is kept to (-inf,inf)

DBTranslator4ContinuousVariable() [3/8]

template<typename GUM_SCALAR>

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable	(	const ContinuousVariable< GUM_SCALAR > &	var,
		const std::vector< std::string > &	missing_symbols,
		const bool	fit_range = false )

default constructor with a continuous variable as translator

Parameters

var	a continuous variable that will be used for translations. The translator keeps a copy of this variable
missing_symbols	the set of symbols in the database representing missing values
fit_range	if true, the range of the variable is updated so that it precisely fits the range of the observed values in the database, else the range is kept to (-inf,inf)

Warning

If a missing value symbol is a number included in the range of the continuous variable, it will be discarded. If the fit_range parameter is on, the range of the variable is updated so that it can contain the range of the observed values in the database.

DBTranslator4ContinuousVariable() [4/8]

template<typename GUM_SCALAR>

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable	(	const ContinuousVariable< GUM_SCALAR > &	var,
		const bool	fit_range = false )

default constructor with a continuous variable as translator but without missing symbol

Parameters

var	a continuous variable that will be used for translations. The translator keeps a copy of this variable
fit_range	if true, the range of the variable is updated so that it precisely fits the range of the observed values in the database, else the range is kept to (-inf,inf)

Warning

If a missing value symbol is a number included in the range of the continuous variable, it will be discarded. If the fit_range parameter is on, the range of the variable is updated so that it can contain the range of the observed values in the database.

DBTranslator4ContinuousVariable() [5/8]

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable	(	const IContinuousVariable &	var,
		const std::vector< std::string > &	missing_symbols,
		const bool	fit_range = false )

default constructor with a IContinuous variable as translator

Parameters

var	a IContinuous variable that will be used for translations. The translator keeps a copy of this variable
missing_symbols	the set of symbols in the database representing missing values
fit_range	if true, the range of the variable is updated so that it precisely fits the range of the observed values in the database, else the range is kept to (-inf,inf)

Warning

If a missing value symbol is a number included in the range of the continuous variable, it will be discarded. If the fit_range parameter is on, the range of the variable is updated so that it can contain the range of the observed values in the database.

DBTranslator4ContinuousVariable() [6/8]

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable	(	const IContinuousVariable &	var,
		const bool	fit_range = false )

default constructor with a IContinuous variable as translator but without missing symbol

Parameters

var	a IContinuous variable that will be used for translations. The translator keeps a copy of this variable
fit_range	if true, the range of the variable is updated so that it precisely fits the range of the observed values in the database, else the range is kept to (-inf,inf)

Warning

If a missing value symbol is a number included in the range of the continuous variable, it will be discarded. If the fit_range parameter is on, the range of the variable is updated so that it can contain the range of the observed values in the database.

DBTranslator4ContinuousVariable() [7/8]

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable

(

const DBTranslator4ContinuousVariable &

from

)

copy constructor

References DBTranslator4ContinuousVariable().

Here is the call graph for this function:

DBTranslator4ContinuousVariable() [8/8]

gum::learning::DBTranslator4ContinuousVariable::DBTranslator4ContinuousVariable

(

DBTranslator4ContinuousVariable &&

from

)

move constructor

References DBTranslator4ContinuousVariable().

Here is the call graph for this function:

~DBTranslator4ContinuousVariable()

virtual gum::learning::DBTranslator4ContinuousVariable::~DBTranslator4ContinuousVariable ( )

virtual

destructor

Member Function Documentation

clone()

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

virtual

virtual copy constructor

Implements gum::learning::DBTranslator.

References DBTranslator4ContinuousVariable().

Here is the call graph for this function:

domainSize()

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

finalvirtual

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

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

inherited

alias for method translate

operator=() [1/2]

DBTranslator4ContinuousVariable & gum::learning::DBTranslator4ContinuousVariable::operator=

(

const DBTranslator4ContinuousVariable &

from

)

copy operator

References DBTranslator4ContinuousVariable().

Here is the call graph for this function:

operator=() [2/2]

DBTranslator4ContinuousVariable & gum::learning::DBTranslator4ContinuousVariable::operator=

(

DBTranslator4ContinuousVariable &&

from

)

move operator

References DBTranslator4ContinuousVariable().

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::DBTranslator4ContinuousVariable::reorder ( )

finalvirtual

returns an empty mapping, indicating that old tanslations are equal to the newly reordered 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::DBTranslator4ContinuousVariable::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:

1. if the translator is not in an editable dictionary mode, then the translator raises a NotFound exception.
2. 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 DBTranslator4ContinuousVariable that contains a variable whose domain is [x,y] as well as a missing value symbol z \(\in\) [x,y]).

Warning

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

If the variable contained into the translator has a value in its domain equal to a missing value symbol, this value will be taken into account in the translations, not the missing value.

Returns

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

Exceptions

UnknownLabelInDatabase	is raised if the number represented by the string is out of the range of the continuous variable and the translator is not in an editable dictionary mode.
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 DBTranslator4ContinuousVariable that contains a variable whose domain is [x,y] as well as a missing value symbol z \(\in\) [x,y]).
TypeError	is raised if the translation cannot be found and the insertion of the string into the translator's dictionary fails due to str being impossible to be converted into an appropriate type.

Implements gum::learning::DBTranslator.

translateBack()

virtual std::string gum::learning::DBTranslator4ContinuousVariable::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 is outside the domain of the continuous variable stored within the translator

Implements gum::learning::DBTranslator.

variable()

virtual const IContinuousVariable * gum::learning::DBTranslator4ContinuousVariable::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/DBTranslator4ContinuousVariable.h