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, Literal 

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 """Use DABL for automatic data correlation and visualization of 

39 :py:class:`~.ExperimentData`. 

40 """ 

41 

42 AUTO = DABL # use dabl as the current default 

43 """The default automatic :py:class:`~.ExperimentData` visualization method.""" 

44 

45 

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

47 """ 

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

49 adding them to the warnings filter. 

50 

51 Parameters 

52 ---------- 

53 plotter_method: MlosVizMethod 

54 The method to use for visualizing the Experiment results. 

55 """ 

56 base.ignore_plotter_warnings() 

57 if plotter_method == MlosVizMethod.DABL: 

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

59 

60 mlos_viz.dabl.ignore_plotter_warnings() 

61 else: 

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

63 

64 

65def plot( 

66 exp_data: ExperimentData | None = None, 

67 *, 

68 results_df: pandas.DataFrame | None = None, 

69 objectives: dict[str, Literal["min", "max"]] | None = None, 

70 plotter_method: MlosVizMethod = MlosVizMethod.AUTO, 

71 filter_warnings: bool = True, 

72 **kwargs: Any, 

73) -> None: 

74 """ 

75 Plots the results of the given :py:class:`~.ExperimentData`. 

76 

77 Intended to be used from a Jupyter notebook. 

78 

79 Parameters 

80 ---------- 

81 exp_data: ExperimentData 

82 The Experiment data to plot. 

83 results_df : pandas.DataFrame | None 

84 Optional `results_df` to plot. 

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

86 objectives : Optional[dict[str, Literal["min", "max"]]] 

87 Optional objectives to plot. 

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

89 plotter_method: MlosVizMethod 

90 The method to use for visualizing the Experiment results. 

91 filter_warnings: bool 

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

93 kwargs : dict 

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

95 """ 

96 if filter_warnings: 

97 ignore_plotter_warnings(plotter_method) 

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

99 

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

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

102 

103 if MlosVizMethod.DABL: 

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

105 

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

107 else: 

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