moe.views.schemas package

Submodules

moe.views.schemas.bandit_pretty_view module

Base schemas for creating SampledArm and allocations for bandit endpoints along with base request/response schema components.

class moe.views.schemas.bandit_pretty_view.ArmAllocations[source]

Bases: colander.Schema

Colander SingleArm Dictionary of (arm name, allocation) key-value pairs.

schema_type

alias of Schema

title = 'Arm Allocations'
validator(node, cstruct)[source]

Raise an exception if the node value (cstruct) is not a valid dictionary of (arm name, allocation) key-value pairs.

The total allocation must sums to 1. Each allocation is in range [0,1].

Parameters:
  • node (colander.SchemaNode subclass instance) – the node being validated (usually self)
  • cstruct (dictionary of (arm name, allocation) key-value pairs) – the value being validated
class moe.views.schemas.bandit_pretty_view.ArmsSampled[source]

Bases: colander.Schema

Colander SingleArm Dictionary of (arm name, SingleArm) key-value pairs.

schema_type

alias of Schema

title = 'Arms Sampled'
validator(node, cstruct)[source]

Raise an exception if the node value (cstruct) is not a valid dictionary of (arm name, SingleArm) key-value pairs. Default value for loss is 0. Default value for variance of an arm is None.

Parameters:
  • node (colander.SchemaNode subclass instance) – the node being validated (usually self)
  • cstruct (dictionary of (arm name, SingleArm) key-value pairs) – the value being validated
moe.views.schemas.bandit_pretty_view.BANDIT_EPSILON_SUBTYPES_TO_HYPERPARAMETER_INFO_SCHEMA_CLASSES = {'greedy': <class 'moe.views.schemas.bandit_pretty_view.BanditEpsilonGreedyHyperparameterInfo'>, 'first': <class 'moe.views.schemas.bandit_pretty_view.BanditEpsilonFirstHyperparameterInfo'>}

Mapping from bandit epsilon subtypes (moe.bandit.constant.EPSILON_SUBTYPES) to hyperparameter info schemas, e.g., moe.views.schemas.bandit_pretty_view.BanditEpsilonFirstHyperparameterInfo.

class moe.views.schemas.bandit_pretty_view.BanditEpsilonFirstHyperparameterInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

The hyperparameter info needed for every Bandit Epsilon-First request.

Required fields

Variables:
  • epsilon – (0.0 <= float64 <= 1.0) epsilon value for epsilon-first bandit. This strategy pulls the optimal arm (best expected return) with if it is in exploitation phase (number sampled > epsilon * total_samples). Otherwise a random arm is pulled (exploration).
  • total_samples – (int >= 0) total number of samples for epsilon-first bandit. total_samples is T from Multi-Armed Bandits.
class moe.views.schemas.bandit_pretty_view.BanditEpsilonGreedyHyperparameterInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

The hyperparameter info needed for every Bandit Epsilon request.

Required fields

Variables:epsilon – (0.0 <= float64 <= 1.0) epsilon value for epsilon-greedy bandit. This strategy pulls the optimal arm (best expected return) with probability 1-epsilon. With probability epsilon a random arm is pulled.
class moe.views.schemas.bandit_pretty_view.BanditHistoricalInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

The Bandit historical info needed for every request.

Contains:

  • arms_sampled - ArmsSampled
class moe.views.schemas.bandit_pretty_view.BanditResponse(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A moe.views.rest.bandit_epsilon and moe.views.rest.bandit_ucb response colander schema.

Output fields

Variables:

Example Response

Content-Type: text/javascript

{
    "endpoint":"bandit_epsilon",
    "arm_allocations": {
        "arm1": 0.95,
        "arm2": 0.025,
        "arm3": 0.025,
        }
    "winner": "arm1",
}

moe.views.schemas.base_schemas module

Base level schemas for the response/request schemas of each MOE REST endpoint.

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!

class moe.views.schemas.base_schemas.BoundedDomainInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.DomainInfo

The domain info needed for every request, along with bounds for optimization.

Note

For EI/next points, selecting a domain that is substantially larger than the bounding box of the historical data may lead MOE to favor exploring near the boundaries instead of near existing data.

Required fields

All required fields from DomainInfo

Variables:domain_bounds – (list of list of float64) the bounds of the domain of type moe.views.schemas.base_schemas.Domain
class moe.views.schemas.base_schemas.CovarianceInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

The covariance info needed for every request.

Warning

Very large length scales (adverse conditioning effects) and very small length scales (irrelevant dimensions) can negatively impact MOE’s performance. It may be worth checking that your length scales are “reasonable.”

Additionally, 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.

Required fields

Variables:
  • covariance_type – (str) a covariance type in moe.optimal_learning.python.python_version.constant.COVARIANCE_TYPES
  • hyperparameters – (list of float64) the hyperparameters corresponding to the given covariance_type
class moe.views.schemas.base_schemas.Domain(*args, **kw)[source]

Bases: colander.SequenceSchema

A list of domain interval DomainCoordinate objects.

class moe.views.schemas.base_schemas.DomainCoordinate(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A single domain interval.

class moe.views.schemas.base_schemas.DomainInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

The domain info needed for every request.

Required fields

Variables:dim – (int >= 0) the dimension of the domain (int)

Optional fields

Variables:domain_type – (str) the type of domain to use, one of moe.optimal_learning.python.python_version.constant.DOMAIN_TYPES (default: TENSOR_PRODUCT_DOMAIN_TYPE)
class moe.views.schemas.base_schemas.GpHistoricalInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

The Gaussian Process info needed for every request.

Warning

If the points are too close together (relative to the length scales in moe.views.schemas.base_schemas.CovarianceInfo) with simultaneously very low or zero noise, the condition number of the GPP’s covariance matrix can be very large. The matrix may even become numerically singular.

In such cases, check for (nearly) duplicates points and be mindful of large length scales.

Warning

0 noise_variance in the input historical data may lead to [numerically] singular covariance matrices. This becomes more likely as num_sampled increases. Noise caps the condition number at roughly 1.0 / min(noise), so adding artificial noise (e.g., 1.0e-12) can aid with conditioning issues.

MOE does not do this for you automatically since 0 noise may be extremely important for some users.

Note

MOE performs best if the input points_sampled_value are 0 mean.

Required fields

Variables:points_sampled – (list of PointsSampled) The moe.views.schemas.base_schemas.PointsSampled (point, value, noise) that make up the historical data.
class moe.views.schemas.base_schemas.GradientDescentParametersSchema(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

Parameters for the gradient descent optimizer.

See moe.optimal_learning.python.cpp_wrappers.optimization.GradientDescentParameters

class moe.views.schemas.base_schemas.LBFGSBParametersSchema(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

Parameters for the L-BFGS-B optimizer.

See moe.optimal_learning.python.python_version.optimization.LBFGSBParameters

class moe.views.schemas.base_schemas.ListOfExpectedImprovements(*args, **kw)[source]

Bases: colander.SequenceSchema

A list of floats all geq 0.0.

class moe.views.schemas.base_schemas.ListOfFloats(*args, **kw)[source]

Bases: colander.SequenceSchema

Colander list of floats.

class moe.views.schemas.base_schemas.ListOfPointsInDomain(*args, **kw)[source]

Bases: colander.SequenceSchema

A list of lists of floats.

class moe.views.schemas.base_schemas.ListOfPositiveFloats(*args, **kw)[source]

Bases: colander.SequenceSchema

Colander list of positive floats.

class moe.views.schemas.base_schemas.MVNDSTParametersSchema(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

Parameters for mvndst within qEI (moe.optimal_learning.python.python_version.expected_improvement.ExpectedImprovement._compute_expected_improvement_qd_analytic()).

See moe.optimal_learning.python.python_version.expected_improvement.MVNDSTParameters

class moe.views.schemas.base_schemas.MatrixOfFloats(*args, **kw)[source]

Bases: colander.SequenceSchema

A 2d list of floats.

class moe.views.schemas.base_schemas.NewtonParametersSchema(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

Parameters for the newton optimizer.

See moe.optimal_learning.python.cpp_wrappers.optimization.NewtonParameters

class moe.views.schemas.base_schemas.NullParametersSchema(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

Parameters for the null optimizer.

moe.views.schemas.base_schemas.OPTIMIZER_TYPES_TO_SCHEMA_CLASSES = {'null_optimizer': <class 'moe.views.schemas.base_schemas.NullParametersSchema'>, 'l_bfgs_b_optimizer': <class 'moe.views.schemas.base_schemas.LBFGSBParametersSchema'>, 'newton_optimizer': <class 'moe.views.schemas.base_schemas.NewtonParametersSchema'>, 'gradient_descent_optimizer': <class 'moe.views.schemas.base_schemas.GradientDescentParametersSchema'>}

Mapping from optimizer types (moe.optimal_learning.python.constant.OPTIMIZER_TYPES) to optimizer schemas, e.g., moe.views.schemas.base_schemas.NewtonParametersSchema.

class moe.views.schemas.base_schemas.OptimizerInfo(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

Schema specifying the behavior of the multistarted optimizers in the optimal_learning library.

Note

This schema does not provide default values for its fields. These defaults *DO EXIST*; see moe.optimal_learning.python.constant. However the defaults are dependent on external factors (like whether we’re computing EI, log marginal, etc.) and are not known statically.

See moe.views.optimizable_gp_pretty_view.OptimizableGpPrettyView.get_params_from_request() for an example of how this schema is used.

Note

The field optimizer_parameters is *NOT VALIDATED*. Users of this schema are responsible for passing its contents through the appropriate schema using the moe.views.schemas.base_schemas.OPTIMIZER_TYPES_TO_SCHEMA_CLASSES dict provided above.

TODO(GH-303): Try schema bindings as a way to automate setting validators and missing values.

Optional fields

Variables:
  • optimizer_type – (str) the optimization type from moe.optimal_learning.python.constant.OPTIMIZER_TYPES (default: GRADIENT_DESCENT_OPTIMIZER)
  • num_multistarts – (int > 0) number of locations from which to start optimization runs
  • num_random_samples – (int >= 0) number of random search points to use if multistart optimization fails
  • optimizer_parameters – (dict) a dict corresponding the the parameters of the optimization method
class moe.views.schemas.base_schemas.PointsSampled(*args, **kw)[source]

Bases: colander.SequenceSchema

A list of SinglePoint objects.

class moe.views.schemas.base_schemas.PositiveFloat(*arg, **kw)[source]

Bases: colander.SchemaNode

Colander positive (finite) float.

schema_type

alias of Float

title = 'Positive Float'
validator(node, cstruct)[source]

Raise an exception if the node value (cstruct) is non-positive or non-finite.

Parameters:
  • node (colander.SchemaNode subclass instance) – the node being validated (usually self)
  • cstruct (float) – the value being validated
Raise:

colander.Invalid if cstruct value is bad
class moe.views.schemas.base_schemas.SinglePoint(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A point object.

Required fields

Variables:
  • point – (moe.views.schemas.base_schemas.ListOfFloats) The point sampled (in the domain of the function)
  • value – (float64) The value returned by the function
  • value_var – (float64 >= 0.0) The noise/measurement variance (if any) associated with value
class moe.views.schemas.base_schemas.StrictMappingSchema(*arg, **kw)[source]

Bases: colander.Schema

A colander.MappingSchema that raises exceptions when asked to serialize/deserialize unknown keys.

Note

by default, colander.MappingSchema ignores/throws out unknown keys.

schema_type(**kw)[source]

Set MappingSchema to raise colander.Invalid when serializing/deserializing unknown keys.

This overrides the staticmethod of the same name in colander._SchemaNode. schema_type encodes the same information as the typ ctor argument to colander.SchemaNode See: http://colander.readthedocs.org/en/latest/api.html#colander.SchemaNode

Note

Passing typ or setting schema_type in subclasses will *override* this!

This solution follows: https://github.com/Pylons/colander/issues/116

Note

colander’s default behavior is unknown='ignore'; the other option is 'preserve'. See: http://colander.readthedocs.org/en/latest/api.html#colander.Mapping

moe.views.schemas.gp_next_points_pretty_view module

Base request/response schemas for gp_next_points_* endpoints; e.g., moe.views.rest.gp_next_points_epi.GpNextPointsEpi.

class moe.views.schemas.gp_next_points_pretty_view.GpNextPointsRequest(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A request colander schema for the various subclasses of moe.views.gp_next_points_pretty_view.GpNextPointsPrettyView; e.g., moe.views.rest.gp_next_points_epi.GpNextPointsEpi.

Warning

Requesting num_to_sample > num_sampled can lead to singular GP-variance matrices and other conditioning issues (e.g., the resulting points may be tightly clustered). We suggest bootstrapping with a few grid points, random search, etc.

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

Required fields

Variables:

Optional fields

Variables:
  • num_to_sample – (int) number of next points to generate (default: 1)
  • 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
  • covariance_info – (moe.views.schemas.base_schemas.CovarianceInfo) dict of covariance information
  • optimizer_info – (moe.views.schemas.base_schemas.OptimizerInfo) dict of optimizer information
  • points_being_sampled – (list of float64) points in domain being sampled in concurrent experiments (default: [])

General Timing Results

Here are some “broad-strokes” timing results for EI 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, MC = num_mc_iterations, and q = num_to_sample

Note

constant liar, kriging, and EPI (with num_to_sample = 1) all fall under the analytic EI name.

Note

EI optimization times can vary widely as some randomly generated test cases are very “easy.” Thus we give rough ranges.

Analytic EI
dim, N Gradient Descent
3, 20 0.3 - 0.6s
3, 40 0.5 - 1.4s
3, 120 0.8 - 2.9s
6, 20 0.4 - 0.9s
6, 40 1.25 - 1.8s
6, 120 2.9 - 5.0s

We expect this to scale as ~ O(dim) and ~ O(N^3). The O(N^3) only happens once per multistart. Per iteration there’s an O(N^2) dependence but as you can see, the dependence on dim is stronger.

MC EI (N = 20, dim = 3)
q, MC Gradient Descent
2, 10k 50 - 80s
4, 10k 120 - 180s
8, 10k 400 - 580s
2, 40k 230 - 480s
4, 40k 600 - 700s

We expect this to scale as ~ O(q^2) and ~ O(MC). Scaling with dim and N should be similar to the analytic case.

Example Minimal Request

Content-Type: text/javascript

{
    "num_to_sample": 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,
        "domain_bounds": [
            {"min": 0.0, "max": 1.0},
            ],
        },
}

Example Full Request

Content-Type: text/javascript

{
    "num_to_sample": 1,
    "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,
        "domain_bounds": [
            {"min": 0.0, "max": 1.0},
            ],
        },
    "covariance_info": {
        "covariance_type": "square_exponential",
        "hyperparameters": [1.0, 1.0],
        },
    "optimizer_info": {
        "optimizer_type": "gradient_descent_optimizer",
        "num_multistarts": 200,
        "num_random_samples": 4000,
        "optimizer_parameters": {
            "gamma": 0.5,
            ...
            },
        },
}
class moe.views.schemas.gp_next_points_pretty_view.GpNextPointsResponse(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A response colander schema for the various subclasses of moe.views.gp_next_points_pretty_view.GpNextPointsPrettyView; e.g., moe.views.rest.gp_next_points_epi.GpNextPointsEpi.

Output fields

Variables:

Example Response

{
    "endpoint": "gp_ei",
    "points_to_sample": [["0.478332304526"]],
    "status": {
        "expected_improvement": "0.443478498868",
        "optimizer_success": {
            'gradient_descent_tensor_product_domain_found_update': True,
            },
        },
}
class moe.views.schemas.gp_next_points_pretty_view.GpNextPointsStatus(*arg, **kw)[source]

Bases: moe.views.schemas.base_schemas.StrictMappingSchema

A status schema for the various subclasses of moe.views.gp_next_points_pretty_view.GpNextPointsPrettyView; e.g., moe.views.rest.gp_next_points_epi.GpNextPointsEpi.

Output fields

Variables:

Module contents

Request/Response schemas for the MOE REST interface and associated building blocks.

Contains:

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!