moe.views.schemas.rest package¶

Submodules¶

moe.views.schemas.rest.bandit_bla module¶

Request/response schemas for bandit_bla endpoints.

class moe.views.schemas.rest.bandit_bla.BanditBLARequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.bandit_bla request colander schema.

Required fields

Variables:	historical_info – (`moe.views.schemas.bandit_pretty_view.BanditHistoricalInfo`) object of historical data describing arm performance

Optional fields

Variables:	subtype – (str) subtype of the BLA bandit algorithm (default: BLA)

Example Minimal Request

Content-Type: text/javascript

{
    "historical_info": {
        "arms_sampled": {
            "arm1": {"win": 20, "total": 25},
            "arm2": {"win": 20, "total": 30},
            "arm3": {"win": 0, "total": 0},
            },
        },
}

Example Full Request

Content-Type: text/javascript

{
    "subtype": "BLA",
    "historical_info": {
        "arms_sampled": {
            "arm1": {"win": 20, "loss": 0, "total": 25},
            "arm2": {"win": 20, "loss": 0, "total": 30},
            "arm3": {"win": 0, "loss": 0, "total": 0},
            },
        },
}

moe.views.schemas.rest.bandit_epsilon module¶

Request/response schemas for bandit_epsilon endpoints.

class moe.views.schemas.rest.bandit_epsilon.BanditEpsilonRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.bandit_epsilon request colander schema.

Required fields

Variables:	historical_info – (`moe.views.schemas.bandit_pretty_view.BanditHistoricalInfo`) object of historical data describing arm performance

Optional fields

Variables:	subtype – (str) subtype of the epsilon bandit algorithm (default: greedy) hyperparameter_info – (`BanditEpsilonFirstHyperparameterInfo` or `BanditEpsilonGreedyHyperparameterInfo`) dict of hyperparameter information

Example Minimal Request

Content-Type: text/javascript

{
    "historical_info": {
        "arms_sampled": {
            "arm1": {"win": 20, "loss": 5, "total": 25},
            "arm2": {"win": 20, "loss": 10, "total": 30},
            "arm3": {"win": 0, "loss": 0, "total": 0},
            },
        },
}

Example Full Request

Content-Type: text/javascript

{
    "subtype": "greedy",
    "historical_info": {
        "arms_sampled": {
            "arm1": {"win": 20, "loss": 5, "total": 25},
            "arm2": {"win": 20, "loss": 10, "total": 30},
            "arm3": {"win": 0, "loss": 0, "total": 0},
            },
        },
    "hyperparameter_info": {
        "epsilon": 0.05,
        },
}

moe.views.schemas.rest.bandit_ucb module¶

Request/response schemas for bandit_ucb endpoints.

class moe.views.schemas.rest.bandit_ucb.BanditUCBRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.bandit_ucb request colander schema.

Required fields

Variables:	historical_info – (`moe.views.schemas.bandit_pretty_view.BanditHistoricalInfo`) object of historical data describing arm performance

Optional fields

Variables:	subtype – (str) subtype of the UCB bandit algorithm (default: UCB1)

Example Minimal Request

Content-Type: text/javascript

{
    "historical_info": {
        "arms_sampled": {
            "arm1": {"win": 20, "loss": 5, "total": 25},
            "arm2": {"win": 20, "loss": 10, "total": 30},
            "arm3": {"win": 0, "loss": 0, "total": 0},
            },
        },
}

Example Full Request

Content-Type: text/javascript

{
    "subtype": "UCB1-tuned",
    "historical_info": {
        "arms_sampled": {
            "arm1": {"win": 20, "loss": 5, "total": 25, "variance": 0.1},
            "arm2": {"win": 20, "loss": 10, "total": 30, "variance": 0.2},
            "arm3": {"win": 0, "loss": 0, "total": 0},
            },
        },
}

moe.views.schemas.rest.gp_ei module¶

Request/response schemas for gp_ei endpoints.

class moe.views.schemas.rest.gp_ei.GpEiRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.gp_ei.GpEiView request colander schema.

Note

Requesting points_to_evaluate and points_being_sampled that are close to each or close to existing points_sampled may result in a [numerically] singular GP-variance matrix (which is required by EI).

See additional notes in moe.views.schemas.base_schemas.CovarianceInfo, moe.views.schemas.base_schemas.GpHistoricalInfo.

Required fields

Variables:	points_to_evaluate – (list of list of float64) points in domain to calculate Expected Improvement (EI) at (`moe.views.schemas.base_schemas.ListOfPointsInDomain`) gp_historical_info – (`moe.views.schemas.base_schemas.GpHistoricalInfo`) object of historical data

Optional fields

Variables:

points_being_sampled – (list of list of float64) points in domain being sampled in concurrent experiments (default: []) (moe.views.schemas.base_schemas.ListOfPointsInDomain)
mc_iterations – (int) number of Monte Carlo (MC) iterations to perform in numerical integration to calculate EI
max_num_threads – (int) maximum number of threads to use in computation (default: 1)
covariance_info – (moe.views.schemas.base_schemas.CovarianceInfo) dict of covariance information

Example Minimal Request

Content-Type: text/javascript

{
    "points_to_evaluate": [[0.1], [0.5], [0.9]],
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "dim": 1,
        },
}

Example Full Request

Content-Type: text/javascript

{
    "points_to_evaluate": [[0.1], [0.5], [0.9]],
    "points_being_sampled": [[0.2], [0.7]],
    "mc_iterations": 10000,
    "max_num_threads": 1,
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "domain_type": "tensor_product"
        "dim": 1,
        },
    "covariance_info": {
        "covariance_type": "square_exponential",
        "hyperparameters": [1.0, 1.0],
        },
}

class moe.views.schemas.rest.gp_ei.GpEiResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.gp_ei.GpEiView response colander schema.

Output fields

Variables:	endpoint – (str) the endpoint that was called expected_improvement – (list of float64) calculated expected improvements (`moe.views.schemas.base_schemas.ListOfExpectedImprovements`)

Example Response

{
    "endpoint":"gp_ei",
    "expected_improvement":["0.197246898375","0.443163755117","0.155819546878"]
}

moe.views.schemas.rest.gp_hyper_opt module¶

Request/response schemas for gp_hyper_opt endpoints.

class moe.views.schemas.rest.gp_hyper_opt.GpHyperOptRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.gp_hyper_opt.GpHyperOptView request colander schema.

Note

Particularly when the amount of historical data is low, the log likelihood may grow toward extreme hyperparameter values (i.e., toward 0 or infinity). Select reasonable domain bounds. For example, in a driving distance parameter, the scale of feet is irrelevant, as is the scale of 1000s of miles.

Note

MOE’s default optimization parameters were tuned for hyperparameter values roughly in [0.01, 100]. Venturing too far out of this range means the defaults may perform poorly.

See additional notes in moe.views.schemas.base_schemas.CovarianceInfo, moe.views.schemas.base_schemas.GpHistoricalInfo.

Required fields

Variables:	gp_historical_info – (`moe.views.schemas.base_schemas.GpHistoricalInfo`) object of historical data domain_info – (`moe.views.schemas.base_schemas.DomainInfo`) dict of domain information for the GP hyperparameter_domain_info – (`moe.views.schemas.base_schemas.BoundedDomainInfo`) dict of domain information for the hyperparameter optimization

Optional fields

Variables:	max_num_threads – (int) maximum number of threads to use in computation covariance_info – (`moe.views.schemas.base_schemas.CovarianceInfo`) dict of covariance information, used as a starting point for optimization optimizer_info – (`moe.views.schemas.base_schemas.OptimizerInfo`) dict of optimizer information

General Timing Results

Here are some “broad-strokes” timing results for hyperparameter optimization. These tests are not complete nor comprehensive; they’re just a starting point. The tests were run on a Ivy Bridge 2.3 GHz quad-core CPU (i7-3615QM). Data was generated from a Gaussian Process prior. The optimization parameters were the default values (see moe.optimal_learning.python.constant) as of sha c19257049f16036e5e2823df87fbe0812720e291.

Below, N = num_sampled.

Scaling with dim (N = 40)
dim	Gradient Descent	Newton
3	85s	3.6s
6	80s	7.2s
12	108s	19.5s

GD scales ~ O(dim) and Newton ~ O(dim^2) although these dim values are not large enough to show the asymptotic behavior.

Scaling with N (dim = 3)
N	Gradient Descent	Newton
20	14s	0.72s
40	85s	3.6s
120	2100s	60s

Both methods scale as ~ O(N^3) which is clearly shown here.

Example Request

Content-Type: text/javascript

{
    "max_num_threads": 1,
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "dim": 1,
        },
    "covariance_info": {
        "covariance_type": "square_exponential",
        "hyperparameters": [1.0, 1.0],
        },
    "hyperparameter_domain_info": {
        "dim": 2,
        "domain_bounds": [
            {"min": 0.1, "max": 2.0},
            {"min": 0.1, "max": 2.0},
            ],
        },
    "optimizer_info": {
        "optimizer_type": "newton_optimizer",
        "num_multistarts": 200,
        "num_random_samples": 4000,
        "optimizer_parameters": {
            "gamma": 1.2,
            ...
            },
        },
    "log_likelihood_info": "log_marginal_likelihood"
}

class moe.views.schemas.rest.gp_hyper_opt.GpHyperOptResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.gp_hyper_opt.GpHyperOptView response colander schema.

Output fields

Variables:	endpoint – (str) the endpoint that was called covariance_info – (`moe.views.schemas.base_schemas.CovarianceInfo`) dict of covariance information status – (`moe.views.schemas.rest.gp_hyper_opt.GpHyperOptStatus`) dict indicating final log likelihood value/gradient and optimization status messages (e.g., success)

Example Response

{
    "endpoint":"gp_hyper_opt",
    "covariance_info": {
        "covariance_type": "square_exponential",
        "hyperparameters": ["0.88", "1.24"],
        },
    "status": {
        "log_likelihood": "-37.3279872",
        "grad_log_likelihood: ["-3.8897e-12", "1.32789789e-11"],
        "optimizer_success": {
                'newton_found_update': True,
            },
        },
}

class moe.views.schemas.rest.gp_hyper_opt.GpHyperOptStatus(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.gp_hyper_opt.GpHyperOptView status schema.

Output fields

Variables:	log_likelihood – (float64) The log likelihood at the new hyperparameters grad_log_likelihood – (list of float64) The gradient of the log likelihood at the new hyperparameters optimizer_success – (dict) Whether or not the optimizer converged to an optimal set of hyperparameters

moe.views.schemas.rest.gp_mean_var module¶

Request/response schemas for gp_mean, gp_var, and gp_mean_var (and _diag) endpoints.

class moe.views.schemas.rest.gp_mean_var.GpEndpointResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A base schema for the endpoint name.

Output fields

Variables:	endpoint – (str) the endpoint that was called

Example Response

{
    "endpoint":"gp_mean_var",
}

class moe.views.schemas.rest.gp_mean_var.GpMeanMixinResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A mixin response colander schema for the mean of a gaussian process.

Output fields

Variables:	mean – (list of float64) the means of the GP at `points_to_evaluate` (`moe.views.schemas.base_schemas.ListOfFloats`)

Example Response

{
    "mean": ["0.0873832198661","0.0130505261903","0.174755506336"],
}

class moe.views.schemas.rest.gp_mean_var.GpMeanResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.rest.gp_mean_var.GpEndpointResponse, moe.views.schemas.rest.gp_mean_var.GpMeanMixinResponse

A moe.views.rest.gp_mean_var.GpMeanView response colander schema.

See composing members’ docstrings.

class moe.views.schemas.rest.gp_mean_var.GpMeanVarDiagResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.rest.gp_mean_var.GpMeanResponse, moe.views.schemas.rest.gp_mean_var.GpVarDiagMixinResponse

A moe.views.rest.gp_mean_var.GpMeanVarDiagView response colander schema.

See composing members’ docstrings.

class moe.views.schemas.rest.gp_mean_var.GpMeanVarRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A request colander schema for the views in moe.views.rest.gp_mean_var.

Note

Requesting points_to_evaluate that are close to each or close to existing points_sampled may result in a [numerically] singular GP-variance matrix.

See additional notes in moe.views.schemas.base_schemas.CovarianceInfo, moe.views.schemas.base_schemas.GpHistoricalInfo.

Required fields

Variables:	points_to_evaluate – (list of list of float64) points in domain to calculate the Gaussian Process (GP) mean and covariance at (`moe.views.schemas.base_schemas.ListOfPointsInDomain`) gp_historical_info – (`moe.views.schemas.base_schemas.GpHistoricalInfo`) object of historical data

Optional fields

Variables:	covariance_info – (`moe.views.schemas.base_schemas.CovarianceInfo`) dict of covariance information

Example Minimal Request

Content-Type: text/javascript

{
    "points_to_evaluate": [[0.1], [0.5], [0.9]],
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "dim": 1,
        },
}

Example Full Request

Content-Type: text/javascript

{
    "points_to_evaluate": [[0.1], [0.5], [0.9]],
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "domain_type": "tensor_product"
        "dim": 1,
        },
    "covariance_info": {
        "covariance_type": "square_exponential",
        "hyperparameters": [1.0, 1.0],
        },
}

class moe.views.schemas.rest.gp_mean_var.GpMeanVarResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.rest.gp_mean_var.GpMeanResponse, moe.views.schemas.rest.gp_mean_var.GpVarMixinResponse

A moe.views.rest.gp_mean_var.GpMeanVarView response colander schema.

See composing members’ docstrings.

class moe.views.schemas.rest.gp_mean_var.GpVarDiagMixinResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A mixin response colander schema for the variance of a gaussian process.

Output fields

Variables:	var – (list of float64) variances of the GP at `points_to_evaluate`; i.e., diagonal of the `var` response from gp_mean_var (`moe.views.schemas.base_schemas.ListOfFloats`)

Example Response

{
    "var": ["0.228910114429","0.996177332647","0.228910114429"],
}

class moe.views.schemas.rest.gp_mean_var.GpVarDiagResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.rest.gp_mean_var.GpEndpointResponse, moe.views.schemas.rest.gp_mean_var.GpVarDiagMixinResponse

A moe.views.rest.gp_mean_var.GpVarDiagView response colander schema.

See composing members’ docstrings.

class moe.views.schemas.rest.gp_mean_var.GpVarMixinResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A mixin response colander schema for the [co]variance of a gaussian process.

Output fields

Variables:	var – (`moe.views.schemas.base_schemas.MatrixOfFloats`) matrix of covariance of the GP at `points_to_evaluate`

Example Response

{
    "var": [
            ["0.228910114429","0.0969433771923","0.000268292907969"],
            ["0.0969433771923","0.996177332647","0.0969433771923"],
            ["0.000268292907969","0.0969433771923","0.228910114429"]
        ],
}

class moe.views.schemas.rest.gp_mean_var.GpVarResponse(*arg, **kw)[source]¶

Bases: moe.views.schemas.rest.gp_mean_var.GpEndpointResponse, moe.views.schemas.rest.gp_mean_var.GpVarMixinResponse

A moe.views.rest.gp_mean_var.GpVarView response colander schema.

See composing members’ docstrings.

moe.views.schemas.rest.gp_next_points_constant_liar module¶

Response schemas for gp_next_points_constant_liar endpoints.

class moe.views.schemas.rest.gp_next_points_constant_liar.GpNextPointsConstantLiarRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest

Extends the standard request moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest with a lie value, for use with moe.views.rest.gp_next_points_constant_liar.GpNextPointsConstantLiar.

See moe.optimal_learning.python.cpp_wrappers.expected_improvement.constant_liar_expected_improvement_optimization() for more info.

Warning

Setting lie_value < best_so_far (= min(points_sampled_value)) will lead to poor results. The resulting points_to_sample will be tightly clustered. Such results are generally of low value and may cause singular GP-variance matrices too.

Warning

Setting lie_noise_variance to 0 may cause singular GP covariance matrices when paired with large num_to_sample (for the same reason given in moe.views.schemas.base_schemas.GpHistoricalInfo).

Setting large lie_noise_variance may cause the output points_to_sample to cluster–if one heuristic estimate is good and has large noise, MOE will want to increase resample that location to increase certainty.

See additional notes/warnings in moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest.

Required fields

Variables:	gp_historical_info – (`moe.views.schemas.base_schemas.GpHistoricalInfo`) dict of historical data domain_info – (`moe.views.schemas.base_schemas.BoundedDomainInfo`) dict of domain information

Optional fields

Variables:

num_to_sample – (int) number of next points to generate (default: 1)
lie_method – (str) name from CONSTANT_LIAR_METHODS representing the liar method to use (default: ‘constant_liar_min’)
lie_value – (float64) the ‘lie’ the Constant Liar heuristic will use (default: None). If lie_value is not None the algorithm will use this value instead of one calculated using lie_method.
lie_noise_variance – (float64 >= 0.0) the noise variance of the ‘lie’ value (default: 0.0)
covariance_info – (moe.views.schemas.base_schemas.CovarianceInfo) dict of covariance information
optimiaztion_info – (moe.views.schemas.base_schemas.OptimizerInfo) dict of optimization information

General Timing Results

See the Analytic EI table in moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest for rough timing numbers.

Example Request

Content-Type: text/javascript

{
    "num_to_sample": 1,
    "lie_value": 0.0,
    "lie_noise_variance": 1e-12,
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "dim": 1,
        "domain_bounds": [
            {"min": 0.0, "max": 1.0},
            ],
        },
}

moe.views.schemas.rest.gp_next_points_kriging module¶

Response schemas for gp_next_points_kriging endpoints.

class moe.views.schemas.rest.gp_next_points_kriging.GpNextPointsKrigingRequest(*arg, **kw)[source]¶

Bases: moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest

Extends the standard request moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest with kriging parameters, for use with moe.views.rest.gp_next_points_kriging.GpNextPointsKriging.

See moe.optimal_learning.python.cpp_wrappers.expected_improvement.kriging_believer_expected_improvement_optimization() for more info.

Warning

Setting kriging_noise_variance to 0 may cause singular GP covariance matrices when paired with large num_to_sample (for the same reason given in moe.views.schemas.base_schemas.GpHistoricalInfo).

Setting large kriging_noise_variance may cause the output points_to_sample to cluster–if one heuristic estimate is good and has large noise, MOE will want to increase resample that location to increase certainty.

See additional notes/warnings in moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest.

Required fields

Variables:	gp_historical_info – (`moe.views.schemas.base_schemas.GpHistoricalInfo`) dict of historical data domain_info – (`moe.views.schemas.base_schemas.BoundedDomainInfo`) dict of domain information

Optional fields

Variables:

num_to_sample – number of next points to generate (default: 1)
std_deviation_coef – (float64) amount of GP-variance to add to each Kriging estimate, see moe.optimal_learning.python.cpp_wrappers.expected_improvement.kriging_believer_expected_improvement_optimization() (default: 0.0)
kriging_noise_variance – (float64 >= 0.0) noise variance for each Kriging estimate, see moe.optimal_learning.python.cpp_wrappers.expected_improvement.kriging_believer_expected_improvement_optimization() (default: 0.0)
covariance_info – (moe.views.schemas.base_schemas.CovarianceInfo) dict of covariance information
optimiaztion_info – (moe.views.schemas.base_schemas.OptimizerInfo) dict of optimization information

General Timing Results

See the Analytic EI table in moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest for rough timing numbers.

Example Request

Content-Type: text/javascript

{
    "num_to_sample": 1,
    "std_deviation_coef": 0.0,
    "kriging_noise_variance": 0.0,
    "gp_historical_info": {
        "points_sampled": [
                {"value_var": 0.01, "value": 0.1, "point": [0.0]},
                {"value_var": 0.01, "value": 0.2, "point": [1.0]}
            ],
        },
    "domain_info": {
        "dim": 1,
        "domain_bounds": [
            {"min": 0.0, "max": 1.0},
            ],
        },
}

Module contents¶

Request/response schemas for the MOE REST interface.

Contains schemas for each endpoint represented in moe.views.rest.

Warning

Outputs of colander schema serialization/deserialization should be treated as READ-ONLY. It appears that “missing=” and “default=” value are weak-copied (by reference). Thus changing missing/default fields in the output dict can modify the schema!