org.tribuo.interop

Class ExternalModel<T extends Output<T>,U,V>

java.lang.Object

org.tribuo.Model<T>

org.tribuo.interop.ExternalModel<T,U,V>

Type Parameters:

T - The output subclass that this model operates on.

U - The internal representation of features.

V - The internal representation of outputs.

All Implemented Interfaces:

com.oracle.labs.mlrg.olcut.provenance.Provenancable<ModelProvenance>, Serializable

Direct Known Subclasses:

ONNXExternalModel, TensorflowExternalModel, XGBoostExternalModel

public abstract class ExternalModel<T extends Output<T>,U,V>
extends Model<T>

This is the base class for third party models which are trained externally and loaded into Tribuo for prediction.

Batch size defaults to DEFAULT_BATCH_SIZE

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BATCH_SIZE Default batch size for external model batch predictions.
protected int[]	featureBackwardMapping
protected int[]	featureForwardMapping

Fields inherited from class org.tribuo.Model

ALL_OUTPUTS, BIAS_FEATURE, featureIDMap, generatesProbabilities, name, outputIDInfo, provenance, provenanceOutput

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ExternalModel(String name, ModelProvenance provenance, ImmutableFeatureMap featureIDMap, ImmutableOutputInfo<T> outputIDInfo, boolean generatesProbabilities, Map<String,Integer> featureMapping)
protected	ExternalModel(String name, ModelProvenance provenance, ImmutableFeatureMap featureIDMap, ImmutableOutputInfo<T> outputIDInfo, int[] featureForwardMapping, int[] featureBackwardMapping, boolean generatesProbabilities)

Method Summary

Modifier and Type	Method and Description
protected abstract U	convertFeatures(SparseVector input) Converts from a SparseVector using the external model's indices into the ingestion format for the external model.
protected abstract U	convertFeaturesList(List<SparseVector> input) Converts from a list of SparseVector using the external model's indices into the ingestion format for the external model.
protected abstract List<Prediction<T>>	convertOutput(V output, int[] numValidFeatures, List<Example<T>> examples) Converts the output of the external model into a list of Predictions.
protected abstract Prediction<T>	convertOutput(V output, int numValidFeatures, Example<T> example) Converts the output of the external model into a Prediction.
protected static ImmutableFeatureMap	createFeatureMap(Set<String> featureNames) Creates an immutable feature map from a set of feature names.
protected static <T extends Output<T>> ImmutableOutputInfo<T>	createOutputInfo(OutputFactory<T> factory, Map<T,Integer> outputs) Creates an output info from a set of outputs.
protected abstract V	externalPrediction(U input) Runs the external model's prediction function.
int	getBatchSize() Gets the current testing batch size.
Optional<Excuse<T>>	getExcuse(Example<T> example) By default third party models don't return excuses.
protected List<Prediction<T>>	innerPredict(Iterable<Example<T>> examples) Called by the base implementations of Model.predict(Iterable) and Model.predict(Dataset).
Prediction<T>	predict(Example<T> example) Uses the model to predict the output for a single example.
void	setBatchSize(int batchSize) Sets a new batch size.

Methods inherited from class org.tribuo.Model

copy, copy, generatesProbabilities, getExcuses, getFeatureIDMap, getName, getOutputIDInfo, getProvenance, getTopFeatures, predict, predict, setName, toString, validate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_BATCH_SIZE

public static final int DEFAULT_BATCH_SIZE

Default batch size for external model batch predictions.

See Also:

Constant Field Values

featureForwardMapping

protected final int[] featureForwardMapping

featureBackwardMapping

protected final int[] featureBackwardMapping

Constructor Detail

ExternalModel

protected ExternalModel(String name,
                        ModelProvenance provenance,
                        ImmutableFeatureMap featureIDMap,
                        ImmutableOutputInfo<T> outputIDInfo,
                        boolean generatesProbabilities,
                        Map<String,Integer> featureMapping)

ExternalModel

protected ExternalModel(String name,
                        ModelProvenance provenance,
                        ImmutableFeatureMap featureIDMap,
                        ImmutableOutputInfo<T> outputIDInfo,
                        int[] featureForwardMapping,
                        int[] featureBackwardMapping,
                        boolean generatesProbabilities)

Method Detail

predict

public Prediction<T> predict(Example<T> example)

Description copied from class: Model

Uses the model to predict the output for a single example.

predict does not mutate the example.

Throws IllegalArgumentException if the example has no features or no feature overlap with the model.

Specified by:

predict in class Model<T extends Output<T>>

Parameters:

example - the example to predict.

Returns:

the result of the prediction.

innerPredict

protected List<Prediction<T>> innerPredict(Iterable<Example<T>> examples)

Description copied from class: Model

Called by the base implementations of Model.predict(Iterable) and Model.predict(Dataset).

Overrides:

innerPredict in class Model<T extends Output<T>>

Parameters:

examples - The examples to predict.

Returns:

The results of the predictions, in the same order as the examples.

convertFeatures

protected abstract U convertFeatures(SparseVector input)

Converts from a SparseVector using the external model's indices into the ingestion format for the external model.

Parameters:

input - The features using external indices.

Returns:

The ingestion format for the external model.

convertFeaturesList

protected abstract U convertFeaturesList(List<SparseVector> input)

Converts from a list of SparseVector using the external model's indices into the ingestion format for the external model.

Parameters:

input - The features using external indices.

Returns:

The ingestion format for the external model.

externalPrediction

protected abstract V externalPrediction(U input)

Runs the external model's prediction function.

Parameters:

input - The input in the external model's format.

Returns:

The output in the external model's format.

convertOutput

protected abstract Prediction<T> convertOutput(V output,
                                               int numValidFeatures,
                                               Example<T> example)

Converts the output of the external model into a Prediction.

Parameters:

output - The output of the external model.

numValidFeatures - The number of valid features in the input.

example - The input example, used to construct the Prediction.

Returns:

A Tribuo Prediction.

convertOutput

protected abstract List<Prediction<T>> convertOutput(V output,
                                                     int[] numValidFeatures,
                                                     List<Example<T>> examples)

Converts the output of the external model into a list of Predictions.

Parameters:

output - The output of the external model.

numValidFeatures - An array with the number of valid features in each example.

examples - The input examples, used to construct the Predictions.

Returns:

A list of Tribuo Predictions.

getExcuse

public Optional<Excuse<T>> getExcuse(Example<T> example)

By default third party models don't return excuses.

Specified by:

getExcuse in class Model<T extends Output<T>>

Parameters:

example - The input example.

Returns:

Optional.empty.

getBatchSize

public int getBatchSize()

Gets the current testing batch size.

Returns:

The batch size.

setBatchSize

public void setBatchSize(int batchSize)

Sets a new batch size.

Throws IllegalArgumentException if the batch size isn't positive.

Parameters:

batchSize - The batch size to use.

createFeatureMap

protected static ImmutableFeatureMap createFeatureMap(Set<String> featureNames)

Creates an immutable feature map from a set of feature names.

Each feature is unobserved.

Parameters:

featureNames - The names of the features to create.

Returns:

A feature map representing the feature names.

createOutputInfo

protected static <T extends Output<T>> ImmutableOutputInfo<T> createOutputInfo(OutputFactory<T> factory,
                                                                               Map<T,Integer> outputs)

Creates an output info from a set of outputs.

Type Parameters:

T - The type of the outputs.

Parameters:

factory - The output factory to use.

outputs - The outputs and ids to observe.

Returns:

An immutable output info representing the outputs.