REST Resource: projects.locations.studies

Resource: Study

A message representing a Study.

JSON representation
{
  "name": string,
  "studyConfig": {
    object (StudyConfig)
  },
  "state": enum (State),
  "createTime": string,
  "inactiveReason": string
}
Fields
name

string

Output only. The name of a study.

studyConfig

object (StudyConfig)

Required. Configuration of the study.

state

enum (State)

Output only. The detailed state of a study.

createTime

string (Timestamp format)

Output only. Time at which the study was created.

inactiveReason

string

Output only. A human readable reason why the Study is inactive. This should be empty if a study is ACTIVE or COMPLETED.

StudyConfig

Represents configuration of a study.

JSON representation
{
  "metrics": [
    {
      object (MetricSpec)
    }
  ],
  "parameters": [
    {
      object (ParameterSpec)
    }
  ],
  "algorithm": enum (Algorithm),
  "automatedStoppingConfig": {
    object (AutomatedStoppingConfig)
  }
}
Fields
metrics[]

object (MetricSpec)

Metric specs for the study.

parameters[]

object (ParameterSpec)

Required. The set of parameters to tune.

algorithm

enum (Algorithm)

The search algorithm specified for the study.

automatedStoppingConfig

object (AutomatedStoppingConfig)

Configuration for automated stopping of unpromising Trials.

MetricSpec

Represents a metric to optimize.

JSON representation
{
  "goal": enum (GoalType),
  "metric": string
}
Fields
goal

enum (GoalType)

Required. The optimization goal of the metric.

metric

string

Required. The name of the metric.

GoalType

The available types of optimization goals.

Enums
GOAL_TYPE_UNSPECIFIED Goal Type will default to maximize.
MAXIMIZE Maximize the goal metric.
MINIMIZE Minimize the goal metric.

ParameterSpec

Represents a single parameter to optimize.

JSON representation
{
  "parameter": string,
  "type": enum (ParameterType),
  "scaleType": enum (ScaleType),
  "childParameterSpecs": [
    {
      object (ParameterSpec)
    }
  ],

  // Union field parameter_value_spec can be only one of the following:
  "doubleValueSpec": {
    object (DoubleValueSpec)
  },
  "integerValueSpec": {
    object (IntegerValueSpec)
  },
  "categoricalValueSpec": {
    object (CategoricalValueSpec)
  },
  "discreteValueSpec": {
    object (DiscreteValueSpec)
  }
  // End of list of possible types for union field parameter_value_spec.

  // Union field matching_parent_values can be only one of the following:
  "parentDiscreteValues": {
    object (MatchingParentDiscreteValueSpec)
  },
  "parentIntValues": {
    object (MatchingParentIntValueSpec)
  },
  "parentCategoricalValues": {
    object (MatchingParentCategoricalValueSpec)
  }
  // End of list of possible types for union field matching_parent_values.
}
Fields
parameter

string

Required. The parameter name must be unique amongst all ParameterSpecs.

type

enum (ParameterType)

Required. The type of the parameter.

scaleType

enum (ScaleType)

How the parameter should be scaled. Leave unset for categorical parameters.

childParameterSpecs[]

object (ParameterSpec)

A child node is active if the parameter's value matches the child node's matching_parent_values.

If two items in childParameterSpecs have the same name, they must have disjoint matching_parent_values.

Union field parameter_value_spec.

parameter_value_spec can be only one of the following:

doubleValueSpec

object (DoubleValueSpec)

The value spec for a 'DOUBLE' parameter.

integerValueSpec

object (IntegerValueSpec)

The value spec for an 'INTEGER' parameter.

categoricalValueSpec

object (CategoricalValueSpec)

The value spec for a 'CATEGORICAL' parameter.

discreteValueSpec

object (DiscreteValueSpec)

The value spec for a 'DISCRETE' parameter.

Union field matching_parent_values. A set of Parameter values from the parent ParameterSpec's feasible space. One of these must be set if this ParameterSpec is a child of another ParameterSpec. matching_parent_values can be only one of the following:
parentDiscreteValues

object (MatchingParentDiscreteValueSpec)

parentIntValues

object (MatchingParentIntValueSpec)

parentCategoricalValues

object (MatchingParentCategoricalValueSpec)

ParameterType

The type of the parameter.

Enums
PARAMETER_TYPE_UNSPECIFIED You must specify a valid type. Using this unspecified type will result in an error.
DOUBLE Type for real-valued parameters.
INTEGER Type for integral parameters.
CATEGORICAL The parameter is categorical, with a value chosen from the categories field.
DISCRETE The parameter is real valued, with a fixed set of feasible points. If type==DISCRETE, feasible_points must be provided, and {minValue, maxValue} will be ignored.

DoubleValueSpec

JSON representation
{
  "minValue": number,
  "maxValue": number
}
Fields
minValue

number

Must be specified if type is DOUBLE. Minimum value of the parameter.

maxValue

number

Must be specified if type is DOUBLE. Maximum value of the parameter.

IntegerValueSpec

JSON representation
{
  "minValue": string,
  "maxValue": string
}
Fields
minValue

string (int64 format)

Must be specified if type is INTEGER. Minimum value of the parameter.

maxValue

string (int64 format)

Must be specified if type is INTEGER. Maximum value of the parameter.

CategoricalValueSpec

JSON representation
{
  "values": [
    string
  ]
}
Fields
values[]

string

Must be specified if type is CATEGORICAL. The list of possible categories.

DiscreteValueSpec

JSON representation
{
  "values": [
    number
  ]
}
Fields
values[]

number

Must be specified if type is DISCRETE. A list of feasible points. The list should be in strictly increasing order. For instance, this parameter might have possible settings of 1.5, 2.5, and 4.0. This list should not contain more than 1,000 values.

ScaleType

The type of scaling that should be applied to this parameter.

Enums
SCALE_TYPE_UNSPECIFIED By default, no scaling is applied.
UNIT_LINEAR_SCALE Scales the feasible space to (0, 1) linearly.
UNIT_LOG_SCALE Scales the feasible space logarithmically to (0, 1). The entire feasible space must be strictly positive.
UNIT_REVERSE_LOG_SCALE Scales the feasible space "reverse" logarithmically to (0, 1). The result is that values close to the top of the feasible space are spread out more than points near the bottom. The entire feasible space must be strictly positive.

MatchingParentDiscreteValueSpec

Represents the spec to match discrete values from parent parameter.

JSON representation
{
  "values": [
    number
  ]
}
Fields
values[]

number

Matches values of the parent parameter with type 'DISCRETE'. All values must exist in discreteValueSpec of parent parameter.

MatchingParentIntValueSpec

Represents the spec to match integer values from parent parameter.

JSON representation
{
  "values": [
    string
  ]
}
Fields
values[]

string (int64 format)

Matches values of the parent parameter with type 'INTEGER'. All values must lie in integerValueSpec of parent parameter.

MatchingParentCategoricalValueSpec

Represents the spec to match categorical values from parent parameter.

JSON representation
{
  "values": [
    string
  ]
}
Fields
values[]

string

Matches values of the parent parameter with type 'CATEGORICAL'. All values must exist in categoricalValueSpec of parent parameter.

Algorithm

The available search algorithms for the study.

Enums
ALGORITHM_UNSPECIFIED The default algorithm used by the Cloud AI Platform Optimization service.
GAUSSIAN_PROCESS_BANDIT Gaussian Process Bandit.

AutomatedStoppingConfig

Configuration for Automated Early Stopping of Trials. If no implementation_config is set, automated early stopping will not be run.

JSON representation
{

  // Union field automated_stopping_config can be only one of the following:
  "decayCurveStoppingConfig": {
    object (DecayCurveAutomatedStoppingConfig)
  },
  "medianAutomatedStoppingConfig": {
    object (MedianAutomatedStoppingConfig)
  }
  // End of list of possible types for union field automated_stopping_config.
}
Fields

Union field automated_stopping_config.

automated_stopping_config can be only one of the following:

decayCurveStoppingConfig

object (DecayCurveAutomatedStoppingConfig)

medianAutomatedStoppingConfig

object (MedianAutomatedStoppingConfig)

DecayCurveAutomatedStoppingConfig

JSON representation
{
  "useElapsedTime": boolean
}
Fields
useElapsedTime

boolean

If true, measurement.elapsed_time is used as the x-axis of each Trials Decay Curve. Otherwise, Measurement.steps will be used as the x-axis.

MedianAutomatedStoppingConfig

The median automated stopping rule stops a pending trial if the trial's best objectiveValue is strictly below the median 'performance' of all completed trials reported up to the trial's last measurement. Currently, 'performance' refers to the running average of the objective values reported by the trial in each measurement.

JSON representation
{
  "useElapsedTime": boolean
}
Fields
useElapsedTime

boolean

If true, the median automated stopping rule applies to measurement.use_elapsed_time, which means the elapsedTime field of the current trial's latest measurement is used to compute the median objective value for each completed trial.

State

Describes the study state.

Enums
STATE_UNSPECIFIED The study state is unspecified.
ACTIVE The study is active.
INACTIVE The study is stopped due to an internal error.
COMPLETED The study is done when the service exhausts the parameter search space or maxTrialCount is reached.

Methods

create

Creates a study.

delete

Deletes a study.

get

Gets a study.

list

Lists all the studies in a region for an associated project.