optimeo.bo#

This module provides a class for optimizing experiments using Bayesian Optimization (BO) with the [Ax platform](https://ax.dev/). It includes methods for initializing the experiment, suggesting trials, predicting outcomes, and plotting results.

You can see an example notebook [here](../examples/bo.ipynb).

class optimeo.bo.BOExperiment(features, outcomes, ranges=None, N=1, maximize=True, fixed_features=None, outcome_constraints=None, objective_thresholds=None, feature_constraints=None, optim='bo', acq_func=None, seed=42)[source]#

Bases: object

BOExperiment is a class designed to facilitate Bayesian Optimization experiments using the [Ax platform](https://ax.dev/). It encapsulates the experiment setup, including features, outcomes, constraints, and optimization methods.

Example

from optimeo.bo import BOExperiment, read_experimental_data

features, outcomes = read_experimental_data('data.csv', out_pos=[-2, -1])
experiment = BOExperiment(
    features,
    outcomes,
    N=5,
    maximize={'out1': True, 'out2': False},
)
experiment.suggest_next_trials()
experiment.plot_model(metricname='outcome1')
experiment.plot_optimization_trace()
Parameters:

  • features (Dict[str, Dict[str, Any]]) – A dictionary defining the features of the experiment, including their types and ranges. Each feature is represented as a dictionary with keys ‘type’, ‘data’, and ‘range’. - ‘type’: The type of the feature (e.g., ‘int’, ‘float’, ‘text’). - ‘data’: The observed data for the feature. - ‘range’: The range of values for the feature.

  • outcomes (Dict[str, Dict[str, Any]]) – A dictionary defining the outcomes of the experiment, including their types and observed data. Each outcome is represented as a dictionary with keys ‘type’ and ‘data’. - ‘type’: The type of the outcome (e.g., ‘int’, ‘float’). - ‘data’: The observed data for the outcome.

  • ranges (Optional[Dict[str, Dict[str, Any]]]) – A dictionary defining the ranges of the features. Default is None. If not provided, the ranges will be inferred from the features data. The ranges should be in the format {‘feature_name’: [minvalue,maxvalue]}.

  • N (int) – The number of trials to suggest in each optimization step. Must be a positive integer.

  • maximize (Union[bool, Dict[str, bool]]) – A boolean or dict indicating whether to maximize the outcomes in the form {‘outcome1’:True, ‘outcome2’:False}. If a single boolean is provided, it is applied to all outcomes. Default is True.

  • fixed_features (Optional[Dict[str, Any]]) – A dictionary defining fixed features with their values. Default is None. If provided, the fixed features will be treated as fixed parameters in the generation process. The fixed features should be in the format {‘feature_name’: value}. The values should be the fixed values for the respective features.

  • outcome_constraints (Optional[List[str]]) – Constraints on the outcomes, specified as a list of strings. Default is None. The constraints should be in the format {‘outcome_name’: [minvalue,maxvalue]}.

  • objective_thresholds (Optional[Dict[str, float]]) – Reference-point thresholds for multi-objective optimization, specified per outcome in the format {'outcome_name': threshold}. Default is None. Setting these avoids Ax’s default winsorization warning for multi-objective runs.

  • feature_constraints (Optional[List[str]]) – Constraints on the features, specified as a list of strings. Default is None. The constraints should be in the format {‘feature_name’: [minvalue,maxvalue]}.

  • optim (str) – The optimization method to use, either ‘bo’ for Bayesian Optimization or ‘sobol’ for Sobol sequence. Default is ‘bo’.

  • acq_func (Optional[Dict[str, Any]]) –

    The acquisition function to use for the optimization process. It must be a dict with 2 keys: - acqf: the acquisition function class to use (e.g., UpperConfidenceBound), - acqf_kwargs: a dict of the kwargs to pass to the acquisition function class. (e.g. {‘beta’: 0.1}).

    If not provided, the default acquisition function is used (LogExpectedImprovement or qLogExpectedImprovement if N>1).

Variables:

  • features (Dict[str, Dict[str, Any]]) – A dictionary defining the features of the experiment, including their types and ranges.

  • outcomes (Dict[str, Dict[str, Any]]) – A dictionary defining the outcomes of the experiment, including their types and observed data.

  • N (int) – The number of trials to suggest in each optimization step. Must be a positive integer.

  • maximize (Union[bool, List[bool]]) – A boolean or list of booleans indicating whether to maximize the outcomes. If a single boolean is provided, it is applied to all outcomes.

  • outcome_constraints (Optional[Dict[str, Dict[str, float]]]) – Constraints on the outcomes, specified as a dictionary or list of dictionaries.

  • feature_constraints (Optional[List[Dict[str, Any]]]) – Constraints on the features, specified as a list of dictionaries.

  • optim (str) – The optimization method to use, either ‘bo’ for Bayesian Optimization or ‘sobol’ for Sobol sequence.

  • data (pd.DataFrame) – A DataFrame representing the current data in the experiment, including features and outcomes.

  • acq_func (dict) – The acquisition function to use for the optimization process.

  • generator_run – The generator run for the experiment, used to generate new candidates.

  • model – The model used for predictions in the experiment.

  • ax_client – The AxClient for the experiment, used to manage trials and data.

  • gs – The generation strategy for the experiment, used to generate new candidates.

  • parameters – The parameters for the experiment, including their types and ranges.

  • names – The names of the features in the experiment.

  • fixed_features – The fixed features for the experiment, used to generate new candidates.

  • candidate – The candidate(s) suggested by the optimization process.

initialize_ax_client()[source]#

Initialize AxClient with experiment parameters, objectives, and constraints.

suggest_next_trials()[source]#

Suggest next trial(s) from the current model and generation strategy.

predict(params)[source]#

Predict outcomes for a list of parameter dictionaries.

update_experiment(params, outcomes)[source]#

Update the experiment with new observations and refresh internal state.

plot_model(metricname=None, slice_values=None, linear=False)[source]#

Plot model predictions as slices or contours.

plot_optimization_trace(optimum=None)[source]#

Plot optimization progress over trials.

plot_pareto_frontier()[source]#

Plot Pareto frontier for multi-objective problems.

get_best_parameters()[source]#

Return best parameter set(s) and associated outcomes.

clear_trials()[source]#

Remove all current trials.

candidate#

The candidate(s) suggested by the optimization process.

ax_client#

Ax’s client for the experiment.

model#

Ax’s Gaussian Process model.

parameters#

Ax’s parameters for the experiment.

generator_run#

Ax’s generator run for the experiment.

gs#

Ax’s generation strategy for the experiment.

Nmetrics#

The number of metrics in the experiment.

property seed: int#

Random seed for reproducibility. Default is 42.

property features#

A dictionary defining the features of the experiment, including their types and ranges.

Example

features = {
    'feature1': {'type': 'int', 'data': [1, 2, 3], 'range': [1, 3]},
    'feature2': {'type': 'float', 'data': [0.1, 0.2, 0.3], 'range': [0.1, 0.3]},
    'feature3': {'type': 'text', 'data': ['A', 'B', 'C'], 'range': ['A', 'B', 'C']},
}
property ranges#

A dictionary defining the ranges of the features. Default is None.

If not provided, the ranges will be inferred from the features data. The ranges should be in the format {‘feature_name’: [minvalue,maxvalue]}.

property names#

The names of the features.

property outcomes#

A dictionary defining the outcomes of the experiment, including their types and observed data.

Example

outcomes = {
    'outcome1': {'type': 'float', 'data': [0.1, 0.2, 0.3]},
    'outcome2': {'type': 'float', 'data': [1.0, 2.0, 3.0]},
}
property fixed_features#

A dictionary defining fixed features with their values. Default is None. If provided, the fixed features will be treated as fixed parameters in the generation process. The fixed features should be in the format {‘feature_name’: value}. The values should be the fixed values for the respective features.

property N#

The number of trials to suggest in each optimization step. Must be a positive integer. Default is 1.

property maximize#

A boolean or dict indicating whether to maximize outcomes in the form {'outcome1': True, 'outcome2': False}. If a single boolean is provided, it is applied to all outcomes. Default is True.

property outcome_constraints#

Constraints on the outcomes, specified as a list of strings. Default is None.

property objective_thresholds#

Reference-point thresholds for multi-objective optimization.

Format: {'outcome_name': threshold}.

property feature_constraints#

Constraints on the features, specified as a list of strings. Default is None.

Example

feature_constraints = [
    'feature1 <= 10.0',
    'feature1 + 2*feature2 >= 3.0',
]
property optim#

The optimization method to use, either ‘bo’ for Bayesian Optimization or ‘sobol’ for Sobol sequence. Default is ‘bo’.

property data: DataFrame#

Returns a DataFrame of the current data in the experiment, including features and outcomes.

property pareto_frontier#

The Pareto frontier for multi-objective optimization experiments.

property acq_func#

The acquisition function to use for the optimization process. It must be a dict with 2 keys: - acqf: the acquisition function class to use (e.g., UpperConfidenceBound), - acqf_kwargs: a dict of the kwargs to pass to the acquisition function class. (e.g. {‘beta’: 0.1}).

If not provided, the default acquisition function is used (LogExpectedImprovement or qLogExpectedImprovement if N>1).

Example

acq_func = {
    'acqf': UpperConfidenceBound,
    'acqf_kwargs': {'beta': 0.1},  # lower = exploitation, higher = exploration
}
initialize_ax_client()[source]#

Initialize the AxClient with the experiment’s parameters, objectives, and constraints.

set_model()[source]#

Set the model to be used for predictions. This method is called after initializing the AxClient.

set_gs()[source]#

Set the generation strategy for the experiment. This method is called after initializing the AxClient.

clear_trials()[source]#

Clear all trials in the experiment.

suggest_next_trials(with_predicted=True)[source]#

Suggest the next set of trials based on the current model and optimization strategy.

Returns:

DataFrame containing the suggested trials and their predicted outcomes.

Return type:

pd.DataFrame

predict(params)[source]#

Predict the outcomes for a given set of parameters using the current model.

Parameters:

params (List[Dict[str, Any]]) – List of parameter dictionaries for which to predict outcomes.

Returns:

List of predicted outcomes for the given parameters.

Return type:

List[Dict[str, float]]

update_experiment(params, outcomes)[source]#

Update the experiment with new parameters and outcomes, and reinitialize the AxClient.

Parameters:

  • params (Dict[str, Any]) – Dictionary of new parameters to update the experiment with.

  • outcomes (Dict[str, Any]) – Dictionary of new outcomes to update the experiment with.

plot_model(metricname=None, slice_values={}, linear=False)[source]#

Plot the model’s predictions for the experiment’s parameters and outcomes. :param metricname: The name of the metric to plot. If None, the first outcome metric is used. :type metricname: Optional[str] :param slice_values: Dictionary of slice values for plotting. :type slice_values: Optional[Dict[str, Any]] :param linear: Whether to plot a linear slice plot. Default is False. :type linear: bool

Returns:

Plotly figure of the model’s predictions.

Return type:

plotly.graph_objects.Figure

plot_optimization_trace(optimum=None)[source]#

Plot the optimization trace, showing the progress of the optimization over trials.

Parameters:

optimum (Optional[float]) – The optimal value to plot on the optimization trace.

Returns:

Plotly figure of the optimization trace.

Return type:

plotly.graph_objects.Figure

plot_feature_importances(relative=False)[source]#

Plot feature importances using Ax default Sensitivity Analysis cards (same analysis family as in Ax tutorials).

Parameters:

relative (bool, optional) – Used only by the fallback Ax helper plot if analysis cards are unavailable. Default is False.

Returns:

Plotly figure of feature importances.

Return type:

plotly.graph_objects.Figure

compute_pareto_frontier()[source]#

Compute the Pareto frontier for multi-objective optimization experiments.

Return type:

The Pareto frontier.

plot_pareto_frontier(show_error_bars=True)[source]#

Plot the Pareto frontier for multi-objective optimization experiments.

Parameters:

show_error_bars (bool, optional) – Whether to show error bars on the plot. Default is True.

Returns:

Plotly figure of the Pareto frontier.

Return type:

plotly.graph_objects.Figure

get_best_parameters()[source]#

Return the best parameters found by the optimization process.

Returns:

DataFrame containing the best parameters and their outcomes.

Return type:

pd.DataFrame

optimeo.bo.flatten_dict(d, parent_key='', sep='_')[source]#

Flatten a nested dictionary.

optimeo.bo.ordered_dict_to_dataframe(data)[source]#

Convert an OrderedDict with arbitrary nesting to a DataFrame.

optimeo.bo.read_experimental_data(file_path, out_pos=[-1])[source]#

Read experimental data from a CSV file and format it into features and outcomes dictionaries.

Parameters:

  • (str) (file_path) – Path to the CSV file containing experimental data.

  • int) (out_pos (list of) – Column indices of the outcome variables. Default is the last column.

  • file_path (str)

Returns:

Formatted features and outcomes dictionaries.

Return type:

Tuple[Dict[str, Dict[str, Any]], Dict[str, Dict[str, Any]]]