hex.grid

Class GridSearch<MP extends Model.Parameters>

java.lang.Object

water.Iced<T>

water.Keyed

water.Job<Grid>

hex.grid.GridSearch<MP>

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, Freezable

public final class GridSearch<MP extends Model.Parameters>
extends Job<Grid>

Grid search job. This job represents a generic interface to launch "any" hyper space search. It triggers sub-jobs for each point in hyper space. It produces Grid object which contains a list of build models. A triggered model builder job can fail! Grid search is parametrized by:

• model factory (ModelFactory) defines model build process
• hyper space walk strategy (HyperSpaceWalker defines how the space of hyper parameters is traversed

The job is started by the startGridSearch method which create a new grid search, put representation of Grid into distributed KV store, and for each parameter in hyper space of possible parameters, it launches a separated model building job. The launch of jobs is sequential and blocking. So after finish the last model, whole grid search job is done as well. By default, the grid search invokes cartezian grid search, but it can be modified by passing explicit hyper space walk strategy via the startGridSearch(Key, ModelFactory, HyperSpaceWalker) method. If any of forked jobs fails then the failure is ignored, and grid search normally continue in traversing the hyper space. Typical usage from Java is:

// Create initial parameters and fill them by references to data
 GBMModel.GBMParameters params = new GBMModel.GBMParameters();
 params._train = fr._key;
 params._response_column = "cylinders";

 // Define hyper-space to search
 HashMap<String,Object[]> hyperParms = new HashMap<>();
 hyperParms.put("_ntrees", new Integer[]{1, 2});
 hyperParms.put("_distribution",new Distribution.Family[] {Distribution.Family.multinomial});
 hyperParms.put("_max_depth",new Integer[]{1,2,5});
 hyperParms.put("_learn_rate",new Float[]{0.01f,0.1f,0.3f});

 // Launch grid search job creating GBM models
 GridSearch gridSearchJob = GridSearch.startGridSearch(params, hyperParms, GBM_MODEL_FACTORY);

 // Block till the end of the job and get result
 Grid grid = gridSearchJob.get()

 // Get built models
 Model[] models = grid.getModels()
 

See Also:

ModelFactory, HyperSpaceWalker, startGridSearch(Key, ModelFactory, HyperSpaceWalker), Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class water.Job

Job.JobCancelledException, Job.JobState, Job.Progress, Job.ProgressUpdate, Job.ValidationMessage

Nested classes/interfaces inherited from class water.Keyed

Keyed.BinarySerializer<X extends Keyed>

Field Summary

Fields inherited from class water.Job

_description, _dest, _end_time, _exception, _messages, _progressKey, _start_time, _state, LIST

Fields inherited from class water.Keyed

_key, EMPTY_KEY_LIST

Method Summary

Methods

Modifier and Type	Method and Description
int	getModelCount() Returns expected number of models in resulting Grid object.
protected static Key<Grid>	gridKeyName(java.lang.String modelName, Frame fr) Defines a key for a new Grid object holding results of grid search.
static <MP extends Model.Parameters> GridSearch	startGridSearch(Key<Grid> destKey, ModelFactory<MP> modelFactory, HyperSpaceWalker<MP> hyperSpaceWalker) Start a new grid search job.
static <MP extends Model.Parameters> GridSearch	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, ModelFactory<MP> modelFactory) Start a new grid search job.
static <MP extends Model.Parameters> GridSearch	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, ModelFactory<MP> modelFactory, ModelParametersBuilderFactory<MP> paramsBuilderFactory) Start a new grid search job.
static <MP extends Model.Parameters> GridSearch	startGridSearch(MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, ModelFactory<MP> modelFactory)

Methods inherited from class water.Job

block, canBeDone, cancel, cancel, checksum_impl, clearValidationErrors, createProgressKey, deleteProgressKey, dest, done, done, error_count_or_uninitialized, error_count, error, failed, get, hide, info, isCancelledOrCrashed, isDone, isRunning, isRunning, isStopped, jobKey, jobs, message, msec, progress_msg, progress, remove_impl, start, update, update, update, update, updateValidationMessages, validationErrors, warn

Methods inherited from class water.Keyed

checksum, getBinarySerializer, getPublishedKeys, remove, remove, remove, remove

Methods inherited from class water.Iced

clone, frozenType, read_impl, read, readExternal, readJSON_impl, readJSON, toJsonString, write_impl, write, writeExternal, writeJSON_impl, writeJSON

Methods inherited from class java.lang.Object

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

Method Detail

getModelCount

public int getModelCount()

Returns expected number of models in resulting Grid object. The number can differ from final number of models due to visiting duplicate points in hyper space.

Returns:

expected number of models produced by this grid search

gridKeyName

protected static Key<Grid> gridKeyName(java.lang.String modelName,
                    Frame fr)

Defines a key for a new Grid object holding results of grid search.

Returns:

a grid key for a particular modeling class and frame.

Throws:

java.lang.IllegalArgumentException - if frame is not saved to distributed store.

startGridSearch

public static <MP extends Model.Parameters> GridSearch startGridSearch(Key<Grid> destKey,
                                                       MP params,
                                                       java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                       ModelFactory<MP> modelFactory,
                                                       ModelParametersBuilderFactory<MP> paramsBuilderFactory)

Start a new grid search job.

This method launches "classical" grid search traversing cartezian grid of parameters point-by-point.

Parameters:

destKey - A key to store result of grid search under.

params - Default parameters for model builder. This object is used to create a specific model parameters for a combination of hyper parameters.

hyperParams - A set of arrays of hyper parameter values, used to specify a simple fully-filled-in grid search.

modelFactory - defines a strategy for creating new model builders

paramsBuilderFactory - defines a strategy for creating a new model parameters based on common parameters and list of hyper-parameters

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

public static <MP extends Model.Parameters> GridSearch startGridSearch(Key<Grid> destKey,
                                                       MP params,
                                                       java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                       ModelFactory<MP> modelFactory)

Start a new grid search job.

This method launches "classical" grid search traversing cartezian grid of parameters point-by-point.

Parameters:

destKey - A key to store result of grid search under.

params - Default parameters for model builder. This object is used to create a specific model parameters for a combination of hyper parameters.

hyperParams - A set of arrays of hyper parameter values, used to specify a simple fully-filled-in grid search.

modelFactory - defines a strategy for creating new model builders

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.

startGridSearch

public static <MP extends Model.Parameters> GridSearch startGridSearch(MP params,
                                                       java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                       ModelFactory<MP> modelFactory)

startGridSearch

public static <MP extends Model.Parameters> GridSearch startGridSearch(Key<Grid> destKey,
                                                       ModelFactory<MP> modelFactory,
                                                       HyperSpaceWalker<MP> hyperSpaceWalker)

Start a new grid search job.

This method launches any grid search traversing space of hyper parameters based on specified strategy.

Parameters:

destKey - A key to store result of grid search under.

modelFactory - defines a strategy for creating new model builders

hyperSpaceWalker - defines a strategy for traversing a hyper space. The object itself holds definition of hyper space.

Returns:

GridSearch Job, with models run with these parameters, built as needed - expected to be an expensive operation. If the models in question are "in progress", a 2nd build will NOT be kicked off. This is a non-blocking call.