twinlab.Emulator.recommend

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

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:

• "optimise" will obtain suggested "X" values the evaluation of which (acquiring the corresponding "y") will maximize the knowledge of the emulator about the location of the maximum. A classic use case for this would be a user trying to maximize the output of a model (e.g., the combination of metals that creates the strongest alloy). This method can also be used to minimize an output, by using the weights argument of RecommendParams to multiply the output by -1. If an emulator has multiple outputs, then a weighted combination of the outputs can be minimized/maximized. The weights argument of RecommendParams can control the weight assigned to each output, or can be used to focus on a single output. For example, this can be used to find the maximum strength of a pipe given a set of design parameters.

• "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 1 then recommendations are all suggested at simultaneously, and are designed to be the optimal 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. See the documentation for RecommendParams() for more information on the available parameters.

For the "explore" functionality, generating recommendations is not supported for multi-output emulators (when "y" has more than one dimension).

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 Emulator.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, "optimise")

          x
0  0.273920
1  0.306423
2  0.226851

0.046944751