Package org.tribuo.impl

Class BinaryFeaturesExample<T extends Output<T>>

java.lang.Object
org.tribuo.Example<T>
org.tribuo.impl.BinaryFeaturesExample<T>
Type Parameters:
T - The output type.
All Implemented Interfaces:
Serializable, Iterable<Feature>, ProtoSerializable<org.tribuo.protos.core.ExampleProto>
public final class BinaryFeaturesExample<T extends Output<T>> extends Example<T>
An Example backed by a single array of feature names. This implementation is modeled after ArrayExample but does not store feature values because it assumes only binary features - i.e., features with a feature value of 1.0. The following methods throw an UnsupportedOperationException:
See Also:

  • Field Details

    • CURRENT_VERSION

      public static final int CURRENT_VERSION
      Protobuf serialization version.
      See Also:

    • DEFAULT_SIZE

      public static final int DEFAULT_SIZE
      Default initial size of the backing arrays.
      See Also:

    • featureNames

      protected String[] featureNames
      Feature names array.

    • size

      protected int size
      Number of valid features in this example.

  • Constructor Details

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, float weight, int initialSize)
      Constructs an example from an output and a weight, with an initial size for the feature arrays.
      Parameters:
      output - The output.
      weight - The weight.
      initialSize - The initial size of the feature arrays.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, float weight, Map<String,Object> metadata)
      Constructs an example from an output, a weight and the metadata.
      Parameters:
      output - The output.
      weight - The weight.
      metadata - The metadata.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, float weight)
      Constructs an example from an output and a weight.
      Parameters:
      output - The output.
      weight - The example weight.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, Map<String,Object> metadata)
      Constructs an example from an output and the metadata.
      Parameters:
      output - The output.
      metadata - The metadata.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output)
      Constructs an example from an output.
      Parameters:
      output - The output.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, String[] names)
      Constructs an example from an output and an array of names. This is currently the most efficient constructor.
      Parameters:
      output - The output.
      names - The feature names.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, List<? extends Feature> features)
      Constructs an example from an output and a list of features. This constructor will throw an IllegalArgumentException if any of the features have a feature value that does not equal 1.0.
      Parameters:
      output - The output (e.g., label) of the example
      features - The list of features.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(Example<T> other)
      Copy constructor. This constructor will throw an IllegalArgumentException if any of the features have a feature value that does not equal 1.0.
      Parameters:
      other - The example to copy.

    • BinaryFeaturesExample

      public BinaryFeaturesExample(T output, Example<U> other, float weight)
      Clones an example's features, but uses the supplied output and weight.
      Type Parameters:
      U - The output type of the other example.
      Parameters:
      output - The output to use.
      other - The features to use.
      weight - The weight to use.

  • Method Details

    • deserializeFromProto

      public static BinaryFeaturesExample<?> deserializeFromProto(int version, String className, com.google.protobuf.Any message) throws com.google.protobuf.InvalidProtocolBufferException
      Deserialization factory.
      Parameters:
      version - The serialized object version.
      className - The class name.
      message - The serialized data.
      Returns:
      The deserialized object.
      Throws:
      com.google.protobuf.InvalidProtocolBufferException - If the protobuf could not be parsed from the message.

    • add

      public void add(String name)
      Adds a single feature with a value of 1.
      Parameters:
      name - The name of the feature.

    • isBinary

      public static boolean isBinary(Feature feature)
      Is the supplied feature binary (i.e., does it have a value of 1.0)?
      Parameters:
      feature - The feature to check.
      Returns:
      True if it's a binary feature.

    • checkIsBinary

      public static void checkIsBinary(Feature feature)
      Checks if the supplied feature is binary, if not throw an IllegalArgumentException.
      Parameters:
      feature - The feature to check.

    • add

      public void add(Feature feature)
      Adds a feature to this example. This method will throw an IllegalArgumentException if any of the features have a feature value that does not equal 1.0.
      Specified by:
      add in class Example<T extends Output<T>>
      Parameters:
      feature - The feature to add to this example.

    • addAll

      public void addAll(Collection<? extends Feature> features)
      Adds a collection of features to this example. This method will throw an IllegalArgumentException if any of the features have a feature value that does not equal 1.0.
      Specified by:
      addAll in class Example<T extends Output<T>>
      Parameters:
      features - The features to add to this example.

    • growArray

      protected void growArray(int minCapacity)
      Grows the backing arrays storing the names.
      Parameters:
      minCapacity - The new minimum capacity required.

    • growArray

      protected void growArray()
      Grows the backing arrays by size+1.

    • newCapacity

      protected int newCapacity(int minCapacity)
      Returns a capacity at least as large as the given minimum capacity. Returns the current capacity increased by 50% if that suffices. Will not return a capacity greater than MAX_ARRAY_SIZE unless the given minimum capacity is greater than MAX_ARRAY_SIZE.
      Parameters:
      minCapacity - the desired minimum capacity
      Returns:
      The new capacity.
      Throws:
      OutOfMemoryError - if minCapacity is less than zero

    • sort

      protected void sort()
      Sorts the feature list to maintain the lexicographic order invariant.
      Specified by:
      sort in class Example<T extends Output<T>>

    • size

      public int size()
      Description copied from class: Example
      Return how many features are in this example.
      Specified by:
      size in class Example<T extends Output<T>>
      Returns:
      The number of features.

    • removeFeatures

      public void removeFeatures(List<Feature> featureList)
      Description copied from class: Example
      Removes all features in this list from the Example.
      Specified by:
      removeFeatures in class Example<T extends Output<T>>
      Parameters:
      featureList - Features to remove from this Example.

    • validateExample

      public boolean validateExample()
      Description copied from class: Example
      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.
      Specified by:
      validateExample in class Example<T extends Output<T>>
      Returns:
      true if the example is valid.

    • copy

      public BinaryFeaturesExample<T> copy()
      Description copied from class: Example
      Returns a deep copy of this Example.
      Specified by:
      copy in class Example<T extends Output<T>>
      Returns:
      A deep copy of this example.

    • lookup

      public Feature lookup(String i)
      Description copied from class: Example
      Returns the Feature in this Example which has the supplied name, if it's present.
      Overrides:
      lookup in class Example<T extends Output<T>>
      Parameters:
      i - The feature name to lookup.
      Returns:
      The feature object.

    • set

      public void set(Feature feature)
      Description copied from class: Example
      Overwrites the feature with the matching name.

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

      Specified by:
      set in class Example<T extends Output<T>>
      Parameters:
      feature - The new feature value.

    • transform

      public void transform(TransformerMap transformerMap)
      Description copied from class: Example
      Transforms this example by applying the transformations from the supplied TransformerMap.

      Can be overridden for performance reasons.

      Overrides:
      transform in class Example<T extends Output<T>>
      Parameters:
      transformerMap - The transformations to apply.

    • reduceByName

      public void reduceByName(Merger merger)
      Description copied from class: Example
      Merges features with the same name using the supplied Merger.
      Specified by:
      reduceByName in class Example<T extends Output<T>>
      Parameters:
      merger - this parameter is ignored because we do not store feature values in this class. So, the 'merging' can be thought of as a logical AND.

    • isDense

      public boolean isDense(FeatureMap fMap)
      Description copied from class: Example
      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.

      Specified by:
      isDense in class Example<T extends Output<T>>
      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

      protected void densify(List<String> featureList)
      Description copied from class: Example
      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.

      Specified by:
      densify in class Example<T extends Output<T>>
      Parameters:
      featureList - A *sorted* list of feature names.

    • densify

      public void densify(FeatureMap fMap)
      Description copied from class: Example
      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.

      Overrides:
      densify in class Example<T extends Output<T>>
      Parameters:
      fMap - The feature map to use for densification.

    • iterator

      public Iterator<Feature> iterator()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • serialize

      public org.tribuo.protos.core.ExampleProto serialize()
      Description copied from interface: ProtoSerializable
      Serializes this object to a protobuf.
      Returns:
      The protobuf.

    • canonicalize

      public void canonicalize(FeatureMap featureMap)
      Description copied from class: Example
      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.
      Specified by:
      canonicalize in class Example<T extends Output<T>>
      Parameters:
      featureMap - The feature map containing canonical feature names.