ClassificationDataStream Class Reference

#include <ClassificationDataStream.h>

Public Member Functions
	ClassificationDataStream (const UINT numDimensions=0, const std::string datasetName="NOT_SET", const std::string infoText="")
	ClassificationDataStream (const ClassificationDataStream &rhs)
virtual	~ClassificationDataStream ()
ClassificationDataStream &	operator= (const ClassificationDataStream &rhs)
ClassificationSample &	operator[] (const UINT i)
const ClassificationSample &	operator[] (const UINT i) const
void	clear ()
bool	setNumDimensions (const UINT numDimensions)
bool	setDatasetName (const std::string datasetName)
bool	setInfoText (const std::string infoText)
bool	setClassNameForCorrespondingClassLabel (const std::string className, const UINT classLabel)
bool	addSample (const UINT classLabel, const VectorFloat &sample)
bool	addSample (const UINT classLabel, const MatrixFloat &sample)
bool	removeLastSample ()
UINT	eraseAllSamplesWithClassLabel (const UINT classLabel)
bool	relabelAllSamplesWithClassLabel (const UINT oldClassLabel, const UINT newClassLabel)
bool	setExternalRanges (const Vector< MinMax > &externalRanges, const bool useExternalRanges=false)
bool	enableExternalRangeScaling (const bool useExternalRanges)
bool	scale (const Float minTarget, const Float maxTarget)
bool	scale (const Vector< MinMax > &ranges, const Float minTarget, const Float maxTarget)
bool	resetPlaybackIndex (const UINT playbackIndex)
ClassificationSample	getNextSample ()
TimeSeriesClassificationData	getAllTrainingExamplesWithClassLabel (const UINT classLabel) const
bool	save (const std::string &filename)
bool	load (const std::string &filename)
bool	saveDatasetToFile (const std::string &filename)
bool	saveDatasetToCSVFile (const std::string &filename)
bool	loadDatasetFromFile (const std::string &filename)
bool	loadDatasetFromCSVFile (const std::string &filename, const UINT classLabelColumnIndex=0)
bool	printStats () const
std::string	getDatasetName () const
std::string	getInfoText () const
UINT	getNumDimensions () const
UINT	getNumSamples () const
UINT	getNumClasses () const
UINT	getMinimumClassLabel () const
UINT	getMaximumClassLabel () const
UINT	getClassLabelIndexValue (const UINT classLabel) const
std::string	getClassNameForCorrespondingClassLabel (const UINT classLabel)
Vector< MinMax >	getRanges () const
Vector< ClassTracker >	getClassTracker () const
Vector< TimeSeriesPositionTracker >	getTimeSeriesPositionTracker () const
std::deque< ClassificationSample >	getClassificationSamples () const
ClassificationDataStream	getSubset (const UINT startIndex, const UINT endIndex) const
TimeSeriesClassificationData	getTimeSeriesClassificationData (const bool includeNullGestures=false) const
ClassificationData	getClassificationData (const bool includeNullGestures=false) const
MatrixFloat	getTimeSeriesData (const TimeSeriesPositionTracker &trackerInfo) const
MatrixFloat	getDataAsMatrixFloat () const
Vector< UINT >	getClassLabels () const

Protected Attributes
std::string	datasetName
	The name of the dataset.
std::string	infoText
	Some infoText about the dataset.
UINT	numDimensions
	The number of dimensions in the dataset.
UINT	totalNumSamples
UINT	lastClassID
UINT	playbackIndex
bool	trackingClass
bool	useExternalRanges
	A flag to show if the dataset should be scaled using the externalRanges values.
Vector< MinMax >	externalRanges
	A Vector containing a set of externalRanges set by the user.
Vector< ClassTracker >	classTracker
std::deque< ClassificationSample >	data
Vector< TimeSeriesPositionTracker >	timeSeriesPositionTracker
DebugLog	debugLog
	Default debugging log.
ErrorLog	errorLog
	Default error log.
WarningLog	warningLog
	Default warning log.

Detailed Description

GRT MIT License Copyright (c) <2012> <Nicholas Gillian, Media Lab, MIT>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Definition at line 42 of file ClassificationDataStream.h.

Constructor & Destructor Documentation

GRT_BEGIN_NAMESPACE ClassificationDataStream::ClassificationDataStream	(	const UINT	numDimensions = 0,
		const std::string	datasetName = "NOT_SET",
		const std::string	infoText = ""
	)

Constructor, sets the name of the dataset and the number of dimensions of the training data. The name of the dataset should not contain any spaces.

Parameters

numDimensions	the number of dimensions of the training data, should be an unsigned integer greater than 0
datasetName	the name of the dataset, should not contain any spaces
infoText	some info about the data in this dataset, this can contain spaces

Definition at line 26 of file ClassificationDataStream.cpp.

ClassificationDataStream::ClassificationDataStream

(

const ClassificationDataStream &

rhs

)

Copy Constructor, copies the ClassificationDataStream from the rhs instance to this instance

Parameters

rhs	another instance of the ClassificationDataStream class from which the data will be copied to this instance

Definition at line 44 of file ClassificationDataStream.cpp.

ClassificationDataStream::~ClassificationDataStream ( )

virtual

Default Destructor

Definition at line 48 of file ClassificationDataStream.cpp.

Member Function Documentation

bool ClassificationDataStream::addSample	(	const UINT	classLabel,
		const VectorFloat &	sample
	)

Adds a new labelled sample to the dataset. The dimensionality of the sample should match the number of dimensions in the ClassificationDataStream. The class label can be zero (this should represent a null class).

Parameters

classLabel	the class label of the corresponding sample
sample	the new sample you want to add to the dataset. The dimensionality of this sample should match the number of dimensions in the ClassificationDataStream

Returns

true if the sample was correctly added to the dataset, false otherwise

Definition at line 127 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::addSample	(	const UINT	classLabel,
		const MatrixFloat &	sample
	)

Adds a new labelled sample to the dataset. The dimensionality of the sample should match the number of dimensions in the ClassificationDataStream. The class label can be zero (this should represent a null class).

Parameters

classLabel	the class label of the corresponding sample
sample	the new sample you want to add to the dataset. The number of rows of this sample should match the number of dimensions in the ClassificationDataStream

Returns

true if the sample was correctly added to the dataset, false otherwise

Definition at line 169 of file ClassificationDataStream.cpp.

void ClassificationDataStream::clear

(

)

Clears any previous training data and counters

Definition at line 72 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::enableExternalRangeScaling

(

const bool

useExternalRanges

)

Sets if the dataset should be scaled using an external range (if useExternalRanges == true) or the ranges of the dataset (if false). The external ranges need to be set FIRST before calling this function, otherwise it will return false.

Parameters

useExternalRanges

sets if these ranges should be used to scale the dataset

Returns

returns true if the useExternalRanges variable was set, false otherwise

Definition at line 361 of file ClassificationDataStream.cpp.

UINT ClassificationDataStream::eraseAllSamplesWithClassLabel

(

const UINT

classLabel

)

Deletes from the dataset all the samples with a specific class label.

Parameters

classLabel

the class label of the samples you wish to delete from the dataset

Returns

the number of samples deleted from the dataset

Definition at line 250 of file ClassificationDataStream.cpp.

TimeSeriesClassificationData ClassificationDataStream::getAllTrainingExamplesWithClassLabel

(

const UINT

classLabel

)

const

Gets all the timeseries that have a specific class label.

Parameters

classLabel

the class label of the timeseries you want to find

Returns

a TimeSeriesClassificationData dataset containing any timeseries that have the matching classlabel

Definition at line 401 of file ClassificationDataStream.cpp.

ClassificationData ClassificationDataStream::getClassificationData

(

const bool

includeNullGestures = false

)

const

This function segments the continuous time series data into individual samples and then adds these samples into a new ClassificationData dataset. This new dataset is then returned. By default, the new dataset will not contain any samples with the class label of GRT_DEFAULT_NULL_CLASS_LABEL (as this is assumed to be a NULL gesture) unless you set the includeNullGestures parameter to true.

Returns

returns a new ClassificationData built from the samples in this dataset.

Definition at line 877 of file ClassificationDataStream.cpp.

std::deque< ClassificationSample > ClassificationDataStream::getClassificationSamples ( ) const

inline

Gets the classification data as a Vector of ClassificationSample.

Returns

a Vector of ClassificationSamples

Definition at line 406 of file ClassificationDataStream.h.

UINT ClassificationDataStream::getClassLabelIndexValue

(

const UINT

classLabel

)

const

Gets the index of the class label from the class tracker.

Returns

an unsigned int representing the index of the class label in the class tracker

Definition at line 440 of file ClassificationDataStream.cpp.

Vector< UINT > ClassificationDataStream::getClassLabels

(

)

const

Gets the class labels in the current dataset.

Returns

a Vector containing the class labels from the current dataset.

Definition at line 931 of file ClassificationDataStream.cpp.

std::string ClassificationDataStream::getClassNameForCorrespondingClassLabel

(

const UINT

classLabel

)

Gets the name of the class with a given class label. If the class label does not exist then the std::string "CLASS_LABEL_NOT_FOUND" will be returned.

Returns

a std::string containing the name of the given class label or the std::string "CLASS_LABEL_NOT_FOUND" if the class label does not exist

Definition at line 450 of file ClassificationDataStream.cpp.

Vector< ClassTracker > ClassificationDataStream::getClassTracker ( ) const

inline

Gets the class tracker for each class in the dataset.

Returns

a Vector of ClassTracker, one for each class in the dataset

Definition at line 392 of file ClassificationDataStream.h.

MatrixFloat ClassificationDataStream::getDataAsMatrixFloat

(

)

const

Gets all the data as a MatrixFloat. This returns just the data, not the labels. This will be an M by N MatrixFloat, where M is the number of samples and N is the number of dimensions.

Returns

a MatrixFloat containing the data from the current dataset.

Definition at line 919 of file ClassificationDataStream.cpp.

std::string ClassificationDataStream::getDatasetName ( ) const

inline

Gets the name of the dataset.

Returns

returns the name of the dataset

Definition at line 322 of file ClassificationDataStream.h.

std::string ClassificationDataStream::getInfoText ( ) const

inline

Gets the infotext for the dataset

Returns

returns the infotext of the dataset

Definition at line 329 of file ClassificationDataStream.h.

UINT ClassificationDataStream::getMaximumClassLabel

(

)

const

Gets the maximum class label in the dataset. If there are no values in the dataset then the value 0 will be returned.

Returns

an unsigned int representing the maximum class label in the dataset

Definition at line 428 of file ClassificationDataStream.cpp.

UINT ClassificationDataStream::getMinimumClassLabel

(

)

const

Gets the minimum class label in the dataset. If there are no values in the dataset then the value 99999 will be returned.

Returns

an unsigned int representing the minimum class label in the dataset

Definition at line 415 of file ClassificationDataStream.cpp.

ClassificationSample ClassificationDataStream::getNextSample

(

)

Gets the next sample, this will also increment the playback index. If the playback index reaches the last data sample then it will be reset to 0.

Returns

the ClassificationSample at the current playback index

Definition at line 394 of file ClassificationDataStream.cpp.

UINT ClassificationDataStream::getNumClasses ( ) const

inline

Gets the number of classes.

Returns

an unsigned int representing the number of classes

Definition at line 350 of file ClassificationDataStream.h.

UINT ClassificationDataStream::getNumDimensions ( ) const

inline

Gets the number of dimensions of the labelled classification data.

Returns

an unsigned int representing the number of dimensions in the classification data

Definition at line 336 of file ClassificationDataStream.h.

UINT ClassificationDataStream::getNumSamples ( ) const

inline

Gets the number of samples in the classification data across all the classes.

Returns

an unsigned int representing the total number of samples in the classification data

Definition at line 343 of file ClassificationDataStream.h.

Vector< MinMax > ClassificationDataStream::getRanges

(

)

const

Gets the ranges of the classification data.

Returns

a Vector of minimum and maximum values for each dimension of the data

Definition at line 460 of file ClassificationDataStream.cpp.

ClassificationDataStream ClassificationDataStream::getSubset	(	const UINT	startIndex,
		const UINT	endIndex
	)		const

Gets a new ClassificationDataStream dataset drawn from the startIndex and endIndex values. The startIndex and endIndex values must be valid (i.e. if the current dataset has 1000 samples then you can not have a startIndex or endIndex value that is greater or equal to 1000).

Parameters

startIndex	the index of the first value from the current dataset that you want to start the new subset from
endIndex	the index of the last value from the current dataset that you want to end the new dataset at (inclusive)

Returns

returns a new ClassificationDataStream subset of the current dataset drawn from the startIndex and endIndex values

Definition at line 831 of file ClassificationDataStream.cpp.

TimeSeriesClassificationData ClassificationDataStream::getTimeSeriesClassificationData

(

const bool

includeNullGestures = false

)

const

This function segments the continuous time series data into individual time series and then adds these time series into a new TimeSeriesClassificationData dataset. This new dataset is then returned. By default, the new dataset will not contain any time series with the class label of GRT_DEFAULT_NULL_CLASS_LABEL (as this is assumed to be a NULL gesture) unless you set the includeNullGestures parameter to true.

Returns

returns a new TimeSeriesClassificationData built from the time series data in this dataset.

Definition at line 858 of file ClassificationDataStream.cpp.

MatrixFloat ClassificationDataStream::getTimeSeriesData

(

const TimeSeriesPositionTracker &

trackerInfo

)

const

This function segments a specific time series from the main data set and returns this as a MatrixFloat. You should use one of the TimeSeriesPositionTracker elements from the timeSeriesPositionTracker Vector to indicate to the function which time series you want to retrieve. You can get the TimeSeriesPositionTracker elements using the getTimeSeriesPositionTracker() function.

The MatrixFloat will be empty if the trackerInfo indexs (the startIndex and the endIndex) are not valid.

Returns

returns a new LabelledClassificationData built from the samples in this dataset.

Definition at line 898 of file ClassificationDataStream.cpp.

Vector< TimeSeriesPositionTracker > ClassificationDataStream::getTimeSeriesPositionTracker ( ) const

inline

Gets the timeseries position tracker, a Vector of TimeSeriesPositionTracker which indicate the start and end position of each time series in the dataset.

Returns

a Vector of TimeSeriesPositionTracker, one for each timeseries in the dataset

Definition at line 399 of file ClassificationDataStream.h.

bool ClassificationDataStream::load

(

const std::string &

filename

)

Load the data from a file. If the file format ends in '.csv' then the function will try and load the data from a csv format. If this fails then it will try and load the data as a custom GRT file.

Parameters

filename

the name of the file the data will be loaded from

Returns

true if the data was loaded successfully, false otherwise

Definition at line 492 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::loadDatasetFromCSVFile	(	const std::string &	filename,
		const UINT	classLabelColumnIndex = 0
	)

Loads the labelled timeseries classification data from a CSV file. This assumes the data is formatted with each row representing a sample. The class label should be the first column followed by the sample data as the following N columns, where N is the number of dimensions in the data. If the class label is not the first column, you should set the 2nd argument (UINT classLabelColumnIndex) to the column index that contains the class label.

Parameters

filename	the name of the file the data will be loaded from
classLabelColumnIndex	the index of the column containing the class label. Default value = 0

Returns

true if the data was loaded successfully, false otherwise

Definition at line 743 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::loadDatasetFromFile

(

const std::string &

filename

)

Loads the data from a custom file format.

Parameters

filename

the name of the file the data will be loaded from

Returns

true if the data was loaded successfully, false otherwise

Definition at line 557 of file ClassificationDataStream.cpp.

ClassificationDataStream & ClassificationDataStream::operator=

(

const ClassificationDataStream &

rhs

)

Sets the equals operator, copies the data from the rhs instance to this instance

Parameters

rhs	another instance of the ClassificationDataStream class from which the data will be copied to this instance

Returns

a reference to this instance of ClassificationDataStream

Definition at line 50 of file ClassificationDataStream.cpp.

ClassificationSample& ClassificationDataStream::operator[] ( const UINT  i )

inline

Array Subscript Operator, returns the ClassificationSample at index i. It is up to the user to ensure that i is within the range of [0 totalNumSamples-1]

Parameters

i	the index of the training sample you want to access. Must be within the range of [0 totalNumSamples-1]

Returns

a reference to the i'th ClassificationSample

Definition at line 82 of file ClassificationDataStream.h.

const ClassificationSample& ClassificationDataStream::operator[] ( const UINT  i ) const

inline

Const Array Subscript Operator, returns the ClassificationSample at index i. It is up to the user to ensure that i is within the range of [0 totalNumSamples-1]

Parameters

i	the index of the training sample you want to access. Must be within the range of [0 totalNumSamples-1]

Returns

a reference to the i'th ClassificationSample

Definition at line 93 of file ClassificationDataStream.h.

bool ClassificationDataStream::printStats

(

)

const

Prints the dataset info (such as its name and infoText) and the stats (such as the number of examples, number of dimensions, number of classes, etc.) to the std out.

Returns

returns true if the dataset info and stats were printed successfully, false otherwise

Definition at line 798 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::relabelAllSamplesWithClassLabel	(	const UINT	oldClassLabel,
		const UINT	newClassLabel
	)

Relabels all the samples with the class label A with the new class label B.

Parameters

oldClassLabel	the class label of the samples you want to relabel
newClassLabel	the class label the samples will be relabelled with

Returns

returns true if the samples were correctly relablled, false otherwise

Definition at line 299 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::removeLastSample

(

)

Removes the last training sample added to the dataset.

Returns

true if the last sample was removed, false otherwise

Definition at line 218 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::resetPlaybackIndex

(

const UINT

playbackIndex

)

Sets the playback index to a specific index. The index should be within the range [0 totalNumSamples-1].

Parameters

playbackIndex

the value you want to set the playback index to

Returns

true if the playback index was set correctly, false otherwise

Definition at line 386 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::save

(

const std::string &

filename

)

Saves the data to a file. If the file format ends in '.csv' then the data will be saved as comma-seperated-values, otherwise it will be saved to a custom GRT file (which contains the csv data with an additional header).

Parameters

filename

the name of the file the data will be saved to

Returns

true if the data was saved successfully, false otherwise

Definition at line 481 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::saveDatasetToCSVFile

(

const std::string &

filename

)

Saves the data to a CSV file. This will save the timeseries counter as the first column, the class label as the second column, and the sample data as the following N columns, where N is the number of dimensions in the data. Each row will represent a sample.

Parameters

filename

the name of the file the data will be saved to

Returns

true if the data was saved successfully, false otherwise

Definition at line 720 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::saveDatasetToFile

(

const std::string &

filename

)

Saves the labelled timeseries classification data to a custom file format.

Parameters

filename

the name of the file the data will be saved to

Returns

true if the data was saved successfully, false otherwise

Definition at line 503 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::scale	(	const Float	minTarget,
		const Float	maxTarget
	)

Scales the dataset to the new target range. This function uses the minimum and maximum values of the current dataset as the source range.

Parameters

minTarget	the minimum value of the target range
maxTarget	the maximum value of the target range

Returns

true if the data was scaled correctly, false otherwise

Definition at line 369 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::scale	(	const Vector< MinMax > &	ranges,
		const Float	minTarget,
		const Float	maxTarget
	)

Scales the dataset to the new target range, using the Vector of ranges as the min and max source ranges.

Parameters

ranges	the minimum and maximum values for the source range
minTarget	the minimum value of the target range
maxTarget	the maximum value of the target range

Returns

true if the data was scaled correctly, false otherwise

Definition at line 374 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::setClassNameForCorrespondingClassLabel	(	const std::string	className,
		const UINT	classLabel
	)

Sets the name of the class with the given class label. There should not be any spaces in the className. Will return true if the name is set, or false if the class label does not exist.

Parameters

className	the new class name
classLabel	the class label for the corresponding class name

Returns

returns true if the name is set, or false if the class label does not exist

Definition at line 114 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::setDatasetName

(

const std::string

datasetName

)

Sets the name of the dataset. There should not be any spaces in the name. Will return true if the name is set, or false otherwise.

Parameters

datasetName

the new dataset name

Returns

returns true if the name is set, or false otherwise

Definition at line 97 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::setExternalRanges	(	const Vector< MinMax > &	externalRanges,
		const bool	useExternalRanges = false
	)

Sets the external ranges of the dataset, also sets if the dataset should be scaled using these values. The dimensionality of the externalRanges Vector should match the number of dimensions of this dataset.

Parameters

externalRanges	an N dimensional Vector containing the min and max values of the expected ranges of the dataset.
useExternalRanges	sets if these ranges should be used to scale the dataset, default value is false.

Returns

returns true if the external ranges were set, false otherwise

Definition at line 351 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::setInfoText

(

const std::string

infoText

)

Sets the info std::string. This can be any std::string with information about how the training data was recorded for example.

Parameters

infoText

the infoText

Returns

true if the infoText was correctly updated, false otherwise

Definition at line 109 of file ClassificationDataStream.cpp.

bool ClassificationDataStream::setNumDimensions

(

const UINT

numDimensions

)

Sets the number of dimensions in the training data. This should be an unsigned integer greater than zero. This will clear any previous training data and counters. This function needs to be called before any new samples can be added to the dataset, unless the numDimensions variable was set in the constructor or some data was already loaded from a file

Parameters

numDimensions

the number of dimensions of the training data. Must be an unsigned integer greater than zero

Returns

true if the number of dimensions was correctly updated, false otherwise

Definition at line 81 of file ClassificationDataStream.cpp.

---

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

• ClassificationDataStream.h
• ClassificationDataStream.cpp