Package org.tribuo

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:

  • 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.
    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.
    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 Details

    • DEFAULT_METADATA_SIZE

      protected static final int DEFAULT_METADATA_SIZE
      The default initial size of the metadata map.
      See Also:

    • DEFAULT_WEIGHT

      public static final float DEFAULT_WEIGHT
      The default weight.
      See Also:

    • 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:

    • 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.

    • 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.