Class Model<T extends Output<T>>

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:

  • Field Details

  • Constructor Details

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

    • 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<T extends Output<T>>

    • 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