added documentation to plotting methods and added info about monitoring, recording, plotting to usage.rst

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) <https://wandb.ai/site>`_ 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
 ------------------

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()

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]

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('_', '-')