Coverage for mlos_viz/mlos_viz/__init__.py: 100%

1# 

2# Copyright (c) Microsoft Corporation. 

3# Licensed under the MIT License. 

4# 

5""" 

6mlos_viz is a framework to help visualizing, explain, and gain insights from results 

7from the :py:mod:`mlos_bench` framework for benchmarking and optimization automation. 

8 

9It can be installed from `pypi <https://pypi.org/project/mlos-viz>`_ via ``pip 

10install mlos-viz``. 

11 

12Overview 

13++++++++ 

14 

15Its main entrypoint is the :py:func:`plot` function, which can be used to 

16automatically visualize :py:class:`~.ExperimentData` from :py:mod:`mlos_bench` using 

17other libraries for automatic data correlation and visualization like 

18:external:py:func:`dabl <dabl.plot>`. 

19""" 

20 

21from enum import Enum 

22from typing import Any, Dict, Literal, Optional 

23 

24import pandas 

25 

26from mlos_bench.storage.base_experiment_data import ExperimentData 

27from mlos_viz import base 

28from mlos_viz.util import expand_results_data_args 

29from mlos_viz.version import VERSION 

30 

31__version__ = VERSION 

32 

33 

34class MlosVizMethod(Enum): 

35 """What method to use for visualizing the experiment results.""" 

36 

37 DABL = "dabl" 

38 AUTO = DABL # use dabl as the current default 

39 

40 

41def ignore_plotter_warnings(plotter_method: MlosVizMethod = MlosVizMethod.AUTO) -> None: 

42 """ 

43 Suppress some annoying warnings from third-party data visualization packages by 

44 adding them to the warnings filter. 

45 

46 Parameters 

47 ---------- 

48 plotter_method: MlosVizMethod 

49 The method to use for visualizing the experiment results. 

50 """ 

51 base.ignore_plotter_warnings() 

52 if plotter_method == MlosVizMethod.DABL: 

53 import mlos_viz.dabl # pylint: disable=import-outside-toplevel 

54 

55 mlos_viz.dabl.ignore_plotter_warnings() 

56 else: 

57 raise NotImplementedError(f"Unhandled method: {plotter_method}") 

58 

59 

60def plot( 

61 exp_data: Optional[ExperimentData] = None, 

62 *, 

63 results_df: Optional[pandas.DataFrame] = None, 

64 objectives: Optional[Dict[str, Literal["min", "max"]]] = None, 

65 plotter_method: MlosVizMethod = MlosVizMethod.AUTO, 

66 filter_warnings: bool = True, 

67 **kwargs: Any, 

68) -> None: 

69 """ 

70 Plots the results of the experiment. 

71 

72 Intended to be used from a Jupyter notebook. 

73 

74 Parameters 

75 ---------- 

76 exp_data: ExperimentData 

77 The experiment data to plot. 

78 results_df : Optional[pandas.DataFrame] 

79 Optional `results_df` to plot. 

80 If not provided, defaults to :py:attr:`.ExperimentData.results_df` property. 

81 objectives : Optional[Dict[str, Literal["min", "max"]]] 

82 Optional objectives to plot. 

83 If not provided, defaults to :py:attr:`.ExperimentData.objectives` property. 

84 plotter_method: MlosVizMethod 

85 The method to use for visualizing the experiment results. 

86 filter_warnings: bool 

87 Whether or not to filter some warnings from the plotter. 

88 kwargs : dict 

89 Remaining keyword arguments are passed along to the underlying plotter(s). 

90 """ 

91 if filter_warnings: 

92 ignore_plotter_warnings(plotter_method) 

93 (results_df, _obj_cols) = expand_results_data_args(exp_data, results_df, objectives) 

94 

95 base.plot_optimizer_trends(exp_data, results_df=results_df, objectives=objectives) 

96 base.plot_top_n_configs(exp_data, results_df=results_df, objectives=objectives, **kwargs) 

97 

98 if MlosVizMethod.DABL: 

99 import mlos_viz.dabl # pylint: disable=import-outside-toplevel 

100 

101 mlos_viz.dabl.plot(exp_data, results_df=results_df, objectives=objectives) 

102 else: 

103 raise NotImplementedError(f"Unhandled method: {plotter_method}")