Class Example<T extends Output<T>>
- Type Parameters:
T
- The type of output that this example contains.
- All Implemented Interfaces:
Serializable
,Iterable<Feature>
- Direct Known Subclasses:
ArrayExample
,BinaryFeaturesExample
,ListExample
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
Modifier and TypeFieldDescriptionprotected static final int
The default initial size of the metadata map.static final float
The default weight.The example metadata.static final String
By convention the example name is stored using this metadata key.protected final T
The output associated with this example.protected float
The weight associated with this example. -
Constructor Summary
ModifierConstructorDescriptionprotected
Copies the output, weight and metadata into this example.protected
Construct an empty example using the supplied output andDEFAULT_WEIGHT
as the weight.protected
Construct an empty example using the supplied output and weight.protected
Construct an empty example using the supplied output, weight and metadata.protected
Construct an empty example using the supplied output, metadata andDEFAULT_WEIGHT
as the weight. -
Method Summary
Modifier and TypeMethodDescriptionabstract void
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 theFeatureMap
.boolean
containsMetadata
(String key) Test if the metadata contains the supplied key.copy()
Returns a deep copy of this Example.protected abstract void
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.Returns a copy of this example's metadata.getMetadataValue
(String key) Gets the associated metadata value for this key, if it exists.Gets the example'sOutput
.float
Gets the example's weight.abstract boolean
isDense
(FeatureMap fMap) Is this example dense wrt the supplied feature map.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 suppliedMerger
.abstract void
removeFeatures
(List<Feature> featureList) Removes all features in this list from the Example.abstract void
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 suppliedTransformerMap
.abstract boolean
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_SIZEThe default initial size of the metadata map.- See Also:
-
DEFAULT_WEIGHT
public static final float DEFAULT_WEIGHTThe default weight.- See Also:
-
NAME
By convention the example name is stored using this metadata key.Note: not all examples are named.
- See Also:
-
output
The output associated with this example. -
weight
protected float weightThe weight associated with this example. -
metadata
The example metadata.
-
-
Constructor Details
-
Example
Construct an empty example using the supplied output, weight and metadata.- Parameters:
output
- The output.weight
- The weight.metadata
- The metadata.
-
Example
Construct an empty example using the supplied output and weight.- Parameters:
output
- The output.weight
- The weight.
-
Example
Construct an empty example using the supplied output, metadata andDEFAULT_WEIGHT
as the weight.- Parameters:
output
- The output.metadata
- The metadata.
-
Example
Construct an empty example using the supplied output andDEFAULT_WEIGHT
as the weight.- Parameters:
output
- The output.
-
Example
Copies the output, weight and metadata into this example.- Parameters:
other
- The example to copy.
-
-
Method Details
-
getOutput
Gets the example'sOutput
.- 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
Gets the associated metadata value for this key, if it exists. Otherwise returnOptional.empty()
.- Parameters:
key
- The key to check.- Returns:
- The value if present.
-
setMetadataValue
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
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
Returns a copy of this example's metadata.- Returns:
- The metadata.
-
sort
protected abstract void sort()Sorts the example by the string comparator. -
add
Adds a feature. This maintains the sorted invariant and has a lg(example.size()) cost per insertion.- Parameters:
feature
- The feature to add.
-
addAll
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
Removes all features in this list from the Example.- Parameters:
featureList
- Features to remove from this Example.
-
reduceByName
Merges features with the same name using the suppliedMerger
.- 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
Transforms this example by applying the transformations from the suppliedTransformerMap
.Can be overridden for performance reasons.
- Parameters:
transformerMap
- The transformations to apply.
-
isDense
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
Converts all implicit zeros into explicit zeros based on the supplied feature map.- Parameters:
fMap
- The feature map to use for densification.
-
densify
Converts all implicit zeros into explicit zeros based on the supplied feature names.- Parameters:
featureNames
- A *sorted* list of feature names.
-
copy
Returns a deep copy of this Example.- Returns:
- A deep copy of this example.
-
lookup
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
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
Reassigns feature name Strings in the Example to point to those in theFeatureMap
. This significantly reduces memory allocation. It is called when an Example is added to aMutableDataset
, and should not be called outside of that context as it may interact unexpectedly withHashedFeatureMap
.- Parameters:
featureMap
- The feature map containing canonical feature names.
-