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, ...])	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`([batch_size, pending_experiments])	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.
`toggle_discrete_candidates`(constraints, exclude)	In-/exclude certain discrete points in/from the candidate set.
`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
`allow_recommending_already_measured`	Allow to recommend experiments that were already measured earlier.
`allow_recommending_already_recommended`	Allow to recommend experiments that were already recommended earlier.
`allow_recommending_pending_experiments`	Allow pending experiments to be part of the recommendations.
`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.

__init__(searchspace: Parameter | SubspaceDiscrete | SubspaceContinuous | SearchSpace, objective: Target | Objective | None = None, recommender: RecommenderProtocol = NOTHING, *, allow_recommending_already_measured: bool | UnspecifiedType = NOTHING, allow_recommending_already_recommended: bool | UnspecifiedType = NOTHING, allow_recommending_pending_experiments: bool | UnspecifiedType = NOTHING)¶

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(batch_size: int | None = None, pending_experiments: DataFrame | None = None)[source]¶

Get the current surrogate model.

Parameters:

batch_size (Optional[int]) – See recommend(). Only required when using meta recommenders that demand it.
pending_experiments (Optional[DataFrame]) – See recommend(). Only required when using meta recommenders that demand it.

Raises:

RuntimeError – If the current recommender does not provide a surrogate model.

Returns:

The surrogate of the current recommender.

Return type:

Surrogate

Note

Currently, this method always returns the surrogate model with respect to the transformed target(s) / objective. This means that if you are using a SingleTargetObjective with a transformed target or a DesirabilityObjective, the model’s output will correspond to the transformed quantities and not the original untransformed target(s).

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

Get the posterior predictive distribution for the given candidates.

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)[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.

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.

toggle_discrete_candidates(constraints: Collection[DiscreteConstraint] | DataFrame, exclude: bool, complement: bool = False, dry_run: bool = False)[source]¶

In-/exclude certain discrete points in/from the candidate set.

Parameters:

constraints (Collection[DiscreteConstraint] | DataFrame) – A filtering mechanism determining the candidates subset to be in-/excluded. Can be either a collection of DiscreteConstraint or a dataframe. For the latter, see filter_df() for details.
exclude (bool) – If True, the specified candidates are excluded. If False, the candidates are considered for recommendation.
complement (bool) – If True, the filtering mechanism is inverted so that the complement of the candidate subset specified by the filter is toggled. For details, see filter_df().
dry_run (bool) – If True, the target subset is only extracted but not affected. If False, the candidate set is updated correspondingly. Useful for setting up the correct filtering mechanism.

Return type:

DataFrame

Returns:

A new dataframe containing the discrete candidate set passing through the specified filter.

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

allow_recommending_already_measured: bool | UnspecifiedType¶: Allow to recommend experiments that were already measured earlier. Can only be set for discrete search spaces.

allow_recommending_already_recommended: bool | UnspecifiedType¶: Allow to recommend experiments that were already recommended earlier. Can only be set for discrete search spaces.

allow_recommending_pending_experiments: bool | UnspecifiedType¶: Allow pending experiments to be part of the recommendations. Can only be set for discrete search spaces.

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.