edu.udo.cs.yale.example
Interface ExampleSet

All Superinterfaces:

java.lang.Cloneable, IOObject, java.lang.Iterable<Example>, ResultObject

All Known Implementing Classes:

AbstractExampleSet, AttributeWeightedExampleSet, ConditionedExampleSet, ExampleSetAdapter, SimpleExampleSet, SplittedExampleSet

public interface ExampleSet
extends ResultObject, java.lang.Cloneable, java.lang.Iterable<Example>

Interface definition for all example sets. Usually, example sets do not contain any data but are only views on an example table (for example for sampling or feature selection purposes). It should be possible to create a layered view on the data, hence the name multi-layered data view. ExampleSet implementation should support this view concept.

Version:

$Id: ExampleSet.java,v 2.46 2006/09/30 00:05:30 ingomierswa Exp $

Author:

Ingo Mierswa, Simon Fischer

Field Summary

static java.lang.String	ATTRIBUTE_NAME The name of regular attributes.
static java.lang.String	BATCH_NAME The name of the special attribute batch.
static java.lang.String	CLUSTER_NAME The name of the special attribute cluster.
static java.lang.String	CONFIDENCE_NAME The name of the confidence special attributes.
static java.lang.String	ID_NAME The name of the special attribute id.
static java.lang.String[]	KNOWN_ATTRIBUTE_TYPES All known names of regular and special attribute types as an array.
static java.lang.String	LABEL_NAME The name of the special attribute label.
static java.lang.String	PREDICTION_NAME The name of the special attribute prediction.
static int	TYPE_ATTRIBUTE Indicates a regular attribute type.
static int	TYPE_BATCH Indicates the special attribute type batch (example batches).
static int	TYPE_CLUSTER Indicates the special attribute type cluster.
static int	TYPE_ID Indicates the special attribute type id.
static int	TYPE_LABEL Indicates the special attribute type label.
static int	TYPE_PREDICTION Indicates the special attribute type prediction.
static int	TYPE_WEIGHT Indicates the special attribute type weight (example weights).
static java.lang.String	WEIGHT_NAME The name of the special attribute weight (example weights).

Method Summary

void	addAllAttributes(java.util.Collection<Attribute> c) Adds all new attributes in the collection, i.e. all attributes from the given collection which were not already part of this example set.
void	addAttribute(Attribute attribute) Adds a new attribute.
void	clearPredictedLabel() Removes the predicted label.
void	clearUserData() Clears all user data.
void	clearWeight() Removes the weight attribute.
java.lang.Object	clone() Clones the example set.
boolean	contains(Attribute attribute) Returns true if this example set contains the given attribute.
boolean	containsValueType(int valueType) Returns true if this example set contains an attribute with the given value type (see Ontology).
Attribute	createClusterAttribute() Creates a new cluster attribute of appropriate type.
Attribute	createSpecialAttribute(java.lang.String name, int valueType) Creates a new (single) special attribute with given name and value type.
Attribute	createWeightAttribute() Creates a new weight attribute.
boolean	equals(java.lang.Object o) True if all attributes are equal.
Attribute	getAttribute(int index) Returns the Attribute with the given index.
Attribute	getAttribute(java.lang.String name) Returns the attribute with the given name.
int	getBlockEndIndex(int startindex) Returns the last attribute index belonging to the block starting at startindex.
Attribute	getCluster() Returns the cluster attribute.
Example	getExample(int index) Returns the i-th example.
Example	getExampleFromId(double value) Returns the example with the given id value.
ExampleReader	getExampleReader() Deprecated. Please use Iterable.iterator() instead
ExampleTable	getExampleTable() Returns the underlying example table.
Attribute	getId() Returns the ID attribute, i.e. an attribute containing a unique integer for each example.
Attribute	getLabel() Returns the label attribute used for classification and regression.
int	getNumberOfAttributes() Returns the number of attributes of the examples in this set.
Attribute	getPredictedLabel() Returns the label predicted by some model.
int	getSize() Deprecated. Please use the method size() instead
Attribute	getSpecialAttribute(java.lang.String name) Returns the special attribute with the given name or null if no special attribute with this name exists.
java.util.Collection<java.lang.String>	getSpecialAttributeNames() Returns a collection of all keys of special attributes.
java.util.Map<java.lang.String,Attribute>	getSpecialAttributes() Returns a map of all special attribute names to the corresponding attributes.
java.lang.Object	getUserData(java.lang.String key) Returns the user data set by setUserData()
java.util.Set<java.lang.String>	getUserDataKeys() Returns all askable keys of user data.
Attribute	getWeight() Returns the weight attribute.
void	recalculateAllAttributeStatistics() Recalculate all attribute statistics.
void	recalculateAttributeStatistics(Attribute attribute) Recalculate the attribute statistics of the given attribute.
void	remapAllIds() Remaps all ids.
void	removeAllAttributes() Removes all attributes.
void	removeAttribute(Attribute attribute) Removes an attribute.
Attribute	removeAttribute(int index) Removes the attribute with the given index.
Attribute	replaceAttribute(Attribute first, Attribute second) Replaces the first attribute by the second.
void	setAttributes(ExampleSet exampleSet) Copies thie list of attributes from the given example set.
void	setCluster(Attribute cluster) Sets the cluster attribute.
void	setId(Attribute idAttribute) Sets the ID attribute.
void	setLabel(Attribute label) Sets the label attribute used for classification and regression.
void	setPredictedLabel(Attribute predictedLabel) Sets the predicted label.
void	setSpecialAttribute(java.lang.String name, Attribute attribute) Adds a special, i.e. named Attribute to the example set.
void	setUserData(java.lang.String key, java.lang.Object data) Sets arbitrary user data, e.g. to cache certain performance values etc.
void	setWeight(Attribute weight) Seturns the weight attribute.
int	size() Returns the number of examples in this example set.
void	writeAttributeFile(java.io.File attFile, java.io.File dataFile) Writes the attribute meta descriptions into a file.
void	writeDataFile(java.io.File dataFile) Writes the data and the attribute description to a file.
void	writeSparseAttributeFile(java.io.File attFile, java.io.File dataFile, int format) Writes the attribute meta descriptions for a sparse data file into a file.
void	writeSparseDataFile(java.io.File dataFile, int format) Writes the data and the attribute description to a sparse data file.

Methods inherited from interface edu.udo.cs.yale.operator.ResultObject

getActions, getName, getVisualisationComponent, toResultString

Methods inherited from interface edu.udo.cs.yale.operator.IOObject

copy, write, write

Methods inherited from interface java.lang.Iterable

iterator

Field Detail

ATTRIBUTE_NAME

static final java.lang.String ATTRIBUTE_NAME

The name of regular attributes.

See Also:

Constant Field Values

ID_NAME

static final java.lang.String ID_NAME

The name of the special attribute id.

See Also:

Constant Field Values

LABEL_NAME

static final java.lang.String LABEL_NAME

The name of the special attribute label.

See Also:

Constant Field Values

PREDICTION_NAME

static final java.lang.String PREDICTION_NAME

The name of the special attribute prediction.

See Also:

Constant Field Values

CLUSTER_NAME

static final java.lang.String CLUSTER_NAME

The name of the special attribute cluster.

See Also:

Constant Field Values

WEIGHT_NAME

static final java.lang.String WEIGHT_NAME

The name of the special attribute weight (example weights).

See Also:

Constant Field Values

BATCH_NAME

static final java.lang.String BATCH_NAME

The name of the special attribute batch.

See Also:

Constant Field Values

CONFIDENCE_NAME

static final java.lang.String CONFIDENCE_NAME

The name of the confidence special attributes.

See Also:

Constant Field Values

KNOWN_ATTRIBUTE_TYPES

static final java.lang.String[] KNOWN_ATTRIBUTE_TYPES

All known names of regular and special attribute types as an array.

TYPE_ATTRIBUTE

static final int TYPE_ATTRIBUTE

Indicates a regular attribute type.

See Also:

Constant Field Values

TYPE_LABEL

static final int TYPE_LABEL

Indicates the special attribute type label.

See Also:

Constant Field Values

TYPE_ID

static final int TYPE_ID

Indicates the special attribute type id.

See Also:

Constant Field Values

TYPE_WEIGHT

static final int TYPE_WEIGHT

Indicates the special attribute type weight (example weights).

See Also:

Constant Field Values

TYPE_BATCH

static final int TYPE_BATCH

Indicates the special attribute type batch (example batches).

See Also:

Constant Field Values

TYPE_CLUSTER

static final int TYPE_CLUSTER

Indicates the special attribute type cluster.

See Also:

Constant Field Values

TYPE_PREDICTION

static final int TYPE_PREDICTION

Indicates the special attribute type prediction.

See Also:

Constant Field Values

Method Detail

getNumberOfAttributes

int getNumberOfAttributes()

Returns the number of attributes of the examples in this set.

getAttribute

Attribute getAttribute(int index)

Returns the Attribute with the given index.

getAttribute

Attribute getAttribute(java.lang.String name)

Returns the attribute with the given name. This can be a regular attribute or a special attribute.

contains

boolean contains(Attribute attribute)

Returns true if this example set contains the given attribute.

containsValueType

boolean containsValueType(int valueType)

Returns true if this example set contains an attribute with the given value type (see Ontology).

addAttribute

void addAttribute(Attribute attribute)

Adds a new attribute.

Throws:

java.lang.RuntimeException - Iff the ExampleSet already contains the attribute.

addAllAttributes

void addAllAttributes(java.util.Collection<Attribute> c)

Adds all new attributes in the collection, i.e. all attributes from the given collection which were not already part of this example set. Please note that a check will be performed if the attributes were already part of this example set. This of course can drastically reduce runtime. If you want to just add all given attributes without this check you should add each attribue on its own.

setAttributes

void setAttributes(ExampleSet exampleSet)

Copies thie list of attributes from the given example set.

replaceAttribute

Attribute replaceAttribute(Attribute first,
                           Attribute second)

Replaces the first attribute by the second. The second attribute is returned after replacement.

removeAttribute

void removeAttribute(Attribute attribute)

Removes an attribute.

Throws:

java.util.NoSuchElementException - If the attribute does not exist.

removeAttribute

Attribute removeAttribute(int index)

Removes the attribute with the given index.

Returns:

The removed attribute

removeAllAttributes

void removeAllAttributes()

Removes all attributes.

setSpecialAttribute

void setSpecialAttribute(java.lang.String name,
                         Attribute attribute)

Adds a special, i.e. named Attribute to the example set. Special attributes are labels, weights, etc., i.e. all non-regular attributes. If the attribute is already defined, it is replaced. By convention, special attributes are named lowercase. Special attributes are also delivered by getAttribute(String name).

getSpecialAttribute

Attribute getSpecialAttribute(java.lang.String name)

Returns the special attribute with the given name or null if no special attribute with this name exists.

getSpecialAttributeNames

java.util.Collection<java.lang.String> getSpecialAttributeNames()

Returns a collection of all keys of special attributes.

getSpecialAttributes

java.util.Map<java.lang.String,Attribute> getSpecialAttributes()

Returns a map of all special attribute names to the corresponding attributes.

getLabel

Attribute getLabel()

Returns the label attribute used for classification and regression.

setLabel

void setLabel(Attribute label)

Sets the label attribute used for classification and regression.

getWeight

Attribute getWeight()

Returns the weight attribute.

setWeight

void setWeight(Attribute weight)

Seturns the weight attribute.

createWeightAttribute

Attribute createWeightAttribute()

Creates a new weight attribute. If the example set already has a weight attribute, it is overwritten.

getPredictedLabel

Attribute getPredictedLabel()

Returns the label predicted by some model.

setPredictedLabel

void setPredictedLabel(Attribute predictedLabel)

Sets the predicted label.

clearPredictedLabel

void clearPredictedLabel()

Removes the predicted label.

clearWeight

void clearWeight()

Removes the weight attribute.

getCluster

Attribute getCluster()

Returns the cluster attribute.

setCluster

void setCluster(Attribute cluster)

Sets the cluster attribute.

createClusterAttribute

Attribute createClusterAttribute()
                                 throws OperatorException

Creates a new cluster attribute of appropriate type. If the example set already has a cluster attribute, it is overwritten.

Throws:

OperatorException

createSpecialAttribute

Attribute createSpecialAttribute(java.lang.String name,
                                 int valueType)
                                 throws OperatorException

Creates a new (single) special attribute with given name and value type. If the example set already has a special attribute with this name, it is overwritten.

Throws:

OperatorException

getId

Attribute getId()

Returns the ID attribute, i.e. an attribute containing a unique integer for each example. May be null.

setId

void setId(Attribute idAttribute)

Sets the ID attribute.

getSize

@Deprecated
int getSize()

Deprecated. Please use the method size() instead

Returns the number of examples in this example set. This number should not be used to create for-loops to iterate through all examples. TODO: remove

size

int size()

Returns the number of examples in this example set. This number should not be used to create for-loops to iterate through all examples.

getExampleReader

@Deprecated
ExampleReader getExampleReader()

Deprecated. Please use Iterable.iterator() instead

Returns a reader that can be used to iterate over all examples of this set. This method should be used for all scans through the data. It is not guaranteed that asking for an example by using the index in the example table is efficiently implemented. Therefore for-loops for iterations are not an option.

getExampleTable

ExampleTable getExampleTable()

Returns the underlying example table. Most operators should operate on the example set and manipulate example to change table data instead of using the table directly.

getExampleFromId

Example getExampleFromId(double value)

Returns the example with the given id value. If the example set does not contain an id attribute this method should return null.

getExample

Example getExample(int index)

Returns the i-th example. It is not guaranteed that asking for an example by using the index in the example table is efficiently implemented. Therefore for-loops for iterations are not an option and an ExampleReader should be used.

remapAllIds

void remapAllIds()

Remaps all ids. This method should be invoked after Id tagging or example set loading.

writeDataFile

void writeDataFile(java.io.File dataFile)
                   throws java.io.IOException

Writes the data and the attribute description to a file.

Throws:

java.io.IOException

writeAttributeFile

void writeAttributeFile(java.io.File attFile,
                        java.io.File dataFile)
                        throws java.io.IOException

Writes the attribute meta descriptions into a file. The data file is used in order to determine the relative file positions and is not allowed to be null.

Throws:

java.io.IOException

writeSparseDataFile

void writeSparseDataFile(java.io.File dataFile,
                         int format)
                         throws java.io.IOException

Writes the data and the attribute description to a sparse data file.

Parameters:

format - specified by SparseFormatExampleSource

Throws:

java.io.IOException

writeSparseAttributeFile

void writeSparseAttributeFile(java.io.File attFile,
                              java.io.File dataFile,
                              int format)
                              throws java.io.IOException

Writes the attribute meta descriptions for a sparse data file into a file. The data file is used in order to determine the relative file positions and is not allowed to be null.

Parameters:

format - specified by SparseFormatExampleSource

Throws:

java.io.IOException

setUserData

void setUserData(java.lang.String key,
                 java.lang.Object data)

Sets arbitrary user data, e.g. to cache certain performance values etc. Make sure to use a unique prefix for your keys.

getUserData

java.lang.Object getUserData(java.lang.String key)

Returns the user data set by setUserData()

See Also:

setUserData(String,Object)

getUserDataKeys

java.util.Set<java.lang.String> getUserDataKeys()

Returns all askable keys of user data.

clearUserData

void clearUserData()

Clears all user data. This method must be called whenever attributes are added or removed or the example set changes in a way that makes a new calculation of such values necessary.

getBlockEndIndex

int getBlockEndIndex(int startindex)

Returns the last attribute index belonging to the block starting at startindex.

clone

java.lang.Object clone()

Clones the example set.

equals

boolean equals(java.lang.Object o)

True if all attributes are equal.

Overrides:

equals in class java.lang.Object

recalculateAllAttributeStatistics

void recalculateAllAttributeStatistics()

Recalculate all attribute statistics.

recalculateAttributeStatistics

void recalculateAttributeStatistics(Attribute attribute)

Recalculate the attribute statistics of the given attribute.