Architecture

Data flow overview

Tribuo loads data using a DataSource implementation, which might load from a location like a DB or a file on disk. This DataSource processes the input data, converting it into Tribuo’s storage format, an Example. An Example is a tuple of an Output (i.e., what you want to predict) and a list of Features, where each Feature is a tuple of a String feature name and a double feature value... The DataSource is then read into a Dataset, which accumulates statistics about the data for future use in model construction. Datasets can be split into chunks to separate out training and testing data, or to filter out examples according to some criterion... If the new Examples have known Outputs, then the Predictions can be passed to an Evaluator, which calculates statistics like the accuracy (i.e., the number of times the predicted output was the same as the provided output).

Structure

Tribuo includes several top level modules:

  • Core provides Tribuo’s core classes and interfaces.
  • Data provides loaders for text, sql and csv data, along with the columnar package which provides infrastructure for working with columnar data.
  • Math provides Tribuo’s linear algebra library, along with kernels and gradient optimizers.
  • JSON provides a JSON data loader and a tool to strip provenance from trained models.

Tribuo has separate modules for each prediction task:

  • Classification contains an Output implementation called Label, which represents a multi-class classification...
  • Regression contains an Output implementation called Regressor, which represents multidimensional regression.
  • AnomalyDetection contains an Output implementation called Event, which represents the detection of an anomalous or expected event...
  • Clustering contains an Output implementation called ClusterID, which represents the cluster id number assigned...
  • MultiLabel contains an Output implementation called MultiLabel, which represents a multi-label classification...

Finally, there are cross-cutting module collections:

  • Common provides shared infrastructure for the prediction tasks.
  • Interop provides infrastructure for working with large external libraries like TensorFlow and ONNX Runtime.
  • Util provides independent libraries that Tribuo uses for specific tasks.

Configuration, Options and Provenance

Many of Tribuo’s trainers, datasources and other classes implement the Configurable interface... The configuration system provides the basis of Tribuo’s model tracking Provenance system, which records all hyperparameters, dataset parameters (e.g., file location, train/test split, etc.), and any user-supplied instance information, along with run specific information such as the file hash, number of training examples, etc... This configuration can be loaded into a fresh ConfigurationManager and optionally saved to disk. The evaluation or model training can then be repeated or rerun with tweaks like new data or a hyperparameter change.

A snippet from the classification SGD trainer illustrates configuration:

public class LinearSGDTrainer implements Trainer<Label>, WeightedExamples {
    @Config(description="The classification objective function to use.")
    private LabelObjective objective = new LogMulticlass();
    ...
}

Data Loading

Built-in formats

Tribuo supports several common input formats for loading in data:

  • libsvm/svmlight - a sparse numerical format for classification and regression tasks.
  • IDX - a dense multidimensional numerical format for classification and regression...
  • CSV - a plain text delimited format (using an RFC4180 compliant parser).
  • JSON - JavaScript Object Notation...
  • SQL - Tribuo has a JDBC loader, which can query a database and convert the result set into Tribuo Examples...
  • text - a one document per line format...

Columnar Inputs

Columnar data sources require a configurable extraction step to map the columns into Tribuo Example and Feature objects. A single column may contain multiple features, may be extraneous, or may contain Example-level metadata.

Splitting up Datasets

DataSources are not designed for splitting data into chunks; however, Tribuo provides several other mechanisms for splitting data into training and test sets, subsampling data based on its properties, and creating cross-validation folds...

Weights and Metadata

Examples can have metadata attached to them, and this metadata can be used to filter out Examples or otherwise tag them for special processing...

Obfuscation

One of Tribuo’s benefits is its extensive tracking of model metadata and provenance; however, we realise this metadata isn’t necessarily something that should live in third-party accessible, deployed models...

Provenance

Provenance can be removed from Model objects using the StripProvenance...

Feature Hashing

In addition to its use as a dimensionality reduction technique, feature hashing also obfuscates the original feature names in cases where the forward mapping from original names to hashed names has not been stored by the system.

Serialization

Tribuo supports Java serialization and from v4.3 it supports serializing objects to protobufs...

ONNX Export

From v4.2 Tribuo supports exporting some models in the ONNX model format. The ONNX format is a cross-platform model exchange format which can be loaded in by many machine learning libraries...

ONNX and provenance

Tribuo-exported ONNX files contain the Tribuo model provenance, stored as a protobuf in the metadata field “TRIBUO_PROVENANCE”...

ONNX and deployment

The ONNX format is widely supported in industry and cloud providers...

Reproducibility

From v4.2 Tribuo has a built-in reproducibility system for non-sequence Models... This system produces a diff of the reproduced model’s provenance against the original provenance, highlighting areas where the new model may behave differently to the old one.