btb.tuning package

Module contents

Top level of the tuning module.

class btb.tuning.BooleanHyperParam(default=False)[source]

Bases: btb.tuning.hyperparams.base.BaseHyperParam

BooleanHyperParam class.

The BooleanHyperParam class is responsible for the transformation of boolean values in to normalized search space of \([0, 1]\), providing the ability to sample values of those and to inverse transform from the search space into the hyperparameter space.

Hyperparameter space:

{True, False}

Parameters

default (bool) – Default boolean value for the hyperparameter. Defaults to False.

cardinality = 2
dimensions = 1
sample(n_samples)[source]

Generate sample values in the hyperparameter search space \({0, 1}\).

Parameters

n_samples (int) – Number of values to sample.

Returns

2D array with shape of (n_samples, 1) with normalized values inside the search space \({0, 1}\).

Return type

numpy.ndarray

Example

The example below shows simple usage case where a BooleanHyperParam is being created and it’s sample method is being called with a number of samples to be obtained.

>>> instance = BooleanHyperParam()
>>> instance.sample(2)
array([[1],
       [1]])
class btb.tuning.CategoricalHyperParam(choices, default=<object object>)[source]

Bases: btb.tuning.hyperparams.base.BaseHyperParam

CategoricalHyperParam Class.

The CategoricalHyperParam class is responsible for the transform of categorical values in to normalized search space and provides the inverse transform from search space to hyperparameter space. Also provides a method that generates samples of those.

Hyperparameter space:

\(h_1, h_2,... h_K\) where K is the number of categories.

Search Space:

\(\{ 0, 1 \}^K\) where K is the number of categories.

Parameters
  • choices (list) – List of values that the hyperparameter can be.

  • default (str or None) – Default value for the hyperparameter to take. Defaults to the first item in choices

NO_DEFAULT = <object object>
sample(n_samples)[source]

Generate sample values in the hyperparameter search space of [0, 1]^K.

Parameters

n_samples (int) – Number of values to sample.

Returns

2D array with shape of (n_samples, self.dimensions) with normalized values inside the search space \([0, 1]^K\).

Return type

numpy.ndarray

Example

The example below shows simple usage case where a CategoricalHyperParam is being created with three possible values, (Cat, Dog, Tiger), and it’s method sample is being called with a number of samples to be obtained. A numpy.ndarray with values from the search space is being returned.

>>> instance = CategoricalHyperParam(choices=['Cat', 'Dog', 'Tiger'])
>>> instance.sample(2)
array([[1, 0, 0],
       [0, 1, 0]])
class btb.tuning.GCPEiTuner(tunable, maximize=True, num_candidates=1000, min_trials=5, length_scale=0.1)[source]

Bases: btb.tuning.metamodels.gaussian_process.GaussianCopulaProcessMetaModel, btb.tuning.tuners.gaussian_process.GPEiTuner

Gaussian Copula Process Expected Improvement Tuner.

This class uses a GaussianProcessRegressor model from the sklearn.gaussian_process package, using an ExpectedImprovement function to return the better configurations predicted from the meta model that converts the input data using a Univariate copula.

class btb.tuning.GCPTuner(tunable, maximize=True, num_candidates=1000, min_trials=5, length_scale=0.1)[source]

Bases: btb.tuning.metamodels.gaussian_process.GaussianCopulaProcessMetaModel, btb.tuning.tuners.gaussian_process.GPTuner

Gaussian Copula Process Tuner.

This class uses a GaussianProcessRegressor model from the sklearn.gaussian_process package, using a numpy.argmax function to return the better configurations predicted from the meta model that converts the input data using a Univariate copula.

class btb.tuning.GPEiTuner(tunable, maximize=True, num_candidates=1000, min_trials=5, length_scale=0.1)[source]

Bases: btb.tuning.metamodels.gaussian_process.GaussianProcessMetaModel, btb.tuning.acquisition.expected_improvement.ExpectedImprovementAcquisition, btb.tuning.tuners.base.BaseMetaModelTuner

Gaussian Process Expected Improvement Tuner.

This class uses a GaussianProcessRegressor model from the sklearn.gaussian_process package, using an ExpectedImprovement function to return the better configurations predicted from the model.

class btb.tuning.GPTuner(tunable, maximize=True, num_candidates=1000, min_trials=5, length_scale=0.1)[source]

Bases: btb.tuning.metamodels.gaussian_process.GaussianProcessMetaModel, btb.tuning.acquisition.predicted_score.PredictedScoreAcquisition, btb.tuning.tuners.base.BaseMetaModelTuner

Gaussian Process Tuner.

This class uses a GaussianProcessRegressor model from the sklearn.gaussian_process package, using a numpy.argmax function to return the better configurations predicted from the model.

class btb.tuning.FloatHyperParam(min=None, max=None, default=None, include_min=True, include_max=True)[source]

Bases: btb.tuning.hyperparams.numerical.NumericalHyperParam

FloatHyperParam class.

The FloatHyperParam class represents a single hyperparameter within a range of float numbers, where min and max can take as value any float number within that range, having min to be smaller than max.

Hyperparameter space:

\(h_1, h_2,... h_n\) where \(h_i = i * (max - min) + min\)

Search space:

\(s_1, s_2,... s_n\) where \(s_i = (i - min) / (max - min)\)

Parameters
  • min (float) – Float number to represent the minimum value that this hyperparameter can take, by default is None which will take the system’s minimum float value possible.

  • max (float) – Float number to represent the maximum value that this hyperparameter can take, by default is None which will take the system’s maximum float value possible.

  • default (float) – Float number that represents the default value for the hyperparameter. Defaults to self.min

  • include_min (bool) – Either or not to include the minimum value in the search space.

  • include_max (bool) – Either or not to include the maximum value in the search space.

cardinality = inf
sample(n_samples)[source]

Generate sample values in the hyperparameter search space \({0, 1}\).

Parameters

n_samples (int) – Number of values to sample.

Returns

2D array with shape of (n_samples, 1) with normalized values inside the search space \({0, 1}\).

Return type

numpy.ndarray

Example

The example below shows simple usage case where a FloatHyperParam is being created with a range that goes from 0.1 to 0.9 and it’s sample method is being called with a number of samples to be obtained. A numpy.ndarray with values from the search space is being returned.

>>> instance = FloatHyperParam(min=0.1, max=0.9)
>>> instance.sample(2)
array([[0.52058728],
       [0.00582452]])
class btb.tuning.IntHyperParam(min=None, max=None, default=None, include_min=True, include_max=True, step=1)[source]

Bases: btb.tuning.hyperparams.numerical.NumericalHyperParam

IntHyperParam class.

The IntHyperParam class represents a single hyperparameter within an range of int numbers, where min and max can take as value any int number that compose this range having min to be smaller than max.

Hyperparameter space:

\(h_1, h_2,... h_n\) where \(h_i = min + (i - 1) * step\)

Search space:

\(s_1, s_2,... s_n\) where \(s_i = \frac{interval}{2} + (i - 1) * interval\)

Parameters
  • min (int) – Integer number to represent the minimum value that this hyperparameter can take, by default is None which will take the system’s minimum int value possible.

  • max (int) – Integer number to represent the maximum value that this hyperparameter can take, by default is None which will take the system’s maximum int value possible.

  • default (int) – Integer number that represents the default value for the hyperparameter. Defaults to self.min.

  • step (int) – Increase amount to take for each sample. Defaults to 1.

  • include_min (bool) – Either or not to include the minimum value in the search space.

  • include_max (bool) – Either or not to include the maximum value in the search space.

dimensions = 1
sample(n_samples)[source]

Generate sample values in the hyperparameter search space of [0, 1).

Parameters

n_samples (int) – Number of values to sample.

Returns

2D array with shape of (n_samples, 1) with normalized values inside the search space \({0, 1}\).

Return type

numpy.ndarray

Example

The example below shows simple usage case where a IntHyperParam is being created with a range that goes from 1 to 4 and it’s sample method is being called with a number of samples to be obtained. A numpy.ndarray with values from the search space is being returned.

>>> instance = IntHyperParam(min=1, max=4)
>>> instance.sample(2)
array([[0.625],
       [0.375]])
exception btb.tuning.StopTuning[source]

Bases: Exception

class btb.tuning.Tunable(hyperparams)[source]

Bases: object

Tunable class.

The Tunable class represents a collection of HyperParams that need to be tuned as a whole, at once.

hyperparams

Dict of HyperParams.

cardinality

Int or np.inf amount that indicates the number of combinations possible for this tunable.

Parameters

hyperparams (dict) – Dictionary object that contains the name and the hyperparameter asociated to it.

cardinality = 1
dimensions = 0
classmethod from_dict(dict_hyperparams)[source]

Create an instance from a dictionary containing information over hyperparameters.

Class method that creates an instance from a dictionary that describes the type of a hyperparameter, the range or values that this can have and the default value of the hyperparameter.

Parameters

dict_hyperparams (dict) –

A python dictionary containing as key the given name for the hyperparameter and as value a dictionary containing the following keys:

  • Type (str):

    bool for BoolHyperParam, int for IntHyperParam, float for FloatHyperParam, str for CategoricalHyperParam.

  • Range or Values (list):

    Range / values that this hyperparameter can take, in case of CategoricalHyperParam those will be used as the choices, for NumericalHyperParams the min value will be used as the minimum value and the max value will be used as the maximum value.

  • Default (str, bool, int, float or None):

    The default value for the hyperparameter.

Returns

A Tunable instance with the given hyperparameters.

Return type

Tunable

get_defaults()[source]

Return the default combination for the hyperparameters.

hyperparams = None
inverse_transform(values)[source]

Invert one or more hyperparameter configurations.

Invert one or more hyperparameter configurations from the normalized search space \([0, 1]^K\) to the original hyperparameter space.

Parameters

values (array-like) – 2D array of normalized values with shape (n, dimensions) where dimensions is the sum of dimensions from all the HyperParams that compose this tunable.

Returns

pandas.DataFrame

Example

The example below shows a simple usage of a Tunable class which will inverse transform a valid data from a 2D list and a pandas.DataFrame will be returned.

>>> from btb.tuning.hyperparams.boolean import BooleanHyperParam
>>> from btb.tuning.hyperparams.categorical import CategoricalHyperParam
>>> from btb.tuning.hyperparams.numerical import IntHyperParam
>>> chp = CategoricalHyperParam(['cat', 'dog'])
>>> bhp = BooleanHyperParam()
>>> ihp = IntHyperParam(1, 10)
>>> hyperparams = {
...     'chp': chp,
...     'bhp': bhp,
...     'ihp': ihp
... }
>>> tunable = Tunable(hyperparams)
>>> values = [
...     [1, 0, 0, 0.95],
...     [0, 1, 1, 0.05]
... ]
>>> tunable.inverse_transform(values)
   chp    bhp ihp
0  cat  False  10
1  dog   True   1
names = None
sample(n_samples)[source]

Sample values in the hyperparameters space for this tunable.

Parameters

n_samlpes (int) – Number of values to sample.

Returns

2D array with shape of (n_samples, dimensions) where dimensions is the sum of dimensions from all the HyperParams that compose this tunable.

Return type

numpy.ndarray

Example

The example below shows a simple usage of a Tunable class which will generate 2 samples by calling it’s sample method. This will return a numpy.ndarray.

>>> from btb.tuning.hyperparams.boolean import BooleanHyperParam
>>> from btb.tuning.hyperparams.categorical import CategoricalHyperParam
>>> from btb.tuning.hyperparams.numerical import IntHyperParam
>>> chp = CategoricalHyperParam(['cat', 'dog'])
>>> bhp = BooleanHyperParam()
>>> ihp = IntHyperParam(1, 10)
>>> hyperparams = {
...     'chp': chp,
...     'bhp': bhp,
...     'ihp': ihp
... }
>>> tunable = Tunable(hyperparams)
>>> tunable.sample(2)
array([[0.  , 1.  , 0.  , 0.45],
       [1.  , 0.  , 1.  , 0.95]])
transform(values)[source]

Transform one or more hyperparameter configurations.

Transform one or more hyperparameter configurations from the original hyperparameter space to the normalized search space.

Parameters

values (pandas.DataFrame, pandas.Series, dict, list(dict), 2D array-like) – Values of shape (n, len(self.hyperparams)).

Returns

2D array of shape (len(values), dimensions) where dimensions is the sum of dimensions from all the HyperParams that compose this tunable.

Return type

numpy.ndarray

Example

The example below shows a simple usage of a Tunable class which will transform a valid data from a 2D list and a numpy.ndarray is being returned.

>>> from btb.tuning.hyperparams.boolean import BooleanHyperParam
>>> from btb.tuning.hyperparams.categorical import CategoricalHyperParam
>>> from btb.tuning.hyperparams.numerical import IntHyperParam
>>> chp = CategoricalHyperParam(['cat', 'dog'])
>>> bhp = BooleanHyperParam()
>>> ihp = IntHyperParam(1, 10)
>>> hyperparams = {
...     'chp': chp,
...     'bhp': bhp,
...     'ihp': ihp
... }
>>> tunable = Tunable(hyperparams)
>>> values = [
...     ['cat', False, 10],
...     ['dog', True, 1],
... ]
>>> tunable.transform(values)
array([[1.  , 0.  , 0.  , 0.95],
       [0.  , 1.  , 1.  , 0.05]])
class btb.tuning.UniformTuner(tunable, maximize=True)[source]

Bases: btb.tuning.tuners.base.BaseTuner