SubspaceDiscrete

class baybe.searchspace.discrete.SubspaceDiscrete

Bases: SerialMixin

Class for managing discrete subspaces.

Builds the subspace from parameter definitions and optional constraints, keeps track of search metadata, and provides access to candidate sets and different parameter views.

Public methods

__init__(parameters, exp_rep[, metadata, ...])	Method generated by attrs for class SubspaceDiscrete.
empty()	Create an empty discrete subspace.
estimate_product_space_size(parameters)	Estimate an upper bound for the memory size of a product space.
from_dataframe(df[, parameters, empty_encoding])	Create a discrete subspace with a specified set of configurations.
from_dict(dictionary)	Create an object from its dictionary representation.
from_json(string)	Create an object from its JSON representation.
from_parameter(parameter)	Create a subspace from a single parameter.
from_product(parameters[, constraints, ...])	See baybe.searchspace.core.SearchSpace.
from_simplex(max_sum, simplex_parameters[, ...])	Efficiently create discrete simplex subspaces.
get_candidates([...])	Return the set of candidate parameter settings that can be tested.
get_parameters_by_name(names)	Return parameters with the specified names.
mark_as_measured(measurements, ...)	Mark the given elements of the space as measured.
to_dict()	Create an object's dictionary representation.
to_json()	Create an object's JSON representation.
to_searchspace()	Turn the subspace into a search space with no continuous part.
transform([df, allow_missing, allow_extra, data])	See baybe.searchspace.core.SearchSpace.transform().

Public attributes and properties

parameters	The list of parameters of the subspace.
exp_rep	The experimental representation of the subspace.
metadata	The metadata.
empty_encoding	Flag encoding whether an empty encoding is used.
constraints	A list of constraints for restricting the space.
comp_rep	The computational representation of the space.
comp_rep_bounds	The minimum and maximum values of the computational representation.
comp_rep_columns	The columns spanning the computational representation.
is_empty	Return whether this subspace is empty.
parameter_names	Return tuple of parameter names.

__init__(parameters: Collection[Parameter], exp_rep: DataFrame, metadata: DataFrame = NOTHING, empty_encoding: bool = False, constraints: Sequence = NOTHING, comp_rep: DataFrame = NOTHING)

Method generated by attrs for class SubspaceDiscrete.

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

classmethod empty()

Create an empty discrete subspace.

Return type:

SubspaceDiscrete

static estimate_product_space_size(parameters: Sequence[DiscreteParameter])

Estimate an upper bound for the memory size of a product space.

Parameters:

parameters (Sequence[DiscreteParameter]) – The parameters spanning the product space.

Return type:

MemorySize

Returns:

The estimated memory size.

classmethod from_dataframe(df: DataFrame, parameters: Sequence[DiscreteParameter] | None = None, empty_encoding: bool = False)

Create a discrete subspace with a specified set of configurations.

Parameters:

• df (DataFrame) – The experimental representation of the search space to be created.

• parameters (Optional[Sequence[DiscreteParameter]]) – Optional parameter objects corresponding to the columns in the given dataframe that can be provided to explicitly control parameter attributes. If a match between column name and parameter name is found, the corresponding parameter object is used. If a column has no match in the parameter list, a baybe.parameters.numerical.NumericalDiscreteParameter is created if possible, or a baybe.parameters.categorical.CategoricalParameter is used as fallback. For both types, default values are used for their optional arguments. For more details, see baybe.parameters.utils.get_parameters_from_dataframe().

• empty_encoding (bool) – See baybe.searchspace.core.SearchSpace.from_product().

Return type:

SubspaceDiscrete

Returns:

The created discrete subspace.

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.

classmethod from_parameter(parameter: DiscreteParameter)

Create a subspace from a single parameter.

Parameters:

parameter (DiscreteParameter) – The parameter to span the subspace.

Return type:

SubspaceDiscrete

Returns:

The created subspace.

classmethod from_product(parameters: Sequence[DiscreteParameter], constraints: Sequence[DiscreteConstraint] | None = None, empty_encoding: bool = False)

See baybe.searchspace.core.SearchSpace.

Return type:

SubspaceDiscrete

classmethod from_simplex(max_sum: float, simplex_parameters: Sequence[NumericalDiscreteParameter], product_parameters: Sequence[DiscreteParameter] | None = None, constraints: Sequence[DiscreteConstraint] | None = None, min_nonzero: int = 0, max_nonzero: int | None = None, boundary_only: bool = False, tolerance: float = 1e-06)

Efficiently create discrete simplex subspaces.

The same result can be achieved using baybe.searchspace.discrete.SubspaceDiscrete.from_product() in combination with appropriate constraints. However, such an approach is inefficient because the Cartesian product involved creates an exponentially large set of candidates, most of which do not satisfy the simplex constraints and must be subsequently be filtered out by the method.

By contrast, this method uses a shortcut that removes invalid candidates already during the creation of parameter combinations, resulting in a significantly faster construction.

Parameters:

• max_sum (float) – The maximum sum of the parameter values defining the simplex size.

• simplex_parameters (Sequence[NumericalDiscreteParameter]) – The parameters to be used for the simplex construction.

• product_parameters (Optional[Sequence[DiscreteParameter]]) – Optional parameters that enter in form of a Cartesian product.

• constraints (Optional[Sequence[DiscreteConstraint]]) – See baybe.searchspace.core.SearchSpace.

• min_nonzero (int) – Optional restriction on the minimum number of nonzero parameter values in the simplex construction.

• max_nonzero (Optional[int]) – Optional restriction on the maximum number of nonzero parameter values in the simplex construction.

• boundary_only (bool) – Flag determining whether to keep only parameter configurations on the simplex boundary.

• tolerance (float) – Numerical tolerance used to validate the simplex constraint.

Raises:

• ValueError – If the passed simplex parameters are not suitable for a simplex construction.

• ValueError – If the passed product parameters are not discrete.

• ValueError – If the passed simplex parameters and product parameters are not disjoint.

Return type:

SubspaceDiscrete

Returns:

The created simplex subspace.

Note

The achieved efficiency gains can vary depending on the particular order in which the parameters are passed to this method, as the configuration space is built up incrementally from the parameter sequence.

get_candidates(allow_repeated_recommendations: bool = False, allow_recommending_already_measured: bool = False, exclude: DataFrame | None = None)

Return the set of candidate parameter settings that can be tested.

Parameters:

• allow_repeated_recommendations (bool) – If True, parameter settings that have already been recommended in an earlier iteration are still considered valid candidates. This is relevant, for instance, when an earlier recommended parameter setting has not been measured by the user (for any reason) after the corresponding recommendation was made.

• allow_recommending_already_measured (bool) – If True, parameters settings for which there are already target values available are still considered as valid candidates.

• exclude (Optional[DataFrame]) – Points in experimental representation that should be excluded as candidates.

Return type:

tuple[DataFrame, DataFrame]

Returns:

The candidate parameter settings both in experimental and computational representation.

get_parameters_by_name(names: Sequence[str])

Return parameters with the specified names.

Parameters:

names (Sequence[str]) – Sequence of parameter names.

Return type:

tuple[DiscreteParameter, ...]

Returns:

The named parameters.

mark_as_measured(measurements: DataFrame, numerical_measurements_must_be_within_tolerance: bool)

Mark the given elements of the space as measured.

Parameters:

• measurements (DataFrame) – A dataframe containing parameter settings that should be marked as measured.

• numerical_measurements_must_be_within_tolerance (bool) – See baybe.utils.dataframe.fuzzy_row_match().

Return type:

None

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.

to_searchspace()

Turn the subspace into a search space with no continuous part.

Return type:

SearchSpace

transform(df: DataFrame | None = None, /, *, allow_missing: bool = False, allow_extra: bool | None = None, data: DataFrame | None = None)

See baybe.searchspace.core.SearchSpace.transform().

Return type:

DataFrame

comp_rep: DataFrame

The computational representation of the space. Technically not required but added as an optional initializer argument to allow ingestion from e.g. serialized objects and thereby speed up construction. If not provided, the default hook will derive it from exp_rep.

property comp_rep_bounds: DataFrame

The minimum and maximum values of the computational representation.

property comp_rep_columns: tuple[str, ...]

The columns spanning the computational representation.

constraints: tuple[DiscreteConstraint, ...]

A list of constraints for restricting the space.

empty_encoding: bool

Flag encoding whether an empty encoding is used.

exp_rep: DataFrame

The experimental representation of the subspace.

property is_empty: bool

Return whether this subspace is empty.

metadata: DataFrame

The metadata.

property parameter_names: tuple[str, ...]

Return tuple of parameter names.

parameters: tuple[DiscreteParameter, ...]

The list of parameters of the subspace.