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>, ProtoSerializable<org.tribuo.protos.core.ExampleProto>
Direct Known Subclasses:
ArrayExample, BinaryFeaturesExample, ListExample
public abstract class Example<T extends Output<T>> extends Object implements Iterable<Feature>, ProtoSerializable<org.tribuo.protos.core.ExampleProto>, 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). Values with are not Serializable will cause exceptions if the example is serialized. Note protobuf serialization only supports string values, and will coerce all values to strings before serialization. In a future release metadata will only support String values.

See Also:

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

      That is, it inserts a zero valued feature for each feature in the map that is not present in this example.

      Note: this is an optional method, some implementations of Example may throw UnsupportedOperationException or may have additional requirements on the fMap argument and consequently throw IllegalArgumentException if those requirements are not met.

      Parameters:
      fMap - The feature map to use for densification.

    • densify

      protected abstract void densify(List<String> featureNames)
      Adds zero valued features for each feature name in featureNames.

      featureNames must be sorted lexicographically using the String comparator, and behaviour is undefined otherwise.

      Note: this is an optional method, some implementations of Example may throw UnsupportedOperationException or may have additional requirements on the featureNames argument and consequently throw IllegalArgumentException if those requirements are not met.

      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.

    • deserialize

      public static Example<?> deserialize(org.tribuo.protos.core.ExampleProto proto)
      Deserializes an example proto into an example.
      Parameters:
      proto - The proto to deserialize.
      Returns:
      The deserialized example.