hex.grid

Class GridSearch<MP extends Model.Parameters>

java.lang.Object

water.Iced<T>

water.Keyed<GridSearch>

hex.grid.GridSearch<MP>

All Implemented Interfaces:

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

public final class GridSearch<MP extends Model.Parameters>
extends Keyed<GridSearch>

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 hyper space walk strategy (HyperSpaceWalker which 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, 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 DistributionFamily[] {DistributionFamily.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:

HyperSpaceWalker, startGridSearch(Key, HyperSpaceWalker), Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GridSearch.SimpleParametersBuilderFactory<MP extends Model.Parameters> The factory is producing a parameters builder which uses reflection to setup field values.

Field Summary

Fields

Modifier and Type	Field and Description
Job<Grid>	_job
Key<Grid>	_result

Fields inherited from class water.Keyed

_key

Method Summary

Methods

Modifier and Type	Method and Description
long	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> Job<Grid>	startGridSearch(Key<Grid> destKey, HyperSpaceWalker<MP,?> hyperSpaceWalker) Start a new grid search job.
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams) Start a new grid search job.
static <MP extends Model.Parameters> Job<Grid>	startGridSearch(Key<Grid> destKey, MP params, java.util.Map<java.lang.String,java.lang.Object[]> hyperParams, ModelParametersBuilderFactory<MP> paramsBuilderFactory, HyperSpaceSearchCriteria search_criteria) Start a new grid search job.

Methods inherited from class water.Keyed

checksum_impl, checksum, makeSchema, readAll_impl, readAll, remove_impl, remove, remove, remove, remove, writeAll_impl, 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, toString, wait, wait, wait

Field Detail

_result

public final Key<Grid> _result

_job

public final Job<Grid> _job

Method Detail

getModelCount

public long 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> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                      MP params,
                                                      java.util.Map<java.lang.String,java.lang.Object[]> hyperParams,
                                                      ModelParametersBuilderFactory<MP> paramsBuilderFactory,
                                                      HyperSpaceSearchCriteria search_criteria)

Start a new grid search job. This is the method that gets called by GridSearchHandler.do_train().

This method launches a "classical" grid search traversing cartesian grid of parameters point-by-point, or a random hyperparameter search, depending on the value of the strategy parameter.

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.

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> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                      MP params,
                                                      java.util.Map<java.lang.String,java.lang.Object[]> hyperParams)

Start a new grid search job.

This method launches "classical" grid search traversing cartesian grid of parameters point-by-point. For more advanced hyperparameter search behavior call the referenced method.

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.

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.

See Also:

startGridSearch(Key, Model.Parameters, Map, ModelParametersBuilderFactory, HyperSpaceSearchCriteria)

startGridSearch

public static <MP extends Model.Parameters> Job<Grid> startGridSearch(Key<Grid> destKey,
                                                      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.

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.