ebcpy.utils package

Package containing utility functions used in different packages. Contains a statistics analyzer and a visualizer.

ebcpy.utils.setup_logger(name: str, working_directory: Path | str | None = None, level=10)[source]

Setup an class or module specific logger instance to ensure readable output for users.

Parameters:

  • name (str) – The name of the logger instance

  • working_directory (str,Path) – The path where to store the logfile. If None is given, logs are not stored.

  • level (str) – The logging level, default is DEBUG

New in version 0.1.7.

Submodules

ebcpy.utils.conversion module

Module with functions to convert certain format into other formats.

ebcpy.utils.conversion.convert_tsd_to_clustering_txt(tsd, save_path_file, columns=None)[source]

Function to convert a TimeSeriesData object to a txt-file readable within the TICC-module.

Parameters:

  • tsd (TimeSeriesData) – TimeSeriesData object

  • save_path_file (str,os.path.normpath) – File path and name where to store the output .mat file.

  • columns (list) – A list with names of columns that should be saved to .mat file. If no list is provided, all columns are converted.

Returns True on Success, savepath of txt-file:

Returns the version 4 mat-file

Returns:

str,os.path.normpath:

Path where the data is saved. Equal to save_path_file

Examples:

>>> import os
>>> project_dir = os.path.dirname(os.path.dirname(__file__))
>>> example_file = os.path.normpath(project_dir + "//tests//data//example_data.csv")
>>> save_path = os.path.normpath(project_dir + "//tests//data//example_data_converted.txt")
>>> cols = ["sine.freqHz / Hz"]
>>> tsd = TimeSeriesData(example_file, sep=";")
>>> filepath = convert_tsd_to_clustering_txt(tsd,
>>>                                          save_path, columns=cols)
>>> os.remove(filepath)
ebcpy.utils.conversion.convert_tsd_to_modelica_mat(tsd, save_path_file, **kwargs)[source]

Function to convert a tsd to a mat-file readable within Dymola.

Parameters:

  • tsd (TimeSeriesData) – TimeSeriesData object

  • save_path_file (str,os.path.normpath) – File path and name where to store the output .mat file.

  • columns (list) – A list with names of columns that should be saved to .mat file. If no list is provided, all columns are converted.

  • offset (float) – Offset for time in seconds, default 0

Returns mat_file:

Returns the version 4 mat-file

Returns:

str,os.path.normpath:

Path where the data is saved. Equal to save_path_file

Examples:

>>> import os
>>> from ebcpy import TimeSeriesData
>>> project_dir = os.path.dirname(os.path.dirname(__file__))
>>> example_file = os.path.normpath(project_dir + "//tests//data//example_data.csv")
>>> save_path = os.path.normpath(project_dir + "//tests//data//example_data_converted.mat")
>>> cols = ["sine.freqHz / Hz"]
>>> tsd = TimeSeriesData(example_file, sep=";")
>>> filepath = convert_tsd_to_modelica_mat(tsd,
>>>                                        save_path, columns=cols)
>>> os.remove(filepath)
ebcpy.utils.conversion.convert_tsd_to_modelica_txt(tsd, table_name, save_path_file, **kwargs)[source]

Convert a TimeSeriesData object to modelica readable text. This is especially useful for generating input data for a modelica simulation.

Parameters:

  • tsd (TimeSeriesData) – TimeSeriesData object

  • table_name (str) – Name of the table for modelica. Needed in Modelica to correctly load the file.

  • save_path_file (str,os.path.normpath) – File path and name where to store the output .txt file.

  • columns (list) – A list with names of columns that should be saved to .mat file. If no list is provided, all columns are converted.

  • offset (float) – Offset for time in seconds, default 0

  • sep (str) – Separator used to separate values between columns

  • with_tag (Boolean) – Use True each variable and tag is written to the file If False, only the variable name is written to the file.

Returns:

str,os.path.normpath:

Path where the data is saved. Equal to save_path_file

Examples:

>>> import os
>>> from ebcpy import TimeSeriesData
>>> project_dir = os.path.dirname(os.path.dirname(__file__))
>>> example_file = os.path.normpath(project_dir + "//tests//data//example_data.csv")
>>> save_path = os.path.normpath(project_dir + "//tests//data//example_data_converted.txt")
>>> cols = ["sine.freqHz / Hz"]
>>> tsd = TimeSeriesData(example_file, sep=";")
>>> filepath = convert_tsd_to_modelica_txt(tsd, "dummy_input_data", save_path, columns=cols)
>>> os.remove(filepath)

ebcpy.utils.reproduction module

This module contains scripts to extract information out of simulation / programming based research and enable a reproduction of the results at a later stage.

class ebcpy.utils.reproduction.CopyFile(filename: str, sourcepath: Path, remove: bool)[source]

Bases: object

Data-class for information on a file which will be copied to the zip

Parameters:

  • filename (str) – Name of the file in the zip. Can be a relative path.

  • sourcepath (pathlib.Path) – Path on the current machine where the file to copy is located

  • remove (bool) – If True, the file will be moved instead of just copied.

filename: str
remove: bool
sourcepath: Path
class ebcpy.utils.reproduction.ReproductionFile(filename: str, content: str)[source]

Bases: object

Data-class for a text-file which will be written to te zip.

Arguments:
filename: str

Name of the file in the zip. Can be a relative path.

content: str

Content of the text file

content: str
filename: str
ebcpy.utils.reproduction.creat_copy_files_from_dir(foldername: str, sourcepath: Path, remove: bool = False)[source]

Creates a list with CopyFiles for each file in a directory where which will be saved in the zip under the foldername with all subdirectories.

Parameters:

  • foldername (str) – Name of the folder in the zip. Can be a relative path.

  • sourcepath (pathlib.Path) – Path on the current machine where the directory to copy is located

  • remove (bool) – Default is False. If True, the files in the directory will be moved instead of just copied.

Return list:

Returns a list with CopyFiles for each file in the directory source path.

ebcpy.utils.reproduction.get_git_information(path: Path, name: str | None = None, zip_folder_path: str | None = None)[source]

Function to get the git information for a given path.

Parameters:

  • path (pathlib.Path) – Path to possible git repo

  • name (str) – Name of the repo. If not given, the name in the URL will be used.

  • zip_folder_path (str) – If given, the PATH of the difference_files for the .zip will be zip_folder_path plus WARNING_GIT_DIFFERENCE…

Returns:

If the path is not a git repository, this function returns None. Else, a dictionary with the keys ‘url’, ‘commit’ and ‘difference_files’.

ebcpy.utils.reproduction.save_reproduction_archive(title: str | None = None, path: Path | str | None = None, log_message: str | None = None, files: List[ReproductionFile | CopyFile] | None = None, file: Path | str | None = None, search_on_pypi: bool = False)[source]

Function to save a reproduction archive which contains files to reproduce any simulation/software based study.

Parameters:

  • title (str) – Title of the study

  • path (pathlib.Path) – Where to store the .zip file. If not given, os.getcwd() is used.

  • log_message (str) – Specific message for this run of the study. If given, you are not asked at the end of your script to give the log_message.

  • files (list) – List of files to save along the standard ones. Examples would be plots, tables etc.

  • file (pathlib.Path) – The file which is used to run. Default is __file__ of __main__ module

  • search_on_pypi (bool) – If True, all python packages which are not a git-repo are checked for availability on pypi Default is False. Does not work if no internet connection is available.

ebcpy.utils.statistics_analyzer module

Module for calculating statistical measures based on given methods.

class ebcpy.utils.statistics_analyzer.StatisticsAnalyzer(method, for_minimization=True)[source]

Bases: object

Class for calculation of the statistical measure based on the given method. Either instantiate the class and run StatisticsAnalyzer.calc(meas, sim), or go for direct calculation with StatisticsAnalyzer.calc_METHOD(meas, sim). Where METHOD stands for one of the available methods (see below).

Parameters:

  • method ((str, callable)) –

    If string, it must be one of the following:

    • MAE(Mean absolute error)

    • R2(coefficient of determination)

    • MSE (Mean squared error)

    • RMSE(root mean square error)

    • CVRMSE(variance of RMSE)

    • NRMSE(Normalized RMSE)

    If callable, the function needs to take exactly two arguments and return a scalar value (e.g. float). The arguments should be able to handle list and numpy arrays.

    Example:

    >>> def my_func(x, y)
>>>     return sum(x - y)
>>> StatisticsAnalyzer(method=my_func)

  • for_minimization (Boolean) – Default True. To reduce (minimize) the error in given data, we either have to minimize or maximize the statistical measure. Example: R2 has to be maximized to minimize the error in data.

calc(meas, sim)[source]

Placeholder class before instantiating the class correctly.

static calc_cvrmse(meas, sim)[source]

Calculates the CVRMSE (variance of root mean square error) THIS IS A TEST for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float CVRMSE: CVRMSE of the given data.

static calc_mae(meas, sim)[source]

Calculates the MAE (mean absolute error) for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float MAE: MAE os the given data.

static calc_mse(meas, sim)[source]

Calculates the MSE (mean square error) for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float MSE: MSE of the given data.

static calc_nmbe(meas, sim)[source]

Calculates the NMBE (normalized mean bias error) for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float NMBE: NMBE of the given data.

static calc_nrmse(meas, sim)[source]

Calculates the NRMSE (normalized root mean square error) for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float NRMSE: NRMSE of the given data.

static calc_r2(meas, sim)[source]

Calculates the MAE (mean absolute error) for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float MAE: R2 of the given data.

static calc_rmse(meas, sim)[source]

Calculates the RMSE (root mean square error) for the given numpy array of measured and simulated data.

Parameters:

  • meas (np.array) – Array with measurement data

  • sim (np.array) – Array with simulation data

Returns:

float RMSE: RMSE of the given data.