twinlab.Emulator.recommend

Emulator.recommend(num_points, acq_func, params=<twinlab.params.RecommendParams object>, wait=True, verbose=False)

Draw new recommended data points from a trained emulator that exists on the twinLab cloud.

The recommend functionality of an emulator is used to suggest new data points to sample. These new data points can be chosen depending on a variety of different user objectives. Currently, the user can choose between "optimise" and "explore" acquisition functions. Choosing "optimise" will obtain suggested "X" values the evaluation of which (acquiring the corresponding "y") will maximise the knowledge of the emulator about the location of the maximum. A classic use case for this would be a user trying to maximise the output of a model. For example, the maximum strenth of a pipe given a set of design parameters. Choosing "explore" will instead suggest "X" that reduce the overall uncertainty of the emulator across the entire input space. A classic use case for this would be a user trying to reduce overally uncertainty. For example, a user trying to reduce the uncertainty in the strength of a pipe across all design parameters. The number of requested data points can be specified by the user, and if this is greater than one then then recommendations are all suggested at once, and are designed to be the optmial set, as a group, to achieve the user outcome. twinLab optimises which specific acquisition function within the chosen category will be used, prioritising numerical stability based on the number of points requested.

The value of the acquisition function is also returned to the user. While this is of limited value in isolation, the trend of the acquisition function value over multiple iterations of Recommend can be used to understand the performance of the emulator. The Emualtor.learn method can be used to improve the performance of an emulator iteratively.

Parameters:

• num_points (int) – The number of samples to draw for each row of the evaluation data.

• acq_func (str) – Specifies the acquisition function to be used when recommending new points. The acquisition function can be either "explore" or "optimise".

• params (RecommendParams, optional) – A parameter configuration that contains all of the optional recommendation parameters.

• wait (bool, optional) – If True wait for the job to complete, otherwise return the process ID and exit.

• verbose (bool, optional) – Display detailed information about the operation while running.

Returns:

By default, a tuple is returned containing the recommended samples and the acquisition function value. Instead, if wait=False, the process ID is returned. The results can then be retrieved later using Emulator.get_process(<process_id>). Process IDs associated with an emulator can be found using Emulator.list_processes().

Return type:

Tuple[pandas.DataFrame, float], str

Example

emulator = tl.Emulator("quickstart")
emulator.recommend(5, "explore")

          x
0  0.852853
1  0.914091
2  0.804012
3  0.353463
4  0.595268

-0.00553509

Example

emulator = tl.Emulator("quickstart")
emulator.recommend(3, "optimisation")

          x
0  0.273920
1  0.306423
2  0.226851

0.046944751