Campaign¶

class baybe.campaign.Campaign[source]¶

Bases: SerialMixin

Main class for interaction with BayBE.

Campaigns define and record an experimentation process, i.e. the execution of a series of measurements and the iterative sequence of events involved.

In particular, a campaign:

Defines the objective of an experimentation process.
Defines the search space over which the experimental parameter may vary.
Defines a recommender for exploring the search space.
Records the measurement data collected during the process.
Records metadata about the progress of the experimentation process.

Public methods

`__init__`(searchspace[, objective, recommender])	Method generated by attrs for class Campaign.
`add_measurements`(data[, ...])	Add results from a dataframe to the internal database.
`from_config`(config_json)	Create a campaign from a configuration JSON.
`from_dict`(dictionary)	Create an object from its dictionary representation.
`from_json`(string)	Create an object from its JSON representation.
`get_surrogate`()	Get the current surrogate model.
`posterior`(candidates)	Get the posterior predictive distribution for the given candidates.
`recommend`(batch_size[, pending_experiments, ...])	Provide the recommendations for the next batch of experiments.
`to_dict`()	Create an object's dictionary representation.
`to_json`()	Create an object's JSON representation.
`validate_config`(config_json)	Validate a given campaign configuration JSON.

Public attributes and properties

`searchspace`	The search space in which the experiments are conducted.
`objective`	The optimization objective.
`recommender`	The employed recommender
`n_batches_done`	The number of already processed batches.
`n_fits_done`	The number of fits already done.
`measurements`	The experimental data added to the Campaign.
`parameters`	The parameters of the underlying search space.
`targets`	The targets of the underlying objective.

Method generated by attrs for class Campaign.

For details on the parameters, see Public attributes and properties.

add_measurements(data: DataFrame, numerical_measurements_must_be_within_tolerance: bool = True)[source]¶

Add results from a dataframe to the internal database.

Each addition of data is considered a new batch. Added results are checked for validity. Categorical values need to have an exact match. For numerical values, a campaign flag determines if values that lie outside a specified tolerance are accepted. Note that this modifies the provided data in-place.

Parameters:

data (DataFrame) – The data to be added (with filled values for targets). Preferably created via baybe.campaign.Campaign.recommend().
numerical_measurements_must_be_within_tolerance (bool) – Flag indicating if numerical parameters need to be within their tolerances.

Raises:

ValueError – If one of the targets has missing values or NaNs in the provided dataframe.
TypeError – If the target has non-numeric entries in the provided dataframe.

Return type:

None

classmethod from_config(config_json: str)[source]¶

Create a campaign from a configuration JSON.

Parameters:: config_json (str) – The string with the configuration JSON.
Return type:: Campaign
Returns:: The constructed campaign.

classmethod from_dict(dictionary: dict)¶

Create an object from its dictionary representation.

Parameters:: dictionary (dict) – The dictionary representation.
Return type:: TypeVar(_T)
Returns:: The reconstructed object.

classmethod from_json(string: str)¶

Create an object from its JSON representation.

Parameters:: string (str) – The JSON representation of the object.
Return type:: TypeVar(_T)
Returns:: The reconstructed object.

get_surrogate()[source]¶

Get the current surrogate model.

Raises:: RuntimeError – If the current recommender does not provide a surrogate model.
Returns:: The surrogate of the current recommender.
Return type:: Surrogate

posterior(candidates: pd.DataFrame)[source]¶

Get the posterior predictive distribution for the given candidates.

The predictive distribution is based on the surrogate model of the last used recommender.

Parameters:: candidates (pd.DataFrame) – The candidate points in experimental recommendations. For details, see baybe.surrogates.base.Surrogate.posterior().
Raises:: IncompatibilityError – If the underlying surrogate model exposes no method for computing the posterior distribution.
Returns:: The corresponding posterior object. For details, see baybe.surrogates.base.Surrogate.posterior().
Return type:: Posterior

recommend(batch_size: int, pending_experiments: DataFrame | None = None, batch_quantity: int | None = None)[source]¶

Provide the recommendations for the next batch of experiments.

Parameters:

batch_size (int) – Number of requested recommendations.
pending_experiments (Optional[DataFrame]) – Parameter configurations specifying experiments that are currently pending.
batch_quantity (Optional[int]) – Deprecated! Use batch_size instead.

Return type:

DataFrame

Returns:

Dataframe containing the recommendations in experimental representation.

Raises:

ValueError – If batch_size is smaller than 1.

to_dict()¶

Create an object’s dictionary representation.

Return type:: dict

to_json()¶

Create an object’s JSON representation.

Return type:: str
Returns:: The JSON representation as a string.

classmethod validate_config(config_json: str)[source]¶

Validate a given campaign configuration JSON.

Parameters:: config_json (str) – The JSON that should be validated.
Return type:: None

property measurements: DataFrame¶: The experimental data added to the Campaign.

n_batches_done: int¶: The number of already processed batches.

n_fits_done: int¶: The number of fits already done.

objective: Objective | None¶: The optimization objective. When passing a baybe.targets.base.Target, conversion to baybe.objectives.single.SingleTargetObjective is automatically applied.

property parameters: tuple[Parameter, ...]¶: The parameters of the underlying search space.

recommender: RecommenderProtocol¶: The employed recommender

searchspace: SearchSpace¶: The search space in which the experiments are conducted. When passing a baybe.parameters.base.Parameter, a baybe.searchspace.discrete.SubspaceDiscrete, or a a baybe.searchspace.continuous.SubspaceContinuous, conversion to baybe.searchspace.core.SearchSpace is automatically applied.

property targets: tuple[Target, ...]¶: The targets of the underlying objective.