Class Example<T extends Output<T>>

java.lang.Object

org.tribuo.Example<T>

Type Parameters:

T - The type of output that this example contains.

All Implemented Interfaces:

Serializable, Iterable<Feature>

Direct Known Subclasses:

ArrayExample, BinaryFeaturesExample, ListExample

public abstract class Example<T extends Output<T>>
extends Object
implements Iterable<Feature>, Serializable

An example used for training and evaluation. Examples have a true output associated with them or an instance from OutputFactory.getUnknownOutput() and a list of features that can be used for prediction.

An example is a sorted set of features, sorted by the String comparator on the feature name.

Examples have metadata associated with them, stored as a map from a String key, to an Object value. This metadata is append only for any given example, and the metadata values should be immutable (as they will be referenced rather than copied when an example is copied).

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected static final int	DEFAULT_METADATA_SIZE	The default initial size of the metadata map.
static final float	DEFAULT_WEIGHT	The default weight.
protected Map<String,Object>	metadata	The example metadata.
static final String	NAME	By convention the example name is stored using this metadata key.
protected final T	output	The output associated with this example.
protected float	weight	The weight associated with this example.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Example(Example<T> other)	Copies the output, weight and metadata into this example.
protected	Example(T output)	Construct an empty example using the supplied output and DEFAULT_WEIGHT as the weight.
protected	Example(T output, float weight)	Construct an empty example using the supplied output and weight.
protected	Example(T output, float weight, Map<String,Object> metadata)	Construct an empty example using the supplied output, weight and metadata.
protected	Example(T output, Map<String,Object> metadata)	Construct an empty example using the supplied output, metadata and DEFAULT_WEIGHT as the weight.

Method Summary

Modifier and Type	Method	Description
abstract void	add(Feature feature)	Adds a feature.
abstract void	addAll(Collection<? extends Feature> features)	Adds a collection of features.
abstract void	canonicalize(FeatureMap featureMap)	Reassigns feature name Strings in the Example to point to those in the FeatureMap.
boolean	containsMetadata(String key)	Test if the metadata contains the supplied key.
abstract Example<T>	copy()	Returns a deep copy of this Example.
protected abstract void	densify(List<String> featureNames)	Converts all implicit zeros into explicit zeros based on the supplied feature names.
protected void	densify(FeatureMap fMap)	Converts all implicit zeros into explicit zeros based on the supplied feature map.
Map<String,Object>	getMetadata()	Returns a copy of this example's metadata.
Optional<Object>	getMetadataValue(String key)	Gets the associated metadata value for this key, if it exists.
T	getOutput()	Gets the example's Output.
float	getWeight()	Gets the example's weight.
Feature	lookup(String i)	Returns the Feature in this Example which has the supplied name, if it's present.
abstract void	reduceByName(Merger merger)	Merges features with the same name using the supplied Merger.
abstract void	removeFeatures(List<Feature> featureList)	Removes all features in this list from the Example.
abstract void	set(Feature feature)	Overwrites the feature with the matching name.
void	setMetadataValue(String key, Object value)	Puts the specified key, value pair into the metadata.
void	setWeight(float weight)	Sets the example's weight.
abstract int	size()	Return how many features are in this example.
protected abstract void	sort()	Sorts the example by the string comparator.
void	transform(TransformerMap transformerMap)	Transforms this example by applying the transformations from the supplied TransformerMap.
abstract boolean	validateExample()	Checks the example to see if all the feature names are unique, the feature values are not NaN, and there is at least one feature.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Field Details

DEFAULT_METADATA_SIZE

protected static final int DEFAULT_METADATA_SIZE

The default initial size of the metadata map.

See Also:

• Constant Field Values

DEFAULT_WEIGHT

public static final float DEFAULT_WEIGHT

The default weight.

See Also:

• Constant Field Values

NAME

public static final String NAME

By convention the example name is stored using this metadata key.

Note: not all examples are named.

See Also:

• Constant Field Values

output

protected final T extends Output<T> output

The output associated with this example.

weight

protected float weight

The weight associated with this example.

metadata

protected Map<String,Object> metadata

The example metadata.

Constructor Details

Example

protected Example(T output,
 float weight,
 Map<String,Object> metadata)

Construct an empty example using the supplied output, weight and metadata.

Parameters:

output - The output.

weight - The weight.

metadata - The metadata.

Example

protected Example(T output,
 float weight)

Construct an empty example using the supplied output and weight.

Parameters:

output - The output.

weight - The weight.

Example

protected Example(T output,
 Map<String,Object> metadata)

Construct an empty example using the supplied output, metadata and DEFAULT_WEIGHT as the weight.

Parameters:

output - The output.

metadata - The metadata.

Example

protected Example(T output)

Construct an empty example using the supplied output and DEFAULT_WEIGHT as the weight.

Parameters:

output - The output.

Example

protected Example(Example<T> other)

Copies the output, weight and metadata into this example.

Parameters:

other - The example to copy.

Method Details

getOutput

public T getOutput()

Gets the example's Output.

Returns:

The example's output.

getWeight

public float getWeight()

Gets the example's weight.

Returns:

The example's weight.

setWeight

public void setWeight(float weight)

Sets the example's weight.

Parameters:

weight - The new weight.

getMetadataValue

public Optional<Object> getMetadataValue(String key)

Gets the associated metadata value for this key, if it exists. Otherwise return Optional.empty().

Parameters:

key - The key to check.

Returns:

The value if present.

setMetadataValue

public void setMetadataValue(String key,
 Object value)

Puts the specified key, value pair into the metadata.

Example metadata is append only, and so this method throws IllegalArgumentException if the key is already present.

Parameters:

key - The key.

value - The value.

containsMetadata

public boolean containsMetadata(String key)

Test if the metadata contains the supplied key.

Parameters:

key - The key to test.

Returns:

True if the metadata contains a value for the supplied key.

getMetadata

public Map<String,Object> getMetadata()

Returns a copy of this example's metadata.

Returns:

The metadata.

sort

protected abstract void sort()

Sorts the example by the string comparator.

add

public abstract void add(Feature feature)

Adds a feature. This maintains the sorted invariant and has a lg(example.size()) cost per insertion.

Parameters:

feature - The feature to add.

addAll

public abstract void addAll(Collection<? extends Feature> features)

Adds a collection of features. This maintains the sorted invariant but is more efficient than adding one at a time due to allocation.

Parameters:

features - The features to add.

size

public abstract int size()

Return how many features are in this example.

Returns:

The number of features.

removeFeatures

public abstract void removeFeatures(List<Feature> featureList)

Removes all features in this list from the Example.

Parameters:

featureList - Features to remove from this Example.

reduceByName

public abstract void reduceByName(Merger merger)

Merges features with the same name using the supplied Merger.

Parameters:

merger - A function to merge two doubles.

validateExample

public abstract boolean validateExample()

Checks the example to see if all the feature names are unique, the feature values are not NaN, and there is at least one feature.

Returns:

true if the example is valid.

transform

public void transform(TransformerMap transformerMap)

Transforms this example by applying the transformations from the supplied TransformerMap.

Can be overridden for performance reasons.

Parameters:

transformerMap - The transformations to apply.

densify

protected void densify(FeatureMap fMap)

Converts all implicit zeros into explicit zeros based on the supplied feature map.

Parameters:

fMap - The feature map to use for densification.

densify

protected abstract void densify(List<String> featureNames)

Converts all implicit zeros into explicit zeros based on the supplied feature names.

Parameters:

featureNames - A *sorted* list of feature names.

copy

public abstract Example<T> copy()

Returns a deep copy of this Example.

Returns:

A deep copy of this example.

lookup

public Feature lookup(String i)

Returns the Feature in this Example which has the supplied name, if it's present.

Parameters:

i - The feature name to lookup.

Returns:

The feature object.

set

public abstract void set(Feature feature)

Overwrites the feature with the matching name.

Throws IllegalArgumentException if there isn't a feature with that name in this example.

Parameters:

feature - The new feature value.

canonicalize

public abstract void canonicalize(FeatureMap featureMap)

Reassigns feature name Strings in the Example to point to those in the FeatureMap. This significantly reduces memory allocation. It is called when an Example is added to a MutableDataset, and should not be called outside of that context as it may interact unexpectedly with HashedFeatureMap.

Parameters:

featureMap - The feature map containing canonical feature names.