lti::classifier::outputVector Class Reference

An output vector is the result of classifying data with any classifier. More...

#include <ltiClassifier.h>

Inheritance diagram for lti::classifier::outputVector:

[legend]

Collaboration diagram for lti::classifier::outputVector:

[legend]

List of all members.

Public Member Functions
	outputVector ()
	outputVector (const outputVector &other)
	outputVector (const int &size)
	outputVector (const ivector &theIds, const dvector &theValues)
outputVector &	copy (const outputVector &other)
outputVector &	operator= (const outputVector &other)
outputVector *	clone () const
int	size () const
bool	find (const int &id, int &pos) const
void	setValues (const dvector &theValues)
bool	setValueByPosition (const int &pos, const double &value)
bool	setValueById (const int &id, const double &value)
const dvector &	getValues () const
void	setIds (const ivector &theIds)
void	setIdsAndValues (const ivector &theIds, const dvector &theValues)
const ivector &	getIds () const
bool	setPair (const int &pos, const int &id, const double &value)
bool	getId (const int &pos, int &id) const
bool	getValueByPosition (const int &pos, double &value) const
bool	getValueById (const int &id, double &value) const
bool	getPair (const int &pos, int &id, double &value) const
bool	setWinnerUnit (const int &pos)
int	setWinnerAtMax ()
int	getWinnerUnit () const
void	setReject (const bool &rej)
bool	isRejected () const
void	setConfidenceValue (const double &conf)
double	getConfidenceValue () const
void	sortAscending ()
void	sortDescending ()
void	makeProbDistribution ()
bool	compatible (const outputVector &other) const
bool	noMultipleIds () const
void	idMaximize ()
void	idSum ()
double	maxValue () const
int	maxPosition () const
int	maxId () const
void	maxPair (int &id, double &value) const
double	minValue () const
int	minPosition () const
int	minId () const
void	minPair (int &id, double &value) const
outputVector &	add (const outputVector &other)
outputVector &	add (const outputVector &a, const outputVector &b)
outputVector &	add (const double &s)
outputVector &	addScaled (const outputVector &other, const double &s)
outputVector &	mul (const outputVector &other)
outputVector &	mul (const outputVector &a, const outputVector &b)
outputVector &	mul (const double &s)
outputVector &	divide (const double &s)
outputVector &	max (const outputVector &other)
outputVector &	max (const outputVector &a, const outputVector &b)
outputVector &	min (const outputVector &other)
outputVector &	min (const outputVector &a, const outputVector &b)
bool	write (ioHandler &handler, const bool complete=true) const
bool	read (ioHandler &handler, const bool complete=true)
Protected Attributes
ivector	ids
dvector	values
int	winner
double	confidence
bool	reject
bool	valid
bool	sortedAsc
bool	sortedDesc

Detailed Description

An output vector is the result of classifying data with any classifier.

It is usually built by a classifier using its internal outputTemplate. The outputVector contains labels (also called ids) and values (usually probabilities). Typically, each label occurs only once in the outputVector and all values are between 0 and 1 and form a probability distribution. However, this is not required by definition. Each classifier should document the nature of its outputVector.

In general, an ouputVector looks like this:

Some classifiers have multiple outputs for each class or unnormalized values. In case this is not wanted in further processing outputVector supplies several methods for manipulation of labels and values.

The method idMaximize() searches for all multiple ids and erases all but the entry with the highest value. For the above example this leads to the following outputVector:

The values for multiple ids are summed using the method idSum(). After execution there is only one entry for each label with the sum of values as new value. For the example the result is:

Due to algorithmic reasons both methods sort the labels in ascending order. You can check wether multiple labels exist with the method noMultipleIds().

For many application it is useful if the values of the ouputVector form a probability distribution over the labels, i.e. all values are greater equal zero and the sum over all values is one. This is accomplished by the method makeProbDistribution(). It sets values below zero to zero and then normalizes the values to sum to one. When applied to the two outputVectors above the method gives the following results:

A classifier or an independent module can decide that a classification result does not contain any useful informations. Such an outputVector is marked as rejected by calling setReject() with argument either true or false. The status is queried with isRejected().

Some classifiers, instead of rejecting a result or not, give confidence values. These lie between 0 for lowest and 1 for highest confidence. The confidence is set with setConfidenceValue() and queried with getConfidenceValue().

NOTE: Confidence values are not taken into account when algebraic methods are called.

If possible all classifiers should define a winner unit. This is the index (which usually corresponds to the same posisition in an internal result) in the ouputVector which achieved the best result in the classification. The winner unit is specified by calling setWinnerUnit(). If the winner unit is the one with the maximum value in the ouputVector, the method setWinnerAtMax() can be used. The information is retrieved with getWinnerUnit().

If two or more outputVectors are to be merged or compared it is useful to know whether they describe the same set of labels. The method compatible() checks whether another outputVector contains exactly the same labels as this outputVector.

Other functional groups of methods include:

read-access methods: getId(), getValueByPosition(), getValueById(), getPair(), getValues(), getIds()
write-access methods: setId(), setValueByPosition(), setValueById(), setPair(), setValues(), setIds(),setIdsAndValues()
searchMethods: find(), maxValue(), maxPosition(), maxId(), maxPair(), minValue(), minPosition(), minId(), minPair()
sorting methods: sortAscending(), sortDescending()
algebraic methods: various methods that add or multiply ouputVectors or apply min or max operators.

Constructor & Destructor Documentation

lti::classifier::outputVector::outputVector ( )

Default Constructor.

lti::classifier::outputVector::outputVector ( const outputVector & other )

Copy Constructor.

lti::classifier::outputVector::outputVector ( const int & size )

Constructor.

Creates an outputVector of the given size.

Parameters:

size

size of the output vector

lti::classifier::outputVector::outputVector	(	const ivector &	theIds,
		const dvector &	theValues
	)

Constructor.

Sets the values and the ids.

Member Function Documentation

outputVector& lti::classifier::outputVector::add ( const double & s )

Adds the given scalar to each value of the outputVector.

Parameters:

s

the scalar to be added

Returns:: this outputVector

outputVector& lti::classifier::outputVector::add	(	const outputVector &	a,
		const outputVector &	b
	)

Adds the two outputVectors and writes the result into this outputVector.

Parameters:

	a	the first summand
	b	the second summand

Returns:: this outputVector

See also:: add(const outputVector& other)

outputVector& lti::classifier::outputVector::add ( const outputVector & other )

Adds the other outputVector to this outputVector.

I.e. for each id that exists in both outputVectors the values are added, else the value remains unchanged and the new ids are appended to this outputVector.

Parameters:

other

the outputVector to be added to this one

Returns:: this outputVector

outputVector& lti::classifier::outputVector::addScaled	(	const outputVector &	other,
		const double &	s
	)

Adds the other outputVector scaled by s to this outputVector.

I.e. for each id that exists in both outputVectors the values are added, else the value remains unchanged and the new ids are appended to this outputVector.

Parameters:

	other	the outputVector to be added to this one
	s	scaling factor for the other

Returns:: this outputVector

outputVector* lti::classifier::outputVector::clone ( ) const

clone method.

bool lti::classifier::outputVector::compatible ( const outputVector & other ) const

Checks whether the other outputVector contains exactly the same ids as this outputVector.

Parameters:

other

outputVector to be compared to this

Returns:: true if ids are exactly the same.

outputVector& lti::classifier::outputVector::copy ( const outputVector & other )

copy method.

Copy other into this and return this.

Reimplemented from lti::ioObject.

outputVector& lti::classifier::outputVector::divide ( const double & s )

Divides each value of the outputVector by the given scalar.

Parameters:

s

the scalar

Returns:: this outputVector

bool lti::classifier::outputVector::find	(	const int &	id,
		int &	pos
	)			const

Finds the given id in the outputVector and returns its position if contained in the outputVector.

If the id is not found false is returned and the position set to -1.

Parameters:

	id	find this id
	pos	the position of the id.

Returns:: true if id was found, false otherwise

double lti::classifier::outputVector::getConfidenceValue ( ) const

Returns the confidence value for this outputVector.

Values are between zero (no confidence) and one (total confidence).

bool lti::classifier::outputVector::getId	(	const int &	pos,
		int &	id
	)			const

Returns the id at the given position.

Parameters:

	pos	position in the vector
	id	the id at that position

Returns:: true if id returned, false e.g. for invalid pos

const ivector& lti::classifier::outputVector::getIds ( ) const

Returns a const reference to the ids of the outputVector.

bool lti::classifier::outputVector::getPair	(	const int &	pos,
		int &	id,
		double &	value
	)			const

Returns the id and the value at the given position.

Parameters:

	pos	position in the vector
	id	the id at that position
	value	the value at that position

Returns:: true if id returned, false e.g. for invalid pos

bool lti::classifier::outputVector::getValueById	(	const int &	id,
		double &	value
	)			const

Returns the value for the given id.

If an id is used more than once the value with the lowest position is returned.

Parameters:

	id	id value
	value	the value for the id

Returns:: true if id returned, false e.g. for invalid pos

bool lti::classifier::outputVector::getValueByPosition	(	const int &	pos,
		double &	value
	)			const

Returns the value at the given position.

Parameters:

	pos	position in the vector
	value	the value at that position

Returns:: true if id returned, false e.g. for invalid pos

const dvector& lti::classifier::outputVector::getValues ( ) const

Returns a const reference to the values of the outputVector.

int lti::classifier::outputVector::getWinnerUnit ( ) const

Get position of the winner.

Referenced by lti::SOFM2DVisualizer::drawClasses(), and lti::SOFM2DVisualizer::drawHits().

void lti::classifier::outputVector::idMaximize ( )

If an id is given more than once, the maximum value is sought and all other units of this id erased.

The resulting outputVector is sorted by ids.

void lti::classifier::outputVector::idSum ( )

If an id is given more than once, the sum of the values is computed and only one unit of that id remains.

The resulting outputVector is sorted by ids.

bool lti::classifier::outputVector::isRejected ( ) const

Returns whether the ouputVector was marked as rejected or not.

void lti::classifier::outputVector::makeProbDistribution ( )

Lets the outputVector comply to rules for probability distributions: Values between 0 and 1, sum of values equals 1.

This is done by setting values that are lower than zero to zero and afterwards dividing each value by the sum of values.

outputVector& lti::classifier::outputVector::max	(	const outputVector &	a,
		const outputVector &	b
	)

Calculates the maximum between the two outputVectors and writes it into this outputVector.

Analog to inplace version.

Parameters:

	a	the first outputVector
	b	the second outputVector

Returns:: this outputVector

See also:: max(const outputVector& other)

outputVector& lti::classifier::outputVector::max ( const outputVector & other )

Calculates the maximum between the other and this outputVector.

I.e. for each id that exists in both outputVectors the maximum is taken, else the value stays unchanged and the new ids are appended to this outputVector.

Parameters:

other

the outputVector to be compared to this

Returns:: this outputVector

int lti::classifier::outputVector::maxId ( ) const

Find the id of the maximum value in the outputVector.

Returns:: the id of the maximum value

void lti::classifier::outputVector::maxPair	(	int &	id,
		double &	value
	)			const

Find the id-value pair with the maximum value in the outputVector.

This is faster than finding them separately!

Parameters:

	id	id of the maximum value
	value	the maximum value

int lti::classifier::outputVector::maxPosition ( ) const

Find the position of the maximum value in the outputVector.

Returns:: the position of the maximum value

double lti::classifier::outputVector::maxValue ( ) const

Find the maximum value in the outputVector.

Returns:: the maximum value

outputVector& lti::classifier::outputVector::min	(	const outputVector &	a,
		const outputVector &	b
	)

Calculates the minimum between the two outputVectors and writes it into this outputVector.

Analog to inplace version.

Parameters:

	a	the first outputVector
	b	the second outputVector

Returns:: this outputVector

See also:: min(const outputVector& other)

outputVector& lti::classifier::outputVector::min ( const outputVector & other )

Calculates the minimum between the other and this outputVector.

I.e. for each id that exists in both outputVectors the minimum is taken, else the value is zero and the new ids are appended to this outputVector.

Parameters:

other

the outputVector to be compared to this

Returns:: this outputVector

int lti::classifier::outputVector::minId ( ) const

Find the id of the minimum value in the outputVector.

Returns:: the id of the minimum value

void lti::classifier::outputVector::minPair	(	int &	id,
		double &	value
	)			const

Find the id-value pair with the minimum value in the outputVector.

This is faster than finding them separately!

Parameters:

	id	id of the minimum value
	value	the minimum value

int lti::classifier::outputVector::minPosition ( ) const

Find the position of the minimum value in the outputVector.

Returns:: the position of the minimum value

double lti::classifier::outputVector::minValue ( ) const

Find the minimum value in the outputVector.

Returns:: the minimum value

outputVector& lti::classifier::outputVector::mul ( const double & s )

Multiplies each value of the outputVector with the given scalar.

Parameters:

s

the scalar

Returns:: this outputVector

outputVector& lti::classifier::outputVector::mul	(	const outputVector &	a,
		const outputVector &	b
	)

Multiplies the two outputVectors and writes the result into this outputVector.

Parameters:

	a	the first factor
	b	the second factor

Returns:: this outputVector

See also:: mul(const outputVector& other)

outputVector& lti::classifier::outputVector::mul ( const outputVector & other )

Multiplies the other outputVector with this outputVector.

I.e. for each id that exists in both outputVectors the values are multiplied, else the value is zero and the new ids are appended to this outputVector.

Parameters:

other

the outputVector to be multiplied to this one

Returns:: this outputVector

bool lti::classifier::outputVector::noMultipleIds ( ) const

Returns true if there are never two elements of the outputVector with the same id.

outputVector& lti::classifier::outputVector::operator= ( const outputVector & other )

copy operator.

Copy other into this and return this.

Reimplemented from lti::ioObject.

bool lti::classifier::outputVector::read	(	ioHandler &	handler,
		const bool	complete = `true`
	)			`[virtual]`

read the objectProb from the given ioHandler

Parameters:

	handler	the ioHandler to be used
	complete	if true (the default) the enclosing begin/end will be also written, otherwise only the data block will be written.

Returns:: true if write was successful

Reimplemented from lti::ioObject.

void lti::classifier::outputVector::setConfidenceValue ( const double & conf )

Sets the confidence value for this outputVector.

The value must be between 0 and 1 for lowest and highest confidence. Default is 1. Other values are cropped.

Parameters:

conf

new confidence value betwenn 0 and 1

void lti::classifier::outputVector::setIds ( const ivector & theIds )

Sets the ids of the outputVector.

Parameters:

theIds

the new ids

void lti::classifier::outputVector::setIdsAndValues	(	const ivector &	theIds,
		const dvector &	theValues
	)

Sets the ids of the outputVector and the values.

The state of the instance will be exactly as after constructing an outputVector with ids and values.

If the sizes of both vectors are not equal, the smallest size will be used and the largest vector will be cut.

Parameters:

	theIds	the new ids
	theValues	the new values

bool lti::classifier::outputVector::setPair	(	const int &	pos,
		const int &	id,
		const double &	value
	)

Sets the id and the value at the given position.

If the position does not exist, false is returned.

Parameters:

	pos	position to be changed
	id	id at that position
	value	value at that position

Returns:: false on error

void lti::classifier::outputVector::setReject ( const bool & rej )

Sets whether result is rejected.

Default for reject is false.

Parameters:

rej

true if rejected

bool lti::classifier::outputVector::setValueById	(	const int &	id,
		const double &	value
	)

Sets the value for the given id in the outputVector.

Parameters:

	id	id whose value is to be changed
	value	the new value

Returns:: true if successful, false otherwise.

bool lti::classifier::outputVector::setValueByPosition	(	const int &	pos,
		const double &	value
	)

Sets the value at the given position of the outputVector.

Parameters:

	pos	vector entry, where the value should be written
	value	the new value

Returns:: true if successful, false otherwise.

void lti::classifier::outputVector::setValues ( const dvector & theValues )

Sets the values of the outputVector.

The internal vector will be resized to the size of theValues.

Parameters:

theValues

the new values

int lti::classifier::outputVector::setWinnerAtMax ( )

Set the winner unit as the position of the maximum value of the outputVector.

Returns:: position of the winner unit in the vector

bool lti::classifier::outputVector::setWinnerUnit ( const int & pos )

Set the winner unit.

Parameters:

pos

position of the winner unit in the vector

Returns:: false if pos not between 0..n-1

int lti::classifier::outputVector::size ( ) const

Returns the number of elements in the outputVector.

void lti::classifier::outputVector::sortAscending ( )

Sorts the outputVector so that values are in ascending order.

The sort is only executed if the vector is not already sorted. Ids and winner position are adjusted accordingly.

void lti::classifier::outputVector::sortDescending ( )

Sorts the outputVector so that values are in descending order.

The sort is only executed if the vector is not already sorted. Ids and winner position are adjusted accordingly.

bool lti::classifier::outputVector::write	(	ioHandler &	handler,
		const bool	complete = `true`
	)			const `[virtual]`

write the objectProb in the given ioHandler

Parameters:

	handler	the ioHandler to be used
	complete	if true (the default) the enclosing begin/end will be also written, otherwise only the data block will be written.