Example (Tribuo 4.1.1 API)

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 and Description
`protected static int`	`DEFAULT_METADATA_SIZE` The default initial size of the metadata map.
`static float`	`DEFAULT_WEIGHT` The default weight.
`protected Map<String,Object>`	`metadata` The example metadata.
`static String`	`NAME` By convention the example name is stored using this metadata key.
`protected T`	`output` The output associated with this example.
`protected float`	`weight` The weight associated with this example.

Constructor Summary

Constructors
Modifier	Constructor and 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

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and 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.
`void`	`densify(FeatureMap fMap)` Converts all implicit zeros into explicit zeros based on the supplied feature map.
`protected abstract void`	`densify(List<String> featureNames)` Converts all implicit zeros into explicit zeros based on the supplied feature names.
`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.
`abstract boolean`	`isDense(FeatureMap fMap)` Is this example dense wrt the supplied feature map.
`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 Detail
  - 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 Detail
  - 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 Detail
  - 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.
  - isDense
```
public abstract boolean isDense(FeatureMap fMap)
```
    Is this example dense wrt the supplied feature map.
    An example is "dense" if it contains all the features in the map, and only those features.
    
    Parameters:
    
    fMap - The feature map to check against.
    
    Returns:
    
    True if this example contains only the features in the map, and all the features in the map.
  - densify
```
public 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.

Class Example<T extends Output<T>>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

DEFAULT_METADATA_SIZE

DEFAULT_WEIGHT

NAME

output

weight

metadata

Constructor Detail

Example

Example

Example

Example

Example

Method Detail

getOutput

getWeight

setWeight

getMetadataValue

setMetadataValue

containsMetadata

getMetadata

sort

add

addAll

size

removeFeatures

reduceByName

validateExample

transform

isDense

densify

densify

copy

lookup

set

canonicalize