:py:mod:`eelib.utils.eval.eval_utils`
=====================================

.. py:module:: eelib.utils.eval.eval_utils

.. autoapi-nested-parse::

   Useful helper methods for evaluating .hdf5 results in jupyter notebooks.

   | Author: elenia@TUBS
   | Copyright 2024 elenia
   | This file is part of eELib, which is free software under the terms of the GNU GPL Version 3.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   eelib.utils.eval.eval_utils._extract_datasets_from_group
   eelib.utils.eval.eval_utils.hdf5_file_as_pandas
   eelib.utils.eval.eval_utils.get_config
   eelib.utils.eval.eval_utils.convert_hdf5_to_csv
   eelib.utils.eval.eval_utils.timestep_to_datetime
   eelib.utils.eval.eval_utils.save_figure
   eelib.utils.eval.eval_utils._read_config
   eelib.utils.eval.eval_utils.grid_from_input_file



.. py:function:: _extract_datasets_from_group(group: h5py.Group, parent_name: str = '', pattern: str = None) -> dict

   Recursively extract data from hdf5 file.

   :param group: The group where the search is currently occuring.
   :type group: Group
   :param parent_name: The parent name of that group.
   :type parent_name: str, optional
   :param pattern: regex pattern. If given, only the part matching the first
                   grouping in the pattern remains as the name for each timeseries.
                   Otherwise, the full path of the timeseries is used as its name.
   :type pattern: str

   :raises ValueError: if pattern is given and at least one name does not match it

   :returns: the fully formed subgroup for the current group.
   :rtype: dict


.. py:function:: hdf5_file_as_pandas(path: str, datetime_col: bool = False, pattern: str = None) -> pandas.DataFrame

   Return a dataframe representation of the hdf5 file.

   :param path: hdf5 file path.
   :type path: str
   :param datetime_col: determines whether a datetime column is
                        created using the Config section of the database.
   :type datetime_col: bool, optional
   :param pattern: regex pattern. If given, only the part matching the first
                   grouping in the pattern remains as the name for each timeseries.
                   Otherwise, the full path of the timeseries is used as its name.
   :type pattern: str

   :returns: The resulting dataframe.
   :rtype: pd.DataFrame


.. py:function:: get_config(path: str) -> dict

   Return scenario configuration of the hdf5 file.

   :param path: path of the hdf5 file.
   :type path: str

   :returns: scenario configuration dict.
   :rtype: dict


.. py:function:: convert_hdf5_to_csv(input_path: str, output_path: str, sep: str = ',', na_rep: str = '', datetime_col: bool = False)

   Converts an hdf5 file with the proper format into a csv file. Uses non-compact representation
   unless specified.

   :param input_path: path for input hdf5 file.
   :type input_path: str
   :param output_path: path for the output csv file.
   :type output_path: str
   :param sep: String as Field delimiter for the output file. Defaults to ','.
   :type sep: str, optional
   :param na_rep: Missing data representation. Defaults to ''.
   :type na_rep: str, optional
   :param datetime_col: Whether the function adds a column to dataframe to display
                        the actual date and time in addition to timesteps. Only works if compact=True.
                        Defaults to False.
   :type datetime_col: bool, optional


.. py:function:: timestep_to_datetime(timestep: int, zero_datetime: datetime.datetime | str, step_size: int) -> numpy.datetime64

   Converts a (numpy list of) timestep(s) to a (numpy list of) actual date(s).

   :param timestep: a timestep or a numpy array of timesteps.
   :type timestep: int
   :param zero_datetime: The datetime corresponding to timestep 0.
                         Either as str in the format "YYYY-MM-DD HH:mm:ss" or as datetime64 right away.
   :type zero_datetime: datetime | str
   :param step_size: size of each timestep in seconds.
   :type step_size: int

   :returns: calculated date(s) corresponding to timestep(s).
   :rtype: np.datetime64


.. py:function:: save_figure(fig: matplotlib.figure.Figure, ax: matplotlib.axis.Axis, filename: str, path: str, figsize: tuple[int, int] = (15, 5), dpi: int = 300, format: str = 'svg', rasterized: bool = True)

   Saves a Matplotlib figure with standardized sizing and format.

   :param fig: Matplotlib figure to be saved.
   :type fig: Figure
   :param ax: Matplotlib ax.
   :type ax: Axis
   :param filename: Name of the output file.
   :type filename: str
   :param path: path of the output file.
   :type path: str
   :param figsize: Size of the figure in inches (width, height).
   :type figsize: tuple[int, int]
   :param dpi: Dots per inch for image resolution.
   :type dpi: int
   :param format: Output file format (e.g., 'svg', 'png', 'jpg', etc.).
   :type format: str
   :param rasterized: Whether to rasterize vector elements (True) or not (False).
   :type rasterized: bool


.. py:function:: _read_config(hdf5_data: dict) -> dict

   Return dictionary corresponding to Config grouping.

   :param hdf5_data: data read from an hdf5 file using h5py.
   :type hdf5_data: dict

   :returns: the Config as stored.
   :rtype: dict


.. py:function:: grid_from_input_file(path: str) -> pandapower.auxiliary.pandapowerNet

   Retrieves the grid stored within the eELib convention of an ``input.json``.

   Params:
       path (str): The path to the ``input.json``.

   :raises ValueError: When no grid data was found in ``input.json``.

   :returns: The grid described in the ``input.json``.
   :rtype: pandapowerNet