Configuration

The configuration of CTLearn Optimizer is stored in a YAML configuration file, every available settings and its possible values are listed and explained in detail in subsequent sections.

General settings

Required

True

Type

dict

Key

General_settings

Valid keys

num_cpus, num_gpus, num_cpus_per_trial, num_gpus_per_trial, num_parallel_trials, optimization_type, mode, working_directory, ctlearn_config, n_initial_points, num_max_evals, random_state, remove_training_folders, reload_trials, reload_optimization_results, predict, data_set_to_optimize, metrics_val_to_log, metrics_pred_to_log, metric_to_optimize, user_defined_metric_val, user_defined_metric_pred

num_cpus

Number of cpu cores the user wishes the optimizer to be configured with.

Required

True

Type

int

num_gpus

Number of gpus the user wishes the optimizer to be configured with.

Required

True

Type

int

num_cpus_per_trial

Number of cpu cores to allocate per trial.

Required

True

Type

int

Recommended value

num_cpus / num_parallel_trials

num_gpus_per_trial

Number of gpus to allocate per trial.

Required

True

Type

int

Recommended value

1

num_parallel_trials

Number of maximum concurrent trials.

Required

False

Type

int

Default

1

Note

Obviously, num_cpus and num_gpus must be greater than num_cpus_per_trial and num_gpus_per_trial in order to run parallel trials. For example, if num_parallel_trials is set to 2, then num_cpus and num_gpus must be at least double the num_cpus_per_trial and num_gpus_per_trial respectively.

Note

This setting won’t be used if optimization_type is genetic_algorithm. See Optimizer settings section for more details.

Caution

Setting this option to a value greater than the default is highly RAM and CPU consuming. Make sure you have enough hardware resources.

optimization_type

Optimization algorithm to use.

Required

True

Type

str

Valid options

tree_parzen_estimators, random_search, gaussian_processes, genetic_algorithm

mode

Whether to maximize or minimize the metric.

Required

False

Type

str

Valid options

max, min

Default

max

working_directory

Path to the optimizer working directory.

Required

False

Type

path

Default

current directory path

Recommended value

Default

ctlearn_config

Name of the CTLearn configuration file stored in the working_directory.

Required

True

Type

str

n_initial_points

Number of initial random evaluations of the objective before starting approximate it with the surrogate model.

Required

False

Type

int

Default

30

Note

This setting won’t be used if optimization_type is genetic_algorithm or random_search.

num_max_evals

Number of evaluations of the objective function.

Required

True

Type

int

Note

This setting won’t be used if optimization_type is genetic_algorithm. See Genetic algorithm settings section for more details.

random_state

Set this option to something other than None for reproducible results.

Required

False

Type

int, None

Default

None

Note

This setting won’t be used if optimization_type is genetic_algorithm.

remove_training_folders

Determine whether to remove the logging folders generated by CTLearn. This option is useful for avoiding disk space issues in long optimization runs.

Required

False

Type

bool

Default

True

reload_trials

Set this option to True for loading trials of a past run from working_directory/trials.pkl. This option allows to resume a past optimization run.

Required

False

Type

bool

Default

False

reload_optimization_results

Set this option to True for loading the optimization results file of a past run from working_directory/optimization_results.csv.

Required

False

Type

bool

Default

False

Note

Use this setting in conjunction with reload_trials.

predict

Whether to predict using the trained CTLearn model.

Required

False

Type

bool

Default

False

data_set_to_optimize

Data set to optimize.

Required

False

Type

str

Valid options

validation, prediction

Default

validation

Note

If this option is set to validation, predict must be set to True.

metrics_val_to_log

Validation set metrics to log to the optimization results file.

Required

False

Type

list of str

Valid options

auc, accuracy, accuracy_gamma, accuracy_proton, loss, <user_defined_metric_val/label>

Default

[]

Example
metrics_val_to_log: ['auc', 'dummy_val_metric']

Note

It is required to log at least the metric_to_optimize, _val will be appended to each metric label logged.

metrics_pred_to_log

Prediction set metrics to log to the optimization results file.

Required

False

Type

list of str

Valid options

auc, accuracy, balanced_accuracy, f1, precision, recall, log_loss <user_defined_metric_pred/label>

Default

[]

Example
metrics_val_to_log: ['f1', 'dummy_pred_metric']

Note

It is required to log at least the metric_to_optimize, _pred will be appended to each metric label logged.

Note

This setting will only be used if predict is True.

metric_to_optimize

Metric to optimize label.

Required

True

Type

str

Valid options

Any label included in metrics_val_to_log or metrics_pred_to_log.

user_defined_metric_val

Configuration of the user defined metric to be computed on the validation set.

Required

False

Type

dict

Valid keys

label, expression

Default

None

Example
user_defined_metric_val:
  label: 'dummy_val_metric'
  expression: '(auc + accuracy_gamma)*0.5'

label

metric label.

Required

True

Type

str

expression

Expression to be computed. This expression has access to auc, accuracy, accuracy_gamma, accuracy_proton and loss (from validation set).

Required

True

Type

str

Caution

This expression is computed by passing it to Python eval() method.

user_defined_metric_pred

Configuration of the user defined metric to be computed on the prediction set.

Required

False

Type

dict

Valid keys

label, expression

Default

None

Example
user_defined_metric_val:
  label: 'dummy_pred_metric'
  expression: '(f1 + sklearn.metrics.balanced_accuracy_score(labels, predicted_class))*0.5'

label

Metric label.

Required

True

Type

str

expression

Expression to be computed. This expression has access to auc, accuracy, balanced_accuracy, f1, precision, recall and log_loss (from prediction set). Besides, this expression also has access to labels, gamma_classifier_values and predicted_class values and sklearn.metrics module.

Required

True

Type

str

Caution

This expression is computed by passing it to Python eval() method.

Optimizer settings

Required

True if optimization_type is genetic_algorithm, else False.

Type

dict

Key

Optimizer_settings

Valid keys

tree_parzen_estimators_config, gaussian_processes_config, genetic_algorithm_config

Default

None

tree_parzen_estimators_config

Configuration of the tree parzen estimators based optimization.

Required

False

Type

dict

Valid keys

gamma

Default

None

Note

This setting will only be used if optimization_type is tree_parzen_estimators.

gamma

Instead of modeling the probability \(p(y|λ)\) of observations \(y\) given the configurations \(λ\), the tree parzen estimator models density functions \(p(λ|y < \gamma)\) and \(p(λ|y ≥ \gamma)\). Given a percentile \(\gamma\), the observations are divided in good observations and bad observations and simple 1-d Parzen windows are used to model the two distributions. By using \(p(λ|y < \gamma)\) and \(p(λ|y ≥ \gamma)\) one can estimate the Expected Improvement (EI) of a given run.

Take a look at this paper, section 4, for further information.

Required

False

Type

float

Valid values

Any float in range (0,1).

Default

0.25

Recommend value

Default

gaussian_processes_config

Configuration of the gaussian processes based optimization.

Required

False

Type

dict

Valid keys

base_estimator, acq_function, acq_optimizer, xi, kappa

Default

None

Note

This setting will only be used if optimization_type is gaussian_processes.

base_estimator

Surrogate model to use. It provide predictions on many hyperparameter sets, then the next best point is chosen based on the acquisition function. Available options:

  • Gaussian Processes (GP).

  • Random Forests (RF).

  • Extended Trees (ET).

  • Gradient Boosted Trees (GBRT).

    Required

    False

    Type

    str

    Valid options

    GP, RF, ET, GBRT

    Default

    GP

acq_function`

Acquisition function to use. This function is used to decide which hyperparameters combination is the most promising to try next according to the surrogate model. Available options:

  • Lower Confidence Bound (LCB).

  • Negative Expected Improvement (EI).

  • Negative Probability of Improvement (PI).

  • gp_hedge: probabilistically choose one of the previous three acquisition functions at every iteration.

    Required

    False

    Type

    str

    Valid options

    LCB, EI, PI, gp_hedge

    Default

    gp_hedge

    Recommend value

    Default

acq_optimizer`

Method to optimize the acquisition function, the base_estimator model is updated with the optimal value obtained by optimizing acq_func with acq_optimizer. The adquisition function is computed at a specific number of points sampled randomly in the search space.

  • Sampling: the point where the adquisition function is minimum is selected.

  • Lbfgs: this algorithm takes some number of the best randomly tried points, then, using this points as initial points, lbfgs is run for 20 iterations to find local minima, finally, the optimal of these local minima is used to update the prior.

  • Auto: acq_optimizer is configured on the basis of the base_estimator and the space searched over.

    Required

    False

    Type

    str

    Valid options

    sampling, lbfgs, auto

    Default

    auto

    Recommend value

    Default

xi

Controls how much improvement the user wants over the previous best values. The higher this value is, the bigger the improvement is expected.

Required

False

Type

float

Default

0.01

Recommend value

Default

Note

This setting will only be used when acq_function is either EI or PI.

kappa

Controls how much of the variance in the predicted values should be taken into account. The higher this value is, the more we are favouring exploration over exploitation, and vice versa.

Required

False

Type

float

Default

1.96

Recommend value

Default

Note

This setting will only be used when acq_function is LCB or PI.

genetic_algorithm_config

Configuration of the genetic algorithm based optimization.

Required

True if optimization_type is genetic_algorithm, else False.

Type

dict

Valid keys

max_generation, population_size, population_decay, keep_top_ratio, kappa

Default

None

Note

This setting will only be used if optimization_type is genetic_algorithm.

Note

This method is inherently parallel. Therefore, it doesn’t make sense to apply it without enought hardware resources to run several trials at the same time. The same advices given in num_parallel_trials apply in this case.

max_generation

Maximum iteration number of genetic search.

Required

True

Type

int

population_size

Number of trials of the initial generation. This value is a kind of equivalent of num_parallel_trials.

Required

True

Type

int

population_decay

Decay ratio of population size for the next generation.

Required

False

Type

float

Valid values

Any float in range (0,1).

Default

0.95

Recommend value

Default

keep_top_ratio

Ratio of the top performance population.

Required

False

Type

float

Valid values

Any float in range (0,1).

Default

0.2

Recommend value

Default

selection_bound

Threshold for performing selection.

Required

False

Type

float

Valid values

Any float in range (0,1).

Default

0.4

Recommend value

Default

crossover_bound

Threshold for performing crossover.

Required

False

Type

float

Valid values

Any float in range (0,1).

Default

0.4

Recommend value

Default

CTLearn settings

These are CTLearn related configuration options that have been included in this package in order to improve its functionality and ease of use. The user can refer to CTLearn v0.3.0 example_config file for additional information.

Required

True

Type

dict

Key

CTLearn_settings

Valid keys

seed, num_training_steps_per_validation, num_validations, example_type, model, sorting, min_num_tels, selected_tel_types, training_file_list, prediction_file_list, batch_size, model_directory, validation_split

seed

Seed for randomly splitting data into training and validation sets.

Required

False

Type

int

Default

None

num_validations

Number of validations made before finishing training. If 0, run forever.

Required

True

Type

int

num_training_steps_per_validation

Number of training steps to run before each evaluation on the validation set.

Required

True

Type

int

example_type

How to construct examples from the data.

Required

True

Type

str

Valid options

array, single_tel

model

Required

True

Type

str

Valid options

cnn_rnn, single_tel

Note

If this option is set to cnn_rnn, example_type must be set to array, if this option is set to single_tel, example_type must beset to single_tel.

sorting

How to sort telescope images when loading data in array mode.

Required

False

Type

str

Valid options

trigger, size, null

Default

null

min_num_tels

Minimum number of triggered telescopes among all selected telescopes (of all types) which must be present for an event to be loaded. Telescopes that aren’t selected don’t count.

Required

False

Type

int

Default

1

selected_tel_types

List of telescope types to load.

Required

True

Type

str

Valid options

LST:LSTCam, MST:FlashCam, MST:NectarCam, SCT:SCTCam SST:DigiCam, ``SST:ASTRICam, SST:CHEC, MST:VERITAS

training_file_list

Path to a file listing data file paths for training, one per line.

Required

True

Type

path

prediction_file_list

Path to a file listing data file paths for prediction, one per line.

Required

True if predict is True, else False.

Type

path

batch_size

Number of examples per batch for training/prediction.

Required

True

Type

int

model_directory

Path to directory containing model module.

Required

False

Type

path

Default

null

Note

Default if null is to load CTLearn default models directory: ctlearn/ctlearn/default_models/.

validation_split

Randomly chosen fraction of data to set aside for validation.

Required

False

Type

float

Default

0.1

Hyperparameters settings

Required

True

Type

dict

Key

Hyperparameters_settings

Valid keys

hyperparameters_to_log, config, fixed_hyperparameters, dependent_hyperparameters, hyperparameters_to_optimize

Note

The choice of the hyperparameter labels in this section is left to the user, but they must be the same in all the subsections.

Below is an example YAML snippet of this section:

hyperparameters_to_log:
  ['number_of_layers', 'layer1_filters','layer2_filters','layer3_filters',
  'layer4_filters','layer1_kernel', 'layer2_kernel', 'layer3_kernel',
  'layer4_kernel']

config:
  layer1_filters: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 0, 'filters']
  layer2_filters: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 1, 'filters']
  layer3_filters: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 2, 'filters']
  layer4_filters: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 3, 'filters']
  layer1_kernel: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 0, 'kernel_size']
  layer2_kernel: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 1, 'kernel_size']
  layer3_kernel: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 2, 'kernel_size']
  layer4_kernel: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 3, 'kernel_size']
  pool_size: ['Model', 'Model Parameters', 'basic', 'conv_block','max_pool','size']
  pool_strides: ['Model', 'Model Parameters', 'basic', 'conv_block','max_pool','strides']
  optimizer_type: ['Training', 'Hyperparameters', 'optimizer']
  base_learning_rate: ['Training', 'Hyperparameters', 'base_learning_rate']
  adam_epsilon: ['Training', 'Hyperparameters', 'adam_epsilon']
  cnn_rnn_dropout: ['Model', 'Model Parameters', 'cnn_rnn', 'dropout_rate']

fixed_hyperparameters:
  pool_size: 2
  pool_strides: 2
  adam_epsilon: 1.0e-08

dependent_hyperparameters:
  layer2_filters: '2 * layer1_filters'
  layer3_filters: '4 * layer1_filters'
  layer4_filters: '8 * layer1_filters'

hyperparameters_to_optimize:
  layer1_filters:
    type: 'quniform'
    range: [16, 64]
    step: 1
  layer1_kernel:
    type: 'quniform'
    range: [2, 10]
    step: 1
  layer2_kernel:
    type: 'quniform'
    range: [2, 10]
    step: 1
  layer3_kernel:
    type: 'quniform'
    range: [2, 10]
    step: 1
  layer4_kernel:
    type: 'quniform'
    range: [2, 10]
    step: 1
  base_learning_rate:
    type: loguniform
    range: [-5, 0]
  optimizer_type:
    type: 'choice'
    range: ['Adadelta', 'Adam', 'RMSProp', 'SGD']
  cnn_rnn_dropout:
    type: 'uniform'
    range: [0,1]

hyperparameters_to_log

Labels of the hyperparameters whose values the user wishes to log to the optimization results file. At least one label is required.

Required

True

Type

list of str

Valid options

<hyperparameter_label>

config

Dictionary containing the path to the hyperparameter configuration field in CTLearn YAML configuration file for each hyperparameter label.

Required

True

Type

dict

Valid keys

<hyperparameter_label>

Note

It is required to detail the configuration of each hyperparameter label used in fixed_hyperparameters, dependent_hyperparameters and hyperparameters_to_optimize sections.

<hyperparameter_label>

Path to the hyperparameter configuration field in CTLearn YAML configuration file.

Required

True

Type

list of str

Example
# CTLearn YAML configuration file

Model:
  Model Parameters:
    basic:
      batchnorm_decay: 0.99
      conv_block:
        batchnorm: false
        bottleneck: null
        layers:
        - {filters: 117, kernel_size: 12}
        - {filters: 234, kernel_size: 10}
        - {filters: 468, kernel_size: 7}
        - {filters: 936, kernel_size: 6}
        max_pool: {size: 2, strides: 2}
    cnn_rnn:
      cnn_block: {function: conv_block, module: basic}
      dropout_rate: 0.5
      pretrained_weights: null

# corresponding config

config:
  layer1_filters: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 0, 'filters']
  layer2_filters: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 1, 'filters']
  layer1_kernel: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 0, 'kernel_size']
  layer2_kernel: ['Model', 'Model Parameters', 'basic', 'conv_block', 'layers', 1, 'kernel_size']
  pool_size: ['Model', 'Model Parameters', 'basic', 'conv_block','max_pool','size']
  pool_strides: ['Model', 'Model Parameters', 'basic', 'conv_block','max_pool','strides']
  cnn_rnn_dropout: ['Model', 'Model Parameters', 'cnn_rnn', 'dropout_rate']

fixed_hyperparameters

Dictionary containing hyperparameter values the user wishes to set fixed in CTLearn YAML configuration file. These hyperparameters will remain fixed and won’t be optimized.

Required

False

Type

dict

Valid keys

<hyperparameter_label>

Default

None

Example
fixed_hyperparameters:
  pool_strides: 2
  optimizer_type: 'Adam'
  adam_epsilon: 1.0e-08

<hyperparameter_label>

Hyperparameter value.

Required

False

Type

Any Type.

dependent_hyperparameters

Dictionary containing the expression to evaluate for each hyperparameter whose value the user wishes to set up dependent on other hyperparameters values.

Required

False

Type

dict

Valid keys

<hyperparameter_label>

Default

None

Example
dependent_hyperparameters:
  layer2_filters: '2 * layer1_filters'
  layer3_filters: '4 * layer1_filters'
  layer4_filters: '8 * layer1_filters'

hyperparameters_to_optimize:
  layer1_filters:
    type: 'quniform'
    range: [16, 64]
    step: 1

<hyperparameter_label>

Expression to be computed. This expression has access to hyperparameters_to_optimize labels and values.

Required

False

Type

str

hyperparameters_to_optimize

Dictionary containing the configuration of the hyperparameters whose value the user wishes to optimize.

Required

True

Type

dict

Valid keys

<hyperparameter_label>

Example
base_learning_rate:
  type: loguniform
  range: [-5, 0]
layer1_filters:
  type: 'quniform'
  range: [16, 64]
  step: 1
optimizer_type:
 type: 'choice'
 range: ['Adadelta', 'Adam', 'RMSProp', 'SGD']
cnn_rnn_dropout:
 type: 'uniform'
 range: [0,1]

# example of conditional space

number_of_layers:
 type: 'conditional'
 range:
    - value: 1
      cond_params:
        layer1_kernel:
          type: 'quniform'
          range: [2, 10]
          step: 1
        layer1_filters:
          type: 'quniform'
          range: [16, 64]
          step: 1
    - value: 2
      cond_params:
        layer1_kernel:
          type: 'quniform'
          range: [2, 10]
          step: 1
        layer1_filters:
          type: 'quniform'
          range: [16, 64]
          step: 1
        layer2_kernel:
          type: 'quniform'
          range: [2, 10]
          step: 1
        layer2_filters:
          type: 'quniform'
          range: [16, 128]
          step: 1

<hyperparameter_label>

Dictionary containing the hyperparameter search space configuration.

Required

True

Type

dict

Valid keys

type, range, step

type

Hyperparameter search space sampling type. Available options:

  • uniform: generate float value uniformly sampled.

  • quniform: generate integer value uniformly sampled.

  • loguniform: generate float value logarithmically sampled.

  • qloguniform: generate integer value logarithmically sampled.

  • normal: generate float value normally sampled.

  • qnormal: generate integer value normally sampled.

  • lognormal: generate float value log-normally sampled.

  • qlognormal: generate integer value log-normally sampled.

  • choice: generate value sampled from a list of options. Useful for categorical hyperparameters.

  • conditional: generate nested spaces where values of some parameters depend on others. Useful for conditional hyperparameters.

Required

True

Type

str

Valid options

uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal, qlognormal, choice, conditional

Note

If optimization_type is tree_parzen_estimators or random_search all type options are available.

If optimization_type is gaussian_processes only uniform, quniform, loguniform and choice options are available.

If optimization_type is genetic_algorithm only uniform, quniform and choice options are available.

range

Range of values the hyperparameter is sampled from.

  • If type is uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal``or ``qlognormal; then range must be a list of two int or float values that define the lower and upper limits respectively of the range.

  • If type is choice, then range must be a list of options.

  • If type is conditional, then range must be a list of dictionaries containing two keys: value and cond_params:

    • value: int, float or str defining hyperparameter value.

    • cond_params: dictionary containing hyperparameter labels and their respective configurations that will be generated only for the corresponding hyperparameter value. See the example for further clarification.

Required

True

Type

list

Valid options

uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal, qlognormal, choice, conditional

step

Step between sampled values.

Required

False

Type

int

Default

1

Note

This setting will only be used if type is quniform, qloguniform, qnormal or `qlognormal and optimization_type is tree_parzen_estimators or random_search.