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.
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
listofstr- 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
listofstr- 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_logormetrics_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'
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'
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
Trueifoptimization_typeisgenetic_algorithm, elseFalse.- 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
floatin 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_optimizeris configured on the basis of thebase_estimatorand 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
Trueifoptimization_typeisgenetic_algorithm, elseFalse.- 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
floatin 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
floatin range (0,1).- Default
0.2- Recommend value
Default
selection_bound¶
Threshold for performing selection.
- Required
False- Type
float- Valid values
Any
floatin range (0,1).- Default
0.4- Recommend value
Default
crossover_bound¶
Threshold for performing crossover.
- Required
False- Type
float- Valid values
Any
floatin 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:SCTCamSST: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
TrueifpredictisTrue, elseFalse.- Type
path
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
listofstr- 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
listofstr- 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
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; thenrangemust be alistof twointorfloatvalues that define the lower and upper limits respectively of the range.If type is
choice, thenrangemust be alistof options.If type is
conditional, thenrangemust be alistofdictionariescontaining two keys:valueandcond_params:value:int,floatorstrdefining hyperparameter value.cond_params:dictionarycontaining hyperparameter labels and their respective configurations that will be generated only for the corresponding hyperparametervalue. 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.