StudySpec

Stay organized with collections Save and categorize content based on your preferences.

Represents specification of a Study.

JSON representation 
{
  "metrics": [
    {
      object (MetricSpec)
    }
  ],
  "parameters": [
    {
      object (ParameterSpec)
    }
  ],
  "algorithm": enum (Algorithm),
  "observationNoise": enum (ObservationNoise),
  "measurementSelectionType": enum (MeasurementSelectionType),

  // Union field automated_stopping_spec can be only one of the following:
  "decayCurveStoppingSpec": {
    object (DecayCurveAutomatedStoppingSpec)
  },
  "medianAutomatedStoppingSpec": {
    object (MedianAutomatedStoppingSpec)
  },
  "convexStopConfig": {
    object (ConvexStopConfig)
  },
  "convexAutomatedStoppingSpec": {
    object (ConvexAutomatedStoppingSpec)
  }
  // End of list of possible types for union field automated_stopping_spec.
}
Fields
metrics[]

object (MetricSpec)

Required. 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.
observationNoise

enum (ObservationNoise)

The observation noise level of the study. Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline.
measurementSelectionType

enum (MeasurementSelectionType)

Describe which measurement selection type will be used

Union field automated_stopping_spec.

automated_stopping_spec can be only one of the following:
decayCurveStoppingSpec

object (DecayCurveAutomatedStoppingSpec)

The automated early stopping spec using decay curve rule.
medianAutomatedStoppingSpec

object (MedianAutomatedStoppingSpec)

The automated early stopping spec using median rule.
convexStopConfig
(deprecated)

object (ConvexStopConfig)

Deprecated. The automated early stopping using convex stopping rule.
convexAutomatedStoppingSpec

object (ConvexAutomatedStoppingSpec)

The automated early stopping spec using convex stopping rule.

DecayCurveAutomatedStoppingSpec

The decay curve automated stopping rule builds a Gaussian Process Regressor to predict the final objective value of a Trial based on the already completed Trials and the intermediate measurements of the current Trial. Early stopping is requested for the current Trial if there is very low probability to exceed the optimal value found so far.

JSON representation 
{
  "useElapsedDuration": boolean
}
Fields
useElapsedDuration

boolean

True if Measurement.elapsed_duration is used as the x-axis of each Trials Decay Curve. Otherwise, Measurement.step_count will be used as the x-axis.

MedianAutomatedStoppingSpec

The median automated stopping rule stops a pending Trial if the Trial's best objective_value 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 
{
  "useElapsedDuration": boolean
}
Fields
useElapsedDuration

boolean

True if median automated stopping rule applies on Measurement.elapsed_duration. It means that elapsedDuration field of latest measurement of current Trial is used to compute median objective value for each completed Trials.

ConvexStopConfig

Configuration for ConvexStopPolicy.

JSON representation 
{
  "maxNumSteps": string,
  "minNumSteps": string,
  "autoregressiveOrder": string,
  "learningRateParameterName": string,
  "useSeconds": boolean
}
Fields
maxNumSteps

string (int64 format)

Steps used in predicting the final objective for early stopped trials. In general, it's set to be the same as the defined steps in training / tuning. When use_steps is false, this field is set to the maximum elapsed seconds.
minNumSteps

string (int64 format)

Minimum number of steps for a trial to complete. Trials which do not have a measurement with num_steps > minNumSteps won't be considered for early stopping. It's ok to set it to 0, and a trial can be early stopped at any stage. By default, minNumSteps is set to be one-tenth of the maxNumSteps. When use_steps is false, this field is set to the minimum elapsed seconds.
autoregressiveOrder

string (int64 format)

The number of Trial measurements used in autoregressive model for value prediction. A trial won't be considered early stopping if has fewer measurement points.
learningRateParameterName

string

The hyper-parameter name used in the tuning job that stands for learning rate. Leave it blank if learning rate is not in a parameter in tuning. The learning_rate is used to estimate the objective value of the ongoing trial.
useSeconds

boolean

This bool determines whether or not the rule is applied based on elapsed_secs or steps. If useSeconds==false, the early stopping decision is made according to the predicted objective values according to the target steps. If useSeconds==true, elapsed_secs is used instead of steps. Also, in this case, the parameters maxNumSteps and minNumSteps are overloaded to contain max_elapsed_seconds and min_elapsed_seconds.

ConvexAutomatedStoppingSpec

Configuration for ConvexAutomatedStoppingSpec. When there are enough completed trials (configured by minMeasurementCount), for pending trials with enough measurements and steps, the policy first computes an overestimate of the objective value at maxNumSteps according to the slope of the incomplete objective value curve. No prediction can be made if the curve is completely flat. If the overestimation is worse than the best objective value of the completed trials, this pending trial will be early-stopped, but a last measurement will be added to the pending trial with maxNumSteps and predicted objective value from the autoregression model.

JSON representation 
{
  "maxStepCount": string,
  "minStepCount": string,
  "minMeasurementCount": string,
  "learningRateParameterName": string,
  "useElapsedDuration": boolean
}
Fields
maxStepCount

string (int64 format)

Steps used in predicting the final objective for early stopped trials. In general, it's set to be the same as the defined steps in training / tuning. If not defined, it will learn it from the completed trials. When use_steps is false, this field is set to the maximum elapsed seconds.
minStepCount

string (int64 format)

Minimum number of steps for a trial to complete. Trials which do not have a measurement with stepCount > minStepCount won't be considered for early stopping. It's ok to set it to 0, and a trial can be early stopped at any stage. By default, minStepCount is set to be one-tenth of the maxStepCount. When useElapsedDuration is true, this field is set to the minimum elapsed seconds.
minMeasurementCount

string (int64 format)

The minimal number of measurements in a Trial. Early-stopping checks will not trigger if less than minMeasurementCount+1 completed trials or pending trials with less than minMeasurementCount measurements. If not defined, the default value is 5.
learningRateParameterName

string

The hyper-parameter name used in the tuning job that stands for learning rate. Leave it blank if learning rate is not in a parameter in tuning. The learning_rate is used to estimate the objective value of the ongoing trial.
useElapsedDuration

boolean

This bool determines whether or not the rule is applied based on elapsed_secs or steps. If useElapsedDuration==false, the early stopping decision is made according to the predicted objective values according to the target steps. If useElapsedDuration==true, elapsed_secs is used instead of steps. Also, in this case, the parameters maxNumSteps and minNumSteps are overloaded to contain max_elapsed_seconds and min_elapsed_seconds.

MetricSpec

Represents a metric to optimize.

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

string

Required. The ID of the metric. Must not contain whitespaces and must be unique amongst all MetricSpecs.
goal

enum (GoalType)

Required. The optimization goal 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 
{
  "parameterId": string,
  "scaleType": enum (ScaleType),
  "conditionalParameterSpecs": [
    {
      object (ConditionalParameterSpec)
    }
  ],

  // 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.
}
Fields
parameterId

string

Required. The ID of the parameter. Must not contain whitespaces and must be unique amongst all ParameterSpecs.
scaleType

enum (ScaleType)

How the parameter should be scaled. Leave unset for CATEGORICAL parameters.
conditionalParameterSpecs[]

object (ConditionalParameterSpec)

A conditional parameter node is active if the parameter's value matches the conditional node's parent_value_condition.

If two items in conditionalParameterSpecs have the same name, they must have disjoint parent_value_condition.

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.

DoubleValueSpec

Value specification for a parameter in DOUBLE type.

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

number

Required. Inclusive minimum value of the parameter.
maxValue

number

Required. Inclusive maximum value of the parameter.
defaultValue

number

A default value for a DOUBLE parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point.

Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline.

IntegerValueSpec

Value specification for a parameter in INTEGER type.

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

string (int64 format)

Required. Inclusive minimum value of the parameter.
maxValue

string (int64 format)

Required. Inclusive maximum value of the parameter.
defaultValue

string (int64 format)

A default value for an INTEGER parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point.

Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline.

CategoricalValueSpec

Value specification for a parameter in CATEGORICAL type.

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

string

Required. The list of possible categories.
defaultValue

string

A default value for a CATEGORICAL parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point.

Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline.

DiscreteValueSpec

Value specification for a parameter in DISCRETE type.

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

number

Required. A list of possible values. The list should be in increasing order and at least 1e-10 apart. 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.
defaultValue

number

A default value for a DISCRETE parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point. It automatically rounds to the nearest feasible discrete point.

Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline.

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.

ConditionalParameterSpec

Represents a parameter spec with condition from its parent parameter.

JSON representation 
{
  "parameterSpec": {
    object (ParameterSpec)
  },

  // Union field parent_value_condition can be only one of the following:
  "parentDiscreteValues": {
    object (DiscreteValueCondition)
  },
  "parentIntValues": {
    object (IntValueCondition)
  },
  "parentCategoricalValues": {
    object (CategoricalValueCondition)
  }
  // End of list of possible types for union field parent_value_condition.
}
Fields
parameterSpec

object (ParameterSpec)

Required. The spec for a conditional parameter.
Union field parent_value_condition. A set of parameter values from the parent ParameterSpec's feasible space. parent_value_condition can be only one of the following:
parentDiscreteValues

object (DiscreteValueCondition)

The spec for matching values from a parent parameter of DISCRETE type.
parentIntValues

object (IntValueCondition)

The spec for matching values from a parent parameter of INTEGER type.
parentCategoricalValues

object (CategoricalValueCondition)

The spec for matching values from a parent parameter of CATEGORICAL type.

DiscreteValueCondition

Represents the spec to match discrete values from parent parameter.

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

number

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

The Epsilon of the value matching is 1e-10.

IntValueCondition

Represents the spec to match integer values from parent parameter.

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

string (int64 format)

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

CategoricalValueCondition

Represents the spec to match categorical values from parent parameter.

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

string

Required. Matches values of the parent parameter of 'CATEGORICAL' type. 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 Vertex AI for hyperparameter tuning and Vertex AI Vizier.

ObservationNoise

Describes the noise level of the repeated observations.

"Noisy" means that the repeated observations with the same Trial parameters may lead to different metric evaluations.

Enums
OBSERVATION_NOISE_UNSPECIFIED The default noise level chosen by Vertex AI.
LOW Vertex AI assumes that the objective function is (nearly) perfectly reproducible, and will never repeat the same Trial parameters.
HIGH Vertex AI will estimate the amount of noise in metric evaluations, it may repeat the same Trial parameters more than once.

MeasurementSelectionType

This indicates which measurement to use if/when the service automatically selects the final measurement from previously reported intermediate measurements. Choose this based on two considerations: A) Do you expect your measurements to monotonically improve? If so, choose LAST_MEASUREMENT. On the other hand, if you're in a situation where your system can "over-train" and you expect the performance to get better for a while but then start declining, choose BEST_MEASUREMENT. B) Are your measurements significantly noisy and/or irreproducible? If so, BEST_MEASUREMENT will tend to be over-optimistic, and it may be better to choose LAST_MEASUREMENT. If both or neither of (A) and (B) apply, it doesn't matter which selection type is chosen.

Enums
MEASUREMENT_SELECTION_TYPE_UNSPECIFIED Will be treated as LAST_MEASUREMENT.
LAST_MEASUREMENT Use the last measurement reported.
BEST_MEASUREMENT Use the best measurement reported.