hex

Class Model<M extends Model<M,P,O>,P extends Model.Parameters,O extends Model.Output>

java.lang.Object

water.Iced<T>

water.Keyed<T>

water.Lockable<M>

hex.Model<M,P,O>

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, Freezable<M>

Direct Known Subclasses:

ClusteringModel, QuantileModel

public abstract class Model<M extends Model<M,P,O>,P extends Model.Parameters,O extends Model.Output>
extends Lockable<M>

A Model models reality (hopefully). A model can be used to 'score' a row (make a prediction), or a collection of rows on any compatible dataset - meaning the row has all the columns with the same names as used to build the mode and any categorical columns can be adapted.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Model.BigScore
static interface	Model.DeepFeatures
static interface	Model.ExemplarMembers
static interface	Model.GetMostImportantFeatures
static interface	Model.GLRMArchetypes
static class	Model.GridSortBy
static class	Model.InteractionPair This class represents a pair of interacting columns plus some additional data about specific enums to be interacted when the vecs are categorical.
class	Model.JavaModelStreamWriter Model stream writer - output Java code representation of model.
static interface	Model.LeafNodeAssignment
static class	Model.Output Model-specific output class.
static class	Model.Parameters Model-specific parameter class.

Field Summary

Fields

Modifier and Type	Field and Description
Distribution	_dist
O	_output
P	_parms
IcedHashMap<Key,java.lang.String>	_toDelete
java.lang.String[]	_warnings
protected ScoringInfo[]	scoringInfo

Fields inherited from class water.Lockable

_lockers

Fields inherited from class water.Keyed

_key

Constructor Summary

Constructors

Constructor and Description
Model(Key<M> selfKey, P parms, O output) Full constructor

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String[]	adaptTestForTrain(Frame test, boolean expensive, boolean computeMetrics) Adapt a Test/Validation Frame to be compatible for a Training Frame.
static java.lang.String[]	adaptTestForTrain(Frame test, java.lang.String[] origNames, java.lang.String[][] origDomains, java.lang.String[] names, java.lang.String[][] domains, Model.Parameters parms, boolean expensive, boolean computeMetrics, java.lang.String[] interactions, ToEigenVec tev, IcedHashMap<Key,java.lang.String> toDelete, boolean catEncoded)
ModelMetrics	addMetrics(ModelMetrics mm)
ModelMetrics	addModelMetrics(ModelMetrics mm)
void	addWarning(java.lang.String s)
double	auc()
protected long	checksum_impl() High-quality 64-bit checksum of the content of the object.
double	classification_error()
protected static void	cleanup_adapt(Frame adaptFr, Frame fr)
protected void	closeBigScorePredict()
int	compareTo(M o)
Frame	computeDeviances(Frame valid, Frame predictions, java.lang.String outputName) Compute the deviances for each observation
protected double	data(Chunk[] chks, int row, int col)
double	defaultThreshold() Default threshold for assigning class labels to the target class (for binomial models)
void	deleteCrossValidationModels()
double	deviance()
double	deviance(double w, double y, double f) Deviance of given distribution function at predicted value f
void	fillScoringInfo(ScoringInfo scoringInfo) Fill a ScoringInfo with data from the ModelMetrics for this model.
Model.GridSortBy	getDefaultGridSortBy() Identifies the default ordering method for models returned from Grid Search
ModelMojoWriter	getMojo() Override this in models that support serialization into the MOJO format.
ToEigenVec	getToEigenVec()
boolean	isSupervised()
ScoringInfo	last_scored()
double	lift_top_group()
double	logloss()
float	loss()
double	mae()
protected Model.BigScore	makeBigScoreTask(java.lang.String[][] domains, java.lang.String[] names, Frame adaptFrm, boolean computeMetrics, boolean makePrediction, Job j) Allow subclasses to define their own BigScore class.
static InteractionWrappedVec	makeInteraction(Frame fr, Model.InteractionPair ip, boolean useAllFactorLevels, boolean skipMissing, boolean standardize)
static Frame	makeInteractions(Frame fr, boolean valid, Model.InteractionPair[] interactions, boolean useAllFactorLevels, boolean skipMissing, boolean standardize)
static InteractionWrappedVec[]	makeInteractions(Frame fr, Model.InteractionPair[] interactions, boolean useAllFactorLevels, boolean skipMissing, boolean standardize)
abstract ModelMetrics.MetricBuilder	makeMetricBuilder(java.lang.String[] domain)
java.lang.Class<KeyV3.ModelKeyV3>	makeSchema()
protected java.lang.String[]	makeScoringNames()
double	mean_per_class_error()
double	mse()
protected Frame	postProcessPredictions(Frame predictFr)
protected Frame	predictScoreImpl(Frame fr, Frame adaptFrm, java.lang.String destination_key, Job j, boolean computeMetrics) Score an already adapted frame.
protected Keyed	readAll_impl(AutoBuffer ab, Futures fs)
protected Futures	remove_impl(Futures fs) Override to remove subparts, but not self, of composite Keyed objects.
double	rmsle()
double	score(double[] data)
Frame	score(Frame fr) Bulk score the frame, and auto-name the resulting predictions frame.
Frame	score(Frame fr, java.lang.String destination_key) Bulk score the frame fr, producing a Frame result; the 1st Vec is the predicted class, the remaining Vecs are the probability distributions.
Frame	score(Frame fr, java.lang.String destination_key, Job j)
Frame	score(Frame fr, java.lang.String destination_key, Job j, boolean computeMetrics)
double[]	score0(Chunk[] chks, double offset, int row_in_chunk, double[] tmp, double[] preds)
double[]	score0(Chunk[] chks, int row_in_chunk, double[] tmp, double[] preds) Bulk scoring API for one row.
protected abstract double[]	score0(double[] data, double[] preds) Subclasses implement the scoring logic.
protected double[]	score0(double[] data, double[] preds, double offset) Override scoring logic for models that handle weight/offset
protected ModelMetrics.MetricBuilder	scoreMetrics(Frame adaptFrm) Score an already adapted frame.
ScoringInfo[]	scoring_history()
protected java.lang.String[][]	scoringDomains()
protected void	setupBigScorePredict()
boolean	testJavaScoring(Frame data, Frame model_predictions, double rel_epsilon)
boolean	testJavaScoring(Frame data, Frame model_predictions, double rel_epsilon, double abs_epsilon)
boolean	testJavaScoring(Frame data, Frame model_predictions, double rel_epsilon, double abs_epsilon, double fraction)
java.lang.String	toJava(boolean preview, boolean verboseCode) Return a String which is a valid Java program representing a class that implements the Model.
SBPrintStream	toJava(java.io.OutputStream os, boolean preview, boolean verboseCode)
protected SBPrintStream	toJava(SBPrintStream sb, boolean isGeneratingPreview, boolean verboseCode)
protected boolean	toJavaCheckTooBig()
protected SBPrintStream	toJavaInit(SBPrintStream sb, CodeGeneratorPipeline fileContext)
protected SBPrintStream	toJavaNCLASSES(SBPrintStream sb)
protected void	toJavaPredictBody(SBPrintStream body, CodeGeneratorPipeline classCtx, CodeGeneratorPipeline fileCtx, boolean verboseCode)
protected SBPrintStream	toJavaPROB(SBPrintStream sb)
protected SBPrintStream	toJavaSuper(java.lang.String modelName, SBPrintStream sb) Generate implementation for super class.
java.lang.String	toString()
protected AutoBuffer	writeAll_impl(AutoBuffer ab) Write out K/V pairs, in this case model metrics.

Methods inherited from class water.Lockable

delete_and_lock, delete_and_lock, delete_and_lock, delete, delete, delete, read_lock, read_lock, read_lock, unlock_all, unlock, unlock, unlock, unlock, update, update, update, write_lock, write_lock, write_lock

Methods inherited from class water.Keyed

checksum, readAll, remove, remove, remove, remove, writeAll

Methods inherited from class water.Iced

asBytes, clone, copyOver, frozenType, read, readExternal, readJSON, reloadFromBytes, toJsonString, write, writeExternal, writeJSON

Methods inherited from class java.lang.Object

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

Field Detail

_parms

public P extends Model.Parameters _parms

_output

public O extends Model.Output _output

_warnings

public java.lang.String[] _warnings

_dist

public Distribution _dist

scoringInfo

protected ScoringInfo[] scoringInfo

_toDelete

public IcedHashMap<Key,java.lang.String> _toDelete

Constructor Detail

Model

public Model(Key<M> selfKey,
     P parms,
     O output)

Full constructor

Method Detail

defaultThreshold

public double defaultThreshold()

Default threshold for assigning class labels to the target class (for binomial models)

Returns:

threshold in 0...1

isSupervised

public final boolean isSupervised()

getDefaultGridSortBy

public Model.GridSortBy getDefaultGridSortBy()

Identifies the default ordering method for models returned from Grid Search

Returns:

default sort-by

getToEigenVec

public ToEigenVec getToEigenVec()

addModelMetrics

public ModelMetrics addModelMetrics(ModelMetrics mm)

addWarning

public void addWarning(java.lang.String s)

scoringDomains

protected java.lang.String[][] scoringDomains()

addMetrics

public ModelMetrics addMetrics(ModelMetrics mm)

makeMetricBuilder

public abstract ModelMetrics.MetricBuilder makeMetricBuilder(java.lang.String[] domain)

deviance

public double deviance(double w,
              double y,
              double f)

Deviance of given distribution function at predicted value f

Parameters:

w - observation weight

y - (actual) response

f - (predicted) response in original response space

Returns:

value of gradient

scoring_history

public ScoringInfo[] scoring_history()

fillScoringInfo

public void fillScoringInfo(ScoringInfo scoringInfo)

Fill a ScoringInfo with data from the ModelMetrics for this model.

Parameters:

scoringInfo -

last_scored

public ScoringInfo last_scored()

loss

public float loss()

compareTo

public int compareTo(M o)

classification_error

public double classification_error()

mse

public double mse()

mae

public double mae()

rmsle

public double rmsle()

auc

public double auc()

deviance

public double deviance()

logloss

public double logloss()

mean_per_class_error

public double mean_per_class_error()

lift_top_group

public double lift_top_group()

adaptTestForTrain

public java.lang.String[] adaptTestForTrain(Frame test,
                                   boolean expensive,
                                   boolean computeMetrics)

Adapt a Test/Validation Frame to be compatible for a Training Frame. The intention here is that ModelBuilders can assume the test set has the same count of columns, and within each factor column the same set of same-numbered levels. Extra levels are renumbered past those in the Train set but will still be present in the Test set, thus requiring range-checking. This routine is used before model building (with no Model made yet) to check for compatible datasets, and also used to prepare a large dataset for scoring (with a Model). Adaption does the following things: - Remove any "extra" Vecs appearing only in the test and not the train - Insert any "missing" Vecs appearing only in the train and not the test with all NAs (missingColumnsType). This will issue a warning, and if the "expensive" flag is false won't actually make the column replacement column but instead will bail-out on the whole adaption (but will continue looking for more warnings). - If all columns are missing, issue an error. - Renumber matching cat levels to match the Train levels; this might make "holes" in the Test set cat levels, if some are not in the Test set. - Extra Test levels are renumbered past the end of the Train set, hence the train and test levels match up to all the train levels; there might be extra Test levels past that. - For all mis-matched levels, issue a warning. The test frame is updated in-place to be compatible, by altering the names and Vecs; make a defensive copy if you do not want it modified. There is a fast-path cutout if the test set is already compatible. Since the test-set is conditionally modifed with extra CategoricalWrappedVec optionally added it is recommended to use a Scope enter/exit to track Vec lifetimes.

Parameters:

test - Testing Frame, updated in-place

expensive - Try hard to adapt; this might involve the creation of whole Vecs and thus get expensive. If false, then only adapt if no warnings and errors; otherwise just the messages are produced. Created Vecs have to be deleted by the caller (e.g. Scope.enter/exit).

Returns:

Array of warnings; zero length (never null) for no warnings. Throws IllegalArgumentException if no columns are in common, or if any factor column has no levels in common.

adaptTestForTrain

public static java.lang.String[] adaptTestForTrain(Frame test,
                                   java.lang.String[] origNames,
                                   java.lang.String[][] origDomains,
                                   java.lang.String[] names,
                                   java.lang.String[][] domains,
                                   Model.Parameters parms,
                                   boolean expensive,
                                   boolean computeMetrics,
                                   java.lang.String[] interactions,
                                   ToEigenVec tev,
                                   IcedHashMap<Key,java.lang.String> toDelete,
                                   boolean catEncoded)
                                            throws java.lang.IllegalArgumentException

Parameters:

test - Frame to be adapted

origNames - Training column names before categorical column encoding - can be the same as names

origDomains - Training column levels before categorical column encoding - can be the same as domains

names - Training column names

domains - Training column levels

parms - Model parameters

expensive - Whether to actually do the hard work

computeMetrics - Whether metrics can be (and should be) computed

interactions - Column names to create pairwise interactions with

catEncoded - Whether the categorical columns of the test frame were already transformed via categorical_encoding

Throws:

java.lang.IllegalArgumentException

score

public Frame score(Frame fr)
            throws java.lang.IllegalArgumentException

Bulk score the frame, and auto-name the resulting predictions frame.

Parameters:

fr - frame which should be scored

Returns:

A new frame containing a predicted values. For classification it contains a column with prediction and distribution for all response classes. For regression it contains only one column with predicted values.

Throws:

java.lang.IllegalArgumentException

See Also:

score(Frame, String)

score

public Frame score(Frame fr,
          java.lang.String destination_key)
            throws java.lang.IllegalArgumentException

Bulk score the frame fr, producing a Frame result; the 1st Vec is the predicted class, the remaining Vecs are the probability distributions. For Regression (single-class) models, the 1st and only Vec is the prediction value. The result is in the DKV; caller is responsible for deleting.

Parameters:

fr - frame which should be scored

Returns:

A new frame containing a predicted values. For classification it contains a column with prediction and distribution for all response classes. For regression it contains only one column with predicted values.

Throws:

java.lang.IllegalArgumentException

score

public Frame score(Frame fr,
          java.lang.String destination_key,
          Job j)
            throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

score

public Frame score(Frame fr,
          java.lang.String destination_key,
          Job j,
          boolean computeMetrics)
            throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

computeDeviances

public Frame computeDeviances(Frame valid,
                     Frame predictions,
                     java.lang.String outputName)

Compute the deviances for each observation

Parameters:

valid - Validation Frame (must contain the response)

predictions - Predictions made by the model

outputName - Name of the output frame

Returns:

Frame containing 1 column with the per-row deviances

cleanup_adapt

protected static void cleanup_adapt(Frame adaptFr,
                 Frame fr)

makeScoringNames

protected java.lang.String[] makeScoringNames()

makeBigScoreTask

protected Model.BigScore makeBigScoreTask(java.lang.String[][] domains,
                              java.lang.String[] names,
                              Frame adaptFrm,
                              boolean computeMetrics,
                              boolean makePrediction,
                              Job j)

Allow subclasses to define their own BigScore class.

predictScoreImpl

protected Frame predictScoreImpl(Frame fr,
                     Frame adaptFrm,
                     java.lang.String destination_key,
                     Job j,
                     boolean computeMetrics)

Score an already adapted frame. Returns a new Frame with new result vectors, all in the DKV. Caller responsible for deleting. Input is already adapted to the Model's domain, so the output is also. Also computes the metrics for this frame.

Parameters:

adaptFrm - Already adapted frame

computeMetrics -

Returns:

A Frame containing the prediction column, and class distribution

postProcessPredictions

protected Frame postProcessPredictions(Frame predictFr)

scoreMetrics

protected ModelMetrics.MetricBuilder scoreMetrics(Frame adaptFrm)

Score an already adapted frame. Returns a MetricBuilder that can be used to make a model metrics.

Parameters:

adaptFrm - Already adapted frame

Returns:

MetricBuilder

setupBigScorePredict

protected void setupBigScorePredict()

closeBigScorePredict

protected void closeBigScorePredict()

data

protected double data(Chunk[] chks,
          int row,
          int col)

score0

public double[] score0(Chunk[] chks,
              int row_in_chunk,
              double[] tmp,
              double[] preds)

Bulk scoring API for one row. Chunks are all compatible with the model, and expect the last Chunks are for the final distribution and prediction. Default method is to just load the data into the tmp array, then call subclass scoring logic.

score0

public double[] score0(Chunk[] chks,
              double offset,
              int row_in_chunk,
              double[] tmp,
              double[] preds)

score0

protected abstract double[] score0(double[] data,
              double[] preds)

Subclasses implement the scoring logic. The data is pre-loaded into a re-used temp array, in the order the model expects. The predictions are loaded into the re-used temp array, which is also returned.

score0

protected double[] score0(double[] data,
              double[] preds,
              double offset)

Override scoring logic for models that handle weight/offset

score

public double score(double[] data)

remove_impl

protected Futures remove_impl(Futures fs)

Description copied from class: Keyed

Override to remove subparts, but not self, of composite Keyed objects. Examples include Vec (removing associated Chunk keys) and Frame (removing associated Vec keys.)

Overrides:

remove_impl in class Keyed<M extends Model<M,P,O>>

writeAll_impl

protected AutoBuffer writeAll_impl(AutoBuffer ab)

Write out K/V pairs, in this case model metrics.

Overrides:

writeAll_impl in class Keyed<M extends Model<M,P,O>>

readAll_impl

protected Keyed readAll_impl(AutoBuffer ab,
                 Futures fs)

Overrides:

readAll_impl in class Keyed<M extends Model<M,P,O>>

checksum_impl

protected long checksum_impl()

Description copied from class: Keyed

High-quality 64-bit checksum of the content of the object. Similar to hashcode(), but a long to reduce the chance of hash clashes. For composite objects this should be defined using the subcomponents' checksums (or hashcodes if not available). If two Keyed objects have the same checksum() there should be a 1 - 1/2^64 chance that they are the same object by value.

Overrides:

checksum_impl in class Keyed<M extends Model<M,P,O>>

getMojo

public ModelMojoWriter getMojo()

Override this in models that support serialization into the MOJO format.

Returns:

a class that inherits from ModelMojoWriter

toJava

public final java.lang.String toJava(boolean preview,
                      boolean verboseCode)

Return a String which is a valid Java program representing a class that implements the Model. The Java is of the form:

    class UUIDxxxxModel {
      public static final String NAMES[] = { ....column names... }
      public static final String DOMAINS[][] = { ....domain names... }
      // Pass in data in a double[], pre-aligned to the Model's requirements.
      // Jam predictions into the preds[] array; preds[0] is reserved for the
      // main prediction (class for classifiers or value for regression),
      // and remaining columns hold a probability distribution for classifiers.
      double[] predict( double data[], double preds[] );
      double[] map( HashMap < String,Double > row, double data[] );
      // Does the mapping lookup for every row, no allocation
      double[] predict( HashMap < String,Double > row, double data[], double preds[] );
      // Allocates a double[] for every row
      double[] predict( HashMap < String,Double > row, double preds[] );
      // Allocates a double[] and a double[] for every row
      double[] predict( HashMap < String,Double > row );
    }
  

toJava

public final SBPrintStream toJava(java.io.OutputStream os,
                   boolean preview,
                   boolean verboseCode)

toJava

protected SBPrintStream toJava(SBPrintStream sb,
                   boolean isGeneratingPreview,
                   boolean verboseCode)

toJavaSuper

protected SBPrintStream toJavaSuper(java.lang.String modelName,
                        SBPrintStream sb)

Generate implementation for super class.

toJavaNCLASSES

protected SBPrintStream toJavaNCLASSES(SBPrintStream sb)

toJavaPROB

protected SBPrintStream toJavaPROB(SBPrintStream sb)

toJavaCheckTooBig

protected boolean toJavaCheckTooBig()

toJavaInit

protected SBPrintStream toJavaInit(SBPrintStream sb,
                       CodeGeneratorPipeline fileContext)

toJavaPredictBody

protected void toJavaPredictBody(SBPrintStream body,
                     CodeGeneratorPipeline classCtx,
                     CodeGeneratorPipeline fileCtx,
                     boolean verboseCode)

testJavaScoring

public boolean testJavaScoring(Frame data,
                      Frame model_predictions,
                      double rel_epsilon)

testJavaScoring

public boolean testJavaScoring(Frame data,
                      Frame model_predictions,
                      double rel_epsilon,
                      double abs_epsilon)

testJavaScoring

public boolean testJavaScoring(Frame data,
                      Frame model_predictions,
                      double rel_epsilon,
                      double abs_epsilon,
                      double fraction)

deleteCrossValidationModels

public void deleteCrossValidationModels()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

makeSchema

public java.lang.Class<KeyV3.ModelKeyV3> makeSchema()

Overrides:

makeSchema in class Keyed<M extends Model<M,P,O>>

makeInteractions

public static Frame makeInteractions(Frame fr,
                     boolean valid,
                     Model.InteractionPair[] interactions,
                     boolean useAllFactorLevels,
                     boolean skipMissing,
                     boolean standardize)

makeInteractions

public static InteractionWrappedVec[] makeInteractions(Frame fr,
                                       Model.InteractionPair[] interactions,
                                       boolean useAllFactorLevels,
                                       boolean skipMissing,
                                       boolean standardize)

makeInteraction

public static InteractionWrappedVec makeInteraction(Frame fr,
                                    Model.InteractionPair ip,
                                    boolean useAllFactorLevels,
                                    boolean skipMissing,
                                    boolean standardize)