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:

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:

Optional fields

Variables:

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:

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:

Optional fields

Variables:

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:

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:

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:

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:

Optional fields

Variables:

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!