Model (Tribuo 4.0.2 API)

java.lang.Object
- org.tribuo.Model<T>

Type Parameters:

T - the type of prediction produced by the model.

All Implemented Interfaces:

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

Direct Known Subclasses:

DummyClassifierModel, DummyRegressionModel, EnsembleModel, ExternalModel, IndependentMultiLabelModel, KernelSVMModel, KMeansModel, KNNModel, LibLinearModel, LibSVMModel, LinearSGDModel, LinearSGDModel, MultinomialNaiveBayesModel, SkeletalIndependentRegressionModel, SparseModel, TensorflowCheckpointModel, TensorflowModel, TransformedModel, XGBoostModel
```
public abstract class Model<T extends Output<T>>
extends Object
implements com.oracle.labs.mlrg.olcut.provenance.Provenancable<ModelProvenance>, Serializable
```
A prediction model, which is used to predict outputs for unseen instances. Model implementations must be serializable!
If two features map to the same id in the featureIDMap, then occurrences of those features will be combined at prediction time.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALL_OUTPUTS` Used in getTopFeatures when the Model doesn't support per output feature lists.
`static String`	`BIAS_FEATURE` Used to denote the bias feature in a linear model.
`protected ImmutableFeatureMap`	`featureIDMap` The features this model knows about.
`protected boolean`	`generatesProbabilities` Does this model generate probability distributions in the output.
`protected String`	`name` The model's name.
`protected ImmutableOutputInfo<T>`	`outputIDInfo` The outputs this model predicts.
`protected ModelProvenance`	`provenance` The model provenance.
`protected String`	`provenanceOutput` The cached toString of the model provenance.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Model(String name, ModelProvenance provenance, ImmutableFeatureMap featureIDMap, ImmutableOutputInfo<T> outputIDInfo, boolean generatesProbabilities)` Constructs a new model, storing the supplied fields.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Model<T>`	`copy()` Copies a model, returning a deep copy of any mutable state, and a shallow copy otherwise.
`protected abstract Model<T>`	`copy(String newName, ModelProvenance newProvenance)` Copies a model, replacing it's provenance and name with the supplied values.
`boolean`	`generatesProbabilities()` Does this model generate probabilistic predictions.
`abstract Optional<Excuse<T>>`	`getExcuse(Example<T> example)` Generates an excuse for an example.
`Optional<List<Excuse<T>>>`	`getExcuses(Iterable<Example<T>> examples)` Generates an excuse for each example.
`ImmutableFeatureMap`	`getFeatureIDMap()` Gets the feature domain.
`String`	`getName()` Returns the model name.
`ImmutableOutputInfo<T>`	`getOutputIDInfo()` Gets the output domain.
`ModelProvenance`	`getProvenance()`
`abstract Map<String,List<com.oracle.labs.mlrg.olcut.util.Pair<String,Double>>>`	`getTopFeatures(int n)` Gets the top `n` features associated with this model.
`protected List<Prediction<T>>`	`innerPredict(Iterable<Example<T>> examples)` Called by the base implementations of `predict(Iterable)` and `predict(Dataset)`.
`List<Prediction<T>>`	`predict(Dataset<T> examples)` Uses the model to predict the outputs for multiple examples contained in a data set.
`abstract Prediction<T>`	`predict(Example<T> example)` Uses the model to predict the output for a single example.
`List<Prediction<T>>`	`predict(Iterable<Example<T>> examples)` Uses the model to predict the output for multiple examples.
`void`	`setName(String name)` Sets the model name.
`String`	`toString()`
`boolean`	`validate(Class<? extends Output<?>> clazz)` Validates that this Model does in fact support the supplied output type.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - ALL_OUTPUTS
```
public static final String ALL_OUTPUTS
```
    Used in getTopFeatures when the Model doesn't support per output feature lists.
    
    See Also:
    
    Constant Field Values
  - BIAS_FEATURE
```
public static final String BIAS_FEATURE
```
    Used to denote the bias feature in a linear model.
    
    See Also:
    
    Constant Field Values
  - name
```
protected String name
```
    The model's name.
  - provenance
```
protected final ModelProvenance provenance
```
    The model provenance.
  - provenanceOutput
```
protected final String provenanceOutput
```
    The cached toString of the model provenance.
    Mostly cached so it appears in the serialized output and can be read by grepping the binary.
  - featureIDMap
```
protected final ImmutableFeatureMap featureIDMap
```
    The features this model knows about.
  - outputIDInfo
```
protected final ImmutableOutputInfo<T extends Output<T>> outputIDInfo
```
    The outputs this model predicts.
  - generatesProbabilities
```
protected final boolean generatesProbabilities
```
    Does this model generate probability distributions in the output.
- Constructor Detail
  - Model
```
protected Model(String name,
                ModelProvenance provenance,
                ImmutableFeatureMap featureIDMap,
                ImmutableOutputInfo<T> outputIDInfo,
                boolean generatesProbabilities)
```
    Constructs a new model, storing the supplied fields.
    
    Parameters:
    
    name - The model name.
    
    provenance - The model provenance.
    
    featureIDMap - The features.
    
    outputIDInfo - The possible outputs.
    
    generatesProbabilities - Does this model emit probabilistic outputs.
- Method Detail
  - getName
```
public String getName()
```
    Returns the model name.
    
    Returns:
    
    The model name.
  - setName
```
public void setName(String name)
```
    Sets the model name.
    
    Parameters:
    
    name - The new model name.
  - getProvenance
```
public ModelProvenance getProvenance()
```
    Specified by:
    
    getProvenance in interface com.oracle.labs.mlrg.olcut.provenance.Provenancable<ModelProvenance>
  - getFeatureIDMap
```
public ImmutableFeatureMap getFeatureIDMap()
```
    Gets the feature domain.
    
    Returns:
    
    The feature domain.
  - getOutputIDInfo
```
public ImmutableOutputInfo<T> getOutputIDInfo()
```
    Gets the output domain.
    
    Returns:
    
    The output domain.
  - generatesProbabilities
```
public boolean generatesProbabilities()
```
    Does this model generate probabilistic predictions.
    
    Returns:
    
    True if the model generates probabilistic predictions.
  - validate
```
public boolean validate(Class<? extends Output<?>> clazz)
```
    Validates that this Model does in fact support the supplied output type.
    As the output type is erased at runtime, deserialising a Model is an unchecked operation. This method allows the user to check that the deserialised model is of the appropriate type, rather than seeing if predict(org.tribuo.Example<T>) throws a ClassCastException when called.
    
    Parameters:
    
    clazz - The class object to verify the output type against.
    
    Returns:
    
    True if the output type is assignable to the class object type, false otherwise.
  - predict
```
public abstract Prediction<T> predict(Example<T> example)
```
    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.
    
    Parameters:
    
    example - the example to predict.
    
    Returns:
    
    the result of the prediction.
  - predict
```
public List<Prediction<T>> predict(Iterable<Example<T>> examples)
```
    Uses the model to predict the output for multiple examples.
    Throws IllegalArgumentException if the examples have no features or no feature overlap with the model.
    
    Parameters:
    
    examples - the examples to predict.
    
    Returns:
    
    the results of the prediction, in the same order as the examples.
  - predict
```
public List<Prediction<T>> predict(Dataset<T> examples)
```
    Uses the model to predict the outputs for multiple examples contained in a data set.
    Throws IllegalArgumentException if the examples have no features or no feature overlap with the model.
    
    Parameters:
    
    examples - the data set containing the examples to predict.
    
    Returns:
    
    the results of the predictions, in the same order as the Dataset provides the examples.
  - innerPredict
```
protected List<Prediction<T>> innerPredict(Iterable<Example<T>> examples)
```
    Called by the base implementations of predict(Iterable) and predict(Dataset).
    
    Parameters:
    
    examples - The examples to predict.
    
    Returns:
    
    The results of the predictions, in the same order as the examples.
  - getTopFeatures
```
public abstract Map<String,List<com.oracle.labs.mlrg.olcut.util.Pair<String,Double>>> getTopFeatures(int n)
```
    Gets the top n features associated with this model.
    If the model does not produce per output feature lists, it returns a map with a single element with key Model.ALL_OUTPUTS.
    
    If the model cannot describe it's top features then it returns Collections.emptyMap().
    
    Parameters:
    
    n - the number of features to return. If this value is less than 0, all features should be returned for each class, unless the model cannot score it's features.
    
    Returns:
    
    a map from string outputs to an ordered list of pairs of feature names and weights associated with that feature in the model
  - getExcuse
```
public abstract Optional<Excuse<T>> getExcuse(Example<T> example)
```
    Generates an excuse for an example.
    This attempts to explain a classification result. Generating an excuse may be quite an expensive operation.
    This excuse either contains per class information or an entry with key Model.ALL_OUTPUTS.
    The optional is empty if the model does not provide excuses.
    
    Parameters:
    
    example - The input example.
    
    Returns:
    
    An optional excuse object. The optional is empty if this model does not provide excuses.
  - getExcuses
```
public Optional<List<Excuse<T>>> getExcuses(Iterable<Example<T>> examples)
```
    Generates an excuse for each example.
    This may be an expensive operation, and probably should be overridden in subclasses for performance reasons.
    These excuses either contain per class information or an entry with key Model.ALL_OUTPUTS.
    The optional is empty if the model does not provide excuses.
    
    Parameters:
    
    examples - An iterable of examples
    
    Returns:
    
    A optional list of excuses. The Optional is empty if this model does not provide excuses.
  - copy
```
public Model<T> copy()
```
    Copies a model, returning a deep copy of any mutable state, and a shallow copy otherwise.
    
    Returns:
    
    A copy of the model.
  - copy
```
protected abstract Model<T> copy(String newName,
                                 ModelProvenance newProvenance)
```
    Copies a model, replacing it's provenance and name with the supplied values.
    Used to provide the provenance removal functionality.
    
    Parameters:
    
    newName - The new name.
    
    newProvenance - The new provenance.
    
    Returns:
    
    A copy of the model.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Model<T extends Output<T>>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ALL_OUTPUTS

BIAS_FEATURE

name

provenance

provenanceOutput

featureIDMap

outputIDInfo

generatesProbabilities

Constructor Detail

Model

Method Detail

getName

setName

getProvenance

getFeatureIDMap

getOutputIDInfo

generatesProbabilities

validate

predict

predict

predict

innerPredict

getTopFeatures

getExcuse

getExcuses

copy

copy

toString