diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 9c84042..8b4cc17 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -61,9 +61,11 @@ Evaluating the run ------------------ If monitoring and recording are enabled, the environment states will be traced and recorded automatically. - -Plotting. At the moment a plot of the evaluation score across the different episodes is automatically generated. - +The EnvMonitor class acts as a wrapper for Gym environments, monitoring and logging key information during interactions, +while the EnvRecorder class records state summaries during interactions in the environment. +At the end of each run a plot displaying the step reward is generated. The step reward represents the cumulative sum of rewards obtained by all agents throughout the episode. +Furthermore a comparative plot that shows the achieved score (step reward) over several runs with different seeds or different parameter settings can be generated using the methods provided in plotting/plot_compare_runs.py. +For a more comprehensive evaluation, we recommend using the `Weights and Biases (W&B) `_ framework, with the dataframes generated by the monitor and recorder. These can be found in the run path specified in your script. W&B provides a powerful API for logging and visualizing model training metrics, enabling analysis using predefined or also custom metrics. Indices and tables ------------------ diff --git a/marl_factory_grid/utils/plotting/plot_compare_runs.py b/marl_factory_grid/utils/plotting/plot_compare_runs.py index f4e24d2..a6d0c71 100644 --- a/marl_factory_grid/utils/plotting/plot_compare_runs.py +++ b/marl_factory_grid/utils/plotting/plot_compare_runs.py @@ -15,11 +15,13 @@ MODEL_MAP = None def compare_seed_runs(run_path: Union[str, PathLike], use_tex: bool = False): """ - Todo + Compare multiple runs with different seeds by generating a line plot that shows the evolution of scores (step rewards) + across episodes. - :param filepath: - :param ext: - :return: + :param run_path: The path to the directory containing the monitor files for each run. + :type run_path: Union[str, PathLike] + :param use_tex: A boolean indicating whether to use TeX formatting in the plot. + :type use_tex: bool """ run_path = Path(run_path) df_list = list() @@ -31,7 +33,7 @@ def compare_seed_runs(run_path: Union[str, PathLike], use_tex: bool = False): monitor_df = monitor_df.fillna(0) df_list.append(monitor_df) - df = pd.concat(df_list, ignore_index=True) + df = pd.concat(df_list, ignore_index=True) df = df.fillna(0).rename(columns={'episode': 'Episode', 'run': 'Run'}).sort_values(['Run', 'Episode']) columns = [col for col in df.columns if col not in IGNORED_DF_COLUMNS] @@ -58,12 +60,17 @@ def compare_seed_runs(run_path: Union[str, PathLike], use_tex: bool = False): def compare_model_runs(run_path: Path, run_identifier: Union[str, int], parameter: Union[str, List[str]], use_tex: bool = False): """ + Compares multiple model runs based on specified parameters by generating a line plot showing the evolution of scores (step rewards) + across episodes. - Todo - - :param filepath: - :param ext: - :return: + :param run_path: The path to the directory containing the monitor files for each model run. + :type run_path: Path + :param run_identifier: A string or integer identifying the runs to compare. + :type run_identifier: Union[str, int] + :param parameter: A single parameter or a list of parameters to compare. + :type parameter: Union[str, List[str]] + :param use_tex: A boolean indicating whether to use TeX formatting in the plot. + :type use_tex: bool """ run_path = Path(run_path) df_list = list() @@ -106,12 +113,18 @@ def compare_model_runs(run_path: Path, run_identifier: Union[str, int], paramete def compare_all_parameter_runs(run_root_path: Path, parameter: Union[str, List[str]], param_names: Union[List[str], None] = None, str_to_ignore='', use_tex: bool = False): """ + Compares model runs across different parameter settings by generating a line plot showing the evolution of scores across episodes. - Todo - - :param filepath: - :param ext: - :return: + :param run_root_path: The root path to the directory containing the monitor files for all model runs. + :type run_root_path: Path + :param parameter: The parameter(s) to compare across different runs. + :type parameter: Union[str, List[str]] + :param param_names: A list of custom names for the parameters to be used as labels in the plot. If None, default names will be assigned. + :type param_names: Union[List[str], None] + :param str_to_ignore: A string pattern to ignore in parameter names. + :type str_to_ignore: str + :param use_tex: A boolean indicating whether to use TeX formatting in the plot. + :type use_tex: bool """ run_root_path = Path(run_root_path) df_list = list() diff --git a/marl_factory_grid/utils/plotting/plot_single_runs.py b/marl_factory_grid/utils/plotting/plot_single_runs.py index 5846d32..777c2da 100644 --- a/marl_factory_grid/utils/plotting/plot_single_runs.py +++ b/marl_factory_grid/utils/plotting/plot_single_runs.py @@ -10,14 +10,20 @@ from marl_factory_grid.utils.plotting.plotting_utils import prepare_plot def plot_single_run(run_path: Union[str, PathLike], use_tex: bool = False, column_keys=None, - file_key: str ='monitor', file_ext: str ='pkl'): + file_key: str = 'monitor', file_ext: str = 'pkl'): """ + Plots the Epoch score (step reward) over a single run based on monitoring data stored in a file. - Todo - - :param filepath: - :param ext: - :return: + :param run_path: The path to the directory containing monitoring data or directly to the monitoring file. + :type run_path: Union[str, PathLike] + :param use_tex: Flag indicating whether to use TeX for plotting. + :type use_tex: bool, optional + :param column_keys: Specific columns to include in the plot. If None, includes all columns except ignored ones. + :type column_keys: list or None, optional + :param file_key: The keyword to identify the monitoring file. + :type file_key: str, optional + :param file_ext: The extension of the monitoring file. + :type file_ext: str, optional """ run_path = Path(run_path) df_list = list() @@ -34,7 +40,7 @@ def plot_single_run(run_path: Union[str, PathLike], use_tex: bool = False, colum monitor_df = monitor_df.fillna(0) df_list.append(monitor_df) - df = pd.concat(df_list, ignore_index=True) + df = pd.concat(df_list, ignore_index=True) df = df.fillna(0).rename(columns={'episode': 'Episode'}).sort_values(['Episode']) if column_keys is not None: columns = [col for col in column_keys if col in df.columns] diff --git a/marl_factory_grid/utils/plotting/plotting_utils.py b/marl_factory_grid/utils/plotting/plotting_utils.py index 494e289..aa54f7a 100644 --- a/marl_factory_grid/utils/plotting/plotting_utils.py +++ b/marl_factory_grid/utils/plotting/plotting_utils.py @@ -20,12 +20,12 @@ PALETTE = 10 * ( def plot(filepath, ext='png'): """ + Saves the current plot to a file and displays it. - Todo - - :param filepath: - :param ext: - :return: + :param filepath: The path to save the plot file. + :type filepath: str + :param ext: The file extension of the saved plot. Default is 'png'. + :type ext: str """ plt.tight_layout() figure = plt.gcf() @@ -43,11 +43,18 @@ def plot(filepath, ext='png'): def prepare_tex(df, hue, style, hue_order): """ - Todo + Prepares a line plot for rendering in LaTeX. - :param filepath: - :param ext: - :return: + :param df: The DataFrame containing the data to be plotted. + :type df: pandas.DataFrame + :param hue: Grouping variable that will produce lines with different colors. + :type hue: str + :param style: Grouping variable that will produce lines with different styles. + :type style: str + :param hue_order: Order for the levels of the hue variable in the plot. + :type hue_order: list + :return: The prepared line plot. + :rtype: matplotlib.axes._subplots.AxesSubplot """ sns.set(rc={'text.usetex': True}, style='whitegrid') lineplot = sns.lineplot(data=df, x='Episode', y='Score', ci=95, palette=PALETTE, @@ -60,11 +67,18 @@ def prepare_tex(df, hue, style, hue_order): def prepare_plt(df, hue, style, hue_order): """ - Todo + Prepares a line plot using matplotlib. - :param filepath: - :param ext: - :return: + :param df: The DataFrame containing the data to be plotted. + :type df: pandas.DataFrame + :param hue: Grouping variable that will produce lines with different colors. + :type hue: str + :param style: Grouping variable that will produce lines with different styles. + :type style: str + :param hue_order: Order for the levels of the hue variable in the plot. + :type hue_order: list + :return: The prepared line plot. + :rtype: matplotlib.axes._subplots.AxesSubplot """ print('Struggling to plot Figure using LaTeX - going back to normal.') plt.close('all') @@ -79,11 +93,18 @@ def prepare_plt(df, hue, style, hue_order): def prepare_center_double_column_legend(df, hue, style, hue_order): """ - Todo + Prepares a line plot with a legend centered at the bottom and spread across two columns. - :param filepath: - :param ext: - :return: + :param df: The DataFrame containing the data to be plotted. + :type df: pandas.DataFrame + :param hue: Grouping variable that will produce lines with different colors. + :type hue: str + :param style: Grouping variable that will produce lines with different styles. + :type style: str + :param hue_order: Order for the levels of the hue variable in the plot. + :type hue_order: list + :return: The prepared line plot. + :rtype: matplotlib.axes._subplots.AxesSubplot """ print('Struggling to plot Figure using LaTeX - going back to normal.') plt.close('all') @@ -99,11 +120,21 @@ def prepare_center_double_column_legend(df, hue, style, hue_order): def prepare_plot(filepath, results_df, ext='png', hue='Measurement', style=None, use_tex=False): """ - Todo + Prepares a line plot for visualization. Based on the use tex parameter calls the prepare_tex or prepare_plot + function accordingly, followed by the plot function to save the plot. - :param filepath: - :param ext: - :return: + :param filepath: The file path where the plot will be saved. + :type filepath: str + :param results_df: The DataFrame containing the data to be plotted. + :type results_df: pandas.DataFrame + :param ext: The file extension of the saved plot (default is 'png'). + :type ext: str + :param hue: The variable to determine the color of the lines in the plot. + :type hue: str + :param style: The variable to determine the style of the lines in the plot (default is None). + :type style: str or None + :param use_tex: Whether to use LaTeX for text rendering (default is False). + :type use_tex: bool """ df = results_df.copy() df[hue] = df[hue].str.replace('_', '-')